RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol

RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol

概要

本仕様では、認可サーバーが提供する OAuth 2.0 のクライアントとして登録するためのエンドポイントである Client Registration Endpoint の仕様と、認可サーバーが保持できる登録クライアントに関する情報 (Client Metadata) について定められている。

yapoo

Client Metadata

認可サーバーに登録されたクライアントに関する情報で、JSON または JWT の形式をとる。これは Client Registration Endpoint のリクエストやレスポンスで用いられる。すべて optional だが、client_name と client_uri は推奨 (RECOMMENDED) とされている。

key	type	description
`redirect_uris`	array<string>	認可コードフローやインプリシットフローで用いられる redirect_uri のリスト。リダイレクトを用いるフローの場合このパラメータは必須
`token_endpoint_auth_method`	string	トークンエンドポイントでのクライアント認証方法。この仕様では次の 3 種類が定義されている。・`none`: クライアント認証なし・`client_secret_post` : `client_id` と `client_secret` をリクエストボディで指定する (RFC 6749 Section 2.3.1) ・`client_secret_basic` 同じく RFC 6749 Section 2.3.1 で定められたベーシック認証 (デフォルト値)
`grant_types`	array<string>	トークンエンドポイントで用いることのできる認可グラントの一覧。`authorization_code` や `urn:ietf:params:oauth:grant-type:jwt-bearer` など。デフォルト値は `authorization_code`
`response_types`	array<string>	認可エンドポイントで用いることのできる `response_type` の一覧。 `code`, `token` など。デフォルト値は `code`。 `grant_type` と `response_type` は互いに矛盾がないようにしなければならない。
`client_name`	string	人間にとって判別しやすいクライアントの名称
`client_uri`	string	クライアントの Web サイトの URL
`logo_uri`	string	クライアントのロゴ画像への URL
`scope`	string	クライアントが利用可能なスコープをスペース区切りで示す。指定がない場合、認可サーバーで定めているデフォルト値を適用してもよい。
`contacts`	string	クライアントの運営者などへの連絡先。メールアドレスなど
`tos_uri`	string	クライアントのサービスの利用規約の URL
`policy_uri`	string	クライアントのサービスのプライバシーポリシーの URL
`jwks_uri`	string	クライアントが認可サーバーに提供するJWK セットの URL。例えば RFC7523 のようにトークンエンドポイントのクライアント認証に JWT を用いる場合に利用される
`jwks`	string	JWK セットの JSON 文字列。クライアントがネイティブアプリの場合など `jwks_uri` を提供できない場合に用いる。`jwks_uri` と `jwks` は両方指定されていてはならない。
`software_id`	string	クライアントのソフトウェアの ID。OAuth 2.0 としての異なるクライアントが同じ `software_id` を持つことがありえる
`software_version`	string	`software_id` で示されるソフトウェアのバージョン

一部の項目の多言語対応

client_name, tos_uri, policy_uri, logo_uri, client_uri などの項目は、キーの中で client_name#en や client_name#ja-Jpan-JP のように # 区切りで RFC 5646 で定められる言語タグを示すことで、多言語対応することができる^[1]。Section 2-2 で示された例では以下のような JSON になる。

{
  "client_name#en": "My Client",
  "client_name#ja-Jpan-JP": "クライアント名"
}

例えばクライアントにリソースへのアクセス権限を与えることへの許諾をリソースオーナーから得る場合があるが、その中で示されるサービス名やプライバシーポリシーへのリンクなどが、ブラウザでの設定言語によって切り替わるイメージだろう。

なお、言語タグのない client_name などが指定される場合、この値の言語について何らかの仮定 (これは日本語だ、のような…) を置いてはならないとされている。

Software Statement

Client Metadata を JWT で表現するとき、これを Software Statement という。JWT のペイロードは上で示した JSON である。

JWT の署名アルゴリズムとして RS256 を用いることと、クレームに software_id が含まれることが推奨されている。

脚注

