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

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

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

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

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

ユースケース例

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

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

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

Logto での仕組み​

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

実装概要​

  1. API リソースを登録し、Logto でその権限（スコープ）を定義します。
  2. 組織ロールを組織テンプレートで定義し、関連する API 権限を割り当てます。
  3. 各組織内でユーザーやクライアントにロールを割り当てます。
  4. organization_id を指定して API 用のアクセストークンをリクエストし、組織コンテキストを含めます。
  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 には、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 クレームとパスパラメーターが一致しているか

詳細な手順や言語別ガイドは アクセストークンの検証方法 を参照してください。

Optional: Handle user permission change​

User permissions can change at any time. Because Logto issues JWTs for RBAC, permission updates only appear in newly issued tokens, and never modify existing JWTs.

Scope subset rule:

An access token can only include scopes that were requested in the original OAuth authorization flow. Even if a user gains new permissions, the token issued later can only contain a subset of the originally requested scopes. To access newly granted scopes that were not part of the initial request, the client must run a new authorization flow.

Downscoped permissions​

When a user loses permissions:

  • Newly issued tokens immediately reflect the reduced scopes.
  • Existing JWTs keep the old scopes until they expire.
  • Your API should always validate scopes and rely on short token lifetimes.

If you need faster reactions, implement your own signal that tells clients to refresh their tokens.

Enlarged permissions​

For organization tokens, when a user gains permissions, enlarged permissions will show up on the next issuance (refresh or token request). A new token is still required, but no full re-auth is needed unless the new scopes exceed the original request set.

Recommendations​

  • Validate scopes in your API on every call.
  • Keep token expiration short.
  • Add optional notifications if you need immediate permission-change propagation.

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

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

よくある質問​

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

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

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

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

さらに読む​

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

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

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