Table of Contents

Authlete 以外のシステムが発行したアクセストークンの移行

はじめに

既存の認可サーバーシステム（旧システム）を Authlete に移行する場合、旧システムが過去に発行したアクセストークンをどのように取り扱うかを検討する必要があります。

もしリソースサーバーが、旧システムが発行したか、Authlete が発行したかによらず、クライアントから受け取ったアクセストークンの検証（イントロスペクション）を全て Authlete に依頼するのであれば、Authlete は旧システムのアクセストークンの情報も管理しなくてはなりません。

本記事では、Authlete 以外が発行したアクセストークン情報を Authlete に移行する方法を紹介します。

移行方法

Authlete のトークン管理 API のひとつである /auth/token/create API を用います。この API によって認可サーバーは、クライアントからの認可リクエストやトークンリクエストなしに、任意のトークンを Authlete に生成・格納させることが可能となります。API の引数は以下をご参照ください。

/auth/token/create API

この引数の中でも、オプショナルパラメーターのひとつである accessToken にご注目ください。このパラメーターに文字列が指定されている場合、Authlete はそれをアクセストークンの値として用います（Authlete の内部的には、この値のハッシュ値をデータベースに保存します）。

つまり、この API を用いてトークンを生成する際に、旧システムの発行したアクセストークンの値を accessToken の引数とすることにより、トークンの移行が行えることになります。

実行例

トークン生成

発行済みのトークン情報を用いて /auth/token/create API を呼び出し、Authlete のトークンデータベースに同一の値のトークンを生成します。（見やすさのために折り返しています）

リクエスト

curl -s -X POST .../auth/token/create  \
  -u ...:... \
  -H 'Content-type: application/json' \
  -d '{"grantType":"AUTHORIZATION_CODE", \
       "clientId":"...", \
       "subject":"john", \
       "accessToken":"existingAccessTokenValue
", \
       "accessTokenDuration":3600, \
       "refreshToken":"existingRefreshTokenValue
", \
       "refreshTokenDuration":86400, \
       "properties":[ \
          { \
            "hidden":true, \
            "key":"amount", \
            "value":"100" \
          } \
        ], \
       "scopes":["openid","payment"]}'

レスポンス

{
   "type": "tokenCreateResponse",
   "resultCode": "A109001",
   "resultMessage": "[A109001] An access token was created successfully: authorization_code, client = 17201083166161",
   "accessToken": "existingAccessTokenValue
",
   "action": "OK",
   "clientId": 17201083166161,
   "expiresAt": 1594020768318,
   "expiresIn": 3600,
   "grantType": "AUTHORIZATION_CODE",
   "properties": [
      {
         "hidden": true,
         "key": "amount",
         "value": "100"
      }
   ],
   "refreshToken": "existingRefreshTokenValue
",
   "scopes": [
      "openid",
      "payment"
   ],
   "subject": "john",
   "tokenType": "Bearer"
}

イントロスペクション

「発行済みのアクセストークン」を含む API リクエストを受け取ったリソースサーバーは、そのトークンの有効性の確認と関連情報の取得を行います。以下は Authlete の /auth/introspection API を用いて確認・取得する例です。（見やすさのために折り返しています）

JWT 形式のアクセストークンを用いる場合には、リソースサーバーがそのトークンの検証を行い、含まれている情報を抽出します。

リクエスト

curl -s -X POST \
.../auth/introspection \
-u ...:... \
-H 'Content-type: application/json' \
-d '{"token":"existingAccessTokenValue
"}'

レスポンス

{
    "type": "introspectionResponse",
    "resultCode": "A056001",
    "resultMessage": "[A056001] The access token is valid.",
    "action": "OK",
    "clientId": 17201083166161,
    "clientIdAliasUsed": false,
    "existent": true,
    "expiresAt": 1594020768000,
    "properties": [
        {
            "hidden": true,
            "key": "amount",
            "value": "100"
        }
    ],
    "refreshable": true,
    "responseContent": "Bearer error=\"invalid_request\"",
    "scopes": [
        "openid",
        "payment"
    ],
    "subject": "john",
    "sufficient": true,
    "usable": true
}

トークンの更新

「発行済みのリフレッシュトークン」を用いたトークン更新リクエストを受け取った認可サーバーは、Authlete の /auth/token API を呼び出してそのトークンリクエストを処理します。（見やすさのために折り返しています）

リクエスト

curl -s -X POST $AL_API/auth/token \
-u $AL_SVC \
-H 'Content-type: application/json' \
-d '{
  "clientId": "...",
  "clientSecret": "...",
  "parameters": "grant_type=refresh_token
  &refresh_token=existingRefreshTokenValue
"
}'

レスポンス

{
    "type": "tokenResponse",
    "resultCode": "A053001",
    "resultMessage": "[A053001] The token request (grant_type=refresh_token) was processed successfully.",
    "accessToken": "a4utoeZ-R3WwpbD2q-HbNBlEkie2GZZyrdAmmoeuKd0",
    "accessTokenDuration": 300,
    "accessTokenExpiresAt": 1594018713161,
    "action": "OK",
    "clientId": 17201083166161,
    "clientIdAliasUsed": false,
    "grantType": "REFRESH_TOKEN",
    "properties": [
        {
            "hidden": true,
            "key": "amount",
            "value": "100"
        }
    ],
    "refreshToken": "9JhH1r5-Q54-XApNhGmSS_dxwwUp_SjjoaX81gev_po",
    "refreshTokenDuration": 900,
    "refreshTokenExpiresAt": 1594019313161,
    "responseContent": "{\"access_token\":\"a4utoeZ-R3WwpbD2q-HbNBlEkie2GZZyrdAmmoeuKd0\", \"refresh_token\":\"9JhH1r5-Q54-XApNhGmSS_dxwwUp_SjjoaX81gev_po\", \"scope\":\"openid payment\", \"token_type\":\"Bearer\", \"expires_in\":300}",
    "scopes": [
        "openid",
        "payment"
    ],
    "subject": "john"
}

大量のアクセストークンを移行する場合

大量に存在するアクセストークンの移行に際しては、旧システムからダンプしたアクセストークン情報を Authlete のトークン形式に変換し、Authlete のトークンデータベースに投入する方法が適している場合があります。詳細は弊社サポートにお問い合わせください。

参考情報

OAuth 2.0 / OIDC 実装の新アーキテクチャー
- 7.2.1. /api/auth/token/create API

パラメーター名: accessToken
要否: 任意
説明: 通常、アクセストークンの値は Authlete が自動生成するが（256 ビットのランダム値を base64url で表現したもので 43 文字）、他のシステムで過去に発行されたアクセストークンをそのまま利用したい場合等、アクセストークンの値を指定したい場合にこのリクエストパラメーターを用いる。 Authlete のデータベースはアクセストークンの値そのものは保存せず、ハッシュ値を保存しているので、アクセストークンの値がなんであれ、データベース上は固定長となる。そのため、このリクエストパラメーターに指定するアクセストークンの値の自由度は高いが、そのかわりに、アクセストークンの値が重複しないよう API 呼び出し側で配慮する必要がある（同じアクセストークンの値が来た場合は Authlete 側で拒否はする）。