UserInfo API レスポンスにおけるクレームの追加

はじめに

UserInfo API が応答するクレームは ID トークンに任意のクレームを追加する方法と同様に、claims パラメータを利用することでカスタマイズできます。この記事では、UserInfo エンドポイントのレスポンスに任意のクレームを追加する方法と、クレームの決定に役立つ Authlete の機能について解説します。

基本的な UserInfo エンドポイントの実装

OpenID プロバイダーが Authlete を利用し UserInfo API エンドポイントを実装する場合、以下の 2 つの API を呼び出す必要があります。

Process UserInfo Request /api/{serviceId}/auth/userinfo
Issue UserInfo Response /api/{serviceId}/auth/userinfo/issue

Authlete の Process UserInfo Request エンドポイントは提示されたアクセストークンを検証し、トークンに紐づくユーザーの情報を応答します。その応答をもとに、OpenID プロバイダーはトークンの有効性および紐づいたユーザーを確認し、対象ユーザーの属性をデータストアから収集し、Issue UserInfo Response API に提示します。以下に例を示します。

Process UserInfo Request API

まず OpenID プロバイダーは、リライングパーティが提示したアクセストークンを、Authlete の Process UserInfo Request API に送信します。

curl --request POST \
  --url https://jp.authlete.com/api/{{serviceId}}/auth/userinfo \
  --header 'authorization: Bearer {{serviceAccessToken}}' \
  --header 'content-type: application/json' \
  --data '{"token": "{{accessToken}}"}'

アクセストークンが有効な場合の応答例は以下の通りです。

{
  "action": "OK",
  "clientId": 2064424232,
  "subject": "john",
  "scopes": [
    "openid",
    "email"
  ],
  "claims": [
    "email",
    "email_verified"
  ],
  "token": "{{accessToken}}",
  "clientIdAlias": "2064424232",
  "clientIdAliasUsed": true,
  "consentedClaims": [
    "email",
    "email_verified"
  ],
  "clientEntityIdUsed": false,
  "resultCode": "A091001",
  "resultMessage": "[A091001] The access token presented at the userinfo endpoint is valid."
}

この例では、action が OK であり、トークンが有効であることが示されています。さらに subject が john であると判別できます。この結果をもとに OpenID プロバイダーは john に紐づく属性を収集し、Issue UserInfo Response に提示することになります。

Issue UserInfo Response API

Authlete はユーザーに紐づく属性の値は保持しません。よって、UserInfo レスポンスに含める属性の値は OpenID プロバイダーが用意する必要があります。OpenID プロバイダーは、UserInfo レスポンスに含める属性を決定するために、Authlete から返却される claims パラメータを利用できます。 Process UserInfo Request API の応答に含まれる claims パラメータは、IDトークンに追加する「クレーム」の判別と同様に、/auth/authorization エンドポイントに提示された parameters 内のスコープ（scope）に対応するクレームと、claims パラメーターを用いて個別に指定されるクレームがマージされたリストです。上記の例では scope に openid email が含まれています。そのため、email スコープが展開され email, email_verified が含めるべきクレームとして claims 応答に含まれます。スコープとそれに対応するクレームの一覧は Authlete Java Common の Javadoc ClaimsScope をご確認ください。ここでは Authlete からの応答 claims に以下の項目が含まれているとします。

項目	値
”email"	"john@example.com"
"email_verified”	true

上記のクレームを追加する場合の、OpenID プロバイダーから Authlete への API リクエストは、以下のようになります。(読みやすさのため折り返しています)

curl --request POST \
  --url https://jp.authlete.com/api/{{serviceId}}/auth/userinfo/issue \
  --header 'authorization: Bearer {{serviceAccessToken}}' \
  --header 'content-type: application/json' \
  --data '{"token": "{{accessToken}}",
    "claims": "{
      \"email\": \"john@example.com\",
      \"email_verified\": true}" }'

正常な応答は以下の通りです。responseContent の値（UserInfo レスポンス）に、指定したクレームが追加されていることが確認できます。

{
  "action": "JSON",
  "responseContent": "{\"sub\":\"john\",\"email\":\"john@example.com\",\"email_verified\":true}",
  "resultCode": "A096001",
  "resultMessage": "[A096001] User information was obtained successfully."
}

含めるべきクレームのカスタマイズ

Authlete が自動で計算する claims は OpenID Connect Core の仕様に則したものですが、実際の運用環境には適さない場合があります。例えば、以下のような要件があるでしょう。

ID トークンに含めるクレームと異なるクレームを、UserInfo レスポンスに含めたい
scope は openid, email のみを指定するが、ユーザーの同意内容に基づいて追加のクレームを UserInfo レスポンスに含めたい

この場合、Authlete の consentedClaims を利用し、ユーザーが認可エンドポイントで RP に公開することを許可したクレームを、Introspection エンドポイントや UserInfo エンドポイントに伝達することが可能です。

consentedClaims は Authlete 2.3 以降で利用できます。 consentedClaims の詳細は Authlete Java Doc AuthorizationIssueRequest.html#setConsentedClaims() を確認ください。

ユーザーが提供に同意したクレームを Authlete に伝える

例えば、ユーザーが認可フローにおいて「氏名」「ユーザー名」「メールアドレス」を RP に伝えることに同意し、 OpenID プロバイダーがそれらの情報を UserInfo レスポンスに含める、といった実装を考えます。認可エンドポイントは以下のようなリクエストを Authlete の Process Authorization Request API に送信します。

