2. 客户端元数据

Registered clients have a set of metadata values associated with their client identifier at an authorization server, such as the list of valid redirection URIs or a display name.

These client metadata values are used in two ways:

• as input values to registration requests, and

• as output values in registration responses.

本规范定义以下客户端元数据字段. 除非另有说明, 所有客户端元数据字段的实现和使用都是 OPTIONAL. 所有数据成员类型 (字符串, 数组, 数字) 都依据其 JSON [RFC7159] 表示来定义.

redirect_uris Array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows. As required by Section 2 of OAuth 2.0 [RFC6749], clients using flows with redirection MUST register their redirection URI values. Authorization servers that support dynamic registration for redirect-based flows MUST implement support for this metadata value.

token_endpoint_auth_method String indicator of the requested authentication method for the token endpoint. Values defined by this specification are:

• "none": The client is a public client as defined in OAuth 2.0, Section 2.1, and does not have a client secret.

• "client_secret_post": The client uses the HTTP POST parameters as defined in OAuth 2.0, Section 2.3.1.

• "client_secret_basic": The client uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1.

附加值可以通过第 4.2 节建立的 IANA "OAuth Token Endpoint Authentication Methods" 注册表定义. 绝对 URI 也可以用作此参数的值, 而无需注册. 如果未指定或省略, 默认值为 "client_secret_basic", 表示 OAuth 2.0 第 2.3.1 节规定的 HTTP Basic 认证方案.

grant_types Array of OAuth 2.0 grant type strings that the client can use at the token endpoint. These grant types are defined as follows:

• "authorization_code": The authorization code grant type defined in OAuth 2.0, Section 4.1.

• "implicit": The implicit grant type defined in OAuth 2.0, Section 4.2.

• "password": The resource owner password credentials grant type defined in OAuth 2.0, Section 4.3.

• "client_credentials": The client credentials grant type defined in OAuth 2.0, Section 4.4.

• "refresh_token": The refresh token grant type defined in OAuth 2.0, Section 6.

• "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer Token Grant Type defined in OAuth JWT Bearer Token Profiles [RFC7523].

• "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2.0 Bearer Assertion Grant defined in OAuth SAML 2 Bearer Token Profiles [RFC7522].

If the token endpoint is used in the grant type, the value of this parameter MUST be the same as the value of the "grant_type" parameter passed to the token endpoint defined in the grant type definition. Authorization servers MAY allow for other values as defined in the grant type extension process described in OAuth 2.0, Section 4.5. If omitted, the default behavior is that the client will use only the "authorization_code" Grant Type.

response_types Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint. These response types are defined as follows:

• "code": The authorization code response type defined in OAuth 2.0, Section 4.1.

• "token": The implicit response type defined in OAuth 2.0, Section 4.2.

If the authorization endpoint is used by the grant type, the value of this parameter MUST be the same as the value of the "response_type" parameter passed to the authorization endpoint defined in the grant type definition. Authorization servers MAY allow for other values as defined in the grant type extension process is described in OAuth 2.0, Section 4.5. If omitted, the default is that the client will use only the "code" response type.

client_name Human-readable string name of the client to be presented to the end-user during authorization. If omitted, the authorization server MAY display the raw "client_id" value to the end-user instead. It is RECOMMENDED that clients always send this field. The value of this field MAY be internationalized, as described in Section 2.2.

client_uri URL string of a web page providing information about the client. If present, the server SHOULD display this URL to the end-user in a clickable fashion. It is RECOMMENDED that clients always send this field. The value of this field MUST point to a valid web page. The value of this field MAY be internationalized, as described in Section 2.2.

logo_uri URL string that references a logo for the client. If present, the server SHOULD display this image to the end-user during approval. The value of this field MUST point to a valid image file. The value of this field MAY be internationalized, as described in Section 2.2.

scope String containing a space-separated list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client can use when requesting access tokens. The semantics of values in this list are service specific. If omitted, an authorization server MAY register a client with a default set of scopes.

contacts Array of strings representing ways to contact people responsible for this client, typically email addresses. The authorization server MAY make these contact addresses available to end-users for support requests for the client. See Section 6 for information on Privacy Considerations.

