Internet Engineering Task Force (IETF) J. Richer, Ed. Request for Comments: 7662 October 2015 Category: Standards Track ISSN: 2070-1721
Internet Engineering Task Force (IETF) J. Richer, Ed. Request for Comments: 7662 October 2015 Category: Standards Track ISSN: 2070-1721
OAuth 2.0 Token Introspection
OAuth2.0令牌内省
Abstract
摘要
This specification defines a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token. OAuth 2.0 deployments can use this method to convey information about the authorization context of the token from the authorization server to the protected resource.
本规范定义了受保护资源查询OAuth 2.0授权服务器的方法,以确定OAuth 2.0令牌的活动状态,并确定有关该令牌的元信息。OAuth 2.0部署可以使用此方法将有关令牌的授权上下文的信息从授权服务器传递到受保护的资源。
Status of This Memo
关于下段备忘
This is an Internet Standards Track document.
这是一份互联网标准跟踪文件。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.
本文件是互联网工程任务组(IETF)的产品。它代表了IETF社区的共识。它已经接受了公众审查,并已被互联网工程指导小组(IESG)批准出版。有关互联网标准的更多信息,请参见RFC 5741第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7662.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息,请访问http://www.rfc-editor.org/info/rfc7662.
Copyright Notice
版权公告
Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved.
版权所有(c)2015 IETF信托基金和确定为文件作者的人员。版权所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(http://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件,因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本,并提供简化BSD许可证中所述的无担保。
Table of Contents
目录
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4 2.2. Introspection Response . . . . . . . . . . . . . . . . . 6 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 3.1. OAuth Token Introspection Response Registry . . . . . . . 9 3.1.1. Registration Template . . . . . . . . . . . . . . . . 10 3.1.2. Initial Registry Contents . . . . . . . . . . . . . . 10 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 14 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.1. Normative References . . . . . . . . . . . . . . . . . . 15 6.2. Informative References . . . . . . . . . . . . . . . . . 16 Appendix A. Use with Proof-of-Possession Tokens . . . . . . . . 17 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 17 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introspection Endpoint . . . . . . . . . . . . . . . . . . . 3 2.1. Introspection Request . . . . . . . . . . . . . . . . . . 4 2.2. Introspection Response . . . . . . . . . . . . . . . . . 6 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 3.1. OAuth Token Introspection Response Registry . . . . . . . 9 3.1.1. Registration Template . . . . . . . . . . . . . . . . 10 3.1.2. Initial Registry Contents . . . . . . . . . . . . . . 10 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 14 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.1. Normative References . . . . . . . . . . . . . . . . . . 15 6.2. Informative References . . . . . . . . . . . . . . . . . 16 Appendix A. Use with Proof-of-Possession Tokens . . . . . . . . 17 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 17 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17
In OAuth 2.0 [RFC6749], the contents of tokens are opaque to clients. This means that the client does not need to know anything about the content or structure of the token itself, if there is any. However, there is still a large amount of metadata that may be attached to a token, such as its current validity, approved scopes, and information about the context in which the token was issued. These pieces of information are often vital to protected resources making authorization decisions based on the tokens being presented. Since OAuth 2.0 does not define a protocol for the resource server to learn meta-information about a token that it has received from an authorization server, several different approaches have been developed to bridge this gap. These include using structured token formats such as JWT [RFC7519] or proprietary inter-service communication mechanisms (such as shared databases and protected enterprise service buses) that convey token information.
在OAuth 2.0[RFC6749]中,令牌的内容对客户端是不透明的。这意味着客户端不需要知道任何关于令牌本身的内容或结构的信息(如果有的话)。但是,仍有大量元数据可能附加到令牌,例如其当前有效性、批准的范围以及有关令牌发布的上下文的信息。这些信息通常对于受保护的资源根据所提供的令牌做出授权决策至关重要。由于OAuth 2.0没有为资源服务器定义一个协议来学习从授权服务器接收到的令牌的元信息,因此开发了几种不同的方法来弥补这一差距。其中包括使用结构化令牌格式,如JWT[RFC7519]或专有的服务间通信机制(如共享数据库和受保护的企业服务总线),以传递令牌信息。
This specification defines a protocol that allows authorized protected resources to query the authorization server to determine the set of metadata for a given token that was presented to them by an OAuth 2.0 client. This metadata includes whether or not the token is currently active (or if it has expired or otherwise been revoked), what rights of access the token carries (usually conveyed through OAuth 2.0 scopes), and the authorization context in which the token was granted (including who authorized the token and which client it
此规范定义了一个协议,允许授权受保护资源查询授权服务器,以确定OAuth 2.0客户端提供给它们的给定令牌的元数据集。此元数据包括令牌当前是否处于活动状态(或是否已过期或已被撤销)、令牌所具有的访问权限(通常通过OAuth 2.0作用域传递)以及授予令牌的授权上下文(包括谁授权令牌以及该令牌所属的客户端)
was issued to). Token introspection allows a protected resource to query this information regardless of whether or not it is carried in the token itself, allowing this method to be used along with or independently of structured token values. Additionally, a protected resource can use the mechanism described in this specification to introspect the token in a particular authorization decision context and ascertain the relevant metadata about the token to make this authorization decision appropriately.
下发至)。令牌内省允许受保护的资源查询此信息,而不管它是否包含在令牌本身中,允许此方法与结构化令牌值一起使用或独立于结构化令牌值使用。此外,受保护的资源可以使用本规范中描述的机制在特定授权决策上下文中内省令牌,并确定关于令牌的相关元数据,以适当地做出此授权决策。
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in [RFC2119].
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“建议”、“不建议”、“可能”和“可选”应按照[RFC2119]中的说明进行解释。
Unless otherwise noted, all the protocol parameter names and values are case sensitive.
除非另有说明,否则所有协议参数名称和值都区分大小写。
This section defines the terminology used by this specification. This section is a normative portion of this specification, imposing requirements upon implementations.
本节定义了本规范使用的术语。本节是本规范的规范性部分,对实现提出了要求。
This specification uses the terms "access token", "authorization endpoint", "authorization grant", "authorization server", "client", "client identifier", "protected resource", "refresh token", "resource owner", "resource server", and "token endpoint" defined by OAuth 2.0 [RFC6749], and the terms "claim names" and "claim values" defined by JSON Web Token (JWT) [RFC7519].
本规范使用OAuth 2.0[RFC6749]定义的术语“访问令牌”、“授权端点”、“授权授予”、“授权服务器”、“客户端”、“客户端标识符”、“受保护资源”、“刷新令牌”、“资源所有者”、“资源服务器”和“令牌端点”,以及术语“声明名称”和“声明值”由JSON Web令牌(JWT)[RFC7519]定义。
This specification defines the following terms:
本规范定义了以下术语:
Token Introspection The act of inquiring about the current state of an OAuth 2.0 token through use of the network protocol defined in this document.
令牌内省通过使用本文档中定义的网络协议来查询OAuth 2.0令牌的当前状态的行为。
Introspection Endpoint The OAuth 2.0 endpoint through which the token introspection operation is accomplished.
内省端点完成令牌内省操作的OAuth 2.0端点。
The introspection endpoint is an OAuth 2.0 endpoint that takes a parameter representing an OAuth 2.0 token and returns a JSON [RFC7159] document representing the meta information surrounding the token, including whether this token is currently active. The
内省端点是OAuth 2.0端点,它接受一个表示OAuth 2.0令牌的参数,并返回一个JSON[RFC7159]文档,该文档表示令牌周围的元信息,包括该令牌当前是否处于活动状态。这个
definition of an active token is dependent upon the authorization server, but this is commonly a token that has been issued by this authorization server, is not expired, has not been revoked, and is valid for use at the protected resource making the introspection call.
活动令牌的定义取决于授权服务器,但这通常是一个由该授权服务器颁发的令牌,未过期、未撤销,并且在进行内省调用的受保护资源上有效。
The introspection endpoint MUST be protected by a transport-layer security mechanism as described in Section 4. The means by which the protected resource discovers the location of the introspection endpoint are outside the scope of this specification.
内省端点必须由传输层安全机制保护,如第4节所述。受保护资源发现内省端点位置的方法不在本规范的范围内。
The protected resource calls the introspection endpoint using an HTTP POST [RFC7231] request with parameters sent as "application/x-www-form-urlencoded" data as defined in [W3C.REC-html5-20141028]. The protected resource sends a parameter representing the token along with optional parameters representing additional context that is known by the protected resource to aid the authorization server in its response.
受保护的资源使用HTTP POST[RFC7231]请求调用内省端点,该请求的参数作为[W3C.REC-html5-20141028]中定义的“应用程序/x-www-form-urlencoded”数据发送。受保护资源发送一个表示令牌的参数,以及表示受保护资源已知的其他上下文的可选参数,以帮助授权服务器响应。
token REQUIRED. The string value of the token. For access tokens, this is the "access_token" value returned from the token endpoint defined in OAuth 2.0 [RFC6749], Section 5.1. For refresh tokens, this is the "refresh_token" value returned from the token endpoint as defined in OAuth 2.0 [RFC6749], Section 5.1. Other token types are outside the scope of this specification.
需要代币。标记的字符串值。对于访问令牌,这是从OAuth 2.0[RFC6749]第5.1节中定义的令牌端点返回的“访问令牌”值。对于刷新令牌,这是从OAuth 2.0[RFC6749]第5.1节中定义的令牌端点返回的“刷新令牌”值。其他令牌类型不在本规范的范围内。
token_type_hint OPTIONAL. A hint about the type of the token submitted for introspection. The protected resource MAY pass this parameter to help the authorization server optimize the token lookup. If the server is unable to locate the token using the given hint, it MUST extend its search across all of its supported token types. An authorization server MAY ignore this parameter, particularly if it is able to detect the token type automatically. Values for this field are defined in the "OAuth Token Type Hints" registry defined in OAuth Token Revocation [RFC7009].
令牌\类型\提示可选。关于提交用于内省的令牌类型的提示。受保护的资源可以传递此参数以帮助授权服务器优化令牌查找。如果服务器无法使用给定提示定位令牌,则必须将其搜索扩展到所有受支持的令牌类型。授权服务器可能会忽略此参数,特别是当它能够自动检测令牌类型时。此字段的值在OAuth令牌撤销[RFC7009]中定义的“OAuth令牌类型提示”注册表中定义。
The introspection endpoint MAY accept other OPTIONAL parameters to provide further context to the query. For instance, an authorization server may desire to know the IP address of the client accessing the protected resource to determine if the correct client is likely to be presenting the token. The definition of this or any other parameters are outside the scope of this specification, to be defined by service documentation or extensions to this specification. If the authorization server is unable to determine the state of the token
内省端点可以接受其他可选参数,为查询提供进一步的上下文。例如,授权服务器可能希望知道访问受保护资源的客户端的IP地址,以确定正确的客户端是否可能呈现令牌。此参数或任何其他参数的定义不在本规范的范围内,由服务文档或本规范的扩展定义。如果授权服务器无法确定令牌的状态
without additional information, it SHOULD return an introspection response indicating the token is not active as described in Section 2.2.
在没有其他信息的情况下,它应该返回一个内省响应,指示令牌未处于活动状态,如第2.2节所述。
To prevent token scanning attacks, the endpoint MUST also require some form of authorization to access this endpoint, such as client authentication as described in OAuth 2.0 [RFC6749] or a separate OAuth 2.0 access token such as the bearer token described in OAuth 2.0 Bearer Token Usage [RFC6750]. The methods of managing and validating these authentication credentials are out of scope of this specification.
为了防止令牌扫描攻击,端点还必须需要某种形式的授权才能访问此端点,例如OAuth 2.0[RFC6749]中描述的客户端身份验证或单独的OAuth 2.0访问令牌,例如OAuth 2.0承载令牌使用[RFC6750]中描述的承载令牌。管理和验证这些身份验证凭据的方法不在本规范的范围内。
For example, the following shows a protected resource calling the token introspection endpoint to query about an OAuth 2.0 bearer token. The protected resource is using a separate OAuth 2.0 bearer token to authorize this call.
例如,下面显示了一个受保护的资源调用令牌内省端点来查询OAuth 2.0承载令牌。受保护的资源正在使用单独的OAuth 2.0承载令牌来授权此调用。
The following is a non-normative example request:
以下是一个非规范性示例请求:
POST /introspect HTTP/1.1 Host: server.example.com Accept: application/json Content-Type: application/x-www-form-urlencoded Authorization: Bearer 23410913-abewfq.123483
POST /introspect HTTP/1.1 Host: server.example.com Accept: application/json Content-Type: application/x-www-form-urlencoded Authorization: Bearer 23410913-abewfq.123483
token=2YotnFZFEjr1zCsicMWpAA
令牌=2YotnFZFEjr1zCsicMWpAA
In this example, the protected resource uses a client identifier and client secret to authenticate itself to the introspection endpoint. The protected resource also sends a token type hint indicating that it is inquiring about an access token.
在本例中,受保护的资源使用客户端标识符和客户端密码向内省端点进行自身身份验证。受保护的资源还发送令牌类型提示,指示它正在查询访问令牌。
The following is a non-normative example request:
以下是一个非规范性示例请求:
POST /introspect HTTP/1.1 Host: server.example.com Accept: application/json Content-Type: application/x-www-form-urlencoded Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
POST /introspect HTTP/1.1 Host: server.example.com Accept: application/json Content-Type: application/x-www-form-urlencoded Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=mF_9.B5f-4.1JqM&token_type_hint=access_token
令牌=mF_9.B5f-4.1JqM&令牌类型提示=访问令牌
The server responds with a JSON object [RFC7159] in "application/ json" format with the following top-level members.
服务器以“application/JSON”格式的JSON对象[RFC7159]响应,其中包含以下顶级成员。
active REQUIRED. Boolean indicator of whether or not the presented token is currently active. The specifics of a token's "active" state will vary depending on the implementation of the authorization server and the information it keeps about its tokens, but a "true" value return for the "active" property will generally indicate that a given token has been issued by this authorization server, has not been revoked by the resource owner, and is within its given time window of validity (e.g., after its issuance time and before its expiration time). See Section 4 for information on implementation of such checks.
需要激活。表示当前所提供令牌是否处于活动状态的布尔指示符。令牌的“活动”状态的细节将根据授权服务器的实现及其保留的令牌相关信息而有所不同,但“活动”属性的“true”值返回通常表示给定令牌已由该授权服务器颁发,且未被资源所有者撤销,并且在其给定的有效时间窗口内(例如,在其发行时间之后和到期时间之前)。有关实施此类检查的信息,请参见第4节。
scope OPTIONAL. A JSON string containing a space-separated list of scopes associated with this token, in the format described in Section 3.3 of OAuth 2.0 [RFC6749].
范围可选。一个JSON字符串,包含与此令牌关联的作用域的空格分隔列表,格式如OAuth 2.0[RFC6749]第3.3节所述。
client_id OPTIONAL. Client identifier for the OAuth 2.0 client that requested this token.
客户端id可选。请求此令牌的OAuth 2.0客户端的客户端标识符。
username OPTIONAL. Human-readable identifier for the resource owner who authorized this token.
用户名可选。授权此令牌的资源所有者的可读标识符。
token_type OPTIONAL. Type of the token as defined in Section 5.1 of OAuth 2.0 [RFC6749].
令牌类型是可选的。OAuth 2.0[RFC6749]第5.1节中定义的令牌类型。
exp OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token will expire, as defined in JWT [RFC7519].
exp可选。整数时间戳,自1970年UTC 1月1日起以秒为单位测量,指示此令牌何时过期,如JWT[RFC7519]中所定义。
iat OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token was originally issued, as defined in JWT [RFC7519].
iat可选。整数时间戳,以UTC 1970年1月1日以来的秒数为单位,表示该令牌最初发布的时间,如JWT[RFC7519]中所定义。
nbf OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token is not to be used before, as defined in JWT [RFC7519].
nbf可选。整数时间戳,自1970年UTC 1月1日起以秒为单位测量,指示在此之前不使用此令牌的时间,如JWT[RFC7519]中所定义。
sub OPTIONAL. Subject of the token, as defined in JWT [RFC7519]. Usually a machine-readable identifier of the resource owner who authorized this token.
次可选。令牌的主题,如JWT[RFC7519]中所定义。通常是授权此令牌的资源所有者的机器可读标识符。
aud OPTIONAL. Service-specific string identifier or list of string identifiers representing the intended audience for this token, as defined in JWT [RFC7519].
aud可选。服务特定的字符串标识符或字符串标识符列表,表示此令牌的预期受众,如JWT[RFC7519]中所定义。
iss OPTIONAL. String representing the issuer of this token, as defined in JWT [RFC7519].
iss可选。表示此令牌的颁发者的字符串,如JWT[RFC7519]中所定义。
jti OPTIONAL. String identifier for the token, as defined in JWT [RFC7519].
jti可选。令牌的字符串标识符,如JWT[RFC7519]中所定义。
Specific implementations MAY extend this structure with their own service-specific response names as top-level members of this JSON object. Response names intended to be used across domains MUST be registered in the "OAuth Token Introspection Response" registry defined in Section 3.1.
特定的实现可以使用自己的特定于服务的响应名称作为此JSON对象的顶级成员来扩展此结构。打算跨域使用的响应名称必须在第3.1节中定义的“OAuth令牌内省响应”注册表中注册。
The authorization server MAY respond differently to different protected resources making the same request. For instance, an authorization server MAY limit which scopes from a given token are returned for each protected resource to prevent a protected resource from learning more about the larger network than is necessary for its operation.
授权服务器可能对发出相同请求的不同受保护资源做出不同的响应。例如,授权服务器可以限制为每个受保护的资源返回给定令牌的哪些作用域,以防止受保护的资源对更大网络的了解超过其操作所需的范围。
The response MAY be cached by the protected resource to improve performance and reduce load on the introspection endpoint, but at the cost of liveness of the information used by the protected resource to make authorization decisions. See Section 4 for more information regarding the trade off when the response is cached.
受保护资源可以缓存响应,以提高性能并减少内省端点上的负载,但代价是受保护资源用于做出授权决策的信息的活跃性。有关缓存响应时的权衡的更多信息,请参见第4节。
For example, the following response contains a set of information about an active token:
例如,以下响应包含一组关于活动令牌的信息:
The following is a non-normative example response:
以下是非规范性示例响应:
HTTP/1.1 200 OK Content-Type: application/json
HTTP/1.1 200 OK Content-Type: application/json
{ "active": true, "client_id": "l238j323ds-23ij4", "username": "jdoe", "scope": "read write dolphin", "sub": "Z5O3upPC88QrAjx00dis", "aud": "https://protected.example.net/resource", "iss": "https://server.example.com/", "exp": 1419356238, "iat": 1419350238, "extension_field": "twenty-seven" }
{ "active": true, "client_id": "l238j323ds-23ij4", "username": "jdoe", "scope": "read write dolphin", "sub": "Z5O3upPC88QrAjx00dis", "aud": "https://protected.example.net/resource", "iss": "https://server.example.com/", "exp": 1419356238, "iat": 1419350238, "extension_field": "twenty-seven" }
If the introspection call is properly authorized but the token is not active, does not exist on this server, or the protected resource is not allowed to introspect this particular token, then the authorization server MUST return an introspection response with the "active" field set to "false". Note that to avoid disclosing too much of the authorization server's state to a third party, the authorization server SHOULD NOT include any additional information about an inactive token, including why the token is inactive.
如果内省调用已正确授权,但令牌未处于活动状态,此服务器上不存在令牌,或者不允许受保护资源内省此特定令牌,则授权服务器必须返回一个内省响应,且“活动”字段设置为“false”。请注意,为了避免向第三方披露太多授权服务器的状态,授权服务器不应包含有关非活动令牌的任何附加信息,包括令牌为何处于非活动状态。
The following is a non-normative example response for a token that has been revoked or is otherwise invalid:
以下是已撤销或无效令牌的非规范性示例响应:
HTTP/1.1 200 OK Content-Type: application/json
HTTP/1.1 200 OK Content-Type: application/json
{ "active": false }
{ "active": false }
If the protected resource uses OAuth 2.0 client credentials to authenticate to the introspection endpoint and its credentials are invalid, the authorization server responds with an HTTP 401 (Unauthorized) as described in Section 5.2 of OAuth 2.0 [RFC6749].
如果受保护的资源使用OAuth 2.0客户端凭据对内省端点进行身份验证,并且其凭据无效,则授权服务器将使用HTTP 401(未经授权)进行响应,如OAuth 2.0[RFC6749]第5.2节所述。
If the protected resource uses an OAuth 2.0 bearer token to authorize its call to the introspection endpoint and the token used for authorization does not contain sufficient privileges or is otherwise invalid for this request, the authorization server responds with an HTTP 401 code as described in Section 3 of OAuth 2.0 Bearer Token Usage [RFC6750].
如果受保护的资源使用OAuth 2.0承载令牌来授权其对内省端点的调用,并且用于授权的令牌不包含足够的权限,或者对此请求无效,则授权服务器使用HTTP 401代码响应,如OAuth 2.0承载令牌用法[RFC6750]第3节所述.
Note that a properly formed and authorized query for an inactive or otherwise invalid token (or a token the protected resource is not allowed to know about) is not considered an error response by this specification. In these cases, the authorization server MUST instead respond with an introspection response with the "active" field set to "false" as described in Section 2.2.
请注意,对于非活动或无效令牌(或不允许受保护资源知道的令牌)的正确格式和授权查询不被本规范视为错误响应。在这些情况下,授权服务器必须使用内省响应,将“活动”字段设置为“false”,如第2.2节所述。
This specification establishes the "OAuth Token Introspection Response" registry.
本规范建立了“OAuth令牌内省响应”注册表。
OAuth registration client metadata names and descriptions are registered by Specification Required [RFC5226] after a two-week review period on the oauth-ext-review@ietf.org mailing list, on the advice of one or more Designated Experts. However, to allow for the allocation of names prior to publication, the Designated Expert(s) may approve registration once they are satisfied that such a specification will be published.
OAuth注册客户机元数据名称和描述在OAuth ext上经过两周的审查后,按照所需规范[RFC5226]进行注册-review@ietf.org根据一名或多名指定专家的建议,提供邮件列表。但是,为了允许在发布前分配名称,指定专家可在确信此类规范将发布后批准注册。
Registration requests sent to the mailing list for review should use an appropriate subject (e.g., "Request to register OAuth Token Introspection Response name: example").
发送到邮件列表供审查的注册请求应使用适当的主题(例如,“注册OAuth令牌内省响应名称的请求:示例”)。
Within the review period, the Designated Expert(s) will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful.
在审查期内,指定专家将批准或拒绝注册请求,并将该决定告知审查名单和IANA。拒绝应包括解释,以及(如适用)关于如何使请求成功的建议。
IANA must only accept registry updates from the Designated Expert(s) and should direct all requests for registration to the review mailing list.
IANA必须只接受指定专家的注册更新,并将所有注册请求发送至审查邮件列表。
Name: The name requested (e.g., "example"). This name is case sensitive. Names that match other registered names in a case insensitive manner SHOULD NOT be accepted. Names that match claims registered in the "JSON Web Token Claims" registry established by [RFC7519] SHOULD have comparable definitions and semantics.
名称:请求的名称(例如,“示例”)。此名称区分大小写。不应接受以不区分大小写的方式与其他注册名称匹配的名称。与[RFC7519]建立的“JSON Web令牌声明”注册表中注册的声明匹配的名称应具有可比的定义和语义。
Description: Brief description of the metadata value (e.g., "Example description").
描述:元数据值的简要描述(例如,“示例描述”)。
Change controller: For Standards Track RFCs, state "IESG". For other documents, give the name of the responsible party. Other details (e.g., postal address, email address, home page URI) may also be included.
更改控制器:对于标准跟踪RFC,请注明“IESG”。对于其他文件,请提供责任方的名称。还可以包括其他详细信息(例如,邮政地址、电子邮件地址、主页URI)。
Specification document(s): Reference to the document(s) that specify the token endpoint authorization method, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.
规范文档:对指定令牌端点授权方法的文档的引用,最好包括可用于检索文档副本的URI。也可以包括相关章节的指示,但不需要。
The initial contents of the "OAuth Token Introspection Response" registry are as follows:
“OAuth令牌内省响应”注册表的初始内容如下:
o Name: "active" o Description: Token active status o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“活动”o说明:令牌活动状态o变更控制器:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "username" o Description: User identifier of the resource owner o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“用户名”o说明:资源所有者的用户标识符o变更控制器:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "client_id" o Description: Client identifier of the client o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“客户id”o说明:客户的客户标识符o变更控制器:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "scope" o Description: Authorized scopes of the token o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“范围”o说明:令牌的授权范围o变更控制器:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "token_type" o Description: Type of the token o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“令牌类型”o说明:令牌类型o变更控制器:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "exp" o Description: Expiration timestamp of the token o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“exp”o说明:令牌的到期时间戳o变更控制器:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "iat" o Description: Issuance timestamp of the token o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“iat”o说明:令牌的发行时间戳o变更控制器:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "nbf" o Description: Timestamp before which the token is not valid o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“nbf”o说明:令牌无效的时间戳o变更控制器:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "sub" o Description: Subject of the token o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“子”o说明:令牌o变更控制器的主题:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "aud" o Description: Audience of the token o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“aud”o说明:令牌o变更控制器的受众:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "iss" o Description: Issuer of the token o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“iss”o说明:令牌o变更控制器的发行人:IESG o规范文件:RFC 7662(本文件)第2.2节。
o Name: "jti" o Description: Unique identifier of the token o Change Controller: IESG o Specification Document(s): Section 2.2 of RFC 7662 (this document).
o 名称:“jti”o描述:令牌o变更控制器的唯一标识符:IESG o规范文件:RFC 7662(本文件)第2.2节。
Since there are many different and valid ways to implement an OAuth 2.0 system, there are consequently many ways for an authorization server to determine whether or not a token is currently "active". However, since resource servers using token introspection rely on the authorization server to determine the state of a token, the authorization server MUST perform all applicable checks against a token's state. For instance, these tests include the following:
由于有许多不同且有效的方法来实现OAuth 2.0系统,因此授权服务器有许多方法来确定令牌当前是否处于“活动”状态。但是,由于使用令牌内省的资源服务器依赖于授权服务器来确定令牌的状态,因此授权服务器必须针对令牌的状态执行所有适用的检查。例如,这些测试包括以下内容:
o If the token can expire, the authorization server MUST determine whether or not the token has expired. o If the token can be issued before it is able to be used, the authorization server MUST determine whether or not a token's valid period has started yet. o If the token can be revoked after it was issued, the authorization server MUST determine whether or not such a revocation has taken place. o If the token has been signed, the authorization server MUST validate the signature. o If the token can be used only at certain resource servers, the authorization server MUST determine whether or not the token can be used at the resource server making the introspection call.
o 如果令牌可能过期,则授权服务器必须确定令牌是否已过期。o如果令牌可以在能够使用之前发出,则授权服务器必须确定令牌的有效期是否已经开始。o如果令牌在发出后可以被撤销,则授权服务器必须确定是否发生了此类撤销。o如果令牌已签名,则授权服务器必须验证签名。o如果令牌只能在某些资源服务器上使用,则授权服务器必须确定令牌是否可以在进行内省调用的资源服务器上使用。
If an authorization server fails to perform any applicable check, the resource server could make an erroneous security decision based on that response. Note that not all of these checks will be applicable to all OAuth 2.0 deployments and it is up to the authorization server to determine which of these checks (and any other checks) apply.
如果授权服务器未能执行任何适用的检查,资源服务器可能会根据该响应做出错误的安全决策。请注意,并非所有这些检查都适用于所有OAuth 2.0部署,应由授权服务器确定哪些检查(以及任何其他检查)适用。
If left unprotected and un-throttled, the introspection endpoint could present a means for an attacker to poll a series of possible token values, fishing for a valid token. To prevent this, the authorization server MUST require authentication of protected resources that need to access the introspection endpoint and SHOULD require protected resources to be specifically authorized to call the introspection endpoint. The specifics of such authentication credentials are out of scope of this specification, but commonly these credentials could take the form of any valid client authentication mechanism used with the token endpoint, an OAuth 2.0 access token, or other HTTP authorization or authentication mechanism. A single piece of software acting as both a client and a
如果未受保护且未限制,内省端点可能会为攻击者提供轮询一系列可能的令牌值的方法,以查找有效令牌。为了防止这种情况发生,授权服务器必须要求对需要访问内省端点的受保护资源进行身份验证,并且应该要求对受保护资源进行专门授权,以调用内省端点。此类身份验证凭据的细节不在本规范的范围内,但通常这些凭据可以采用与令牌端点、OAuth 2.0访问令牌或其他HTTP授权或身份验证机制一起使用的任何有效客户端身份验证机制的形式。同时作为客户机和服务器的单个软件
protected resource MAY reuse the same credentials between the token endpoint and the introspection endpoint, though doing so potentially conflates the activities of the client and protected resource portions of the software and the authorization server MAY require separate credentials for each mode.
受保护资源可以在令牌端点和内省端点之间重用相同的凭据,尽管这样做可能会将客户端的活动和软件的受保护资源部分合并,并且授权服务器可能需要每个模式的单独凭据。
Since the introspection endpoint takes in OAuth 2.0 tokens as parameters and responds with information used to make authorization decisions, the server MUST support Transport Layer Security (TLS) 1.2 [RFC5246] and MAY support additional transport-layer mechanisms meeting its security requirements. When using TLS, the client or protected resource MUST perform a TLS/SSL server certificate check, as specified in [RFC6125]. Implementation security considerations can be found in Recommendations for Secure Use of TLS and DTLS [BCP195].
由于内省端点将OAuth 2.0令牌作为参数,并使用用于做出授权决策的信息进行响应,因此服务器必须支持传输层安全性(TLS)1.2[RFC5246],并且可能支持满足其安全性要求的其他传输层机制。使用TLS时,客户端或受保护资源必须执行TLS/SSL服务器证书检查,如[RFC6125]中所述。实施安全注意事项可在TLS和DTL安全使用建议[BCP195]中找到。
To prevent the values of access tokens from leaking into server-side logs via query parameters, an authorization server offering token introspection MAY disallow the use of HTTP GET on the introspection endpoint and instead require the HTTP POST method to be used at the introspection endpoint.
为了防止访问令牌的值通过查询参数泄漏到服务器端日志中,提供令牌内省的授权服务器可能不允许在内省端点上使用HTTP GET,而是要求在内省端点上使用HTTP POST方法。
To avoid disclosing the internal state of the authorization server, an introspection response for an inactive token SHOULD NOT contain any additional claims beyond the required "active" claim (with its value set to "false").
为避免披露授权服务器的内部状态,非活动令牌的内省响应不应包含超出所需“活动”声明(其值设置为“false”)的任何其他声明。
Since a protected resource MAY cache the response of the introspection endpoint, designers of an OAuth 2.0 system using this protocol MUST consider the performance and security trade-offs inherent in caching security information such as this. A less aggressive cache with a short timeout will provide the protected resource with more up-to-date information (due to it needing to query the introspection endpoint more often) at the cost of increased network traffic and load on the introspection endpoint. A more aggressive cache with a longer duration will minimize network traffic and load on the introspection endpoint, but at the risk of stale information about the token. For example, the token may be revoked while the protected resource is relying on the value of the cached response to make authorization decisions. This creates a window during which a revoked token could be used at the protected resource. Consequently, an acceptable cache validity duration needs to be carefully considered given the concerns and sensitivities of the protected resource being accessed and the likelihood of a token being revoked or invalidated in the interim period. Highly sensitive environments can opt to disable caching entirely on the protected resource to eliminate the risk of stale cached information entirely, again at the cost of increased network traffic and server load. If
由于受保护资源可能会缓存内省端点的响应,因此使用此协议的OAuth2系统的设计者必须考虑缓存安全信息所固有的性能和安全性权衡。具有较短超时的攻击性较小的缓存将为受保护的资源提供更多的最新信息(因为它需要更频繁地查询内省端点),但代价是增加网络流量和内省端点上的负载。更具攻击性且持续时间更长的缓存将最大限度地减少内省端点上的网络流量和负载,但会有关于令牌的陈旧信息的风险。例如,当受保护资源依赖于缓存响应的值来做出授权决策时,令牌可能被撤销。这将创建一个窗口,在此期间可在受保护的资源上使用已撤销的令牌。因此,考虑到所访问的受保护资源的关注点和敏感性以及令牌在过渡期间被撤销或失效的可能性,需要仔细考虑可接受的缓存有效期。高度敏感的环境可以选择完全禁用受保护资源上的缓存,以完全消除过时缓存信息的风险,这也是以增加网络流量和服务器负载为代价的。如果
the response contains the "exp" parameter (expiration), the response MUST NOT be cached beyond the time indicated therein.
响应包含“exp”参数(expiration),响应的缓存时间不得超过其中指示的时间。
An authorization server offering token introspection must be able to understand the token values being presented to it during this call. The exact means by which this happens is an implementation detail and is outside the scope of this specification. For unstructured tokens, this could take the form of a simple server-side database query against a data store containing the context information for the token. For structured tokens, this could take the form of the server parsing the token, validating its signature or other protection mechanisms, and returning the information contained in the token back to the protected resource (allowing the protected resource to be unaware of the token's contents, much like the client). Note that for tokens carrying encrypted information that is needed during the introspection process, the authorization server must be able to decrypt and validate the token to access this information. Also note that in cases where the authorization server stores no information about the token and has no means of accessing information about the token by parsing the token itself, it cannot likely offer an introspection service.
提供令牌内省的授权服务器必须能够理解在此调用期间呈现给它的令牌值。发生这种情况的确切方法是实现细节,不在本规范的范围之内。对于非结构化令牌,这可以采取对包含令牌上下文信息的数据存储进行简单服务器端数据库查询的形式。对于结构化令牌,这可能采取以下形式:服务器解析令牌,验证其签名或其他保护机制,并将令牌中包含的信息返回给受保护的资源(允许受保护的资源不知道令牌的内容,就像客户端一样)。请注意,对于携带内省过程中需要的加密信息的令牌,授权服务器必须能够解密和验证令牌以访问此信息。还要注意的是,在授权服务器不存储关于令牌的信息并且无法通过解析令牌本身来访问关于令牌的信息的情况下,它可能无法提供内省服务。
The introspection response may contain privacy-sensitive information such as user identifiers for resource owners. When this is the case, measures MUST be taken to prevent disclosure of this information to unintended parties. One method is to transmit user identifiers as opaque service-specific strings, potentially returning different identifiers to each protected resource.
内省响应可能包含隐私敏感信息,例如资源所有者的用户标识符。在这种情况下,必须采取措施防止向非预期方披露该信息。一种方法是将用户标识符作为不透明的特定于服务的字符串传输,可能会向每个受保护的资源返回不同的标识符。
If the protected resource sends additional information about the client's request to the authorization server (such as the client's IP address) using an extension of this specification, such information could have additional privacy considerations that the extension should detail. However, the nature and implications of such extensions are outside the scope of this specification.
如果受保护的资源使用此规范的扩展向授权服务器发送有关客户端请求的附加信息(例如客户端的IP地址),则此类信息可能具有扩展应详细说明的附加隐私注意事项。但是,此类扩展的性质和含义不在本规范的范围内。
Omitting privacy-sensitive information from an introspection response is the simplest way of minimizing privacy issues.
从内省响应中省略隐私敏感信息是最小化隐私问题的最简单方法。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <http://www.rfc-editor.org/info/rfc2119>.
[RFC2119]Bradner,S.,“RFC中用于表示需求水平的关键词”,BCP 14,RFC 2119,DOI 10.17487/RFC2119,1997年3月<http://www.rfc-editor.org/info/rfc2119>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, DOI 10.17487/RFC5226, May 2008, <http://www.rfc-editor.org/info/rfc5226>.
[RFC5226]Narten,T.和H.Alvestrand,“在RFCs中编写IANA注意事项部分的指南”,BCP 26,RFC 5226,DOI 10.17487/RFC5226,2008年5月<http://www.rfc-editor.org/info/rfc5226>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, <http://www.rfc-editor.org/info/rfc5246>.
[RFC5246]Dierks,T.和E.Rescorla,“传输层安全(TLS)协议版本1.2”,RFC 5246,DOI 10.17487/RFC5246,2008年8月<http://www.rfc-editor.org/info/rfc5246>.
[RFC6125] Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2011, <http://www.rfc-editor.org/info/rfc6125>.
[RFC6125]Saint Andre,P.和J.Hodges,“在传输层安全(TLS)环境下使用X.509(PKIX)证书在互联网公钥基础设施内表示和验证基于域的应用程序服务身份”,RFC 6125,DOI 10.17487/RFC6125,2011年3月<http://www.rfc-editor.org/info/rfc6125>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <http://www.rfc-editor.org/info/rfc6749>.
[RFC6749]Hardt,D.,Ed.“OAuth 2.0授权框架”,RFC 6749,DOI 10.17487/RFC6749,2012年10月<http://www.rfc-editor.org/info/rfc6749>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <http://www.rfc-editor.org/info/rfc6750>.
[RFC6750]Jones,M.和D.Hardt,“OAuth 2.0授权框架:承载令牌使用”,RFC 6750,DOI 10.17487/RFC6750,2012年10月<http://www.rfc-editor.org/info/rfc6750>.
[RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, August 2013, <http://www.rfc-editor.org/info/rfc7009>.
[RFC7009]Lodderstdt,T.,Ed.,Dronia,S.,和M.Scurtescu,“OAuth 2.0代币撤销”,RFC 7009,DOI 10.17487/RFC70092013年8月<http://www.rfc-editor.org/info/rfc7009>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, <http://www.rfc-editor.org/info/rfc7159>.
[RFC7159]Bray,T.,Ed.“JavaScript对象表示法(JSON)数据交换格式”,RFC 7159,DOI 10.17487/RFC7159,2014年3月<http://www.rfc-editor.org/info/rfc7159>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, <http://www.rfc-editor.org/info/rfc7231>.
[RFC7231]Fielding,R.,Ed.和J.Reschke,Ed.,“超文本传输协议(HTTP/1.1):语义和内容”,RFC 7231,DOI 10.17487/RFC72312014年6月<http://www.rfc-editor.org/info/rfc7231>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <http://www.rfc-editor.org/info/rfc7519>.
[RFC7519]Jones,M.,Bradley,J.和N.Sakimura,“JSON网络令牌(JWT)”,RFC 7519,DOI 10.17487/RFC7519,2015年5月<http://www.rfc-editor.org/info/rfc7519>.
[W3C.REC-html5-20141028] Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Navara, E., 0'Connor, E., and S. Pfeiffer, "HTML5", World Wide Web Consortium Recommendation REC-html5-20141028, October 2014, <http://www.w3.org/TR/2014/REC-html5-20141028>.
[W3C.REC-html5-20141028]希克森,I.,伯容,R.,福克纳,S.,莱西亚特,T.,纳瓦拉,E.,0'Connor,E.,和S.Pfeiffer,“html5”,万维网联盟建议REC-html5-20141028,2014年10月<http://www.w3.org/TR/2014/REC-html5-20141028>.
[BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, May 2015, <http://www.rfc-editor.org/info/bcp195>.
[BCP195]Sheffer,Y.,Holz,R.,和P.Saint Andre,“安全使用传输层安全性(TLS)和数据报传输层安全性(DTLS)的建议”,BCP 195,RFC 75252015年5月<http://www.rfc-editor.org/info/bcp195>.
With bearer tokens such as those defined by OAuth 2.0 Bearer Token Usage [RFC6750], the protected resource will have in its possession the entire secret portion of the token for submission to the introspection service. However, for proof-of-possession style tokens, the protected resource will have only a token identifier used during the request, along with the cryptographic signature on the request. To validate the signature on the request, the protected resource could be able to submit the token identifier to the authorization server's introspection endpoint to obtain the necessary key information needed for that token. The details of this usage are outside the scope of this specification and will be defined in an extension to this specification in concert with the definition of proof-of-possession tokens.
对于OAuth 2.0承载令牌用法[RFC6750]定义的承载令牌,受保护资源将拥有令牌的整个秘密部分,以提交给内省服务。但是,对于占有证明样式的令牌,受保护的资源在请求期间将仅使用令牌标识符以及请求上的加密签名。为了验证请求上的签名,受保护资源可以将令牌标识符提交给授权服务器的内省端点,以获得该令牌所需的必要密钥信息。此用法的详细信息不在本规范的范围内,将在本规范的扩展部分中定义,并与占有证明令牌的定义一致。
Acknowledgements
致谢
Thanks to the OAuth Working Group and the User Managed Access Working Group for feedback and review of this document, and to the various implementors of both the client and server components of this specification. In particular, the author would like to thank Amanda Anganes, John Bradley, Thomas Broyer, Brian Campbell, George Fletcher, Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel, Steve Moore, Mike Schwartz, Prabath Siriwardena, Sarah Squire, and Hannes Tschofennig.
感谢OAuth工作组和用户管理访问工作组对本文档的反馈和审查,以及本规范客户机和服务器组件的各种实现者。特别是,作者要感谢阿曼达·安加内斯、约翰·布拉德利、托马斯·布罗耶、布赖恩·坎贝尔、乔治·弗莱彻、保罗·弗里曼特尔、托马斯·哈德乔诺、伊夫·马勒、乔什·曼德尔、史蒂夫·摩尔、迈克·施瓦茨、普拉巴斯·西里沃德纳、莎拉·斯奎尔和汉内斯·乔芬尼。
Author's Address
作者地址
Justin Richer (editor)
贾斯汀·里希(编辑)
Email: ietf@justin.richer.org
Email: ietf@justin.richer.org