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

組織（非 API）権限の保護

Logto の組織テンプレートを利用して、組織レベルのロールと権限を管理・適用し、組織コンテキスト内でのアプリ機能やワークフローへのアクセスを制御できます。

組織（非 API）権限とは？​

組織権限（非 API）は、組織コンテキスト内でユーザーが何をできるかを制御しますが、API レベルでは強制されません。代わりに、バックエンド API ではなく、アプリの機能、UI 要素、ワークフロー、ビジネスアクションへのアクセスを管理します。

ユースケース例

  • 組織内でのメンバー招待や管理
  • 組織ロールの割り当てや変更
  • 組織の請求、設定、管理機能の管理
  • API エンドポイントを持たないダッシュボード、分析、内部ツールへのアクセス

Logto では、OAuth 2.1 とロールベースのアクセス制御 (RBAC) を利用して、これらの組織権限をセキュアに管理でき、マルチテナント SaaS アーキテクチャにも対応しています。

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

Logto での仕組み​

  • 組織レベルの RBAC：ロールと権限は組織テンプレートで定義されます。ユーザーが組織に参加すると、1 つ以上のロールが割り当てられ、特定の権限が付与されます。
  • 非 API 強制：権限はアプリの UI、ワークフロー、またはバックエンドロジックでチェック・適用され、必ずしも API ゲートウェイで強制されるわけではありません。
  • API 保護との分離：組織（非 API）権限は API リソース権限とは別物です。高度なシナリオでは両方を組み合わせて利用できます。
組織権限 RBAC

実装概要​

  1. Logto の組織テンプレートで組織権限を定義します。
  2. 組織固有のアクションに必要な権限をまとめた組織ロールを作成します。
  3. 各組織内のユーザーやクライアントにロールを割り当てます。
  4. リフレッシュトークンまたはクライアントクレデンシャルフローを使って、現在の組織の組織トークン（JWT）を取得します。
  5. アプリの UI やバックエンドでアクセストークンを検証し、組織権限を強制します。

認可フロー：組織権限の認証と保護​

以下のフローは、クライアント（Web、モバイル、バックエンド）が非 API 権限の強制のために組織トークンを取得・利用する流れを示しています。

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

ユーザー認証 = ブラウザ/アプリ。M2M = クライアントクレデンシャル + 組織コンテキストを使うバックエンドサービスやスクリプト。

実装手順​

組織権限の登録​

  1. コンソール → 組織テンプレート → 組織権限

     にアクセスします。
  2. 必要な組織権限を定義します（例：invite:member、manage:billing、view:analytics など）。

詳細な設定手順は 組織権限の定義 を参照してください。

組織ロールの設定​

  1. コンソール → 組織テンプレート → 組織ロール

     にアクセスします。
  2. 先ほど定義した組織権限をまとめたロールを作成します（例：admin、member、billing など）。
  3. これらのロールを各組織内のユーザーやクライアントに割り当てます。

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

組織トークン（非 API）の取得​

クライアント/アプリは、組織権限へアクセスするために組織トークン（非 API）を取得する必要があります。Logto は JSON Web Token (JWT) 形式で組織トークンを発行します。リフレッシュトークンフロー または クライアントクレデンシャルフロー のいずれかで取得できます。

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

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

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

一部の Logto SDK には、UserScope.Organizations など組織用の事前定義スコープがあります。

注記:

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

特定の組織の組織トークンをリクエストするには、getOrganizationToken または getAccessToken（組織 ID 指定）などのメソッドを利用します。

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

クライアントクレデンシャルフロー​

マシン間通信 (M2M) シナリオでは、クライアントクレデンシャルフローを利用して組織権限用のアクセストークンを取得できます。Logto の /oidc/token エンドポイントに組織パラメータを含めて POST リクエストを送信し、クライアント ID とシークレットで組織トークンをリクエストします。

リクエストに含める主なパラメータ：

  • organization_id：トークンを取得したい組織の ID
  • scope：リクエストしたい組織権限（例：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
&organization_id=your-organization-id
&scope=invite:member manage:billing

組織トークンの検証​

Logto が発行する組織トークン（JWT）には、アプリ/UI/バックエンドで組織レベルのアクセス制御を強制するためのクレームが含まれています。

アプリが組織トークンを受け取った際は、次の点を確認してください：

  • トークン署名の検証（Logto の JWKs を利用）
  • トークンの有効期限（exp クレーム）の確認
  • iss（発行者）が Logto エンドポイントと一致しているか
  • aud（オーディエンス）がフォーマットされた組織識別子（例：urn:logto:organization:{organization_id}）と一致しているか
  • scope クレーム（スペース区切り）を分割し、必要な権限が含まれているか

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

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.

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

  • UI のみの強制に頼らない：重要なアクションは必ずバックエンドでも権限を検証してください。
  • オーディエンス制限を利用：aud クレームを必ず確認し、トークンが意図した組織用であることを保証してください。
  • ビジネス主導の権限設計：実際のアクションに対応する明確な名前を使い、各組織ロールに必要なものだけを付与してください。
  • API 権限と非 API 権限は可能な限り分離（ただし両方を 1 つのロールに含めることも可能）。
  • プロダクトの進化に合わせて組織テンプレートを定期的に見直す。

よくある質問​

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

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

非 API 権限はどこで強制すべきですか？​

非 API 権限は、UI（機能制御用）とサーバーサイドロジック（重要なアクション用）の両方でチェックしてください。

さらに読む​

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

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