メインコンテンツまでスキップ

組織レベルの API リソースを保護する

API リソースと組織テンプレートを組み合わせることで、各組織内の API やデータへのアクセスを制限し、SaaS におけるテナントレベルの分離を実現できます。

組織レベルの API リソースとは？​

組織レベルの API リソースとは、特定の組織にスコープされたアプリケーション内のエンドポイントやサービスです。これらの API は組織コンテキストに基づいて認可 (Authorization) とアクセスを強制し、ユーザーやクライアントが自分の組織に関連するデータや操作のみを利用できるようにします。

主なユースケース例

  • 組織メンバー、ロール、設定を管理する API（例： /organizations/{organizationId}/members ）
  • 組織単位のダッシュボード、分析、レポート
  • 組織に紐づく請求、サブスクリプション、監査用エンドポイント
  • アクションやデータがテナントごとに分離されるすべての API

Logto は、OAuth 2.1 とロールベースのアクセス制御 (RBAC) を利用して、これらの組織 API をセキュアに保護し、マルチテナント SaaS アーキテクチャをサポートします。

これらの権限は 組織テンプレート で定義された組織ロールによって管理されます。すべての組織が同じテンプレートを使用するため、全組織で一貫した権限モデルが保証されます。

Logto での仕組み​

  • API リソースと権限はグローバルに登録される： 各 API リソースは一意のリソースインジケーター（URI）と権限（スコープ）のセットで Logto に定義されます。
  • 組織レベルのロール： 組織ロールは組織テンプレートで定義されます。API リソースの権限（スコープ）は組織ロールに割り当てられ、各組織内のユーザーやクライアントに付与されます。
  • コンテキスト認識型認可 (Authorization)： クライアントが API リソースと organization_id の両方を指定してアクセストークンをリクエストすると、Logto は組織コンテキストと API オーディエンスの両方を含むトークンを発行します。トークンの権限（スコープ）は、指定した組織におけるユーザーの組織ロールによって決定されます。
  • グローバルリソースとの分離： API リソースは組織コンテキストの有無にかかわらずアクセスできます。組織 RBAC はリクエストに organization_id が含まれる場合のみ適用されます。すべてのユーザーで共有される API については グローバル API リソースの保護 を参照してください。
組織レベルの API リソース RBAC

実装概要​

  1. API リソースを登録し、Logto でその権限（スコープ）を定義します。
  2. 組織ロールを定義し、関連する API 権限を割り当てます。
  3. 各組織内でユーザーやクライアントにロールを割り当てます。
  4. API 用のアクセストークンを organization_id 付きでリクエストし、組織コンテキストを含めます。
  5. API でアクセストークンを検証し、組織コンテキストと権限の両方を強制します。

Logto における組織 RBAC の適用方法​

  • organization_id なしでアクセストークンをリクエストした場合、グローバルロール／権限のみが考慮されます。
  • organization_id ありでアクセストークンをリクエストした場合、Logto はユーザーの組織ロールとその組織に紐づく権限を評価します。
  • 発行される JWT には API オーディエンス（aud クレーム）と組織コンテキスト（organization_id クレーム）の両方が含まれ、スコープはユーザーの組織ロールで許可されたものに絞り込まれます。

認可 (Authorization) フロー：組織コンテキスト付きで API を認証・保護する​

以下のフローは、クライアント（Web、モバイル、バックエンド）が組織トークンを取得し、組織レベルの API リソースへアクセスする流れを示しています。

このフローは必要なパラメーターやヘッダーの詳細をすべて網羅しているわけではなく、主要なステップに焦点を当てています。実際の動作例はこの後の説明を参照してください。

ユーザー認証 (Authentication) = ブラウザ／アプリ。M2M = クライアント認証情報＋組織コンテキストを使うバックエンドサービスやスクリプト。

実装手順​

API リソースを登録する​

  1. コンソール → API リソース へ移動します。
  2. 新しい API リソース（例： https://api.yourapp.com/org ）を作成し、その権限（スコープ）を定義します。

詳細な設定手順は API リソースと権限の定義 を参照してください。

組織ロールを設定する​

  1. コンソール → 組織テンプレート → 組織ロール へ移動します。
  2. 組織ロール（例： admin、member）を作成し、各ロールに API 権限を割り当てます。
  3. 各組織内でユーザーやクライアントにロールを割り当てます。まだメンバーでない場合は、招待または追加してください。

詳細な設定手順は 組織ロールの利用 を参照してください。

