INTERNET-DRAFT Nat Sakimura Intended Status: Proposed Standard Nomura Research Institute Expires: May 10, 2014 November 6, 2013 OAuth 2.0 Registered JWT Profile 1.0 draft-sakimura-oauth-rjwtprof-01 Abstract This specification defines a profile of OAuth 2.0 framework that provides the holder of key facility for the compliant client. It achieves this without channel binding but solely based on the application protocol to make it easy for the client developers to develop such client. 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 Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of Nat Sakimura Expires May 10, 2014 [Page 1] INTERNET DRAFT OAuth 2.0 Registered JWT Profile 1.0 November 6, 2013 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 Notational Conventions . . . . . . . . . . . . . . . . . . 3 1.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Registered JWT . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Obtaining the Registered JWT . . . . . . . . . . . . . . . . . 4 4. Use of Registered JWT . . . . . . . . . . . . . . . . . . . . 5 4.1 Use of Registered JWT as a grant . . . . . . . . . . . . . . 5 4.1.1 Token request . . . . . . . . . . . . . . . . . . . . . 6 4.1.2 Token response . . . . . . . . . . . . . . . . . . . . . 6 4.1.3 Token error response . . . . . . . . . . . . . . . . . . 6 4.2 Use of Registered JWT as an access token . . . . . . . . . . 6 4.2.1 Resource request . . . . . . . . . . . . . . . . . . . . 6 4.2.2 Resource request verification . . . . . . . . . . . . . 7 4.2.3 Positive Response . . . . . . . . . . . . . . . . . . . 7 4.2.4 Error Response . . . . . . . . . . . . . . . . . . . . . 7 3 Security Considerations . . . . . . . . . . . . . . . . . . . . 8 4 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8 5 References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.1 Normative References . . . . . . . . . . . . . . . . . . . 8 5.2 Informative References . . . . . . . . . . . . . . . . . . 8 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 Nat Sakimura Expires May 10, 2014 [Page 2] INTERNET DRAFT OAuth 2.0 Registered JWT Profile 1.0 November 6, 2013 1 Introduction OAuth 2.0 Bearer Token Usage follows the "Bearer Instrument" pattern that the token is not registered to any party, thus the token can be used by any party that act as a bearer. The flexibility provided by this pattern is very flexible. However, when it has its weakness in the cases of token loss. This draft addresses the issue with another very popular pattern in the area of financial instruments called "registered instruments". In this case, the token is registered to a user, thus it will not be usable by any other party than the registered user whose identity can be verified through evidence of identity. To achieve the same effect as the "registered instruments", this draft uses JWT as the token type and defines two additional claims to make it possible to obtain the identifier of the rightful registered owner of the token. In addition, this draft defines a method to verify that the exerciser of the token is the registered owner of the token. 1.1 Notational Conventions 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 RFC 2119 [RFC2119]. 1.2 Terminology entity something that has separate and distinct existence and that can be identified in a context [ITU-T X.1252] Registered JWT JWS signed JWT that is registered to an entity Note: There are two main ways to achieve this. One is to have the identifier of the owner in the token itself, while the other is to provide an interface that returns the identifier of the owner when asked. Client JWK Public key of the client expressed in the JWK format 2. Registered JWT Nat Sakimura Expires May 10, 2014 [Page 3] INTERNET DRAFT OAuth 2.0 Registered JWT Profile 1.0 November 6, 2013 Registered JWT is a JWT with the following that is JWS signed by the issuer. The algorithm MUST be based on the public key cryptography such as RS256 or ES256 as defined in JWA. For Registered JWT, this document defines the two new claims for JWT. cjk The Client JWK associated with the entity. This is primarily used in the case that the registered owner (the authorized party) of the JWT will not change. cku String. Required if cjk is not available. A https URI from which the value of the Client JWK can be found. This is used in the case where the registered owner of the JWT will change over time. Following is a non-normative example of the JWT payload with the above claims. { "iss":"https://oauth.example.com/", "client_jwk": {"kty":"RSA", "n":"ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddx HmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMs D1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSH SXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdV MTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8 NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ", "e":"AQAB", "d":"Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97I jlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0 BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn 439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYT CBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLh BOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ" }, "aud":"https://resource.example.org/", "sub":"sakimura@example.com#1234", "exp":"2013-03-31T00:00:00Z" } 3. Obtaining the Registered JWT There can be many ways to obtain the Registered JWT but this specification defines one way to do so from the Authorization Endpoint. Nat Sakimura Expires May 10, 2014 [Page 4] INTERNET DRAFT OAuth 2.0 Registered JWT Profile 1.0 November 6, 2013 To obtain the Registered JWT from the Authorization Endpoint, the client sends the OAuth 2.0 authorization request to the authorization endpoint with the following parameter values. grant_type REQUIRED. The value MUST be "urn:ietf:params:oauth:grant-type:jwt- registered" client_id REQUIRED. RFC6749 defined client_id. public_key Base64url encoded JWK that contains the public key for the client. It is usually the JWK that was registered to the server, but it MAY be dynamically generated by the client as well in some circumstances. resonse_type REQUIRED. The value MUST be "code_jwtr". state RECOMMENDED. The state value defined in RFC6749. Once the request is verified and the user authorization was obtained, the server responds with the following parameters as in RFC6749. code REQUIRED. RFC6749 defined code. state REQUIRED. RFC6749 defined state. assertion REQUIRED. Registered JWT with the following member. iss REQUIRED. The issuer, which in this case is the authorization server. sub REQUIRED. The client_id. cjk REQUIRED. The Client JWK. The value MUST be the Base64url decoded public_key that was received in the request. exp REQUIRED. The JWS expiry date. nbf OPTIONAL. The nbf as defined in JWS. Other claims may be present. 4. Use of Registered JWT 4.1 Use of Registered JWT as a grant Nat Sakimura Expires May 10, 2014 [Page 5] INTERNET DRAFT OAuth 2.0 Registered JWT Profile 1.0 November 6, 2013 4.1.1 Token request When using as an extension grant, the following parameters are sent by POST to the token endpoint. grant_type "urn:ietf:params:oauth:grant-type:jwt-registered" assertion The assertion received from the authorization server. A JWS signed JWT with the following claims. request The JWS signed code. The key for signing MUST be the cjk in the assertion. The signing algorithm MUST match that of the key. 4.1.2 Token response Upon successful request, the token endpoint returns the response as in defined in RFC6749 except the following. token_type REQUIRED. The value MUST be "Registered" access_token REQUIRED. A Registered JWT that is JWS signed by the Authorization Server. The access token contains the following members as the payload. iss The issuer identifier. cjk REQUIRED. The Client JWK. The public key of the party that is allowed to exercise this token. aud OPTIONAL. The array of URIs of the protected resource that are allowed to consume this access token. 4.1.3 Token error response When an error occurs, an error response as defined in RFC6749 MUST be returned. 4.2 Use of Registered JWT as an access token 4.2.1 Resource request The obtained Registered JWT formatted access token can be used as follows. access_token The Registered JWT received as an access token. Nat Sakimura Expires May 10, 2014 [Page 6] INTERNET DRAFT OAuth 2.0 Registered JWT Profile 1.0 November 6, 2013 request A JWS signed JWT of which the body is a JSON object with the parameters and the values added as its member. The key used for the signing MUST be the value of cjk of the access token. It MUST contain the following member: jti The jti value defined in JWT. The server MUST keep the record of it between the iat and exp. exp The expiry date as defined in JWT. It MUST be set to a short time after signing. iat The iat as defined in JWT. 4.2.2 Resource request verification Upon receipt of the request, following verification steps MUST be performed. * the jti has not been seen in the past to thwart the replay attack. * the JWS of the value of the 'request' MUST be verified as in JWS. The key used MUST be the cjk in the assertion. 4.2.3 Positive Response The positive response is returned as the application specifies. 4.2.4 Error Response The error response follows section 3.1 of RFC6750. Nat Sakimura Expires May 10, 2014 [Page 7] INTERNET DRAFT OAuth 2.0 Registered JWT Profile 1.0 November 6, 2013 3 Security Considerations 4 IANA Considerations 5 References 5.1 Normative References 5.2 Informative References Authors' Addresses Nat Sakimura Nomura Research Institute EMail: sakimura@gmail.com Nat Sakimura Expires May 10, 2014 [Page 8]