この仕様は OpenID Connect Core 1.0 Section 5.2 で ID トークンの一部のクレームを多言語対応させる仕様と同じ ↩︎

yapoo

Client Registration Endpoint

Client Registration Endpoint は認可サーバーが公開するエンドポイントで、クライアントとしての登録を希望するシステムがこのエンドポイントを用いる。

Client Registration Endpoint は OAuth 2.0 で保護されていても良い (すなわち、リクエストでアクセストークンを要求しても良い)。その場合に Client Registration Endpoint で提示するアクセストークンのことを Initial Access Token と言う。本仕様では Initial Access Token を得る方法はスコープ外とされている。

リクエスト

Client Registration Endpoint は POST を受け付け、Content-Type は application/json でなければならない。

リクエストボディでは JSON で Client Metadata を指定するが、Client Metadata をそのまま JSON として指定する場合と、Software Statement の形で指定する場合とがある。

以下は Section 3.1 で示されるリクエストの例で、Client Metadata をそのままリクエストボディで指定する場合にあたる。

POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: server.example.com

{
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"],
  "client_name": "My Example Client",
  "client_name#ja-Jpan-JP":
     "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D",
  "token_endpoint_auth_method": "client_secret_basic",
  "logo_uri": "https://client.example.org/logo.png",
  "jwks_uri": "https://client.example.org/my_public_keys.jwks",
  "example_extension_parameter": "example_value"
}

以下は Section 3.1.1 で示されるリクエストの例で、こちらは Software Statement を用いる例にあたる。

POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: server.example.com

{
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "software_statement": "eyJhbGciOiJSUzI1NiJ9.eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGllbnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNsaWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ.GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHazdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn05X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxYfHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxskU5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJfIjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA",
  "scope": "read write",
  "example_extension_parameter": "example_value"
}

例にもあるように software_statement に Software Statement を指定するが、Client Metadata の全てを Software Statement に含まなければならないわけではなく、一部の項目をリクエストボディにそのまま記述してもよい。

レスポンス (Client Information Response)

登録に成功した場合のレスポンスのステータスコード 201 で、レスポンスボディは JSON で以下に加え、登録された Client Metadata すべてを返却する必要がある。

parameter	required	description
`client_id`	true	認可エンドポイントその他で指定することになるクライアントの識別子
`client_secret`	false	クライアントシークレット。コンフィデンシャルクライアントの場合にはトークンエンドポイントのクライアント認証で用いる
`client_id_issued_at`	false	`client_id` の発行日時を Unix Time で指定する
`client_secret_expires_at`	true	クライアントシークレットの失効日時を Unix Time で指定する。失効しない場合は `0` を指定する

以下は Section 3.2.1 で示されるレスポンスの例である。

HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
 "client_id": "s6BhdRkqt3",
 "client_secret": "cf136dc3c1fc93f31185e5885805d",
 "client_id_issued_at": 2893256800,
 "client_secret_expires_at": 2893276800,
 "redirect_uris": [
   "https://client.example.org/callback",
   "https://client.example.org/callback2"],
 "grant_types": ["authorization_code", "refresh_token"],
 "client_name": "My Example Client",
 "client_name#ja-Jpan-JP":
    "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D",
 "token_endpoint_auth_method": "client_secret_basic",
 "logo_uri": "https://client.example.org/logo.png",
 "jwks_uri": "https://client.example.org/my_public_keys.jwks",
 "example_extension_parameter": "example_value"
}

登録に失敗した場合はステータスコード 400 で下記のようなレスポンスを返却する。

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

{
 "error": "invalid_redirect_uri",
 "error_description": "The redirection URI
   http://sketchy.example.com is not allowed by this server."
}

error コードとしては本仕様の Section 3.2.2 でいくつか定義されている。

yapoo

登録の後

クライアントとしての登録の後、登録内容の参照・更新・削除を行いたくなる場合があるだろう。その場合の方法を定めているのは RFC 7592 である。