Zenn
Open4

RFC 7521 Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants

OAuth
OIDC
yapooyapoo

RFC 7521 - Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants

概要

RFC 6749 (The OAuth 2.0 Authorization Framework) では複数の認可グラントが定義されている。クライアントはトークンエンドポイントへのリクエストに認可グラントの種別 (grant_type: authorization_code など) と各認可グラントで定められた情報 (認可コードなど) を含め、その引き換えにアクセストークンを得る。

本仕様は RFC 6749 の拡張として「アサーション」を認可グラントとして用いる方法を定義している。この方法ではトークンエンドポイントのリクエストにアサーションを含めることによって、アクセストークンを得ることができる。また、アサーションをトークンエンドポイントでのクライアント認証として用いる方法も定義されている。

アサーション

本仕様におけるアサーションは、クライアントやリソースオーナーなどに関する情報のまとまりであって、デジタル署名などにより発行者の認証と内容の完全性の検証を行えるものを指す。アサーションは加えて発行者に関する情報や、そのアサーションがどのような場合に有効であるとみなされるか (有効期限や受信者) に関する情報も必要になる。

アサーションはクライアントが自ら発行する場合と、認可サーバーが信頼する第三者機関からクライアントに発行される場合とがあるが、具体的な発行のための手続きは本仕様では示されない。

アサーションの形式として典型的なものに JWT がある。JWT は発行者の秘密鍵によって署名されており、ペイロード部分にクライアントに関する情報 (client_id など) を含めることができるほか、exp や nbf などで有効期限を明示し、aud で受信者を限定することができる。

yapooyapoo

アサーションの利用方法

本仕様の Section 4 では OAuth 2.0 のトークンエンドポイントにおけるアサーションの利用方法として下記の 2 つが記載されている。

  • 認可グラントとしての利用
  • クライアント認証としての利用

認可グラントとしての利用

クライアントはトークンエンドポイントにおいて認可サーバーに対してアサーションを提示する。認可サーバーはアサーションを検証しクライアントにアクセストークンを返却する。

以下は Section 4.1 に記載のリクエストの例である。

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&
assertion=PHNhbWxwOl...[omitted for brevity]...ZT4
  • grant_type は認可サーバーが定義する文字列
  • assertion はアサーション
  • 任意パラメータで scope を指定することもできる。(クライアント登録の時点などで) クライアントは自らが指定可能な scope の範囲を知っているので、その範囲内で指定する

この利用方法において、アサーションは (認可コードのように?) 短命なものであり、アクセストークンの有効期限もアサーションの有効期限を大幅に超えるべきではない (SHOULD NOT) とされている。また通常リフレッシュトークンも発行されず、RP はアクセストークンを再発行したときは (まだ有効な) 同じアサーションを再提示するか、新たなアサーションを用意して提示する必要がある。

認可サーバーはアサーションの検証に失敗した場合にはエラーを返却する。トークンエンドポイントのエラーレスポンスは RFC 6749 の Section 5.2 で定義されており、ここでのエラーもそれに沿ったものになるが、パラメータ error の値は invalid_grant でなければならないという指定がある。

以下は Section 4.1.1 に記載されているエラーレスポンスの例である。

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
  "error":"invalid_grant",
  "error_description":"Audience validation failed"
}

クライアント認証としての利用

RFC 6749 の Section 3.2.1 では (コンフィデンシャルクライアントの場合などに) トークンエンドポイントでクライアント認証を行う必要があるとされているが、その具体的な方法については同仕様の Section 2.3 ではベーシック認証しか示されていなかった。本仕様では別の認証方法が定義されている。

以下は Section 4.1 に記載のリクエストの例である。

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth
%3Aclient-assertion-type%3Asaml2-bearer&
client_assertion=PHNhbW...[omitted for brevity]...ZT
  • 認可コードフローの場合が例示されているので grant_type は authorization_code が指定されている
  • code は認可コード
  • client_assertion_type は本仕様で定義される必須パラメータで、認可サーバーが定義する、アサーションのフォーマットを示す文字列
  • client_assertion も本使用で定義される必須パラメータで、アサーションを指定する
  • client_id も指定可能。これは client_assertion に含まれる情報なので不必要だが、もし指定する場合は client_assertion から特定されるクライアントと同一のクライアントでなければならない

認可サーバーは認可グラントの場合と同様、アサーションの検証に失敗した場合はエラーを返却する。ここでレスポンスのパラメータ error は invalid_client となる。

yapooyapoo

アサーションの持つ情報

以上のことから、アサーションは以下の情報を持つ必要がある。

  • 発行者 (必須)
  • 「対象」に関する情報 (必須)
    • 認可グラントとして用いる場合はリソースオーナーの識別子や、匿名ユーザーであることを示すものと認可サーバーと発行者間で合意された文字列 (anonymous など)
    • クライアント認証として用いる場合はクライアントの識別子 (client_id)
  • 受信者 (トークンエンドポイントの URL など)
  • 失効日時 (必須)
  • 発行日時 (任意)
  • アサーションを一意に識別する ID (任意)

アサーションの具体的な形式に関して

これは本仕様では述べられておらず、RFC 7522 (SAML 2.0) や RFC 7523 (JWT) を参照する必要がある。

yapooyapoo

この仕様のユースケースについて

認可グラントとしてはクライアント・クレデンシャルズフローのようにクライアント自身がリソースオーナーの場合などに利用することができそう。

クライアント認証の方法としては、ベーシック認証を選びたくない場合にこちらを選択するイメージだろうか。