グローバル 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 リソースの保護 を参照してください。

実装概要

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 SDK

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

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

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

OAuth 2.0 / OIDC client library

OAuth 2.0 クライアントの設定や認可コードフロー初期化時に、resource パラメーターと必要なスコープを認可リクエストに含めてください。

一部のライブラリは resource パラメーターをネイティブにサポートしていませんが、通常は追加パラメーターとして認可リクエストに渡すことができます。詳細はライブラリのドキュメントを確認してください。

resource および scope パラメーターを含む認可リクエストの非公式例：

GET /oidc/auth?response_type=code
&client_id=your-client-id
&redirect_uri=https://your-app.com/callback
&scope=openid profile offline_access read:products write:products
&resource=https://api.your-app.com
&code_challenge=abc123
&code_challenge_method=S256
&state=xyz
HTTP/1.1
Host: your.logto.endpoint

ユーザーが認証 (Authentication) されると、認可コードが返されます。このコードを Logto の /oidc/token エンドポイントに POST し、リクエストボディに resource パラメーターを含めてアクセス トークンと交換します。

認可コードグラントタイプでのトークンリクエストの非公式例：

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=authorization_code
&code=authorization-code-received
&redirect_uri=https://your-app.com/callback
&resource=https://api.your-app.com

また、refresh_token グラントタイプを使えば、ユーザー操作なしで新しいアクセス トークンを取得できます（リクエストに resource パラメーターを含める必要があります）。

リフレッシュ トークングラントタイプでのトークンリクエストの非公式例：

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=refresh_token
&refresh_token=your-refresh-token
&resource=https://api.your-app.com

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

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

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

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 global API resources, when a user gains permissions, enlarged permissions will NOT show up through refresh. The client must perform a new OAuth authorization flow to obtain a token that includes the new scopes. This can happen silently if the user has an active Logto session.

Recommendations

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

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

• 権限はビジネスに即したものに： 実際のアクションに対応する明確な名前を使いましょう。
• トークン有効期限は短く： トークンが漏洩した場合のリスクを減らせます。
• 付与するスコープは最小限に： 実際に必要な権限だけをトークンに与えましょう。
• オーディエンス制限を利用： 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: リソースインジケーター