tos_uri URL string that points to a human-readable terms of service document for the client that describes a contractual relationship between the end-user and the client that the end-user accepts when authorizing the client. The authorization server SHOULD display this URL to the end-user if it is provided. The value of this field MUST point to a valid web page. The value of this field MAY be internationalized, as described in Section 2.2.

policy_uri URL string that points to a human-readable privacy policy document that describes how the deployment organization collects, uses, retains, and discloses personal data. The authorization server SHOULD display this URL to the end-user if it is provided. The value of this field MUST point to a valid web page. The value of this field MAY be internationalized, as described in Section 2.2.

jwks_uri URL string referencing the client's JSON Web Key (JWK) Set [RFC7517] document, which contains the client's public keys. The value of this field MUST point to a valid JWK Set document. These keys can be used by higher-level protocols that use signing or encryption. For instance, these keys might be used by some applications for validating signed requests made to the token endpoint when using JWTs for client authentication [RFC7523]. Use of this parameter is preferred over the "jwks" parameter, as it allows for easier key rotation. The "jwks_uri" and "jwks" parameters MUST NOT both be present in the same request or response.

jwks Client's JSON Web Key Set [RFC7517] document value, which contains the client's public keys. The value of this field MUST be a JSON object containing a valid JWK Set. These keys can be used by higher-level protocols that use signing or encryption. This parameter is intended to be used by clients that cannot use the "jwks_uri" parameter, such as native clients that cannot host public URLs. The "jwks_uri" and "jwks" parameters MUST NOT both be present in the same request or response.

software_id A unique identifier string (e.g., a Universally Unique Identifier (UUID)) assigned by the client developer or software publisher used by registration endpoints to identify the client software to be dynamically registered. Unlike "client_id", which is issued by the authorization server and SHOULD vary between instances, the "software_id" SHOULD remain the same for all instances of the client software. The "software_id" SHOULD remain the same across multiple updates or versions of the same piece of software. The value of this field is not intended to be human readable and is usually opaque to the client and authorization server.

software_version A version identifier string for the client software identified by "software_id". The value of the "software_version" SHOULD change on any update to the client software identified by the same "software_id". The value of this field is intended to be compared using string equality matching and no other comparison semantics are defined by this specification. The value of this field is outside the scope of this specification, but it is not intended to be human readable and is usually opaque to the client and authorization server. The definition of what constitutes an update to client software that would trigger a change to this value is specific to the software itself and is outside the scope of this specification.

本规范的扩展和配置文件可以使用按照本文档第 4 节 IANA 考虑注册的元数据名称和描述来扩展此列表. 授权服务器 MUST 忽略客户端发送但它不理解的任何客户端元数据 (例如, 在处理期间从客户端注册记录中静默移除未知元数据). 授权服务器 MAY 通过将请求值替换为第 3.2.1 节所述的合适默认值, 或通过返回第 3.2.2 节所述的错误响应, 来拒绝任何请求的客户端元数据值.

Client metadata values can be either communicated directly in the body of a registration request, as described in Section 3.1, or included as claims in a software statement, as described in Section 2.3; a mixture of both is also possible. If the same client metadata name is present in both locations and the software statement is trusted by the authorization server, the value of a claim in the software statement MUST take precedence.

2.1. 授权类型和响应类型之间的关系

The "grant_types" and "response_types" values described above are partially orthogonal, as they refer to arguments passed to different endpoints in the OAuth protocol. However, they are related in that the "grant_types" available to a client influence the "response_types" that the client is allowed to use, and vice versa. For instance, a "grant_types" value that includes "authorization_code" implies a "response_types" value that includes "code", as both values are defined as part of the OAuth 2.0 authorization code grant. As such, a server supporting these fields SHOULD take steps to ensure that a client cannot register itself into an inconsistent state, for example, by returning an "invalid_client_metadata" error response to an inconsistent registration request.

The correlation between the two fields is listed in the table below.

grant_types value includes:	response_types value includes:
authorization_code	code
implicit	token
password	(none)
client_credentials	(none)
refresh_token	(none)
urn:ietf:params:oauth:grant-type:jwt-bearer	(none)
urn:ietf:params:oauth:grant-type:saml2-bearer	(none)

