サービスアクセストークン

Table of Contents

はじめに

本記事では、Authlete のサービスアクセストークン (Service Access Token、以下 SAT) について説明します。

SAT は、単一の Authlete サービスに対して発行されるベアラークレデンシャル（bearer credential）です。これは、認可サーバー、リソースサーバー、CLI スクリプト、または CI/CD パイプラインが、Authlete のランタイム API やサービス管理 API を呼び出す際に提示するクレデンシャルです。

プリセットの利用、または個別の権限選択によって権限をカスタマイズすることで、呼び出し元が必要とするものだけにトークンのスコープを正確に絞り込むことができます。これにより、リソースサーバーにはイントロスペクション権限のみ付与、管理ツールには必要なクライアント管理権限のみ付与、といったことが可能になります。

トークンのプロパティ

トークン名

サービスアクセストークン一覧でトークンを区別するために使用される、人間が読める形式の識別子です。この名前は、トークンの動作や権限には影響しません。

有効期限

トークンの有効期限が切れ、無効になる日時を指定します。

設定した場合、指定された日時以降はそのトークンを使用できません。
設定しない場合、トークンの有効期限は切れません。

自動化で使用されるトークンについては、明示的に有効期限を設定することを強く推奨します。コンソール上では、1ヶ月以内に有効期限が切れるトークンは赤色で表示されます。

トークンの値

トークンの値は、トークンが作成またはローテーションされた際に一度だけ表示されます。

作成時にコピーし、セキュアに保存する必要があります。
以降、このトークンの値を再度取得することはできません。

ローテーション

トークンをローテーションして、新しい値を生成することができます。

ローテーションを行うと、以前のトークン値は即座に無効になります。
新しいトークン値は一回しか表示されないため、コピーして保存する必要があります。
明示的に更新されない限り、権限やメタデータ（名前、有効期限）はローテーション後も保持されます。

トークン一覧

すべてのサービスアクセストークンはテーブルに一覧表示されます。テーブルには以下のカラムが含まれます。

トークン名 (Token Name): ユーザーが定義した識別子。
権限 (Permissions): トークンに割り当てられた権限。
作成日 (Created): トークンが作成された日付。
有効期限 (Expires): 有効期限。設定されていない場合は無期限。
アクション (Actions): 利用可能な操作（ローテーションや削除など）。

権限プリセット

標準的な OAuth 2.0 のロールに合わせた、事前設定された権限セットです。プリセットを選択すると、固定の権限の組み合わせが適用されます。その後、手動で権限を追加または削除すると、プリセットの選択は解除されます。

プリセット	説明	権限
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 エラーのトラブルシューティング](#troubleshooting)を参照してください。

権限の継承

上位レベルの権限は、依存する下位レベルの権限を暗黙的に付与します。継承の連鎖は以下の通りです：

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 を呼び出す例です。

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 を呼び出す例です。

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` を設定）できます。

レスポンスボディの形式は以下の通りです。

{
  "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つです：

該当の操作をカバーするプリセットでトークンを再作成する。 クライアント管理の呼び出しの場合、Admin Authorization Server プリセット (modify_service) が、すべてのクライアント管理およびサービス管理のエンドポイントをカバーします。
カスタム権限でトークンを再作成する。 エラーメッセージで指定されたアクセス権（または権限の継承におけるその最下層の上位権限）のみを選択します。例えば、クライアントのプロビジョニングと更新のみを必要とするワークロードは 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 の運用環境に提供します。プリセットモデルは、標準的な認可サーバー、リソースサーバー、および管理ユースケースを、すぐに利用できる形でカバーします。一方、カスタム権限と継承ルールにより、その他のインテグレーション向けに最小権限のトークンを簡単に発行できます。

詳細については、お問い合わせフォームよりご連絡ください。