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

パーソナルアクセストークン (Personal access token)

パーソナルアクセストークン (PAT) は、ユーザーが認証情報やインタラクティブなサインインを使用せずに アクセス トークン (Access token) を付与するための安全な方法を提供します。これは、CI / CD、スクリプト、またはリソースへプログラム的にアクセスする必要があるアプリケーションに便利です。

パーソナルアクセストークンの管理

コンソールを使用する場合

コンソール > ユーザー管理 のユーザー詳細ページでパーソナルアクセストークンを管理できます。「認証 (Authentication)」カードで、パーソナルアクセストークンの一覧を確認したり、新規作成したりできます。

Management API を使用する場合

Management API をセットアップした後、API エンドポイント を利用してパーソナルアクセストークンの作成、一覧表示、削除が可能です。

PAT を使ってアクセス トークン (Access token) を付与する

PAT を作成した後、トークンエクスチェンジエンドポイントを利用してアプリケーションにアクセス トークン (Access token) を付与できます。

リクエスト

アプリケーションは、HTTP POST メソッドを使用して、テナントの トークンエンドポイント に特別なグラントタイプで トークンエクスチェンジリクエスト を送信します。HTTP リクエストのエンティティボディには application/x-www-form-urlencoded 形式で次のパラメータが含まれます。

  1. client_id: 必須。アプリケーションのクライアント ID。
  2. grant_type: 必須。このパラメータの値は urn:ietf:params:oauth:grant-type:token-exchange で、トークンエクスチェンジが実行されていることを示します。
  3. resource: 任意。リソースインジケーター。他のトークンリクエストと同様です。
  4. scope: 任意。リクエストされたスコープ。他のトークンリクエストと同様です。
  5. subject_token: 必須。ユーザーの PAT。
  6. subject_token_type: 必須。subject_token パラメータで提供されるセキュリティトークンのタイプ。このパラメータの値は urn:logto:token-type:personal_access_token でなければなりません。

レスポンス

トークンエクスチェンジリクエストが成功すると、テナントのトークンエンドポイントはユーザーのアイデンティティを表すアクセス トークン (Access token) を返します。レスポンスには、HTTP レスポンスのエンティティボディに application/json 形式で次のパラメータが含まれます。

  1. access_token: 必須。ユーザーのアクセス トークン (Access token)。authorization_coderefresh_token など他のトークンリクエストと同様です。
  2. issued_token_type: 必須。発行されたトークンのタイプ。このパラメータの値は urn:ietf:params:oauth:token-type:access_token でなければなりません。
  3. token_type: 必須。トークンのタイプ。このパラメータの値は Bearer でなければなりません。
  4. expires_in: 必須。アクセス トークン (Access token) の有効期間(秒単位)。
  5. scope: 任意。アクセス トークン (Access token) のスコープ。

トークンエクスチェンジの例

POST /oidc/token HTTP/1.1
Host: tenant.logto.app
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client-id:client-secret)>

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
&scope=profile
&subject_token=pat_W51arOqe7nynW75nWhvYogyc
&subject_token_type=urn%3Alogto%3Atoken-type%3Apersonal_access_token
HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token": "eyJhbGci...zg",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "profile"
}

アクセス トークン (Access token) のペイロード例:

{
"jti": "iFtbZBeh2M1cTTBuKbHk4",
"sub": "123",
"iss": "https://tenant.logto.app/oidc",
"exp": 1672531200,
"iat": 1672527600,
"scope": "profile",
"client_id": "client-id"
}

パーソナルアクセストークンとは?どのような場合にパーソナルアクセストークンを使うべきか?

パーソナルアクセストークン、マシン間通信 (Machine-to-Machine) 認証 (Authentication)、API キーの定義と実際の利用シナリオ