グローバル 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 = クライアント認証を使うバックエンドサービスやスクリプト。

実装手順​

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 クライアントライブラリでもこのフローを実装できます。

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

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

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

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

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

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

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

よくある質問​

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

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

さらに読む​