curl --request POST \
  --url https://jp.authlete.com/api/{{serviceId}}/auth/authorization \
  --header 'authorization: Bearer {{serviceAccessToken}}' \
  --header 'content-type: application/json' \
  --data '{"parameters": "client_id=rest-client-client&scope=openid%20email&response_type=code&redirect_uri=https://example.com&state=xyz&nonce=12345"}'

応答例 (一部省略)

{
  "action": "INTERACTION",
  "service": {
  },
  "client": {
  },
  "display": "PAGE",
  "maxAge": 0,
  "scopes": [
    {
      "name": "email",
      "defaultEntry": false,
      "description": "A permission to request an OpenID Provider to include the email claim and the email_verified claim in an ID Token. See OpenID Connect Core 1.0, 5.4. for details."
    },
    {
      "name": "openid",
      "defaultEntry": false,
      "description": "A permission to request an OpenID Provider to issue an ID Token. See OpenID Connect Core 1.0, 3.1.2.1. for details."
    }
  ],
  "ticket": "IWjy7qiCFJsHYHBKAfwJNLHfoV86lL7KYC0ojmi-Qrk",
  "resultCode": "A004001",
  "resultMessage": "[A004001] Authlete has successfully issued a ticket to the service (API Key = 666990377) for the authorization request from the client (ID = 1110197986). [response_type=code, openid=true]"
}

OpenID プロバイダーは、氏名とユーザー名、メールアドレスを対象のクライアントに提供するための同意を得たのち、Issue Authorization Response API を呼び出します。この際に consentedClaims として name, username, email, email_verified を指定します。

curl --request POST \
  --url https://jp.authlete.com/api/{{serviceId}}/auth/authorization/issue \
  --header 'authorization: Bearer {{serviceAccessToken}}' \
  --header 'content-type: application/json' \
  --data '{
    "ticket": "{{ticket}}",
    "subject": "john",
    "claims": "{\"claim_for_id_token\":\"value_for_id_token\"}",
    "consentedClaims": ["name", "username", "email", "email_verified"]
}'

Authlete 指定された consentedClaims をデータベースに保存し、Process UserInfo Request API や Process Introspection Request API の応答に含めます。

ここで consentedClaims に指定するクレームはあらかじめ対象サービスの トークン&クレーム > クレーム > サポート可能なクレーム に追加しておく必要がある点に注意してください。

ユーザーが提供に同意したクレームを UserInfo レスポンスの応答に含める

先ほどの認可リクエストに紐づくトークンを、Process UserInfo Request API に送信すると、以下のような応答が得られます。

curl --request POST \
  --url https://jp.authlete.com/api/{{serviceId}}/auth/userinfo \
  --header 'authorization: Bearer {{serviceAccessToken}}' \
  --header 'content-type: application/json' \
  --data '{"token": "{{accessToken}}"}'

{
  "action": "OK",
  "clientId": 1110197986,
  "subject": "john",
  "scopes": [
    "email",
    "openid"
  ],
  "claims": [
    "email",
    "email_verified"
  ],
  "token": "ytaniPwocUVRSDuCBn6EEIR7SYYRxIHkmvv2ht7oPLU",
  "clientIdAlias": "rest-client-client",
  "clientIdAliasUsed": true,
  "clientEntityIdUsed": false,
  "consentedClaims": [
    "name",
    "username",
    "email",
    "email_verified"
  ],
  "resultCode": "A091001",
  "resultMessage": "[A091001] The access token presented at the userinfo endpoint is valid."
}

OpenID プロバイダーは claims 応答の代わりに、consentedClaims 応答を参照し、ユーザーが提供に同意したクレームを UserInfo レスポンスとして返却することが可能となります。

curl --request POST \
  --url https://jp.authlete.com/api/{{serviceId}}/auth/userinfo/issue \
  --header 'authorization: Bearer {{serviceAccessToken}}' \
  --header 'content-type: application/json' \
  --data '{"token": "{{accessToken}}",
    "claims": "{
      \"name\": \"John Doe\",
      \"username\": \"jdoe\",
      \"email\": \"john@example.com\",
      \"email_verified\": true}" }'

上記リクエストの結果、Issue UserInfo Response API は、以下のようにユーザーが提供に同意した「氏名」「ユーザー名」「メールアドレス」を含む UserInfo レスポンスを、responseContent の値として返却します。

{
  "action": "JSON",
  "responseContent": "{\"sub\":\"john\",\"name\":\"John Doe\",\"email\":\"john@example.com\",\"email_verified\":true,\"username\":\"jdoe\"}",
  "resultCode": "A096001",
  "resultMessage": "[A096001] User information was obtained successfully."
}

エンドポイント

トークン & クレーム

鍵管理

メタデータ

エラー処理とデバッグ

セキュリティ

クライアント管理

サービス設定

UserInfo API レスポンスにおけるクレームの追加

はじめに

基本的な UserInfo エンドポイントの実装

Process UserInfo Request API

Issue UserInfo Response API

含めるべきクレームのカスタマイズ

ユーザーが提供に同意したクレームを Authlete に伝える

ユーザーが提供に同意したクレームを UserInfo レスポンスの応答に含める

​はじめに

​基本的な UserInfo エンドポイントの実装

​Process UserInfo Request API

​Issue UserInfo Response API

​含めるべきクレームのカスタマイズ

​ユーザーが提供に同意したクレームを Authlete に伝える

​ユーザーが提供に同意したクレームを UserInfo レスポンスの応答に含める

はじめに

基本的な UserInfo エンドポイントの実装

Process UserInfo Request API

Issue UserInfo Response API

含めるべきクレームのカスタマイズ

ユーザーが提供に同意したクレームを Authlete に伝える

ユーザーが提供に同意したクレームを UserInfo レスポンスの応答に含める