> ## Documentation Index > Fetch the complete documentation index at: https://developers.authlete.com/llms.txt > Use this file to discover all available pages before exploring further. # サービスアクセストークン > 権限、プリセット、継承、API の利用、セキュリティのベストプラクティスなど、Authlete のサービスアクセストークンの仕組みについて解説します。 ## はじめに 本記事では、Authlete の**サービスアクセストークン** (Service Access Token、以下 SAT) について説明します。 SAT は、単一の Authlete サービスに対して発行されるベアラークレデンシャル（bearer credential）です。これは、認可サーバー、リソースサーバー、CLI スクリプト、または CI/CD パイプラインが、Authlete のランタイム API やサービス管理 API を呼び出す際に提示するクレデンシャルです。 プリセットの利用、または個別の権限選択によって権限をカスタマイズすることで、呼び出し元が必要とするものだけにトークンのスコープを正確に絞り込むことができます。これにより、リソースサーバーにはイントロスペクション権限のみ付与、管理ツールには必要なクライアント管理権限のみ付与、といったことが可能になります。 SAT は、サービスレベルのランタイムワークロードに適したクレデンシャルです。組織内のすべてのサービスにまたがる管理プレーンの操作 (サービスの作成、組織の監査ログの取得、Terraform や CI/CD プロビジョニングの実行など) には、代わりに組織アクセストークン（Organization Access Token）を使用してください。
## トークンのプロパティ #### トークン名 サービスアクセストークン一覧でトークンを区別するために使用される、人間が読める形式の識別子です。この名前は、トークンの動作や権限には影響しません。 #### 有効期限 トークンの有効期限が切れ、無効になる日時を指定します。 * 設定した場合、指定された日時以降はそのトークンを使用できません。 * 設定しない場合、トークンの有効期限は切れません。 自動化で使用されるトークンについては、明示的に有効期限を設定することを強く推奨します。コンソール上では、1ヶ月以内に有効期限が切れるトークンは赤色で表示されます。 #### トークンの値 トークンの値は、トークンが作成またはローテーションされた際に一度だけ表示されます。 * 作成時にコピーし、セキュアに保存する必要があります。 * 以降、このトークンの値を再度取得することはできません。 #### ローテーション トークンをローテーションして、新しい値を生成することができます。 * ローテーションを行うと、以前のトークン値は即座に無効になります。 * 新しいトークン値は一回しか表示されないため、コピーして保存する必要があります。 * 明示的に更新されない限り、権限やメタデータ（名前、有効期限）はローテーション後も保持されます。 #### トークン一覧 すべてのサービスアクセストークンはテーブルに一覧表示されます。テーブルには以下のカラムが含まれます。 * **トークン名 (Token Name)**: ユーザーが定義した識別子。 * **権限 (Permissions)**: トークンに割り当てられた権限。 * **作成日 (Created)**: トークンが作成された日付。 * **有効期限 (Expires)**: 有効期限。設定されていない場合は無期限。 * **アクション (Actions)**: 利用可能な操作（ローテーションや削除など）。
## 権限プリセット [標準的な OAuth 2.0 のロール][RFC6749-1.1]に合わせた、事前設定された権限セットです。プリセットを選択すると、固定の権限の組み合わせが適用されます。その後、手動で権限を追加または削除すると、プリセットの選択は解除されます。 | プリセット | 説明 | 権限 | | :------------------------- | :-------------------------------------------------------------------------------- | :------------------ | | Authorization Server | 標準的な認可サーバーが必要とする、すべてのランタイム OAuth/OIDC エンドポイントへのアクセスを許可します。 | `use_service` | | Admin Authorization Server | デフォルトで選択されているプリセットです。サービスに対する完全な管理権限を付与します。ランタイムエンドポイント、クライアント管理、およびサービス設定が含まれます。 | `modify_service` | | Resource Server | リソースサーバーがアクセストークンを検証するために必要な、最小限のアクセス権です。 | `use_introspection` |
## カスタム権限 ユースケースに合うプリセットがない場合は、権限を個別に選択できます。権限は、[権限の継承](#権限の継承)で説明されている継承ルールに従い、上位レベルの権限を選択すると、暗黙的に下位レベルの権限も付与されます。 `preset` と `permissions` の両方が省略された場合は、**トークンを作成**ボタンが無効化されます。トークンを発行する前に、プリセットを選択するか、少なくとも 1 つの権限を選択する必要があります。プリセットが選択された後で、呼び出し元が個別の権限を追加または削除した場合、プリセットの選択は解除されます。 #### `use_service` ランタイムの OAuth/OIDC 操作です。認可サーバーの運用における標準的な権限です。以下の呼び出しを許可します。 * `/auth/authorization` * `/auth/token` * `/auth/userinfo` * `/auth/introspection` * `/auth/revocation` * `/pushed_auth_req` * `/service/configuration` * `/service/jwks/get` * `/backchannel/authentication` * `/device/authorization` * `/device/verification` * `/device/complete` * `/federation/*` * `/vci/*` (Verifiable Credentials) * `/jose/verify` * `/idtoken/reissue` * `/token/create` * `/token/update` * `/token/delete` * `/token/revoke` * `/token/get/list` * `/rs/sign` * `/hsk/get` * `/client/authorization/get/list` * `/client/registration` (動的クライアント登録) また、暗黙的に `use_introspection`、`view_service`、および `view_client` も付与します。 #### `use_introspection` トークンイントロスペクションのみ。リソースサーバーがアクセストークンを検証するために必要な最小限の権限です。以下の呼び出しを許可します。 * `/auth/introspection` * `/auth/introspection/standard` `/auth/authorization` や `/auth/token` といったランタイムのエンドポイントへのアクセスは許可しません。 #### `view_service` サービス設定の参照です。以下の呼び出しを許可します。 * `/service/get` * `/service/get/list` また、暗黙的に `view_client` も付与します。モニタリングダッシュボードや参照のみのインテグレーションに使用してください。 #### `view_client` クライアントの詳細の参照です。以下の呼び出しを許可します。 * `/client/get` * `/client/get/list` * `/client/granted_scopes/get` * `/client/extension/requestable_scopes/get` クライアントの作成、変更、削除は許可しません。クライアントの登録状況を検査する、監査ツールやダッシュボードに使用してください。 #### `modify_client` クライアントの更新および削除です。これには、認可を削除してユーザーのログアウト処理を実行するために必要なエンドポイントも含まれます。以下の呼び出しを許可します。 * `/client/update` * `/client/delete` * `/client/secret/update` * `/client/secret/refresh` * `/client/lock_flag/update` * `/client/extension/requestable_scopes/update` * `/client/granted_scopes/delete` * `/client/authorization/delete` (ユーザーセッションの取り消し / ログアウト) * `/client/authorization/update` また、暗黙的に `view_client` も付与します。 #### `create_client` OAuth クライアントの新規登録をプログラムから行う場合に適します。以下の呼び出しを許可します。 * `/client/create` * `/client/get/default` また、暗黙的に `use_service`、`modify_client`、`view_service`、および `view_client` も付与します。プラットフォームが OAuth クライアントを動的にプロビジョニングする場合に使用してください。 #### `modify_service` サービスの完全な管理を行います。以下の呼び出しを許可します。 * `/service/update` * `/hsk/create` * `/hsk/delete` * `/client/extension/requestable_scopes/delete` 他のすべての SAT 権限を含みます。サービスに対する完全な制御が必要な管理ツールや CI/CD パイプラインに使用してください。 既知の問題: 現状、`modify_service` は `use_introspection` を暗黙的には付与しません。回避策については[403 エラーのトラブルシューティング](#403-エラーのトラブルシューティング)を参照してください。
## 権限の継承 上位レベルの権限は、依存する下位レベルの権限を暗黙的に付与します。継承の連鎖は以下の通りです： * `modify_service` → すべての権限 * `create_client` → `use_service`, `modify_client`, `view_service`, `view_client` * `use_service` → `use_introspection`, `view_service`, `view_client` * `modify_client` → `view_client` * `view_service` → `view_client` カスタム権限セットを構築する際は、呼び出し元が必要とする最も上位レベルの権限のみを選択してください。継承の連鎖により、下位レベルの権限は暗黙的に付与されます。
## サービスアクセストークンの使用 Authlete のサービスレベル API を呼び出す際、`Authorization` ヘッダーにベアラークレデンシャルとしてトークンを指定し、さらに、サービス ID および適切な API サーバー URL と組み合わせて使用してください。 以下は、`use_service` 権限を持つ SAT を使用して、認可サーバーから Process Token Request API を呼び出す例です。 ```shell theme={null} curl --oauth2-bearer ${SERVICE_ACCESS_TOKEN} \ https://${AUTHLETE_SERVER}/api/${SERVICE_ID}/auth/token \ --data-urlencode "parameters=grant_type=authorization_code&code=…&redirect_uri=…" \ --data-urlencode "clientId=client001" \ --data-urlencode "clientSecret=${CLIENT_SECRET}" ``` 以下は、`use_introspection` のみを保持する SAT を使用して、リソースサーバーから Process Introspection Request API を呼び出す例です。 ```shell theme={null} curl --oauth2-bearer ${SERVICE_ACCESS_TOKEN} \ https://${AUTHLETE_SERVER}/api/${SERVICE_ID}/auth/introspection \ --json '{ "token": "${ACCESS_TOKEN_TO_VALIDATE}" }' ``` Authlete API サーバーは呼び出されるたびにトークンの権限をチェックします。エンドポイントの要求する権限がトークンに付与されていない場合、レスポンスは `403 Forbidden` となります。例えば、`use_introspection` のみが付与されたトークンでは `/auth/token` を呼び出すことはできません。
## コンソールによるトークン発行の仕組み サービスアクセストークンは、Authlete IdP の `/api/servicetoken/create` エンドポイントによって発行されます。管理者が**トークンを作成**ボタンをクリックすると、管理コンソールが代行してこのエンドポイントを呼び出します。このエンドポイントは、呼び出し元を IdP ユーザー（セッションまたはユーザーアクセストークン経由）として認証し、対象サービスに対する MODIFY\_SERVICE 権限を要求します。サービスアクセストークンおよび組織アクセストークンは、このエンドポイントのベアラークレデンシャルとしては受け付けられません。 コンソールが送信するリクエストボディの形式は以下の通りです。 | リクエストパラメーター | 必須/任意 | 説明 | | ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `serviceId` | 必須 | トークンが対象とするサービスの ID です。 | | `organizationId` | 必須 | サービスを所有する組織の ID です。 | | `apiServerId` | 必須 | サービスをホストしている API サーバー（クラスター）の ID です。 | | `description` | 必須 | コンソールに表示され、トークンを区別するために使用される、人間が読める形式の名前です。 | | `preset` | 必須 | `standard_as`、`admin_as`、`resource_server`、または `custom` のいずれかです。 | | `permissions` | 条件付き必須 | 明示的な権限のリストです。`preset` が `custom` の場合は必須、それ以外のプリセットの場合は指定すると拒否されます。権限は `use_service`、`use_introspection`、`view_service`、`view_client`、`create_client`、`modify_client`、`modify_service` から選択する必要があります。 | | `durationSeconds` | 任意 | 作成からのトークンの有効期間を**秒単位**で指定します。無期限のトークンの場合は省略（または `null` を設定）できます。 | レスポンスボディの形式は以下の通りです。 ```json theme={null} { "serviceId": 12345, "organizationId": 67890, "apiServerId": 111, "accessToken": "sat_3Yq9bP0u1NiqU6Pz_uIH7n3Z2bP7Sg5K…", "tokenId": "01HW…", "description": "prod-as", "permissions": ["use_service"], "createdAt": "2026-05-12T07:34:22Z", "expiresAt": "2026-06-11T07:34:22Z" } ``` `accessToken` フィールドの値は一度だけ返却されます。後から再取得することはできないため、発行後は直ちにシークレットマネージャー等にコピーして保管してください。同様に、トークンのローテーション時に返される値も一度しか表示されません。
## 403 エラーのトラブルシューティング Authlete の API 呼び出しが HTTP `403 Forbidden` で失敗した場合、レスポンスボディにはエンドポイントが要求する正確な権限名を記載した `resultMessage` が含まれます。 ``` [A457101] (/client/create) Function requires access rights ([CREATE_CLIENT]) for service (233044842478), access token does not have sufficient access. ``` ``` [A456101] (/client/delete/{clientIdentifier}) Function requires access rights ([MODIFY_CLIENT]) for service (1495709902) and client (4140464843). ``` 角括弧で囲まれたアクセス権（例: `[CREATE_CLIENT]`、`[MODIFY_CLIENT]`）を[カスタム権限](#カスタム権限)のいずれかの権限にマッピングし、その権限でトークンを再発行してください。オプションは以下の2つです： 1. **該当の操作をカバーするプリセットでトークンを再作成する。** クライアント管理の呼び出しの場合、**Admin Authorization Server** プリセット (`modify_service`) が、すべてのクライアント管理およびサービス管理のエンドポイントをカバーします。 2. **カスタム権限でトークンを再作成する。** エラーメッセージで指定されたアクセス権（または [権限の継承](#権限の継承)におけるその最下層の上位権限）のみを選択します。例えば、クライアントのプロビジョニングと更新のみを必要とするワークロードは `create_client` を有する必要があります。この単一の権限により、暗黙的に `use_service`、`modify_client`、`view_service`、および `view_client` が付与されます。 Authorization Server プリセットによって適用される `use_service` 権限は、標準的な認可サーバー（Authorization Server）の運用に必要なランタイムの OAuth/OIDC エンドポイントへのアクセスを許可しますが、`/client/create` や `/client/delete` の実行権限は付与しません。クライアントの登録や削除が必要なワークロード（例：テスト用クライアントをプロビジョニングする CI パイプラインや、開発者向けセルフサービスポータルなど）には、`create_client` または `modify_client` 権限が付与されたトークンを発行するか、Admin Authorization Server プリセット（`modify_service`。これがデフォルトで選択されているプリセットです）を使用する必要があります。 既知の問題: 現状、イントロスペクションエンドポイント（`/auth/introspection` および `/auth/introspection/standard`）はトークンに明示的な `use_introspection` 権限を要求します。`modify_service` および `create_client` 権限は `use_introspection` を暗黙的には付与しません（基盤となる `AccessRight` enum の継承は直接的であり、推移的ではありません）。そのため、Admin Authorization Server プリセットで発行されたトークン、または `modify_service` や `create_client` のみを保持するカスタムトークンでは、`/auth/introspection` 呼び出しは HTTP `403` / `A457101` で失敗します。 回避策: イントロスペクションを呼び出すトークンは、Custom プリセットで発行し、上位レベルの権限と併せて `use_introspection` を明示的に含めてください。例：`["modify_service", "use_introspection"]` や `["create_client", "use_introspection"]`。この組み合わせで発行されたトークンは、本問題が修正された後も挙動が変わらないため、回避策は前方互換性があります。Authorization Server プリセット（`use_service`）および Resource Server プリセット（`use_introspection`）は本問題の影響を受けません。 #### 一般的な 403 エラーと切り替え先の権限 | `resultMessage` のアクセス権 | エンドポイント | 修正に必要な最小限の権限 | | ---------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------- | | `[CREATE_CLIENT]` | `/client/create`, `/client/get/default` | `create_client` (または `modify_service`) | | `[MODIFY_CLIENT]` | `/client/update`, `/client/delete`, `/client/secret/*`, `/client/authorization/delete`, … | `modify_client` (または `create_client` / `modify_service`) | | `[MODIFY_SERVICE]` | `/service/update`, `/hsk/create`, `/hsk/delete` | `modify_service` | | `[USE_INTROSPECTION]` | `/auth/introspection`, `/auth/introspection/standard` | `use_introspection` (または `use_service`) | | `[VIEW_CLIENT]` | `/client/get`, `/client/get/list`, `/client/granted_scopes/get` | `view_client` (または任意のより上位レベルの権限) | | `[VIEW_SERVICE]` | `/service/get`, `/service/get/list` | `view_service` (または任意のより上位レベルの権限) |
## 一般的なユースケース | ユースケース | 推奨されるプリセット | 重要な権限 | | ---------------------- | -------------------- | ------------------- | | 標準的な認可サーバー | Authorization Server | `use_service` | | リソースサーバー（イントロスペクションのみ） | Resource Server | `use_introspection` | | ユーザーのログアウト / セッション管理 | Custom | `modify_client` | | 動的なクライアントプロビジョニング | Custom | `create_client` | | モニタリング / インベントリダッシュボード | Custom | `view_service` | | クライアント設定の監査 / 設定レビュー | Custom | `view_client` |
## セキュリティのベストプラクティス * **最小権限の原則を適用する。** リソースサーバーには `use_introspection` のみを、また読み取り専用のダッシュボードには `view_service` のみを付与すべきです。`modify_service` は、信頼された管理ツール専用としてください。 * **ワークロードごとに別々のトークンを使用する。** 認可サーバー、リソースサーバー、CI パイプライン間で単一の SAT を共有しないでください。それぞれに、独自の権限セットとローテーション周期を持つ専用のトークンを付与すべきです。 * **有効期限を設定する。** オートメーションに使用されるすべての SAT に有効期限を設定し、シークレットローテーションポリシーの一環として、ローテーションを実施してください。 * **SAT をソース管理にコミットしない。** シークレットマネージャー（AWS Secrets Manager、GCP Secret Manager、HashiCorp Vault、1Password など）に保存し、実行時に注入するようにしてください。 * **速やかにローテーションする。** 漏洩が疑われる場合、担当者が変更した場合、あるいはトークンを使用するワークロードに変更があった場合には、ローテーションを行ってください。
## まとめ サービスアクセストークンは、Authlete API を呼び出す各ランタイムワークロードに対して、スコープが絞られた単一のクレデンシャルを Authlete の運用環境に提供します。プリセットモデルは、標準的な認可サーバー、リソースサーバー、および管理ユースケースを、すぐに利用できる形でカバーします。一方、カスタム権限と継承ルールにより、その他のインテグレーション向けに最小権限のトークンを簡単に発行できます。 詳細については、[お問い合わせフォーム](https://www.authlete.com/contact)よりご連絡ください。 [CONTACT]: https://www.authlete.com/contact [RFC6749-1.1]: https://datatracker.ietf.org/doc/html/rfc6749#section-1.1