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

組織（非 API）権限の保護

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

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

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

ユースケース例

  • 組織内でメンバーを招待・管理する
  • 組織ロールの割り当てや変更
  • 組織の請求、設定、管理機能の管理
  • 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 の初期化時に、urn:logto:scope:organizations および必要な組織権限（スコープ）を scopes パラメーターに追加します。

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

注記:

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

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

各 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 クレーム（スペース区切り）を分割し、必要な権限が含まれているか確認

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

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

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

よくある質問​

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

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

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

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

さらに読む​

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

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