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

グローバル API リソースの保護

Logto のロールベースのアクセス制御 (RBAC) を使用して、プロダクト全体の API を保護します。グローバルロールと権限を割り当てることで、アプリケーション全体のすべてのユーザーやクライアントのアクセスを制御できます。

グローバル API リソースとは？​

グローバル API リソースとは、組織やテナントに関係なく、すべてのユーザーがアクセスできるアプリケーション内のエンドポイントやサービスです。これらは通常、パブリック向け API、コアプロダクトサービス、または特定の組織に限定されないエンドポイントです。

ユースケース例

  • ユーザーベース全体で共有されるパブリック API やエンドポイント
  • マルチテナンシーに紐づかないマイクロサービス
  • すべての顧客が利用するコアアプリケーション API（例： /api/users、 /api/products）

Logto では、OAuth 2.1 と柔軟なロールベースのアクセス制御を組み合わせて、これらの API を安全に保護できます。

Logto での仕組み​

  • API リソースと権限はグローバルに登録される： 保護したい各 API は、一意のリソースインジケーター（URI）とアクセスを制御する権限（スコープ）のセットで定義されます。
  • アクセスはグローバルロールで制御： 権限をロールに割り当て、それをユーザーやクライアントに割り当てます。
  • 組織レベルの権限とは分離： グローバル API リソースには組織の文脈がありません。ただし、必要に応じて組織ロールと組み合わせて追加の文脈を提供することも可能です。組織レベルの API を保護するには、組織レベルの API リソースの保護 を参照してください。
グローバル API リソース RBAC

実装概要​

  1. API リソースを登録し、Logto でその権限を定義します。
  2. API へのアクセスに必要な権限を持つロールを定義します。
  3. ロールをユーザーやクライアントに割り当てます。
  4. OAuth 2.0 認可フローを使用して API 用のアクセス トークンを取得します（resource パラメーターは登録した API 識別子と一致させる必要があります）。
  5. API でアクセス トークンを検証し、権限を強制します。

リソースインジケーターの理解​

Logto は RFC 8707: OAuth 2.0 のリソースインジケーター に従って API リソースをモデル化しています。リソースインジケーターとは、リクエスト対象の API やサービスを一意に識別する URI です。

ポイント

  • リソースインジケーターは絶対 URI でなければなりません（例： https://api.example.com）
  • フラグメントコンポーネントは不可。可能な限りクエリストリングの使用も避けてください。
  • リソースインジケーターにより、オーディエンス制限付きトークンやマルチ API アーキテクチャのサポートが可能になります。

例

  • Management API: https://my-tenant.logto.app/api
  • カスタムグローバル API: https://api.yourapp.com

認可フロー：API の認証と保護​

以下のフローは、インタラクティブなユーザー認証（ブラウザ / アプリ）とバックエンドのマシン間通信 (M2M) シナリオの両方に適用されます。

このフローは必要なパラメーターやヘッダーの詳細をすべて網羅しているわけではなく、主要なステップに焦点を当てています。実際のフローの動作については、引き続きお読みください。

ユーザー認証 = ブラウザ / アプリ。M2M = クライアント認証を使うバックエンドサービスやスクリプト。

注記:

resource パラメーターは、Logto で登録した API 識別子（リソースインジケーター）と完全に一致している必要があります。

実装手順​

API リソースの登録​

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

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

グローバルロールの設定​

  1. コンソール → ロール に移動します。
  2. API 権限に対応するロール（例： read:products、 write:products）を作成します。
  3. これらのロールを API へのアクセスが必要なユーザーやクライアントに割り当てます。

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

グローバル API リソース用のアクセス トークンの取得​

グローバル API リソースにアクセスする前に、クライアントはアクセス トークンを取得する必要があります。Logto はグローバル API リソース用の JSON Web Token (JWT) をアクセス トークンとして発行します。これは通常、OAuth 2.0 認可コードフロー、リフレッシュ トークンフロー、または クライアント認証フロー を使用して行われます。

