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 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 トークンとしてセットするかどうかを判断することになります。

実行例


たとえば 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%20null%2c
   %22email_verified%22%3a%20null%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"
  ],


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

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