Extensions and profiles of this document that introduce new values to either the "grant_types" or "response_types" parameter MUST document all correspondences between these two parameter types.

2.2. 人类可读客户端元数据

Human-readable client metadata values and client metadata values that reference human-readable values MAY be represented in multiple languages and scripts. For example, the values of fields such as "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" might have multiple locale-specific values in some client registrations to facilitate use in different locations.

为了指定语言和文字, 将 BCP 47 [RFC5646] 语言标签添加到客户端元数据成员名称中, 并以 "#" 字符分隔. 由于 JSON [RFC7159] 成员名称区分大小写, RECOMMENDED 使用 Claim Names 中的语言标签值时, 按照它们在 "IANA Language Subtag" 注册表 [IANA.Language] 中注册的字符大小写书写. 特别是, 通常语言名称使用小写字符, 地区名称使用大写字符, 文字名称使用大小写混合字符. 但是, 由于 BCP 47 语言标签值大小写不敏感, 实现 SHOULD 以大小写不敏感方式解释提供的语言标签值. 根据 BCP 47 中的建议, 用于元数据成员名称的语言标签值应只具体到必要程度. 例如, 在许多上下文中使用 "fr" 可能已经足够, 而不是使用 "fr-CA" 或 "fr-FR".

For example, a client could represent its name in English as "client_name#en": "My Client" and its name in Japanese as "client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D" within the same registration request. The authorization server MAY display any or all of these names to the resource owner during the authorization step, choosing which name to display based on system configuration, user preferences or other factors.

If any human-readable field is sent without a language tag, parties using it MUST NOT make any assumptions about the language, character set, or script of the string value, and the string value MUST be used as is wherever it is presented in a user interface. To facilitate interoperability, it is RECOMMENDED that clients and servers use a human-readable field without any language tags in addition to any language-specific fields, and it is RECOMMENDED that any human-readable fields sent without language tags contain values suitable for display on a wide variety of systems.

Implementer's Note: Many JSON libraries make it possible to reference members of a JSON object as members of an object construct in the native programming environment of the library. However, while the "#" character is a valid character inside of a JSON object's member names, it is not a valid character for use in an object member name in many programming environments. Therefore, implementations will need to use alternative access forms for these claims. For instance, in JavaScript, if one parses the JSON as follows, "var j = JSON.parse(json);", then as a workaround the member "client_name#en-us" can be accessed using the JavaScript syntax "j["client_name#en-us"]".

2.3. 软件声明

A software statement is a JSON Web Token (JWT) [RFC7519] that asserts metadata values about the client software as a bundle. A set of claims that can be used in a software statement are defined in Section 2. When presented to the authorization server as part of a client registration request, the software statement MUST be digitally signed or MACed using JSON Web Signature (JWS) [RFC7515] and MUST contain an "iss" (issuer) claim denoting the party attesting to the claims in the software statement. It is RECOMMENDED that software statements be digitally signed using the "RS256" signature algorithm, although particular applications MAY specify the use of different algorithms. It is RECOMMENDED that software statements contain the "software_id" claim to allow authorization servers to correlate different instances of software using the same software statement.

For example, a software statement could contain the following claims:

  {
   "software_id": "4NRB1-0XZABZI9E6-5SM3R",
   "client_name": "Example Statement-based Client",
   "client_uri": "https://client.example.net/"
  }

以下非规范性 JWT 示例包含这些声明, 并已使用 "RS256" 进行非对称签名 (换行仅为显示目的):

  eyJhbGciOiJSUzI1NiJ9.
  eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll
  bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs
  aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ.
  GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa
  zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0
  5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY
  fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk
  U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf
  IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA

The software statement is typically distributed with all instances of a client application. The means by which a client or developer obtains a software statement are outside the scope of this specification. Some common methods could include a client developer generating a client-specific JWT by registering with a software API publisher to obtain a software statement for a class of clients.

The criteria by which authorization servers determine whether to trust and utilize the information in a software statement are outside the scope of this specification.

In some cases, authorization servers MAY choose to accept a software statement value directly as a client identifier in an authorization request, without a prior dynamic client registration having been performed. The circumstances under which an authorization server would do so, and the specific software statement characteristics required in this case, are outside the scope of this specification.