認可コードまたはリフレッシュ トークンフロー​

Logto 公式 SDK はすべて、リフレッシュ トークンフローを利用したグローバル API リソース用のアクセス トークン取得をサポートしています。標準的な OAuth 2.0 / OIDC クライアントライブラリでもこのフローを実装できます。

Logto クライアントの初期化時に、resources パラメーター（配列）にリソースインジケーターを追加し、scopes パラメーターに必要な権限（スコープ）を追加します。

ユーザーが認証された後、getAccessToken() などでアクセス トークンをリクエストする際に、resource パラメーターまたは同様のパラメーターでリソースインジケーターを渡します。

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

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

マシン間通信 (M2M) シナリオでは、クライアント認証フローを使ってグローバル API リソース用のアクセス トークンを取得できます。Logto の /oidc/token エンドポイントに POST リクエストを送り、クライアント ID とシークレットを使ってアクセス トークンをリクエストします。

リクエストに含めるべき主なパラメーターは 2 つです：

  • resource: アクセスしたい API のリソースインジケーター URI（例： https://api.yourapp.com）
  • scope: API にリクエストしたい権限（例： read:products write:products）

クライアント認証グラントタイプを使ったトークンリクエストの非公式例：

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
&scope=read:products write:products

API での JWT アクセス トークンの検証​

Logto が発行する JWT には、API で認可 (Authorization) を強制するために利用できるクレームが含まれています。

API が Logto 発行のアクセス トークンを受け取った場合、次のことを行うべきです：

  • トークン署名の検証（Logto の JWKs を使用）
  • トークンが有効期限切れでないことの確認（exp クレーム）
  • iss（発行者）が Logto エンドポイントと一致していることの確認
  • aud（オーディエンス）が登録した API リソース識別子（例： https://api.yourapp.com）と一致していることの確認
  • scope クレーム（スペース区切り）を分割し、必要な権限が含まれているか確認

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

オプション：ユーザー権限変更のハンドリング​

備考:

👷 作業中です。 🚧

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

  • 権限はビジネス主導で設計： 実際のアクションに対応する分かりやすい名前を使いましょう。
  • トークンの有効期限は短く： トークンが漏洩した場合のリスクを低減します。
  • 付与するスコープは最小限に： トークンには本当に必要な権限だけを与えましょう。
  • オーディエンス制限を活用： aud クレームを必ず検証し、不正利用を防ぎましょう。

よくある質問​

クライアントが resource パラメーターをサポートしていない場合は？​

Logto コンソールでデフォルトの API リソースを設定してください。トークンリクエストで resource パラメーターが指定されていない場合、このオーディエンスがデフォルトになります。

API から 401 Unauthorized が返される理由は？​

次の一般的な問題を確認してください：

  • トークン署名：バックエンドが Logto から正しい JWKs を取得しているか確認
  • トークンの有効期限：トークンが有効期限切れでないか（exp クレーム）
  • オーディエンス：aud クレームが登録した API リソースインジケーターと一致しているか
  • 必要なスコープ：トークンの scope クレームに必要な権限が含まれているか

フルクライアントなしでテストするには？​

パーソナルアクセストークン を使って認証済みコールをシミュレートできます。これにより、クライアントアプリケーションで完全な OAuth フローを実装せずに API エンドポイントのテストが可能です。

権限リクエスト時にスコープのプレフィックスや短縮形は使えますか？​

いいえ。スコープ名は API リソースで定義した権限名と完全一致している必要があります。プレフィックスや短縮形はワイルドカードとして機能しません。

例：

API リソースで次のように定義している場合：

  • read:elections
  • write:elections

リクエスト時は次のように指定する必要があります：

scopes: ["read:elections", "write:elections"]

これは動作しません：

scopes: ["read", "write"]  // ❌ 権限名と一致しません

さらに読む​

アクセス トークンの検証方法

RBAC 実践：アプリケーションの安全な認可 (Authorization) 実装

 トークンクレームのカスタマイズ RFC 8707: リソースインジケーター