INTERNET-DRAFT N. Sakimura Intended Status: Informational NRI Expires: August 22, 2013 B. Kihara, Ed Lepidum February 18, 2013 Structured Access Token for Sharing Authorization Grant in OpenID Connect draft-sakimura-oidc-structured-token-00 Abstract This specification defines a format of structured access tokens that are issued by the authorization server and received by the resource server in the OpenID Connect protocol. By using this format, the authorization server and the resource server can be easily separated and the validation of the access token can be performed offline. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/1id-abstracts.html The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html Copyright and License Notice Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Sakimura, et al. Expires August 22, 2013 [Page 1] INTERNET DRAFT Structured Access Token in OIDC February 2013 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Structured Access Token Format . . . . . . . . . . . . . . . . 4 2.1. "iss" (Issuer) Claim . . . . . . . . . . . . . . . . . . . 4 2.2. "sub" (Subject) Claim . . . . . . . . . . . . . . . . . . 4 2.3. "aud" (Audience) Claim . . . . . . . . . . . . . . . . . . 4 2.4. "exp" (Expiration Time) Claim . . . . . . . . . . . . . . 4 2.5. "nbf" (Not Before) Claim . . . . . . . . . . . . . . . . . 4 2.6. "iat" (Issued At) Claim . . . . . . . . . . . . . . . . . 4 2.7. "claims" Claim . . . . . . . . . . . . . . . . . . . . . . 4 2.8. "issued_for" Claim . . . . . . . . . . . . . . . . . . . . 5 3. Structured Access Token Usage . . . . . . . . . . . . . . . . 6 3.1. UserInfo Request . . . . . . . . . . . . . . . . . . . . . 6 3.2. Aggregated/Distributed Claims . . . . . . . . . . . . . . 7 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 8 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7.1. Normative References . . . . . . . . . . . . . . . . . . . 8 7.2. Informative References . . . . . . . . . . . . . . . . . . 8 Appendix A. Document History . . . . . . . . . . . . . . . . . . 9 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 Sakimura, et al. Expires August 22, 2013 [Page 2] INTERNET DRAFT Structured Access Token in OIDC February 2013 1. Introduction The OAuth 2.0 authorization framework ([RFC6749]) defines a method for third-party client authorization using access tokens. In OAuth, an authorization server issues an access token to a client, and the client requests resources from a resource server sending the access token. The OpenID Connect protocol ([OIDF.Connect.Standard]) is based on the OAuth framework; an OpenID provider as an authorization server issues an access token to a relying party as a client, and the relying party obtains claims about an entity from a resource server in exchange for the access token. In OAuth, an authorization server and a resource server need neither be the same server nor be closely-coupled. That is, a resource server may has to validate access tokens without information that is implicitly passed from authorization servers. The OAuth 2.0 ([RFC6749]) framework does not define methods for resource servers to validate access tokens and resource servers validate access tokens in implementation-defined behaviors. This specification defines a format of structured access tokens that are issued by the authorization server and received by the resource server in the OpenID Connect protocol ([OIDF.Connect.Standard]). By using this format, the authorization server and the resource server can be easily separated and the validation of the access token can be performed offline. The format of structured access tokens specified in this document is based on the JSON Web Token (JWT) format ([I-D.ietf-oauth-json-web- token]). [[Note: this document should be harmonized with the jwt-bearer draft.]] 1.1. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. Sakimura, et al. Expires August 22, 2013 [Page 3] INTERNET DRAFT Structured Access Token in OIDC February 2013 2. Structured Access Token Format A structured access token will be a JWT ([I-D.ietf-oauth-json-web- token]) that contains claims defined in the following sections and other claims. The JWT MUST be signed unless otherwise the authenticity of the JWT is assured. The JWT MAY be encrypted by the issuer. 2.1. "iss" (Issuer) Claim The "iss" (issuer) claim contains the identifier of the authorization server that issues the access token. Use of this claim is REQUIRED. 2.2. "sub" (Subject) Claim The "sub" (subject) claim contains the identifier of the entity whose claims are provided in exchange for the access token. The value of this claims needs to be shared between the authorization server and the resource server. Use of this claim is REQUIRED. 2.3. "aud" (Audience) Claim The "aud" (audience) claim contains the identifier of the resource server that receives the access token and returns claims. Use of this claim is REQUIRED. 2.4. "exp" (Expiration Time) Claim The "exp" (expiration time) claim contains the expiration time on or after which the JWT MUST NOT be accepted. The value is an integer of seconds from 1970-01-01T00:00:00Z. Use of this claim is REQUIRED. 2.5. "nbf" (Not Before) Claim The "nbf" (not before) claim contains the time before which the JWT MUST NOT be acceppted. The value is an integer of seconds from 1970- 01-01T00:00:00Z. Use of this claim is OPTIONAL. 2.6. "iat" (Issued At) Claim The "iat" (issued at) claim contains the time at which the JWT was issued. The value is an integer of seconds from 1970-01-01T00:00:00Z. Use of this claim is OPTIONAL. 2.7. "claims" Claim The "claims" claim contains the required claims about the entity identified by the "sub" claim. The value is an array of strings. Use Sakimura, et al. Expires August 22, 2013 [Page 4] INTERNET DRAFT Structured Access Token in OIDC February 2013 of this claim is OPTIONAL. 2.8. "issued_for" Claim The "issued_for" claim contains the identifier of the party which is intended to use the access token and to request resources. Use of this claim is OPTIONAL. [[Note: name should be considered.]] Sakimura, et al. Expires August 22, 2013 [Page 5] INTERNET DRAFT Structured Access Token in OIDC February 2013 3. Structured Access Token Usage Structured access tokens can be used for accessing protected resources like end-users' claims. The resource server and the authorization server need to share entities' identifiers beforehand in order to validate access tokens and provide resources by the "sub" claim. When a resource server received a structured access token, the resource server is RECOMMENDED to validate the token in the following criteria. Note that the validation criteria MAY vary by the contents of tokens. o The "aud" claim MUST be the identifier of the resource server or the value that the resource server can accept as the audience of the token. o The value of the "exp" claim MUST be more than the current time. o If the "nbf" claim exists, the value MUST be less than or equal to the current time. o If the "iat" claim exists, the value can be used to reject tokens that are issued at an unacceptable time (e.g., future or too far past). The acceptable range is determined by the resource server. o The token MUST be a valid JWT and signed by the authorization server identified by the "iss" claim. o The "iss" claim MUST be an identifier of an acceptable authorization server. The acceptable values MAY vary by the "sub" claim or other claims. o The "sub" claim MUST be a valid identifier of an entity. The value will be authorization-server specific, so the resource server needs to evaluate the "sub" claim together with the "iss" claim. o The authorization server specified by the "iss" claim MUST be granted to manage authorization by the entity specified by the "sub" claim. After validating a structured access token, a resource server will provide resources specified by the "claims" claim or other claims. 3.1. UserInfo Request When using a structured access token at UserInfo Endpoint, the "claims" claim will be used to specify requested claim names. The following The following is a non-normative example of a JSON object ([RFC4627]) that could be encoded into a JWT ([I-D.ietf-oauth-json-web-token]) for a UserInfo request: { Sakimura, et al. Expires August 22, 2013 [Page 6] INTERNET DRAFT Structured Access Token in OIDC February 2013 "aud":"https://op.example.com/", "iss":"https://op.example.com/", "sub":"alice", "exp":1360387733, "iat":1360386833, "nbf":1360385933, "claims": [ "gender", "picture" ], "issued_for":"https://rp.example.com/" } 3.2. Aggregated/Distributed Claims When using a structured access token for requesting claims to a claims provider in aggregated claims or distributed, the "claims" claim will be used alike the UserInfo request. Typically the claims provider and the OpenID provider will be separated parties, so they need to share the identifier of the entity specified by the "sub" claim beforehand. This may be done, for example, by the claims provider performing as a relying party to the OpenID provider. The following is a non-normative example of a JSON object ([RFC4627]) that could be encoded into JWT: { "aud":"https://cp.example.com/", "iss":"https://op.example.com/", "sub":"82FB7D5C-C6F1-4505-B230-796F31DF683E", // PPID from the OpenID provider to the claims provider "exp":1360847733, "iat":1360846833, "nbf":1360845933, "claims": [ "gender", "picture" ], "issued_for":"https://rp.example.com/" } Sakimura, et al. Expires August 22, 2013 [Page 7] INTERNET DRAFT Structured Access Token in OIDC February 2013 4. Security Considerations 5. Privacy Considerations 6. IANA Considerations 7. References 7.1. Normative References [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. [OIDF.Connect.Standard] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and E. Jay, "OpenID Connect Standard 1.0 - draft 16", January 2013. [I-D.ietf-oauth-json-web-token] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)," draft-ietf-oauth-json- web-token (work in progress), December 2012. 7.2. Informative References [RFC4627] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. [OIDF.Connect.Messages] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0 - draft 15", January 2013, . Sakimura, et al. Expires August 22, 2013 [Page 8] INTERNET DRAFT Structured Access Token in OIDC February 2013 Appendix A. Document History -00 o Initial draft. Authors' Addresses Nat Sakimura Nomura Research Institute EMail: n-sakimura@nri.co.jp Boku Kihara (editor) Lepidum Co. Ltd. EMail: kihara@lepidum.co.jp Sakimura, et al. Expires August 22, 2013 [Page 9]