API リソース用の組織トークンを取得する​

クライアント／アプリは resource と organization_id の両方を指定してトークンをリクエストし、組織レベルの API へアクセスします。Logto は組織トークンを JSON Web Token (JWT) 形式で発行します。これは リフレッシュ トークンフロー または クライアント認証情報フロー のいずれかで取得できます。

リフレッシュ トークンフロー​

ほとんどの Logto 公式 SDK はリフレッシュ トークンフローによる組織トークン取得を標準サポートしています。標準的な OAuth 2.0 / OIDC クライアントライブラリでもこのフローを実装できます。

Logto SDK 初期化時に、urn:logto:scope:organizations および必要な組織権限（スコープ）を scopes パラメーターに追加します。

一部の Logto SDK には組織用のプリセットスコープ（例： JavaScript SDK の UserScope.Organizations ）があります。

注記:

ID トークンの organizations クレーム (Claim) を確認すると、ユーザーが所属している組織 (Organization) の ID 一覧を取得できます。このクレーム (Claim) には、ユーザーがメンバーであるすべての組織 (Organization) がリストされているため、アプリ内で組織 (Organization) の列挙や切り替えが簡単に行えます。

getAccessToken() を呼び出す際、API リソース（resource）と組織 ID（organizationId）の両方を指定して組織トークンを取得します。

各 SDK の詳細は クイックスタート を参照してください。

クライアント認証情報フロー​

マシン間通信 (M2M) シナリオでは、クライアント認証情報フローを使って組織レベルの API リソース権限用アクセストークンを取得できます。Logto の /oidc/token エンドポイントへ組織パラメーター付きで POST し、クライアント ID とシークレットで組織トークンをリクエストします。

主なパラメーター：

  • resource: API リソース識別子（例： https://api.yourapp.com/org ）。
  • organization_id: トークンを取得したい組織の ID。
  • scope: 要求する組織レベルの API リソース権限（例： invite:member、manage:billing ）。

クライアント認証情報グラントタイプでのトークンリクエスト例（非規範的）：

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials
&resource=https://api.yourapp.com/org
&organization_id=your-organization-id
&scope=invite:member manage:billing

組織トークンを検証する​

Logto が発行する組織トークン（JWT）には、API で組織レベルのアクセス制御を強制するためのクレームが含まれます。

アプリが組織トークンを受け取ったら：

  • トークン署名を検証（Logto の JWKs を使用）。
  • トークンの有効期限（exp クレーム）を確認。
  • iss（発行者）が Logto エンドポイントと一致するか確認。
  • aud（オーディエンス）が登録した API リソース識別子（例： https://api.yourapp.com/org ）と一致するか確認。
  • organization_id クレームが正しい組織にスコープされているか検証。
  • scope クレーム（スペース区切り）を分割し、必要な権限が含まれているか確認。
  • API パスに組織 ID（例： /organizations/{organizationId}/members ）が含まれる場合、organization_id クレームとパスパラメーターが一致するか確認。

ステップバイステップや言語別ガイドは アクセストークンの検証方法 を参照してください。

ベストプラクティスとセキュリティのヒント​

  • 常に組織コンテキストを検証する： トークンだけを信用せず、すべての組織スコープ API 呼び出しで organization_id クレームを確認してください。
  • オーディエンス制限を利用する： aud クレームを必ず確認し、トークンが意図した組織用であることを保証してください。
  • 権限はビジネス主導で設計： 実際のアクションに対応する明確な名前を使い、各組織ロールに必要なものだけを付与してください。
  • API 権限と非 API 権限は可能な限り分離（ただし両方を 1 つのロールに含めることも可能）。
  • トークンの有効期間は短く保つ： 万一漏洩した場合のリスクを低減します。
  • 組織テンプレートを定期的に見直す： 製品の進化に合わせてロールや権限を更新してください。

よくある質問​

トークンリクエストに organization_id を含めなかった場合は？​

グローバルロール／権限のみが評価され、組織 RBAC は適用されません。

1 つのロールに組織権限と非組織権限を混在できますか？​

いいえ、組織権限（組織レベルの API 権限を含む）は組織テンプレートで定義されており、グローバル API 権限と混在できません。ただし、組織権限と組織レベルの API 権限を両方含むロールは作成できます。

さらに読む​

アクセストークンの検証方法 トークンクレームのカスタマイズ

ユースケース：マルチテナント SaaS アプリケーションの構築

 RFC 8707: リソースインジケーター