セキュリティトークンサービスにおけるセキュリティトークン交換リクエスト仕様に関するメモ
次のようなAPI Gateway経由でバックエンドのAPIを呼び出す場合、クライアントがAPI Gatewayにアクセスする際に使用するトークンを再利用せず、API Gateway - API通信用のトークンを発行する際に利用する。
- セキュリティトークン
  - 異種環境またはセキュリティドメイン間でのIDおよびセキュリティ情報の共有を目的とした情報
  - 例:JSON Web Tokens（JWT）、Security Assertion Markup Language（SAML）2.0アサーション
- セキュリティトークンサービス（STS）
  - 提供されたセキュリティトークンを検証し、それに応じて新しいセキュリティトークンを発行するサービス

Token Exchange Request and Response

拡張グラントタイプを指定してトークンエンドポイントにリクエストを行うことでセキュリティトークンを取得する。
リクエスト例

POST /as/token.oauth2 HTTP/1.1
Host: as.example.com
Authorization: Basic cnMwODpsb25nLXNlY3VyZS1yYW5kb20tc2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange &resource=https%3A%2F%2Fbackend.example.com%2Fapi
&subject_token=accVkjcJyb4BWCxGsndESCJQbdFMogUC5PbRDqceLTC
&subject_token_type= urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token

grant_type : 必須。urn:ietf:params:oauth:grant-type:token-exchangeは、トークン交換を意味する。
resource : 任意。クライアントがセキュリティトークンを使用するターゲットサービスまたはリソースを示すURI。
requested_token_type : セキュリティトークンの識別子。
subject_token : 必須。要求元の認可を示すセキュリティトークン。アクセストークンなど。
subject_token_type : 必須。subject_tokenパラメータのセキュリティトークンのタイプを示す識別子。

※その他にも任意パラメータあり。

成功した場合、200応答が返却される。

レスポンス例

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store
 
{
　"access_token":"eyJhbGciOiJFUzI1NiIsImtpZCI6IjllciJ9.eyJhdWQiOiJodHRwczovL2JhY2tlbmQuZXhhbXBsZS5jb20iLCJpc3MiOiJodHRwczovL2FzLmV4YW1wbGUuY29tIiwiZXhwIjoxNDQxOTE3NTkzLCJpYXQiOjE0NDE5MTc1MzMsInN1YiI6ImJkY0BleGFtcGxlLmNvbSIsInNjb3BlIjoiYXBpIn0.40y3ZgQedw6rxf59WlwHDD9jryFOr0_Wh3CGozQBihNBhnXEQgU85AI9x3KmsPottVMLPIWvmDCMy5-kdXjwhw",
　"issued_token_type":"urn:ietf:params:oauth:token-type:access_token",
　"token_type":"Bearer",
　"expires_in":60
}

access_token : トークン交換リクエストで発行されたアクセストークン。
issued_token_type : トークン種別。
token_type : 発行されたアクセストークンの使用方法を指定する。Bearerはクライアントがトークン自体の内容以外の追加証明なしに、そのまま提示できることを意味する。
expires_in : 有効期間。秒単位。

Token Type Identifiers

トークン種別の識別子は次のものあg定義されている。
- urn:ietf:params:oauth:token-type:access_token : トークンが、指定された認可サーバーによって発行されたOAuth 2.0アクセストークンであることを示す。
- urn:ietf:params:oauth:token-type:refresh_tokenトークンが、指定された認可サーバーによって発行されたOAuth 2.0リフレッシュトークンであることを示す。
- urn:ietf:params:oauth:token-type:id_token : トークンがIDトークンであることを示す。
- urn:ietf:params:oauth:token-type:saml1 : トークンがbase64urlでエンコードされたSAML 1.1 アサーションであることを示す。
- urn:ietf:params:oauth:token-type:saml2 : トークンがbase64urlでエンコードされたSAML 2.0アサーションであることを示す。
- urn:ietf:params:oauth:token-type:jwt : トークンがJWTであることを示す。

JSON Web Token Claims and Introspection Response Parameters

scope (Scopes) クレーム

トークンに関連付けられたスコープのスペース区切りのリストからなるJSON文字列

    {
      "aud":"https://consumer.example.com",
      "iss":"https://issuer.example.com",
      "exp":1443904177,
      "nbf":1443904077,
      "sub":"dgaf4mvfs75Fci_FL3heQA",
      "scope":"email profile phone address"
    }

client_id(Client Identifier)クレーム

トークンを要求したOAuth 2.0 クライアントのクライアント識別子

{
      "aud":"https://consumer.example.com",
      "iss":"https://issuer.example.com",
      "exp":1443904177,
      "sub":"user@example.com",
      "client_id":"s6BhdRkqt3"
}

may_act(Authorized Actor)クレーム
- ある主体がactorとなり、別の主体に代わって処理することを許可されていることを表す。
- 次の例では、トークン自体のクレームはuser@example.comに関するものであるが、may_actクレームは、admin @ example.comがuser@example.comに代わって処理することを許可されていることを示す。
```
{
      "aud":"https://consumer.example.com",
      "iss":"https://issuer.example.com",
      "exp":1443904177,
      "nbf":1443904077,
      "sub":"user@example.com",
      "may_act":
      {
        "sub":"admin@example.com"
      }
}
```

参考情報