IDトークンに追加する「クレーム」の判別

Table of Contents

IDトークンに追加する「クレーム」の判別

はじめに

OpenID Connect (OIDC) では、リライングパーティ（RP）は認証リクエストにおいて、どのようなクレーム （ユーザー属性など）を ID トークンに含めてほしいかを指定できます。

このときの指定方法によっては、どのクレームが RP から要求されているかの判別が、アイデンティティプロバイダー（OpenID Provider; OP）にとって煩雑な処理となる場合があります。

本記事では、Authlete による、この判別処理の代行について説明します。

要求されているクレームの判別

Authlete をバックエンドとして用いている OP では、OIDC 認証リクエストをユーザーエージェント（Web ブラウザ）経由で受け取った場合、そのリクエスト内容を Authlete の  /auth/authorization API に送信します。

Authlete はリクエスト内容を解析し、ID トークンに含めることを RP が期待しているクレームを判別します。クレームには、スコープ（scope）に含まれる ものと、claims パラメーターを用いて個別に指定される ものがあります。Authlete は前者を展開し、後者と統合します。
そして、Authlete が標準的に含めるクレーム（sub など）以外の、OP が明示的に含めるクレーム（email など）を、/auth/authorization API のレスポンスの “claims” として OP に返却します。

OP はその判別結果をもとに、適切な値を準備し、Authlete の /auth/authorization/issue API を用いて、クレームとして ID トークンにセットします。（参考: ID トークンへのクレームの追加 ）

claims-in-id-token_ja
Claims in an authentication request and how Authlete detects them

ショートカットスコープの展開

OpenID Connect Core 1.0 Section 5.4 では、アクセストークンの発行を伴う場合、OP はショートカットスコープ (例: profile) に含まれるクレームを ID トークンに含めてはならないと制限されています。

Authlete サービスの既定では、同条項に従います。つまり、response_type が id_token 以外 (例: code) の場合には、/auth/authorization API レスポンスの “claims” にショートカットスコープ由来のクレームを含めません。その結果、OP は、それらのクレームを ID トークンとしてセットしないことになります。

この設定は Authlete サービスの「クレームショートカット」によって変更可能です。選択肢は以下です。

  • 制限的 : 同条項に厳密に準拠し、上記の通り動作します。（既定値）
  • 非制限的 : アクセストークンを発行するかどうかに関わらず、ショートカットスコープ由来のクレームを “claims” に含めます。OP は、それらのクレームを ID トークンとしてセットするかどうかを判断することになります。
Screen_Shot_2022-05-23_at_4
Claim Shortcut

実行例

たとえば RP が、以下のスコープならびにクレームを要求したとします。

  • スコープ (openid 以外):

    • profile

  • ID トークンに含めてほしいクレーム:

    • http://example.info/claims/category
    • email_verified

この場合、認証リクエストのクエリストリングは以下のようになります。（見やすさのために折り返しています）

redirect_uri=...
&response_type=code
&client_id=...
&nonce=...
&scope=openid+profile
&claims=%7b%22id\_token%22%3a %7b%22http%3a%2f%2fexample%2einfo%2fclaims%2fcategory%22%3a null%2c
%22email\_verified%22%3a null%7d%7d

上述の「クレームショートカット」の設定が「非制限的」である場合、この値を “parameters” に含めたリクエストを Authlete の /auth/authorization API に送信すると、以下の “claims” を含むレスポンスが返却されます。“profile” スコープが意味するクレームも含まれていることに注目してください。（読みやすいように改行しています）


"claims": [
    "birthdate",
    "email_verified",
    "family_name",
    "gender",
    "given_name",
    "http://example.info/claims/category",
    "locale",
    "middle_name",
    "name",
    "nickname",
    "picture",
    "preferred_username",
    "profile",
    "updated_at",
    "website",
    "zoneinfo"
]

“http://example.info/claims/category" のような、標準ではないクレームは、あらかじめサービスの「サポートするクレーム」に追加しておく必要があります。

claims-in-id-token_2
> Supported Claims >

ここで、この “claims” に含まれるのは、 続く /auth/authorization/issue API へのリクエストの際に、明示的に “claims” パラメーターに指定されることが期待されているクレームのみです。

たとえば sub  は、IDトークンに必ず含まれる値（/auth/authorization/issue リクエストの必須の引数である “subject” パラメーターの値から、Authlete が生成し sub に格納する値）です。言い換えれば、/auth/authorization/issue の claims にて指定するものではありません。そのため、/auth/authorization のレスポンスの “claims” には入りません。