diff options
| author | Andrew Arnott <andrewarnott@gmail.com> | 2012-02-05 19:52:27 -0800 |
|---|---|---|
| committer | Andrew Arnott <andrewarnott@gmail.com> | 2012-02-05 19:52:27 -0800 |
| commit | 7c9dcdb5374d47242e53b9930a3b38565f489ab1 (patch) | |
| tree | ebaa48071fb48d954537159c90374bfb1a06b951 /doc/specs | |
| parent | 07e74be175a23eae83eaf7affe3b24d9cec1513f (diff) | |
| download | DotNetOpenAuth-7c9dcdb5374d47242e53b9930a3b38565f489ab1.zip DotNetOpenAuth-7c9dcdb5374d47242e53b9930a3b38565f489ab1.tar.gz DotNetOpenAuth-7c9dcdb5374d47242e53b9930a3b38565f489ab1.tar.bz2 | |
Updated checked in copies of OAuth2 spec drafts.
Diffstat (limited to 'doc/specs')
| -rw-r--r-- | doc/specs/draft-ietf-oauth-v2-16.txt | 3080 | ||||
| -rw-r--r-- | doc/specs/draft-ietf-oauth-v2-23.txt | 3640 | ||||
| -rw-r--r-- | doc/specs/draft-ietf-oauth-v2-bearer-05.txt | 952 | ||||
| -rw-r--r-- | doc/specs/draft-ietf-oauth-v2-bearer.htm | 1748 | ||||
| -rw-r--r-- | doc/specs/draft-ietf-oauth-v2-bearer.txt | 1232 | ||||
| -rw-r--r-- | doc/specs/draft-ietf-oauth.html | 3072 | ||||
| -rw-r--r-- | doc/specs/draft-jones-json-web-token.htm | 1597 | ||||
| -rw-r--r-- | doc/specs/draft-jones-json-web-token.txt | 1232 |
8 files changed, 9449 insertions, 7104 deletions
diff --git a/doc/specs/draft-ietf-oauth-v2-16.txt b/doc/specs/draft-ietf-oauth-v2-16.txt deleted file mode 100644 index e997172..0000000 --- a/doc/specs/draft-ietf-oauth-v2-16.txt +++ /dev/null @@ -1,3080 +0,0 @@ - - - -Network Working Group E. Hammer-Lahav, Ed. -Internet-Draft Yahoo! -Obsoletes: 5849 (if approved) D. Recordon -Intended status: Standards Track Facebook -Expires: November 20, 2011 D. Hardt - Microsoft - May 19, 2011 - - - The OAuth 2.0 Authorization Protocol - draft-ietf-oauth-v2-16 - -Abstract - - The OAuth 2.0 authorization protocol enables a third-party - application to obtain limited access to an HTTP service, either on - behalf of an end-user by orchestrating an approval interaction - between the end-user and the HTTP service, or by allowing the third- - party application to obtain access on its own behalf. - -Status of this Memo - - This Internet-Draft is submitted in full conformance with the - provisions of BCP 78 and BCP 79. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF). Note that other groups may also distribute - working documents as Internet-Drafts. The list of current Internet- - Drafts is at http://datatracker.ietf.org/drafts/current/. - - 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." - - This Internet-Draft will expire on November 20, 2011. - -Copyright Notice - - Copyright (c) 2011 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 - 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 - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 1] - -Internet-Draft OAuth 2.0 May 2011 - - - 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 5 - 1.3. Access Token . . . . . . . . . . . . . . . . . . . . . . 6 - 1.4. Authorization Grant . . . . . . . . . . . . . . . . . . . 7 - 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9 - 1.6. Document Structure . . . . . . . . . . . . . . . . . . . 11 - 1.7. Notational Conventions . . . . . . . . . . . . . . . . . 11 - 2. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 11 - 2.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 12 - 2.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 13 - 3. Client Authentication . . . . . . . . . . . . . . . . . . . . 14 - 3.1. Client Password Authentication . . . . . . . . . . . . . 15 - 3.2. Other Client Authentication Methods . . . . . . . . . . . 16 - 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 16 - 4.1. Authorization Code . . . . . . . . . . . . . . . . . . . 16 - 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 22 - 4.3. Resource Owner Password Credentials . . . . . . . . . . . 28 - 4.4. Client Credentials . . . . . . . . . . . . . . . . . . . 30 - 4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . 32 - 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 33 - 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 33 - 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 34 - 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 36 - 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 37 - 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 38 - 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 38 - 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 38 - 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 39 - 8.3. Defining New Authorization Grant Types . . . . . . . . . 39 - 8.4. Defining Additional Error Codes . . . . . . . . . . . . . 39 - 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 40 - 10. Security Considerations . . . . . . . . . . . . . . . . . . . 41 - 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 42 - 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 42 - 10.3. Access Token Credentials . . . . . . . . . . . . . . . . 43 - 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 43 - 10.5. Request Confidentiality . . . . . . . . . . . . . . . . . 44 - 10.6. Endpoints Authenticity . . . . . . . . . . . . . . . . . 44 - 10.7. Credentials Guessing Attacks . . . . . . . . . . . . . . 44 - 10.8. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 44 - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 2] - -Internet-Draft OAuth 2.0 May 2011 - - - 10.9. Authorization Codes . . . . . . . . . . . . . . . . . . . 45 - 10.10. Session Fixation . . . . . . . . . . . . . . . . . . . . 45 - 10.11. Redirection URI Validation . . . . . . . . . . . . . . . 46 - 10.12. Resource Owner Password Credentials . . . . . . . . . . . 46 - 10.13. XSRF/CSRF Prevention . . . . . . . . . . . . . . . . . . 46 - 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 - 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 46 - 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 48 - 11.3. The OAuth Extensions Error Registry . . . . . . . . . . . 51 - 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 52 - Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 53 - 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53 - 13.1. Normative References . . . . . . . . . . . . . . . . . . 53 - 13.2. Informative References . . . . . . . . . . . . . . . . . 54 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 55 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 3] - -Internet-Draft OAuth 2.0 May 2011 - - -1. Introduction - - In the traditional client-server authentication model, the client - accesses a protected resource on the server by authenticating with - the server using the resource owner's credentials. In order to - provide third-party applications access to protected resources, the - resource owner shares its credentials with the third-party. This - creates several problems and limitations: - - o Third-party applications are required to store the resource- - owner's credentials for future use, typically a password in clear- - text. - o Servers are required to support password authentication, despite - the security weaknesses created by passwords. - o Third-party applications gain overly broad access to the resource- - owner's protected resources, leaving resource owners without any - ability to restrict duration or access to a limited subset of - resources. - o Resource owners cannot revoke access to an individual third-party - without revoking access to all third-parties, and must do so by - changing their password. - - OAuth addresses these issues by introducing an authorization layer - and separating the role of the client from that of the resource - owner. In OAuth, the client requests access to resources controlled - by the resource owner and hosted by the resource server, and is - issued a different set of credentials than those of the resource - owner. - - Instead of using the resource owner's credentials to access protected - resources, the client obtains an access token - a string denoting a - specific scope, duration, and other access attributes. Access tokens - are issued to third-party clients by an authorization server with the - approval of the resource owner. The client uses the access token to - access the protected resources hosted by the resource server. - - For example, a web end-user (resource owner) can grant a printing - service (client) access to her protected photos stored at a photo - sharing service (resource server), without sharing her username and - password with the printing service. Instead, she authenticates - directly with a server trusted by the photo sharing service - (authorization server) which issues the printing service delegation- - specific credentials (access token). - - This specification is designed for use with HTTP [RFC2616]. The use - of OAuth with any transport protocol other than HTTP is undefined. - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 4] - -Internet-Draft OAuth 2.0 May 2011 - - -1.1. Roles - - OAuth includes four roles working together to grant and provide - access to protected resources - access restricted resources which - require authentication to access: - - resource owner - An entity capable of granting access to a protected resource. - When the resource owner is a person, it is referred to as an end- - user. - resource server - The server hosting the protected resources, capable of accepting - and responding to protected resource requests using access tokens. - client - An application making protected resource requests on behalf of the - resource owner and with its authorization. - authorization server - The server issuing access tokens to the client after successfully - authenticating the resource owner and obtaining authorization. - - The interaction between the authorization server and resource server - is beyond the scope of this specification. The authorization server - may be the same server as the resource server or a separate entity. - A single authorization server may issue access tokens accepted by - multiple resource servers. - -1.2. Protocol Flow - - When interacting with the authorization server, the client identifies - itself using a set of client credentials which include a client - identifier and other authentication attributes. The means through - which the client obtains its credentials are beyond the scope of this - specification, but typically involve registration with the - authorization server. - - - - - - - - - - - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 5] - -Internet-Draft OAuth 2.0 May 2011 - - - +--------+ +---------------+ - | |--(A)- Authorization Request ->| Resource | - | | | Owner | - | |<-(B)-- Authorization Grant ---| | - | | +---------------+ - | | - | | Authorization Grant & +---------------+ - | |--(C)--- Client Credentials -->| Authorization | - | Client | | Server | - | |<-(D)----- Access Token -------| | - | | +---------------+ - | | - | | +---------------+ - | |--(E)----- Access Token ------>| Resource | - | | | Server | - | |<-(F)--- Protected Resource ---| | - +--------+ +---------------+ - - - Figure 1: Abstract Protocol Flow - - The abstract flow illustrated in Figure 1 describes the interaction - between the four roles and includes the following steps: - - (A) The client requests authorization from the resource owner. The - authorization request can be made directly to the resource owner - (as shown), or preferably indirectly via an intermediary such as - an authorization server. - (B) The client receives an authorization grant which represents the - authorization provided by the resource owner. The authorization - grant type depends on the method used by the client and - supported by the authorization server to obtain it. - (C) The client requests an access token by authenticating with the - authorization server using its client credentials (prearranged - between the client and authorization server) and presenting the - authorization grant. - (D) The authorization server validates the client credentials and - the authorization grant, and if valid issues an access token. - (E) The client requests the protected resource from the resource - server and authenticates by presenting the access token. - (F) The resource server validates the access token, and if valid, - serves the request. - -1.3. Access Token - - An access token is a string representing an authorization issued to - the client. The string is usually opaque to the client. Tokens - represent specific scopes and durations of access, granted by the - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 6] - -Internet-Draft OAuth 2.0 May 2011 - - - resource owner, and enforced by the resource server and authorization - server. - - The token may denote an identifier used to retrieve the authorization - information, or self-contain the authorization information in a - verifiable manner (i.e. a token string consisting of some data and a - signature). Additional authentication credentials may be required in - order for the client to use a token. - - The access token provides an abstraction layer, replacing different - authorization constructs (e.g. username and password) with a single - token understood by the resource server. This abstraction enables - issuing access tokens more restrictive than the authorization grant - used to obtain them, as well as removing the resource server's need - to understand a wide range of authentication methods. - - Access tokens can have different formats, structures, and methods of - utilization (e.g. cryptographic properties) based on the resource - server security requirements. Access token attributes and the - methods used to access protected resources are beyond the scope of - this specification and are defined by companion specifications. - -1.4. Authorization Grant - - An authorization grant is a general term used to describe the - intermediate credentials representing the resource owner - authorization (to access its protected resources), and serves as an - abstraction layer. An authorization grant is used by the client to - obtain an access token. - - This specification defines four grant types: authorization code, - implicit, resource owner password credentials, and client - credentials, as well as an extensibility mechanism for defining - additional types. - -1.4.1. Authorization Code - - The authorization code is obtained by using an authorization server - as an intermediary between the client and resource owner. Instead of - requesting authorization directly from the resource owner, the client - directs the resource owner to an authorization server (via its user- - agent as defined in [RFC2616]), which in turn directs the resource - owner back to the client with the authorization code. - - Before directing the resource owner back to the client with the - authorization code, the authorization server authenticates the - resource owner and obtains authorization. Because the resource owner - only authenticates with the authorization server, the resource - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 7] - -Internet-Draft OAuth 2.0 May 2011 - - - owner's credentials are never shared with the client. - - The authorization code provides a few important security benefits - such as the ability to authenticate the client and issuing the access - token directly to the client without potentially exposing it to - others, including the resource owner. - -1.4.2. Implicit - - When an access token is issued to the client directly as the result - of the resource owner authorization, without an intermediary - authorization grant (such as an authorization code), the grant is - considered implicit. - - When issuing an implicit grant, the authorization server cannot - verify the identity of the client, and the access token may be - exposed to the resource owner or other applications with access to - the resource owner's user-agent. - - Implicit grants improve the responsiveness and efficiency of some - clients (such as a client implemented as an in-browser application) - since it reduces the number of round trips required to obtain an - access token. - -1.4.3. Resource Owner Password Credentials - - The resource owner password credentials (e.g. a username and - password) can be used directly as an authorization grant to obtain an - access token. The credentials should only be used when there is a - high degree of trust between the resource owner and the client (e.g. - its computer operating system or a highly privileged application), - and when other authorization grant types are not available (such as - an authorization code). - - Even though this grant type requires direct client access to the - resource owner credentials, the resource owner credentials are used - for a single request and are exchanged for an access token. Unlike - the HTTP Basic authentication scheme defined in [RFC2617], this grant - type (when combined with a refresh token) eliminates the need for the - client to store the resource-owner credentials for future use. - -1.4.4. Client Credentials - - The client credentials can be used as an authorization grant when the - authorization scope is limited to the protected resources under the - control of the client, or to protected resources previously arranged - with the authorization server. Client credentials are used as an - authorization grant typically when the client is acting on its own - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 8] - -Internet-Draft OAuth 2.0 May 2011 - - - behalf (the client is also the resource owner). - -1.4.5. Extensions - - Additional grant types may be defined to provide a bridge between - OAuth and other protocols. For example, - [I-D.ietf-oauth-saml2-bearer] defines a SAML 2.0 - [OASIS.saml-core-2.0-os] bearer assertion grant type, which can be - used to obtain an access token. - -1.5. Refresh Token - - A refresh token is optionally issued by the authorization server to - the client together with an access token. The client can use the - refresh token to request another access token based on the same - authorization, without having to involve the resource owner again, or - having to retain the original authorization grant used to obtain the - initial access token. - - A refresh token is a string representing the authorization granted to - the client by the resource owner. The string is usually opaque to - the client. The token may denote an identifier used to retrieve the - authorization information, or self-contain the authorization - information in a verifiable manner. The refresh token is bound to - the client it was issued to, and its usage requires client - authentication. - - The refresh token can be used to obtain a new access token when the - current access token expires (access tokens may have a shorter - lifetime than authorized by the resource owner), no longer valid, or - to obtain additional access tokens with identical or narrower scope. - - - - - - - - - - - - - - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 9] - -Internet-Draft OAuth 2.0 May 2011 - - - +--------+ Authorization Grant & +---------------+ - | |--(A)-------- Client Credentials --------->| | - | | | | - | |<-(B)----------- Access Token -------------| | - | | & Refresh Token | | - | | | | - | | +----------+ | | - | |--(C)---- Access Token ---->| | | | - | | | | | | - | |<-(D)- Protected Resource --| Resource | | Authorization | - | Client | | Server | | Server | - | |--(E)---- Access Token ---->| | | | - | | | | | | - | |<-(F)- Invalid Token Error -| | | | - | | +----------+ | | - | | | | - | | Refresh Token & | | - | |--(G)-------- Client Credentials --------->| | - | | | | - | |<-(H)----------- Access Token -------------| | - +--------+ & Optional Refresh Token +---------------+ - - - Figure 2: Refreshing an Expired Access Token - - The flow illustrated in Figure 2 includes the following steps: - - (A) The client requests an access token by authenticating with the - authorization server using its client credentials, and - presenting an authorization grant. - (B) The authorization server validates the client credentials and - the authorization grant, and if valid issues an access token and - a refresh token. - (C) The client makes a protected resource requests to the resource - server by presenting the access token. - (D) The resource server validates the access token, and if valid, - serves the request. - (E) Steps (C) and (D) repeat until the access token expires. If the - client knows the access token expired, it skips to step (G), - otherwise it makes another protected resource request. - (F) Since the access token is invalid, the resource server returns - an invalid token error. - (G) The client requests a new access token by authenticating with - the authorization server using its client credentials, and - presenting the refresh token. - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 10] - -Internet-Draft OAuth 2.0 May 2011 - - - (H) The authorization server validates the client credentials and - the refresh token, and if valid issues a new access token (and - optionally, a new refresh token). - -1.6. Document Structure - - This specification is organized into the following sections: - - o Section 2 - describes the two endpoints used to obtain and utilize - the various authorization grant types. - o Section 3 - describes client identification and authentication in - general, and provides one such method for client authentication - using password credentials. - o Section 4 - describes the complete flow for each authorization - grant type, including requesting authorization, authorization - response, and requesting an access token. - o Section 5 - describes the common access token response used for - all non-implicit authorization grant types. - o Section 6 - describes the use of a refresh token to obtain - additional access tokens using the same resource owner - authorization. - o Section 7 - describes how access tokens are used to access - protected resources. - o Section 8 - describes how to extend certain elements of the - protocol. - o Section 9 - provides a security analysis of the protocol. - -1.7. Notational Conventions - - The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', - 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this - specification are to be interpreted as described in [RFC2119]. - - This specification uses the Augmented Backus-Naur Form (ABNF) - notation of [RFC5234]. - - Unless otherwise noted, all the protocol parameter names and values - are case sensitive. - - -2. Protocol Endpoints - - The authorization process utilizes two endpoints (HTTP resources): - - o Authorization endpoint - used to obtain authorization from the - resource owner via user-agent redirection. - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 11] - -Internet-Draft OAuth 2.0 May 2011 - - - o Token endpoint - used to exchange an authorization grant for an - access token, typically with client authentication. - - Not every authorization grant type utilizes both endpoints. - Extension grant types MAY define additional endpoints as needed. - -2.1. Authorization Endpoint - - The authorization endpoint is used to interact with the resource - owner and obtain authorization which is expressed explicitly as an - authorization code (exchanged for an access token), or implicitly by - direct issuance of an access token. - - The authorization server MUST first verify the identity of the - resource owner. The way in which the authorization server - authenticates the resource owner (e.g. username and password login, - session cookies) is beyond the scope of this specification. - - The means through which the client obtains the location of the - authorization endpoint are beyond the scope of this specification but - is typically provided in the service documentation. The endpoint URI - MAY include a query component as defined by [RFC3986] section 3, - which MUST be retained when adding additional query parameters. - - Since requests to the authorization endpoint result in user - authentication and the transmission of clear-text credentials (in the - HTTP response), the authorization server MUST require the use of a - transport-layer security mechanism when sending requests to the - authorization endpoint. The authorization server MUST support TLS - 1.2 as defined in [RFC5246], and MAY support additional transport- - layer mechanisms meeting its security requirements. - - The authorization server MUST support the use of the HTTP "GET" - method [RFC2616] for the authorization endpoint, and MAY support the - use of the "POST" method as well. - - The REQUIRED "response_type" request parameter is used to identify - which grant type the client is requesting: authorization code or - implicit, described in Section 4.1.1 and Section 4.2.1 respectively. - If the request is missing the "response_type" parameter, the - authorization server SHOULD return an error response as described in - Section 4.1.2.1. - - Parameters sent without a value MUST be treated as if they were - omitted from the request. The authorization server SHOULD ignore - unrecognized request parameters. - - Request and response parameters MUST NOT repeat more than once, - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 12] - -Internet-Draft OAuth 2.0 May 2011 - - - unless noted otherwise. - -2.1.1. Redirection URI - - The client directs the resource owner's user-agent to the - authorization endpoint and includes a redirection URI to which the - authorization server will redirect the user-agent back once - authorization has been obtained (or denied). The client MAY omit the - redirection URI if one has been established between the client and - authorization server via other means, such as during the client - registration process. - - The redirection URI MUST be an absolute URI and MAY include a query - component, which MUST be retained by the authorization server when - adding additional query parameters. - - The authorization server SHOULD require the client to pre-register - their redirection URI or at least certain components such as the - scheme, host, port and path. If a redirection URI was registered, - the authorization server MUST compare any redirection URI received at - the authorization endpoint with the registered URI. - - The authorization server SHOULD NOT redirect the user-agent to - unregistered or untrusted URIs to prevent the endpoint from being - used as an open redirector. If no valid redirection URI is - available, the authorization server SHOULD inform the resource owner - directly of the error. - -2.2. Token Endpoint - - The token endpoint is used by the client to obtain an access token by - authenticating with the authorization server and presenting its - authorization grant or refresh token. The token endpoint is used - with every authorization grant except for the implicit grant type - (since an access token is issued directly). - - The means through which the client obtains the location of the token - endpoint are beyond the scope of this specification but is typically - provided in the service documentation. The endpoint URI MAY include - a query component, which MUST be retained when adding additional - query parameters. - - Since requests to the token endpoint result in the transmission of - clear-text credentials (in the HTTP request and response), the - authorization server MUST require the use of a transport-layer - security mechanism when sending requests to the token endpoint. The - authorization server MUST support TLS 1.2 as defined in [RFC5246], - and MAY support additional transport-layer mechanisms meeting its - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 13] - -Internet-Draft OAuth 2.0 May 2011 - - - security requirements. - - The token endpoint requires client authentication as described in - Section 3. The authorization server MAY accept any form of client - authentication meeting its security requirements. The client MUST - NOT use more than one authentication method in each request. - - The client MUST use the HTTP "POST" method when making access token - requests. - - Parameters sent without a value MUST be treated as if they were - omitted from the request. The authorization server SHOULD ignore - unrecognized request parameters. - - Request and response parameters MUST NOT repeat more than once, - unless noted otherwise. - - -3. Client Authentication - - Client credentials are used to identify and authenticate the client. - The client credentials include a client identifier - a unique string - issued to the client to identify itself to the authorization server. - The client identifier is not a secret, it is exposed to the resource - owner, and MUST NOT be used alone for client authentication. Client - authentication is accomplished via additional means such as a - matching client password. - - The methods through which the client obtains its client credentials - are beyond the scope of this specification. However, the client - registration process typically includes gathering relevant - information which is used to educate the resource owner about the - client when requesting authorization. - - Due to the nature of some clients, the authorization server should - not make assumptions about the confidentiality of client credentials - without establishing trust with the client. The authorization server - SHOULD NOT issue client credentials to clients incapable of keeping - their credentials confidential (typically determined during the - client registration process). - - In addition, the authorization server MAY allow unauthenticated - access token requests when the client identity does not matter (e.g. - anonymous client) or when the client identity is established via - other means. For readability purposes only, this specification is - written under the assumption that the authorization server requires - some form of client authentication. However, such language does not - affect the authorization server's discretion in allowing - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 14] - -Internet-Draft OAuth 2.0 May 2011 - - - unauthenticated client requests. - -3.1. Client Password Authentication - - [[ Pending Consensus ]] - - Clients in possession of client password credentials (the client - identifier together with a shared symmetric secret) MAY use the HTTP - Basic authentication scheme as defined in [RFC2617] to authenticate - with the authorization server. The client identifier is used as the - username, and the secret is used as the password. - - When using the HTTP Basic authentication scheme, the client - identifier is included twice in the request (in the "Authorization" - header and in the "client_id" parameter). The authorization server - MUST ensure the two identifiers belong to the same client. - - For example (extra line breaks are for display purposes only): - - - POST /token HTTP/1.1 - Host: server.example.com - Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW - Content-Type: application/x-www-form-urlencoded - - grant_type=authorization_code&client_id=s6BhdRkqt3& - code=i1WsRn1uB1& - redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb - - - Alternatively, the authorization server MAY allow including the - client secret in the request body using the following parameter: - - client_secret - REQUIRED. The client secret. - - The use of the "client_secret" parameter is NOT RECOMMENDED, and - should be limited to clients unable to directly utilize the HTTP - Basic authentication scheme. - - - - - - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 15] - -Internet-Draft OAuth 2.0 May 2011 - - - For example (extra line breaks are for display purposes only): - - - POST /token HTTP/1.1 - Host: server.example.com - Content-Type: application/x-www-form-urlencoded - - grant_type=authorization_code&client_id=s6BhdRkqt3& - client_secret=gX1fBat3bV&code=i1WsRn1uB1& - redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb - - - Since requests using this authentication method result in the - transmission of clear-text credentials, the authorization server MUST - require the use of a transport-layer security mechanism when sending - requests to the token endpoint. - -3.2. Other Client Authentication Methods - - The authorization server MAY support any suitable HTTP authentication - scheme matching its security requirements. When using other - authentication methods, the authorization server MUST define a - mapping between the client identifier and the credentials used to - authenticate. - - -4. Obtaining Authorization - - To request an access token, the client obtains authorization from the - resource owner. The authorization is expressed in the form of an - authorization grant which the client uses to request the access - token. OAuth defines four grant types: authorization code, implicit, - resource owner password credentials, and client credentials. It also - provides an extension mechanism for defining additional grant types. - -4.1. Authorization Code - - The authorization code grant type is suitable for clients capable of - maintaining their client credentials confidential (for authenticating - with the authorization server) such as a client implemented on a - secure server. As a redirection-based flow, the client must be - capable of interacting with the resource owner's user-agent - (typically a web browser) and capable of receiving incoming requests - (via redirection) from the authorization server. - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 16] - -Internet-Draft OAuth 2.0 May 2011 - - - +----------+ - | resource | - | owner | - | | - +----------+ - ^ - | - (B) - +----|-----+ Client Identifier +---------------+ - | -+----(A)--- & Redirect URI ------>| | - | User- | | Authorization | - | Agent -+----(B)-- User authenticates --->| Server | - | | | | - | -+----(C)-- Authorization Code ---<| | - +-|----|---+ +---------------+ - | | ^ v - (A) (C) | | - | | | | - ^ v | | - +---------+ | | - | |>---(D)-- Client Credentials, --------' | - | | Authorization Code, | - | Client | & Redirect URI | - | | | - | |<---(E)----- Access Token -------------------' - +---------+ (w/ Optional Refresh Token) - - - Figure 3: Authorization Code Flow - - The flow illustrated in Figure 3 includes the following steps: - - (A) The client initiates the flow by directing the resource owner's - user-agent to the authorization endpoint. The client includes - its client identifier, requested scope, local state, and a - redirection URI to which the authorization server will send the - user-agent back once access is granted (or denied). - (B) The authorization server authenticates the resource owner (via - the user-agent) and establishes whether the resource owner - grants or denies the client's access request. - (C) Assuming the resource owner grants access, the authorization - server redirects the user-agent back to the client using the - redirection URI provided earlier. The redirection URI includes - an authorization code and any local state provided by the client - earlier. - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 17] - -Internet-Draft OAuth 2.0 May 2011 - - - (D) The client requests an access token from the authorization - server's token endpoint by authenticating using its client - credentials, and includes the authorization code received in the - previous step. The client includes the redirection URI used to - obtain the authorization code for verification. - (E) The authorization server validates the client credentials, the - authorization code, and ensures the redirection URI received - matches the URI used to redirect the client in step (C). If - valid, responds back with an access token. - -4.1.1. Authorization Request - - The client constructs the request URI by adding the following - parameters to the query component of the authorization endpoint URI - using the "application/x-www-form-urlencoded" format as defined by - [W3C.REC-html401-19991224]: - - response_type - REQUIRED. Value MUST be set to "code". - client_id - REQUIRED. The client identifier as described in Section 3. - redirect_uri - REQUIRED, unless a redirection URI has been established between - the client and authorization server via other means. Described - in Section 2.1.1. - scope - OPTIONAL. The scope of the access request expressed as a list - of space-delimited, case sensitive strings. The value is - defined by the authorization server. If the value contains - multiple space-delimited strings, their order does not matter, - and each string adds an additional access range to the - requested scope. - state - OPTIONAL. An opaque value used by the client to maintain state - between the request and callback. The authorization server - includes this value when redirecting the user-agent back to the - client. - - The client directs the resource owner to the constructed URI using an - HTTP redirection response, or by other means available to it via the - user-agent. - - For example, the client directs the user-agent to make the following - HTTP request using transport-layer security (extra line breaks are - for display purposes only): - - - GET /authorize?response_type=code&client_id=s6BhdRkqt3& - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 18] - -Internet-Draft OAuth 2.0 May 2011 - - - redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 - Host: server.example.com - - - The authorization server validates the request to ensure all required - parameters are present and valid. If the request is valid, the - authorization server authenticates the resource owner and obtains an - authorization decision (by asking the resource owner or by - establishing approval via other means). - - When a decision is established, the authorization server directs the - user-agent to the provided client redirection URI using an HTTP - redirection response, or by other means available to it via the user- - agent. - -4.1.2. Authorization Response - - If the resource owner grants the access request, the authorization - server issues an authorization code and delivers it to the client by - adding the following parameters to the query component of the - redirection URI using the "application/x-www-form-urlencoded" format: - - code - REQUIRED. The authorization code generated by the - authorization server. The authorization code SHOULD expire - shortly after it is issued to minimize the risk of leaks. The - client MUST NOT reuse the authorization code. If an - authorization code is used more than once, the authorization - server MAY revoke all tokens previously issued based on that - authorization code. The authorization code is bound to the - client identifier and redirection URI. - state - REQUIRED if the "state" parameter was present in the client - authorization request. Set to the exact value received from - the client. - - For example, the authorization server redirects the user-agent by - sending the following HTTP response: - - - HTTP/1.1 302 Found - Location: https://client.example.com/cb?code=i1WsRn1uB1 - - - The client SHOULD ignore unrecognized response parameters. The - authorization code string size is left undefined by this - specification. The client should avoid making assumptions about code - value sizes. The authorization server should document the size of - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 19] - -Internet-Draft OAuth 2.0 May 2011 - - - any value it issues. - -4.1.2.1. Error Response - - If the request fails due to a missing, invalid, or mismatching - redirection URI, or if the client identifier provided is invalid, the - authorization server SHOULD inform the resource owner of the error, - and MUST NOT redirect the user-agent to the invalid redirection URI. - - If the resource owner denies the access request or if the request - fails for reasons other than a missing or invalid redirection URI, - the authorization server informs the client by adding the following - parameters to the query component of the redirection URI using the - "application/x-www-form-urlencoded" format: - - error - REQUIRED. A single error code from the following: - invalid_request - The request is missing a required parameter, includes an - unsupported parameter or parameter value, or is otherwise - malformed. - unauthorized_client - The client is not authorized to request an authorization - code using this method. - access_denied - The resource owner or authorization server denied the - request. - unsupported_response_type - The authorization server does not support obtaining an - authorization code using this method. - invalid_scope - The requested scope is invalid, unknown, or malformed. - a 4xx or 5xx HTTP status code (except for 400 and 401) - The authorization server MAY set the "error" parameter - value to a numerical HTTP status code from the 4xx or 5xx - range, with the exception of the 400 (Bad Request) and - 401 (Unauthorized) status codes. For example, if the - service is temporarily unavailable, the authorization - server MAY return an error response with "error" set to - "503". - error_description - OPTIONAL. A human-readable text providing additional - information, used to assist in the understanding and resolution - of the error occurred. [[ add language and encoding information - ]] - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 20] - -Internet-Draft OAuth 2.0 May 2011 - - - error_uri - OPTIONAL. A URI identifying a human-readable web page with - information about the error, used to provide the resource owner - with additional information about the error. - state - REQUIRED if a valid "state" parameter was present in the client - authorization request. Set to the exact value received from - the client. - - For example, the authorization server redirects the user-agent by - sending the following HTTP response: - - - HTTP/1.1 302 Found - Location: https://client.example.com/cb?error=access_denied - - -4.1.3. Access Token Request - - The client makes a request to the token endpoint by adding the - following parameters using the "application/x-www-form-urlencoded" - format in the HTTP request entity-body: - - grant_type - REQUIRED. Value MUST be set to "authorization_code". - client_id - REQUIRED. The client identifier as described in Section 3. - code - REQUIRED. The authorization code received from the - authorization server. - redirect_uri - REQUIRED. The redirection URI used by the authorization server - to return the authorization response in the previous step. - - The client includes its authentication credentials as described in - Section 3 - - For example, the client makes the following HTTP using transport- - layer security (extra line breaks are for display purposes only): - - - POST /token HTTP/1.1 - Host: server.example.com - Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW - Content-Type: application/x-www-form-urlencoded - - grant_type=authorization_code&client_id=s6BhdRkqt3& - code=i1WsRn1uB1& - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 21] - -Internet-Draft OAuth 2.0 May 2011 - - - redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb - - - The authorization server MUST: - - o Validate the client credentials and ensure that the authorization - code was issued to that client. - o Verify that the authorization code is valid, and that the - redirection URI matches the redirection URI used by the - authorization server to deliver the authorization code. - -4.1.4. Access Token Response - - If the access token request is valid and authorized, the - authorization server issues an access token and optional refresh - token as described in Section 5.1. If the request client - authentication failed or is invalid, the authorization server returns - an error response as described in Section 5.2. - - An example successful response: - - - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-store - - { - "access_token":"SlAV32hkKG", - "token_type":"example", - "expires_in":3600, - "refresh_token":"8xLOxBtZp8", - "example_parameter":"example_value" - } - - -4.2. Implicit Grant - - The implicit grant type is suitable for clients incapable of - maintaining their client credentials confidential (for authenticating - with the authorization server) such as client applications residing - in a user-agent, typically implemented in a browser using a scripting - language such as JavaScript. - - As a redirection-based flow, the client must be capable of - interacting with the resource owner's user-agent (typically a web - browser) and capable of receiving incoming requests (via redirection) - from the authorization server. - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 22] - -Internet-Draft OAuth 2.0 May 2011 - - - Unlike the authorization code grant type in which the client makes - separate requests for authorization and access token, the client - receives the access token as the result of the authorization request. - - Using the implicit grant type does not include client authentication - since the client is unable to maintain their credential - confidentiality (the client resides on the resource owner's computer - or device which makes the client credentials accessible and - exploitable). Because the access token is encoded into the - redirection URI, it may be exposed to the resource owner and other - applications residing on its computer or device. - - - +----------+ - | Resource | - | Owner | - | | - +----------+ - ^ - | - (B) - +----|-----+ Client Identifier +---------------+ - | -+----(A)--- & Redirect URI ----->| | - | User- | | Authorization | - | Agent -|----(B)-- User authenticates -->| Server | - | | | | - | |<---(C)---- Redirect URI ------<| | - | | with Access Token +---------------+ - | | in Fragment - | | +---------------+ - | |----(D)---- Redirect URI ------>| Web Server | - | | without Fragment | with Client | - | | | Resource | - | (F) |<---(E)------- Script ---------<| | - | | +---------------+ - +-|--------+ - | | - (A) (G) Access Token - | | - ^ v - +---------+ - | | - | Client | - | | - +---------+ - - - Figure 4: Implicit Grant Flow - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 23] - -Internet-Draft OAuth 2.0 May 2011 - - - The flow illustrated in Figure 4 includes the following steps: - - (A) The client initiates the flow by directing the resource owner's - user-agent to the authorization endpoint. The client includes - its client identifier, requested scope, local state, and a - redirection URI to which the authorization server will send the - user-agent back once access is granted (or denied). - (B) The authorization server authenticates the resource owner (via - the user-agent) and establishes whether the resource owner - grants or denies the client's access request. - (C) Assuming the resource owner grants access, the authorization - server redirects the user-agent back to the client using the - redirection URI provided earlier. The redirection URI includes - the access token in the URI fragment. - (D) The user-agent follows the redirection instructions by making a - request to the web server (does not include the fragment). The - user-agent retains the fragment information locally. - (E) The web server returns a web page (typically an HTML document - with an embedded script) capable of accessing the full - redirection URI including the fragment retained by the user- - agent, and extracting the access token (and other parameters) - contained in the fragment. - (F) The user-agent executes the script provided by the web server - locally, which extracts the access token and passes it to the - client. - -4.2.1. Authorization Request - - The client constructs the request URI by adding the following - parameters to the query component of the authorization endpoint URI - using the "application/x-www-form-urlencoded" format: - - response_type - REQUIRED. Value MUST be set to "token". - client_id - REQUIRED. The client identifier as described in Section 3. - redirect_uri - REQUIRED, unless a redirection URI has been established between - the client and authorization server via other means. Described - in Section 2.1.1. - scope - OPTIONAL. The scope of the access request expressed as a list - of space-delimited, case sensitive strings. The value is - defined by the authorization server. If the value contains - multiple space-delimited strings, their order does not matter, - and each string adds an additional access range to the - requested scope. - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 24] - -Internet-Draft OAuth 2.0 May 2011 - - - state - OPTIONAL. An opaque value used by the client to maintain state - between the request and callback. The authorization server - includes this value when redirecting the user-agent back to the - client. - - The client directs the resource owner to the constructed URI using an - HTTP redirection response, or by other means available to it via the - user-agent. - - For example, the client directs the user-agent to make the following - HTTP request using transport-layer security (extra line breaks are - for display purposes only): - - - GET /authorize?response_type=token&client_id=s6BhdRkqt3& - redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 - Host: server.example.com - - - The authorization server validates the request to ensure all required - parameters are present and valid. If the request is valid, the - authorization server authenticates the resource owner and obtains an - authorization decision (by asking the resource owner or by - establishing approval via other means). - - When a decision is established, the authorization server directs the - user-agent to the provided client redirection URI using an HTTP - redirection response, or by other means available to it via the user- - agent. - -4.2.2. Access Token Response - - If the resource owner grants the access request, the authorization - server issues an access token and delivers it to the client by adding - the following parameters to the fragment component of the redirection - URI using the "application/x-www-form-urlencoded" format: - - access_token - REQUIRED. The access token issued by the authorization server. - token_type - REQUIRED. The type of the token issued as described in - Section 7.1. Value is case insensitive. - expires_in - OPTIONAL. The duration in seconds of the access token - lifetime. For example, the value "3600" denotes that the - access token will expire in one hour from the time the response - was generated. - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 25] - -Internet-Draft OAuth 2.0 May 2011 - - - scope - OPTIONAL. The scope of the access request expressed as a list - of space-delimited, case sensitive strings. The value is - defined by the authorization server. If the value contains - multiple space-delimited strings, their order does not matter, - and each string adds an additional access range to the - requested scope. The authorization server SHOULD include the - parameter if the requested scope is different from the one - requested by the client. - state - REQUIRED if the "state" parameter was present in the client - authorization request. Set to the exact value received from - the client. - - For example, the authorization server redirects the user-agent by - sending the following HTTP response (URI extra line breaks are for - display purposes only): - - - HTTP/1.1 302 Found - Location: http://example.com/rd#access_token=FJQbwq9& - token_type=example&expires_in=3600 - - - The client SHOULD ignore unrecognized response parameters. The - access token string size is left undefined by this specification. - The client should avoid making assumptions about value sizes. The - authorization server should document the size of any value it issues. - -4.2.2.1. Error Response - - If the request fails due to a missing, invalid, or mismatching - redirection URI, or if the client identifier provided is invalid, the - authorization server SHOULD inform the resource owner of the error, - and MUST NOT redirect the user-agent to the invalid redirection URI. - - If the resource owner denies the access request or if the request - fails for reasons other than a missing or invalid redirection URI, - the authorization server informs the client by adding the following - parameters to the fragment component of the redirection URI using the - "application/x-www-form-urlencoded" format: - - error - REQUIRED. A single error code from the following: - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 26] - -Internet-Draft OAuth 2.0 May 2011 - - - invalid_request - The request is missing a required parameter, includes an - unsupported parameter or parameter value, or is otherwise - malformed. - unauthorized_client - The client is not authorized to request an access token - using this method. - access_denied - The resource owner or authorization server denied the - request. - unsupported_response_type - The authorization server does not support obtaining an - access token using this method. - invalid_scope - The requested scope is invalid, unknown, or malformed. - a 4xx or 5xx HTTP status code (except for 400 and 401) - The authorization server MAY set the "error" parameter - value to a numerical HTTP status code from the 4xx or 5xx - range, with the exception of the 400 (Bad Request) and - 401 (Unauthorized) status codes. For example, if the - service is temporarily unavailable, the authorization - server MAY return an error response with "error" set to - "503". - error_description - OPTIONAL. A human-readable text providing additional - information, used to assist in the understanding and resolution - of the error occurred. [[ add language and encoding information - ]] - error_uri - OPTIONAL. A URI identifying a human-readable web page with - information about the error, used to provide the resource owner - with additional information about the error. - state - REQUIRED if a valid "state" parameter was present in the client - authorization request. Set to the exact value received from - the client. - - For example, the authorization server redirects the user-agent by - sending the following HTTP response: - - - HTTP/1.1 302 Found - Location: https://client.example.com/cb#error=access_denied - - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 27] - -Internet-Draft OAuth 2.0 May 2011 - - -4.3. Resource Owner Password Credentials - - The resource owner password credentials grant type is suitable in - cases where the resource owner has a trust relationship with the - client, such as its computer operating system or a highly privileged - application. The authorization server should take special care when - enabling the grant type, and only when other flows are not viable. - - The grant type is suitable for clients capable of obtaining the - resource owner credentials (username and password, typically using an - interactive form). It is also used to migrate existing clients using - direct authentication schemes such as HTTP Basic or Digest - authentication to OAuth by converting the stored credentials with an - access token. - - - +----------+ - | Resource | - | Owner | - | | - +----------+ - v - | - (A) Password Credentials - | - v - +---------+ +---------------+ - | | Client Credentials | | - | |>--(B)---- & Resource Owner ----->| | - | Client | Password Credentials | Authorization | - | | | Server | - | |<--(C)---- Access Token ---------<| | - | | (w/ Optional Refresh Token) | | - +---------+ +---------------+ - - - Figure 5: Resource Owner Password Credentials Flow - - The flow illustrated in Figure 5 includes the following steps: - - (A) The resource owner provides the client with its username and - password. - (B) The client requests an access token from the authorization - server's token endpoint by authenticating using its client - credentials, and includes the credentials received from the - resource owner. - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 28] - -Internet-Draft OAuth 2.0 May 2011 - - - (C) The authorization server validates the resource owner - credentials and the client credentials and issues an access - token. - -4.3.1. Authorization Request and Response - - The method through which the client obtains the resource owner - credentials is beyond the scope of this specification. The client - MUST discard the credentials once an access token has been obtained. - -4.3.2. Access Token Request - - The client makes a request to the token endpoint by adding the - following parameters using the "application/x-www-form-urlencoded" - format in the HTTP request entity-body: - - grant_type - REQUIRED. Value MUST be set to "password". - client_id - REQUIRED. The client identifier as described in Section 3. - username - REQUIRED. The resource owner username, encoded as UTF-8. - password - REQUIRED. The resource owner password, encoded as UTF-8. - scope - OPTIONAL. The scope of the access request expressed as a list - of space-delimited, case sensitive strings. The value is - defined by the authorization server. If the value contains - multiple space-delimited strings, their order does not matter, - and each string adds an additional access range to the - requested scope. - - The client includes its authentication credentials as described in - Section 3 - - For example, the client makes the following HTTP request using - transport-layer security (extra line breaks are for display purposes - only): - - - POST /token HTTP/1.1 - Host: server.example.com - Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW - Content-Type: application/x-www-form-urlencoded - - grant_type=password&client_id=s6BhdRkqt3& - username=johndoe&password=A3ddj3w - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 29] - -Internet-Draft OAuth 2.0 May 2011 - - - The authorization server MUST: - - o Validate the client credentials. - o Validate the resource owner password credentials. - -4.3.3. Access Token Response - - If the access token request is valid and authorized, the - authorization server issues an access token and optional refresh - token as described in Section 5.1. If the request failed client - authentication or is invalid, the authorization server returns an - error response as described in Section 5.2. - - An example successful response: - - - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-store - - { - "access_token":"SlAV32hkKG", - "token_type":"example", - "expires_in":3600, - "refresh_token":"8xLOxBtZp8", - "example_parameter":"example_value" - } - - -4.4. Client Credentials - - The client can request an access token using only its client - credentials when the client is requesting access to the protected - resources under its control, or those of another resource owner which - has been previously arranged with the authorization server (the - method of which is beyond the scope of this specification). - - - +---------+ +---------------+ - | | | | - | |>--(A)--- Client Credentials ---->| Authorization | - | Client | | Server | - | |<--(B)---- Access Token ---------<| | - | | (w/ Optional Refresh Token) | | - +---------+ +---------------+ - - - Figure 6: Client Credentials Flow - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 30] - -Internet-Draft OAuth 2.0 May 2011 - - - The flow illustrated in Figure 6 includes the following steps: - - (A) The client requests an access token from the token endpoint by - authenticating using its client credentials. - (B) The authorization server validates the client credentials and - issues an access token. - -4.4.1. Authorization Request and Response - - Since the client credentials are used as the authorization grant, no - additional authorization request is needed as the client is already - in the possession of its client credentials. - -4.4.2. Access Token Request - - The client makes a request to the token endpoint by adding the - following parameters using the "application/x-www-form-urlencoded" - format in the HTTP request entity-body: - - grant_type - REQUIRED. Value MUST be set to "client_credentials". - client_id - REQUIRED. The client identifier as described in Section 3. - scope - OPTIONAL. The scope of the access request expressed as a list - of space-delimited, case sensitive strings. The value is - defined by the authorization server. If the value contains - multiple space-delimited strings, their order does not matter, - and each string adds an additional access range to the - requested scope. - - The client includes its authentication credentials as described in - Section 3 - - For example, the client makes the following HTTP request using - transport-layer security (extra line breaks are for display purposes - only): - - - POST /token HTTP/1.1 - Host: server.example.com - Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW - Content-Type: application/x-www-form-urlencoded - - grant_type=client_credentials&client_id=s6BhdRkqt3 - - - The authorization server MUST validate the client credentials. - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 31] - -Internet-Draft OAuth 2.0 May 2011 - - -4.4.3. Access Token Response - - If the access token request is valid and authorized, the - authorization server issues an access token and optional refresh - token as described in Section 5.1. If the request failed client - authentication or is invalid, the authorization server returns an - error response as described in Section 5.2. - - An example successful response: - - - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-store - - { - "access_token":"SlAV32hkKG", - "token_type":"example", - "expires_in":3600, - "refresh_token":"8xLOxBtZp8", - "example_parameter":"example_value" - } - - -4.5. Extensions - - The client uses an extension grant type by specifying the grant type - using an absolute URI (defined by the authorization server) as the - value of the "grant_type" parameter of the token endpoint, and by - adding any additional parameters necessary. - - For example, to request an access token using a SAML 2.0 assertion - grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client - makes the following HTTP request using transport-layer security (line - breaks are for display purposes only): - - - POST /token HTTP/1.1 - Host: server.example.com - Content-Type: application/x-www-form-urlencoded - - grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fassertion%2F - saml%2F2.0%2Fbearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ - [...omitted for brevity...]V0aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- - - - If the access token request is valid and authorized, the - authorization server issues an access token and optional refresh - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 32] - -Internet-Draft OAuth 2.0 May 2011 - - - token as described in Section 5.1. If the request failed client - authentication or is invalid, the authorization server returns an - error response as described in Section 5.2. - - -5. Issuing an Access Token - - If the access token request is valid and authorized, the - authorization server issues an access token and optional refresh - token as described in Section 5.1. If the request failed client - authentication or is invalid, the authorization server returns an - error response as described in Section 5.2. - -5.1. Successful Response - - The authorization server issues an access token and optional refresh - token, and constructs the response by adding the following parameters - to the entity body of the HTTP response with a 200 (OK) status code: - - access_token - REQUIRED. The access token issued by the authorization server. - token_type - REQUIRED. The type of the token issued as described in - Section 7.1. Value is case insensitive. - expires_in - OPTIONAL. The duration in seconds of the access token - lifetime. For example, the value "3600" denotes that the - access token will expire in one hour from the time the response - was generated. - refresh_token - OPTIONAL. The refresh token which can be used to obtain new - access tokens using the same authorization grant as described - in Section 6. - scope - OPTIONAL. The scope of the access request expressed as a list - of space-delimited, case sensitive strings. The value is - defined by the authorization server. If the value contains - multiple space-delimited strings, their order does not matter, - and each string adds an additional access range to the - requested scope. The authorization server SHOULD include the - parameter if the requested scope is different from the one - requested by the client. - - The parameters are included in the entity body of the HTTP response - using the "application/json" media type as defined by [RFC4627]. The - parameters are serialized into a JSON structure by adding each - parameter at the highest structure level. Parameter names and string - values are included as JSON strings. Numerical values are included - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 33] - -Internet-Draft OAuth 2.0 May 2011 - - - as JSON numbers. - - The authorization server MUST include the HTTP "Cache-Control" - response header field [RFC2616] with a value of "no-store" in any - response containing tokens, secrets, or other sensitive information. - - For example: - - - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-store - - { - "access_token":"SlAV32hkKG", - "token_type":"example", - "expires_in":3600, - "refresh_token":"8xLOxBtZp8", - "example_parameter":"example_value" - } - - - The client SHOULD ignore unrecognized response parameters. The sizes - of tokens and other values received from the authorization server are - left undefined. The client should avoid making assumptions about - value sizes. The authorization server should document the size of - any value it issues. - -5.2. Error Response - - The authorization server responds with an HTTP 400 (Bad Request) - status code and includes the following parameters with the response: - - error - REQUIRED. A single error code from the following: - invalid_request - The request is missing a required parameter, includes an - unsupported parameter or parameter value, repeats a - parameter, includes multiple credentials, utilizes more - than one mechanism for authenticating the client, or is - otherwise malformed. - invalid_client - Client authentication failed (e.g. unknown client, no - client credentials included, multiple client credentials - included, or unsupported credentials type). The - authorization server MAY return an HTTP 401 - (Unauthorized) status code to indicate which HTTP - authentication schemes are supported. If the client - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 34] - -Internet-Draft OAuth 2.0 May 2011 - - - attempted to authenticate via the "Authorization" request - header field, the authorization server MUST respond with - an HTTP 401 (Unauthorized) status code, and include the - "WWW-Authenticate" response header field matching the - authentication scheme used by the client. - invalid_grant - The provided authorization grant is invalid, expired, - revoked, does not match the redirection URI used in the - authorization request, or was issued to another client. - unauthorized_client - The authenticated client is not authorized to use this - authorization grant type. - unsupported_grant_type - The authorization grant type is not supported by the - authorization server. - invalid_scope - The requested scope is invalid, unknown, malformed, or - exceeds the scope granted by the resource owner. - error_description - OPTIONAL. A human-readable text providing additional - information, used to assist in the understanding and resolution - of the error occurred. [[ add language and encoding information - ]] - error_uri - OPTIONAL. A URI identifying a human-readable web page with - information about the error, used to provide the resource owner - with additional information about the error. - - The parameters are included in the entity body of the HTTP response - using the "application/json" media type as defined by [RFC4627]. The - parameters are serialized into a JSON structure by adding each - parameter at the highest structure level. Parameter names and string - values are included as JSON strings. Numerical values are included - as JSON numbers. - - For example: - - - HTTP/1.1 400 Bad Request - Content-Type: application/json - Cache-Control: no-store - - { - "error":"invalid_request" - } - - - If the authorization server encounters an error condition other than - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 35] - -Internet-Draft OAuth 2.0 May 2011 - - - the 400 (Bad Request) and 401 (Unauthorized) responses described - above (e.g. the service is temporarily unavailable), the - authorization server SHOULD include an error response in the entity - body, and set the "error" parameter value to the numerical HTTP - status code returned. - - For example: - - - HTTP/1.1 503 Service Unavailable - Content-Type: application/json - - { - "error":"503" - } - - - -6. Refreshing an Access Token - - If the authorization server issued a refresh token to the client, the - client makes a refresh request to the token endpoint by adding the - following parameters using the "application/x-www-form-urlencoded" - format in the HTTP request entity-body: - - grant_type - REQUIRED. Value MUST be set to "refresh_token". - client_id - REQUIRED. The client identifier as described in Section 3. - refresh_token - REQUIRED. The refresh token issued to the client. - scope - OPTIONAL. The scope of the access request expressed as a list - of space-delimited, case sensitive strings. The value is - defined by the authorization server. If the value contains - multiple space-delimited strings, their order does not matter, - and each string adds an additional access range to the - requested scope. The requested scope MUST be equal or lesser - than the scope originally granted by the resource owner, and if - omitted is treated as equal to the scope originally granted by - the resource owner. - - The client includes its authentication credentials as described in - Section 3. - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 36] - -Internet-Draft OAuth 2.0 May 2011 - - - For example, the client makes the following HTTP request using - transport-layer security (extra line breaks are for display purposes - only): - - - POST /token HTTP/1.1 - Host: server.example.com - Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW - Content-Type: application/x-www-form-urlencoded - - grant_type=refresh_token&client_id=s6BhdRkqt3& - refresh_token=n4E9O119d - - - The authorization server MUST validate the client credentials, ensure - that the refresh token was issued to the authenticated client, - validate the refresh token, and verify that the resource owner's - authorization is still valid. If valid and authorized, the - authorization server issues an access token as described in - Section 5.1. If the request failed verification or is invalid, the - authorization server returns an error response as described in - Section 5.2. - - The authorization server MAY issue a new refresh token, in which - case, the client MUST discard the old refresh token and replace it - with the new refresh token. - - -7. Accessing Protected Resources - - The client accesses protected resources by presenting the access - token to the resource server. The resource server MUST validate the - access token and ensure it has not expired and that its scope covers - the requested resource. The methods used by the resource server to - validate the access token (as well as any error responses) are beyond - the scope of this specification, but generally involve an interaction - or coordination between the resource server and the authorization - server. - - The method in which the client utilized the access token to - authenticate with the resource server depends on the type of access - token issued by the authorization server. Typically, it involves - using the HTTP "Authorization" request header field [RFC2617] with an - authentication scheme defined by the access token type specification. - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 37] - -Internet-Draft OAuth 2.0 May 2011 - - -7.1. Access Token Types - - The access token type provides the client with the information - required to successfully utilize the access token to make a protected - resource request (along with type-specific attributes). The client - MUST NOT use an access token if it does not understand the token - type. - - For example, the "bearer" token type defined in - [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access - token string in the request: - - - GET /resource/1 HTTP/1.1 - Host: example.com - Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw - - - while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is - utilized by issuing a MAC key together with the access token which is - used to sign certain components of the HTTP requests: - - - GET /resource/1 HTTP/1.1 - Host: example.com - Authorization: MAC id="h480djs93hd8", - nonce="274312:dj83hs9s", - mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" - - - The above examples are provided for illustration purposes only. - Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and - [I-D.ietf-oauth-v2-http-mac] specifications before use. - - Each access token type definition specifies the additional attributes - (if any) sent to the client together with the "access_token" response - parameter. It also defines the HTTP authentication method used to - include the access token when making a protected resource request. - - -8. Extensibility - -8.1. Defining Access Token Types - - Access token types can be defined in one of two ways: registered in - the access token type registry (following the procedures in - Section 11.1), or use a unique absolute URI as its name. - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 38] - -Internet-Draft OAuth 2.0 May 2011 - - - Types utilizing a URI name SHOULD be limited to vendor-specific - implementations that are not commonly applicable, and are specific to - the implementation details of the resource server where they are - used. - - All other types MUST be registered. Type names MUST conform to the - type-name ABNF. If the type definition includes a new HTTP - authentication scheme, the type name SHOULD be identical to the HTTP - authentication scheme name (as defined by [RFC2617]). - - - type-name = 1*name-char - name-char = "-" / "." / "_" / DIGIT / ALPHA - - -8.2. Defining New Endpoint Parameters - - New request or response parameters for use with the authorization - endpoint or the token endpoint are defined and registered in the - parameters registry following the procedure in Section 11.2. - - Parameter names MUST conform to the param-name ABNF and parameter - values syntax MUST be well-defined (e.g., using ABNF, or a reference - to the syntax of an existing parameter). - - - param-name = 1*name-char - name-char = "-" / "." / "_" / DIGIT / ALPHA - - - Unregistered vendor-specific parameter extensions that are not - commonly applicable, and are specific to the implementation details - of the authorization server where they are used SHOULD utilize a - vendor-specific prefix that is not likely to conflict with other - registered values (e.g. begin with 'companyname_'). - -8.3. Defining New Authorization Grant Types - - New authorization grant types can be defined by assigning them a - unique absolute URI for use with the "grant_type" parameter. If the - extension grant type requires additional token endpoint parameters, - they MUST be registered in the OAuth parameters registry as described - by Section 11.2. - -8.4. Defining Additional Error Codes - - In cases where protocol extensions (i.e. access token types, - extension parameters, or extension grant types) require additional - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 39] - -Internet-Draft OAuth 2.0 May 2011 - - - error codes to be used with the authorization code grant error - response (Section 4.1.2.1), the implicit grant error response - (Section 4.2.2.1), or the token error response (Section 5.2), such - error codes MAY be defined. - - Extension error codes MUST be registered (following the procedures in - Section 11.3) if the extension they are used in conjunction with is a - registered access token type, a registered endpoint parameter, or an - extension grant type. Error codes used with unregistered extensions - MAY be registered. - - Error codes MUST conform to the error-code ABNF, and SHOULD be - prefixed by an identifying name when possible. For example, an error - identifying an invalid value set to the extension parameter "example" - should be named "example_invalid". - - - error-code = ALPHA *error-char - error-char = "-" / "." / "_" / DIGIT / ALPHA - - - -9. Native Applications - - [[ Pending consensus ]] - - A native application is a client which is installed and executes on - the end-user's device (i.e. desktop application, native mobile - application). Native applications are often capable of interacting - with (or embedding) a user-agent but are limited in how such - interactions affects their overall end-user experience. In many - cases, native applications are incapable of receiving redirection - requests from the authorization server (e.g. due to firewall rules, - operating system restrictions). - - Native applications can utilize OAuth in different ways, based on - their requirements and desired end-user experience: - - o Use the authorization code grant type flow described in - Section 4.1 by launching an external user-agent. The native - application can capture the response by providing a redirection - URI identifying a local (non-network) resource (registered with - the operating system to invoke the native application as handler), - or by providing a redirection URI identifying a server-hosted - resource under the native application's control, which in turn - makes the response available to the native application (e.g. using - the user-agent window title or other locations accessible from - outside the user-agent). - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 40] - -Internet-Draft OAuth 2.0 May 2011 - - - o Use the authorization code grant type flow described in - Section 4.1 by embedding a user-agent. The native application - obtains the response by directly communicating with the embedded - user-agent. Embedded user-agents are discouraged as they - typically provide a less consistent user experience and do not - enable the end-user to verify the authorization server's - authenticity. - - Native applications SHOULD use the authorization code grant type flow - without client password credentials (due to their inability to keep - the credentials confidential) to obtain short-lived access tokens, - and use refresh tokens to maintain access. - - When choosing between launching an external user-agent and an - embedding a user-agent, native application developers should consider - the following: - - o External user-agents may improve completion rate as the end-user - may already have an active session with the authorization server - removing the need to re-authenticate, and provide a familiar user- - agent user experience. The end-user may also rely on extensions - or add-ons to assist with authentication (e.g. password managers - or 2-factor device reader). - o Embedded user-agents often offer a better end-user flow, as they - remove the need to switch context and open new windows but also - may provide less familiar features than the external user-agent. - o Embedded user-agents pose a security challenge because end-users - are authenticating in an unidentified window without access to the - visual protections offered by many user-agents. Embedded user- - agents educate end-user to trust unidentified requests for - authentication (making phishing attacks easier to execute). - - -10. Security Considerations - - As a flexible and extensible framework, OAuth's security - considerations depend on many factors. The following sections - provide implementers with security guidelines focused on three common - client types: - - Web Application - A web application is a client running on a web server. End-users - access the client via an HTML user interface rendered in a user- - agent on the end-user's device. The client credentials as well as - any access token issued to the client are stored on the web server - and are not exposed to or accessible by the end-user. - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 41] - -Internet-Draft OAuth 2.0 May 2011 - - - User-Agent-based Application - A user-agent-based application is a client in which the client - code is downloaded from a web server and executes within a user- - agent on the end-user's device. The OAuth protocol data and - credentials are accessible to the end-user. Since such - applications directly reside within the user-agent, they can make - seamless use of the user-agent capabilities in the end-user - authorization process. - Native Application - A native application is a client which is installed and executes - on the end-user's device. The OAuth protocol data and credentials - are accessible to the end-user. It is assumed that such an - application can protect dynamically issued credentials, such as - refresh tokens, from eavesdropping by other applications residing - on the same device. - - A comprehensive OAuth security model and analysis, as well as - background for the protocol design is provided in - [I-D.lodderstedt-oauth-security]. - -10.1. Client Authentication - - The authorization server issues client credentials to web - applications for the purpose of authenticating them. The - authorization server is encouraged to consider using stronger client - authentication means than a client password. Application developers - MUST ensure confidentiality of client passwords and other - credentials. - - The authorization server MUST NOT issue client passwords or other - credentials to native or user-agent-based applications for the - purpose of client authentication. The authorization server MAY issue - a client password or other credentials for a specific installation of - a native application on a specific device. - -10.2. Client Impersonation - - Given the inability of some clients to keep their client credentials - confidential, a malicious client can impersonate another client and - obtain access to protected resources. The authorization server MUST - authenticate the client whenever possible. If the authorization - server cannot authenticate the a client due to the client's - limitations, the authorization server should utilize other means to - protect resource owners from such malicious clients, including but - not limited to engaging the end-user to assist in identifying the - client and its source. - - The authorization server SHOULD enforce explicit end-user - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 42] - -Internet-Draft OAuth 2.0 May 2011 - - - authentication, or prompt the end-user to authorize access again, - providing the end-user with information about the client, scope, and - duration of the authorization. It is up to the end-user to review - the information in the context of the current client, and authorize - the request. - - The authorization server SHOULD NOT automatically, without active - end-user interaction, process repeated authorization requests without - authenticating the client or relying on other measures to ensure the - repeated request comes from a valid client and not an impersonator. - - The authorization server SHOULD require the client to pre-register - its redirection URI and validate the value of the "redirect_uri" - against the pre-registered value. The client MUST NOT serve an open - redirector resource which can be used by an attacker to construct an - URI that will pass the authorization server's redirection URI - matching rules, and will redirect the end-user's user-agent to the - attacker's server. - - The authorization server SHOULD issue access tokens with limited - scope and duration to clients incapable of authenticating. - -10.3. Access Token Credentials - - Access token credentials MUST be kept confidential in transit and - storage, and shared only among the authorization server, the resource - servers the credentials are valid for, and the client to whom the - credentials were issued. - - When using the implicit grant type, the access token credentials are - transmitted in the URI fragment, which can expose the credentials to - unauthorized parties. - - The authorization server MUST ensure that access token credentials - cannot be generated, modified, or guessed to produce valid access - token credentials. - - The client SHOULD request access token credentials with the minimal - scope and duration necessary. The authorization server SHOULD take - the client identity into account when choosing to honor the requested - scope, and MAY issue credentials with a lesser scope than requested. - -10.4. Refresh Tokens - - Authorization servers MAY issue refresh tokens to web and native - applications. - - Refresh tokens MUST be kept confidential in transit and storage, and - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 43] - -Internet-Draft OAuth 2.0 May 2011 - - - shared only among the authorization server and the client to whom the - refresh tokens were issued. The authorization server MUST maintain - the link between a refresh token and the client to whom it was - issued. - - The authorization server MUST verify the link between the refresh - token and client identity whenever the client's identity can be - authenticated. When client authentication is not possible, the - authorization server SHOULD deploy other means to detect refresh - token abuse. - - The authorization server MUST ensure that refresh tokens cannot be - generated, modified, or guessed to produce valid refresh tokens. - -10.5. Request Confidentiality - - Access token credentials, refresh tokens, resource owner passwords, - and client secrets MUST NOT be transmitted in the clear. - Authorization codes SHOULD NOT be transmitted in the clear. - -10.6. Endpoints Authenticity - - In order to prevent man-in-the-middle and phishing attacks, the - authorization server MUST implement and require TLS with server-side - authentication in all exchanges. The client MUST verify the - authorization server's TLS certificate, as well as the respective - certificate chain. - -10.7. Credentials Guessing Attacks - - The authorization server MUST prevent attackers from guessing access - tokens, authorization codes, refresh tokens, resource owner - passwords, and client secrets. - - When generating tokens and other secrets not intended for direct - human utilization, the authorization server MUST use a reasonable - level of entropy in order to mitigate the risk of guessing attacks. - When creating secrets intended for human usage, the authorization - server MUST utilize other means to protect those secrets. - -10.8. Phishing Attacks - - Native applications SHOULD use external browsers instead of embedding - browsers within the application when requesting end-user - authorization. External browsers offer a familiar user experience - and a trusted environment in which end-users can confirm the - authenticity of the authorization server. - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 44] - -Internet-Draft OAuth 2.0 May 2011 - - - To reduce the risk of phishing attacks, the authorization servers - MUST utilize TLS to allow user-agents to validate the authorization - server's identity. Service providers should educate their end-users - about the risks of phishing attacks and how they can verify the - authorization server's identity. - -10.9. Authorization Codes - - The transmission of authorization codes SHOULD be made over a secure - channel, and the client SHOULD implement TLS for use with its - redirection URI if the URI identifies a network resource. - Authorization codes MUST be kept confidential. Since authorization - codes are transmitted via user-agent redirections, they could - potentially be disclosed through user-agent history and HTTP referrer - headers. - - Authorization codes operate as plaintext bearer credentials, used to - verify that the end-user who granted authorization at the - authorization server, is the same end-user returning to the client to - complete the process. Therefore, if the client relies on the - authorization code for its own end-user authentication, the client - redirection endpoint MUST require TLS. - - Authorization codes SHOULD be short lived and MUST be single use. If - the authorization server observes multiple attempts to exchange an - authorization code for an access token, the authorization server - SHOULD revoke all access tokens already granted based on the - compromised authorization code. - - If the client can be authenticated, the authorization servers MUST - authenticate the client and ensure that the authorization code was - issued to the same client. - -10.10. Session Fixation - - Session fixation attacks leverage the authorization code grant type, - by tricking an end-user to authorize access to a legitimate client, - but to a client account under the control of the attacker. The only - difference between a valid flow and the attack flow is in how the - victim reached the authorization server to grant access. Once at the - authorization server, the victim is prompted with a normal, valid - request on behalf of a legitimate and familiar client. The attacker - then uses the victim's authorization to gain access to the - information authorized by the victim. - - In order to prevent such an attack, authorization servers MUST ensure - that the redirection URI used to obtain the authorization code, is - the same as the redirection URI provided when exchanging the - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 45] - -Internet-Draft OAuth 2.0 May 2011 - - - authorization code for an access token. The authorization server - SHOULD require the client to pre-register their redirection URI and - if provided, MUST validate the redirection URI received in the - authorization request against the pre-registered value. - -10.11. Redirection URI Validation - - [[ Add specific recommendations about redirection validation and - matching ]] - -10.12. Resource Owner Password Credentials - - The resource owner password credentials grant type is often used for - legacy or migration reasons. It reduces the overall risk of storing - username and password in the client, but does not eliminate the need - to expose highly privileged credentials to the client. - - This grant type carries a higher risk than the other grant types - because it maintains the password anti-pattern OAuth seeks to avoid. - The client could abuse the password or the password could - unintentionally be disclosed to an attacker (e.g. via log files or - other records kept by the client). - - Additionally, because the resource owner does not have control over - the authorization process (the resource owner involvement ends when - it hands over its credentials to the client), the client can obtain - access tokens with a broader scope and longer duration than desired - by the resource owner. The authorization server SHOULD restrict the - scope and duration of access tokens issued via this grant type. - - The authorization server and client SHOULD minimize use of this grant - type and utilize other grant types whenever possible. - -10.13. XSRF/CSRF Prevention - - [[ Add text with reference to the 'state' parameter ]] - - -11. IANA Considerations - -11.1. The OAuth Access Token Type Registry - - This specification establishes the OAuth access token type registry. - - Access token types are registered on the advice of one or more - Designated Experts (appointed by the IESG or their delegate), with a - Specification Required (using terminology from [RFC5226]). However, - to allow for the allocation of values prior to publication, the - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 46] - -Internet-Draft OAuth 2.0 May 2011 - - - Designated Expert(s) may approve registration once they are satisfied - that such a specification will be published. - - Registration requests should be sent to the [TBD]@ietf.org mailing - list for review and comment, with an appropriate subject (e.g., - "Request for access toke type: example"). [[ Note to RFC-EDITOR: The - name of the mailing list should be determined in consultation with - the IESG and IANA. Suggested name: oauth-ext-review. ]] - - Within at most 14 days of the request, 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. - - Decisions (or lack thereof) made by the Designated Expert can be - first appealed to Application Area Directors (contactable using - app-ads@tools.ietf.org email address or directly by looking up their - email addresses on http://www.iesg.org/ website) and, if the - appellant is not satisfied with the response, to the full IESG (using - the iesg@iesg.org mailing list). - - IANA should only accept registry updates from the Designated - Expert(s), and should direct all requests for registration to the - review mailing list. - -11.1.1. Registration Template - - Type name: - The name requested (e.g., "example"). - Additional Token Endpoint Response Parameters: - Additional response parameters returned together with the - "access_token" parameter. New parameters MUST be separately - registered in the OAuth parameters registry as described by - Section 11.2. - HTTP Authentication Scheme(s): - The HTTP authentication scheme name(s), if any, used to - authenticate protected resources requests using access token of - this type. - Change controller: - For standards-track RFCs, state "IETF". For others, give the name - of the responsible party. Other details (e.g., postal address, - e-mail address, home page URI) may also be included. - Specification document(s): - Reference to document that specifies the parameter, preferably - including a URI that can be used to retrieve a copy of the - document. An indication of the relevant sections may also be - included, but is not required. - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 47] - -Internet-Draft OAuth 2.0 May 2011 - - -11.2. The OAuth Parameters Registry - - This specification establishes the OAuth parameters registry. - - Additional parameters for inclusion in the authorization endpoint - request, the authorization endpoint response, the token endpoint - request, or the token endpoint response, are registered on the advice - of one or more Designated Experts (appointed by the IESG or their - delegate), with a Specification Required (using terminology from - [RFC5226]). However, to allow for the allocation of values prior to - publication, the Designated Expert(s) may approve registration once - they are satisfied that such a specification will be published. - - Registration requests should be sent to the [TBD]@ietf.org mailing - list for review and comment, with an appropriate subject (e.g., - "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of - the mailing list should be determined in consultation with the IESG - and IANA. Suggested name: oauth-ext-review. ]] - - Within at most 14 days of the request, 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. - - Decisions (or lack thereof) made by the Designated Expert can be - first appealed to Application Area Directors (contactable using - app-ads@tools.ietf.org email address or directly by looking up their - email addresses on http://www.iesg.org/ website) and, if the - appellant is not satisfied with the response, to the full IESG (using - the iesg@iesg.org mailing list). - - IANA should only accept registry updates from the Designated - Expert(s), and should direct all requests for registration to the - review mailing list. - -11.2.1. Registration Template - - Parameter name: - The name requested (e.g., "example"). - Parameter usage location: - The location(s) where parameter can be used. The possible - locations are: authorization request, authorization response, - token request, or token response. - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 48] - -Internet-Draft OAuth 2.0 May 2011 - - - Change controller: - For standards-track RFCs, state "IETF". For others, give the name - of the responsible party. Other details (e.g., postal address, - e-mail address, home page URI) may also be included. - Specification document(s): - Reference to document that specifies the parameter, preferably - including a URI that can be used to retrieve a copy of the - document. An indication of the relevant sections may also be - included, but is not required. - -11.2.2. Initial Registry Contents - - The OAuth Parameters Registry's initial contents are: - - o Parameter name: client_id - o Parameter usage location: authorization request, token request - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: client_secret - o Parameter usage location: token request - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: response_type - o Parameter usage location: authorization request - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: redirect_uri - o Parameter usage location: authorization request, token request - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: scope - o Parameter usage location: authorization request, authorization - response, token request, token response - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: state - o Parameter usage location: authorization request, authorization - response - o Change controller: IETF - o Specification document(s): [[ this document ]] - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 49] - -Internet-Draft OAuth 2.0 May 2011 - - - o Parameter name: code - o Parameter usage location: authorization response, token request - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: error_description - o Parameter usage location: authorization response, token response - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: error_uri - o Parameter usage location: authorization response, token response - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: grant_type - o Parameter usage location: token request - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: access_token - o Parameter usage location: authorization response, token response - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: token_type - o Parameter usage location: authorization response, token response - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: expires_in - o Parameter usage location: authorization response, token response - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: username - o Parameter usage location: token request - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: password - o Parameter usage location: token request - o Change controller: IETF - o Specification document(s): [[ this document ]] - - o Parameter name: refresh_token - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 50] - -Internet-Draft OAuth 2.0 May 2011 - - - o Parameter usage location: token request, token response - o Change controller: IETF - o Specification document(s): [[ this document ]] - -11.3. The OAuth Extensions Error Registry - - This specification establishes the OAuth extensions error registry. - - Additional error codes used together with other protocol extensions - (i.e. extension grant types, access token types, or extension - parameters) are registered on the advice of one or more Designated - Experts (appointed by the IESG or their delegate), with a - Specification Required (using terminology from [RFC5226]). However, - to allow for the allocation of values prior to publication, the - Designated Expert(s) may approve registration once they are satisfied - that such a specification will be published. - - Registration requests should be sent to the [TBD]@ietf.org mailing - list for review and comment, with an appropriate subject (e.g., - "Request for error code: example"). [[ Note to RFC-EDITOR: The name - of the mailing list should be determined in consultation with the - IESG and IANA. Suggested name: oauth-ext-review. ]] - - Within at most 14 days of the request, 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. - - Decisions (or lack thereof) made by the Designated Expert can be - first appealed to Application Area Directors (contactable using - app-ads@tools.ietf.org email address or directly by looking up their - email addresses on http://www.iesg.org/ website) and, if the - appellant is not satisfied with the response, to the full IESG (using - the iesg@iesg.org mailing list). - - IANA should only accept registry updates from the Designated - Expert(s), and should direct all requests for registration to the - review mailing list. - -11.3.1. Registration Template - - Error name: - The name requested (e.g., "example"). - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 51] - -Internet-Draft OAuth 2.0 May 2011 - - - Error usage location: - The location(s) where the error can be used. The possible - locations are: authorization code grant error response - (Section 4.1.2.1), implicit grant error response - (Section 4.2.2.1), or token error response (Section 5.2). - Related protocol extension: - The name of the extension grant type, access token type, or - extension parameter, the error code is used in conjunction with. - Change controller: - For standards-track RFCs, state "IETF". For others, give the name - of the responsible party. Other details (e.g., postal address, - e-mail address, home page URI) may also be included. - Specification document(s): - Reference to document that specifies the error code, preferably - including a URI that can be used to retrieve a copy of the - document. An indication of the relevant sections may also be - included, but is not required. - - -12. Acknowledgements - - The initial OAuth 2.0 protocol specification was edited by David - Recordon, based on two previous publications: the OAuth 1.0 community - specification [RFC5849], and OAuth WRAP (OAuth Web Resource - Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security - Considerations section was drafted by Torsten Lodderstedt, Mark - McGloin, Phil Hunt, and Anthony Nadalin. - - The OAuth 1.0 community specification was edited by Eran Hammer-Lahav - and authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. - Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, - Kellan Elliott-McCrea, Larry Halff, Eran Hammer-Lahav, Ben Laurie, - Chris Messina, John Panzer, Sam Quigley, David Recordon, Eran - Sandler, Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy - Smith. - - The OAuth WRAP specification was edited by Dick Hardt and authored by - Brian Eaton, Yaron Goland, Dick Hardt, and Allen Tom. - - This specification is the work of the OAuth Working Group which - includes dozens of active and dedicated participants. In particular, - the following individuals contributed ideas, feedback, and wording - which shaped and formed the final specification: - - Michael Adams, Andrew Arnott, Dirk Balfanz, Scott Cantor, Blaine - Cook, Brian Campbell, Leah Culver, Bill de hOra, Brian Eaton, Brian - Ellin, Igor Faynberg, George Fletcher, Tim Freeman, Evan Gilbert, - Yaron Goland, Brent Goldman, Kristoffer Gronowski, Justin Hart, Craig - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 52] - -Internet-Draft OAuth 2.0 May 2011 - - - Heath, Phil Hunt, Michael B. Jones, John Kemp, Mark Kent, Raffi - Krikorian, Chasen Le Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui- - Lan Lu, Paul Madsen, Alastair Mair, Eve Maler, James Manger, Mark - McGloin, Laurence Miao, Chuck Mortimore, Justin Richer, Peter Saint- - Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, Luke - Shepard, Vlad Skvortsov, Justin Smith, Jeremy Suriel, Christian - Stuebner, Paul Tarjan, Allen Tom, Franklin Tse, Nick Walker, Skylar - Woodward. - - -Appendix A. Editor's Notes - - While many people contributed to this specification throughout its - long journey, the editor would like to acknowledge and thank a few - individuals for their outstanding and invaluable efforts leading up - to the publication of this specification. It is these individuals - without whom this work would not have existed, or reached its - successful conclusion. - - David Recordon for continuously being one of OAuth's most valuable - assets, bringing pragmatism and urgency to the work, and helping - shape it from its very beginning, as well as being one of the best - collaborators I had the pleasure of working with. - - Mark Nottingham for introducing OAuth to the IETF and setting the - community on this course. Lisa Dusseault for her support and - guidance as the Application area director. Blaine Cook, Peter Saint- - Andre, and Hannes Tschofenig for their work as working group chairs. - - James Manger for his creative ideas and always insightful feedback. - Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, - Marius Scurtescu, and Luke Shepard for their continued participation - and valuable feedback. - - Special thanks goes to Mike Curtis and Yahoo! for their unconditional - support of this work for over three years. - - -13. References - -13.1. Normative References - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., - Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext - Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 53] - -Internet-Draft OAuth 2.0 May 2011 - - - [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., - Leach, P., Luotonen, A., and L. Stewart, "HTTP - Authentication: Basic and Digest Access Authentication", - RFC 2617, June 1999. - - [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifier (URI): Generic Syntax", STD 66, - RFC 3986, January 2005. - - [RFC4627] Crockford, D., "The application/json Media Type for - JavaScript Object Notation (JSON)", RFC 4627, July 2006. - - [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 5226, - May 2008. - - [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", STD 68, RFC 5234, January 2008. - - [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security - (TLS) Protocol Version 1.2", RFC 5246, August 2008. - - [W3C.REC-html401-19991224] - Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 - Specification", World Wide Web Consortium - Recommendation REC-html401-19991224, December 1999, - <http://www.w3.org/TR/1999/REC-html401-19991224>. - -13.2. Informative References - - [I-D.draft-hardt-oauth-01] - Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth - Web Resource Authorization Profiles", January 2010. - - [I-D.ietf-oauth-saml2-bearer] - Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion - Grant Type Profile for OAuth 2.0", - draft-ietf-oauth-saml2-bearer-03 (work in progress), - February 2011. - - [I-D.ietf-oauth-v2-bearer] - Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 - Protocol: Bearer Tokens", draft-ietf-oauth-v2-bearer-04 - (work in progress), March 2011. - - [I-D.ietf-oauth-v2-http-mac] - Hammer-Lahav, E., Barth, A., and B. Adida, "HTTP - Authentication: MAC Access Authentication", - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 54] - -Internet-Draft OAuth 2.0 May 2011 - - - draft-ietf-oauth-v2-http-mac-00 (work in progress), - May 2011. - - [I-D.lodderstedt-oauth-security] - Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 - Threat Model and Security Considerations", - draft-lodderstedt-oauth-security-01 (work in progress), - March 2011. - - [OASIS.saml-core-2.0-os] - Cantor, S., Kemp, J., Philpott, R., and E. Maler, - "Assertions and Protocol for the OASIS Security Assertion - Markup Language (SAML) V2.0", OASIS Standard saml-core- - 2.0-os, March 2005. - - [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, - April 2010. - - -Authors' Addresses - - Eran Hammer-Lahav (editor) - Yahoo! - - Email: eran@hueniverse.com - URI: http://hueniverse.com - - - David Recordon - Facebook - - Email: dr@fb.com - URI: http://www.davidrecordon.com/ - - - Dick Hardt - Microsoft - - Email: dick.hardt@gmail.com - URI: http://dickhardt.org/ - - - - - - - - - - - -Hammer-Lahav, et al. Expires November 20, 2011 [Page 55] - diff --git a/doc/specs/draft-ietf-oauth-v2-23.txt b/doc/specs/draft-ietf-oauth-v2-23.txt new file mode 100644 index 0000000..4716e27 --- /dev/null +++ b/doc/specs/draft-ietf-oauth-v2-23.txt @@ -0,0 +1,3640 @@ + + + +Network Working Group E. Hammer, Ed. +Internet-Draft +Obsoletes: 5849 (if approved) D. Recordon +Intended status: Standards Track Facebook +Expires: July 24, 2012 D. Hardt + Microsoft + January 21, 2012 + + + The OAuth 2.0 Authorization Protocol + draft-ietf-oauth-v2-23 + +Abstract + + The OAuth 2.0 authorization protocol enables a third-party + application to obtain limited access to an HTTP service, either on + behalf of a resource owner by orchestrating an approval interaction + between the resource owner and the HTTP service, or by allowing the + third-party application to obtain access on its own behalf. This + specification replaces and obsoletes the OAuth 1.0 protocol described + in RFC 5849. + +Status of this Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + 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." + + This Internet-Draft will expire on July 24, 2012. + +Copyright Notice + + Copyright (c) 2012 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 + publication of this document. Please review these documents + + + +Hammer, et al. Expires July 24, 2012 [Page 1] + +Internet-Draft OAuth 2.0 January 2012 + + + 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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6 + 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 7 + 1.3.1. Authorization Code . . . . . . . . . . . . . . . . . . 7 + 1.3.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8 + 1.3.3. Resource Owner Password Credentials . . . . . . . . . 8 + 1.3.4. Client Credentials . . . . . . . . . . . . . . . . . . 9 + 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 + 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9 + 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 11 + 1.7. Interoperability . . . . . . . . . . . . . . . . . . . . 11 + 1.8. Notational Conventions . . . . . . . . . . . . . . . . . 12 + 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 12 + 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 13 + 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 14 + 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 14 + 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 15 + 2.3.2. Other Authentication Methods . . . . . . . . . . . . . 16 + 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 16 + 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 16 + 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 16 + 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 17 + 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 18 + 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 20 + 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 20 + 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 21 + 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 22 + 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 22 + 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 23 + 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 24 + 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 26 + 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 27 + 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 28 + 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 30 + 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 31 + 4.3. Resource Owner Password Credentials Grant . . . . . . . . 33 + 4.3.1. Authorization Request and Response . . . . . . . . . . 34 + 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 35 + + + +Hammer, et al. Expires July 24, 2012 [Page 2] + +Internet-Draft OAuth 2.0 January 2012 + + + 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 36 + 4.4. Client Credentials Grant . . . . . . . . . . . . . . . . 36 + 4.4.1. Authorization Request and Response . . . . . . . . . . 37 + 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 37 + 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 37 + 4.5. Extension Grants . . . . . . . . . . . . . . . . . . . . 38 + 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 39 + 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 39 + 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 40 + 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 42 + 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 43 + 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 43 + 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 44 + 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 44 + 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 45 + 8.3. Defining New Authorization Grant Types . . . . . . . . . 45 + 8.4. Defining New Authorization Endpoint Response Types . . . 45 + 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 46 + 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 46 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 47 + 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 48 + 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 48 + 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 49 + 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 49 + 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 50 + 10.6. Authorization Code Redirection URI Manipulation . . . . . 50 + 10.7. Resource Owner Password Credentials . . . . . . . . . . . 51 + 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 52 + 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 52 + 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 52 + 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 52 + 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 53 + 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 54 + 10.14. Code Injection and Input Validation . . . . . . . . . . . 54 + 10.15. Open Redirectors . . . . . . . . . . . . . . . . . . . . 55 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 + 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 55 + 11.1.1. Registration Template . . . . . . . . . . . . . . . . 56 + 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 56 + 11.2.1. Registration Template . . . . . . . . . . . . . . . . 57 + 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 57 + 11.3. The OAuth Authorization Endpoint Response Type + Registry . . . . . . . . . . . . . . . . . . . . . . . . 59 + 11.3.1. Registration Template . . . . . . . . . . . . . . . . 60 + 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 60 + 11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 60 + 11.4.1. Registration Template . . . . . . . . . . . . . . . . 61 + 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 62 + + + +Hammer, et al. Expires July 24, 2012 [Page 3] + +Internet-Draft OAuth 2.0 January 2012 + + + Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 63 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 63 + 13.1. Normative References . . . . . . . . . . . . . . . . . . 63 + 13.2. Informative References . . . . . . . . . . . . . . . . . 64 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 65 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 4] + +Internet-Draft OAuth 2.0 January 2012 + + +1. Introduction + + In the traditional client-server authentication model, the client + requests an access restricted resource (protected resource) on the + server by authenticating with the server using the resource owner's + credentials. In order to provide third-party applications access to + restricted resources, the resource owner shares its credentials with + the third-party. This creates several problems and limitations: + + o Third-party applications are required to store the resource + owner's credentials for future use, typically a password in clear- + text. + o Servers are required to support password authentication, despite + the security weaknesses created by passwords. + o Third-party applications gain overly broad access to the resource + owner's protected resources, leaving resource owners without any + ability to restrict duration or access to a limited subset of + resources. + o Resource owners cannot revoke access to an individual third-party + without revoking access to all third-parties, and must do so by + changing their password. + o Compromise of any third-party application results in compromise of + the end-user s password and all of the data protected by that + password. + + OAuth addresses these issues by introducing an authorization layer + and separating the role of the client from that of the resource + owner. In OAuth, the client requests access to resources controlled + by the resource owner and hosted by the resource server, and is + issued a different set of credentials than those of the resource + owner. + + Instead of using the resource owner's credentials to access protected + resources, the client obtains an access token - a string denoting a + specific scope, lifetime, and other access attributes. Access tokens + are issued to third-party clients by an authorization server with the + approval of the resource owner. The client uses the access token to + access the protected resources hosted by the resource server. + + For example, an end-user (resource owner) can grant a printing + service (client) access to her protected photos stored at a photo + sharing service (resource server), without sharing her username and + password with the printing service. Instead, she authenticates + directly with a server trusted by the photo sharing service + (authorization server) which issues the printing service delegation- + specific credentials (access token). + + This specification is designed for use with HTTP [RFC2616]. The use + + + +Hammer, et al. Expires July 24, 2012 [Page 5] + +Internet-Draft OAuth 2.0 January 2012 + + + of OAuth with any transport protocol other than HTTP is undefined. + +1.1. Roles + + OAuth defines four roles: + + resource owner + An entity capable of granting access to a protected resource (e.g. + end-user). + resource server + The server hosting the protected resources, capable of accepting + and responding to protected resource requests using access tokens. + client + An application making protected resource requests on behalf of the + resource owner and with its authorization. The term client does + not imply any particular implementation characteristics (e.g. + whether the application executes on a server, a desktop, or other + devices). + authorization server + The server issuing access tokens to the client after successfully + authenticating the resource owner and obtaining authorization. + + The interaction between the authorization server and resource server + is beyond the scope of this specification. The authorization server + may be the same server as the resource server or a separate entity. + A single authorization server may issue access tokens accepted by + multiple resource servers. + +1.2. Protocol Flow + + + +--------+ +---------------+ + | |--(A)- Authorization Request ->| Resource | + | | | Owner | + | |<-(B)-- Authorization Grant ---| | + | | +---------------+ + | | + | | +---------------+ + | |--(C)-- Authorization Grant -->| Authorization | + | Client | | Server | + | |<-(D)----- Access Token -------| | + | | +---------------+ + | | + | | +---------------+ + | |--(E)----- Access Token ------>| Resource | + | | | Server | + | |<-(F)--- Protected Resource ---| | + +--------+ +---------------+ + + + +Hammer, et al. Expires July 24, 2012 [Page 6] + +Internet-Draft OAuth 2.0 January 2012 + + + Figure 1: Abstract Protocol Flow + + The abstract flow illustrated in Figure 1 describes the interaction + between the four roles and includes the following steps: + + (A) The client requests authorization from the resource owner. The + authorization request can be made directly to the resource owner + (as shown), or preferably indirectly via the authorization + server as an intermediary. + (B) The client receives an authorization grant which is a credential + representing the resource owner's authorization, expressed using + one of four grant types defined in this specification or using + an extension grant type. The authorization grant type depends + on the method used by the client to request authorization and + the types supported by the authorization server. + (C) The client requests an access token by authenticating with the + authorization server and presenting the authorization grant. + (D) The authorization server authenticates the client and validates + the authorization grant, and if valid issues an access token. + (E) The client requests the protected resource from the resource + server and authenticates by presenting the access token. + (F) The resource server validates the access token, and if valid, + serves the request. + +1.3. Authorization Grant + + An authorization grant is a credential representing the resource + owner's authorization (to access its protected resources) used by the + client to obtain an access token. This specification defines four + grant types: authorization code, implicit, resource owner password + credentials, and client credentials, as well as an extensibility + mechanism for defining additional types. + +1.3.1. Authorization Code + + The authorization code is obtained by using an authorization server + as an intermediary between the client and resource owner. Instead of + requesting authorization directly from the resource owner, the client + directs the resource owner to an authorization server (via its user- + agent as defined in [RFC2616]), which in turn directs the resource + owner back to the client with the authorization code. + + Before directing the resource owner back to the client with the + authorization code, the authorization server authenticates the + resource owner and obtains authorization. Because the resource owner + only authenticates with the authorization server, the resource + owner's credentials are never shared with the client. + + + + +Hammer, et al. Expires July 24, 2012 [Page 7] + +Internet-Draft OAuth 2.0 January 2012 + + + The authorization code provides a few important security benefits + such as the ability to authenticate the client, and the transmission + of the access token directly to the client without passing it through + the resource owner's user-agent, potentially exposing it to others, + including the resource owner. + +1.3.2. Implicit + + The implicit grant is a simplified authorization code flow optimized + for clients implemented in a browser using a scripting language such + as JavaScript. In the implicit flow, instead of issuing the client + an authorization code, the client is issued an access token directly + (as the result of the resource owner authorization). The grant type + is implicit as no intermediate credentials (such as an authorization + code) are issued (and later used to obtain an access token). + + When issuing an access token during the implicit grant flow, the + authorization server does not authenticate the client. In some + cases, the client identity can be verified via the redirection URI + used to deliver the access token to the client. The access token may + be exposed to the resource owner or other applications with access to + the resource owner's user-agent. + + Implicit grants improve the responsiveness and efficiency of some + clients (such as a client implemented as an in-browser application) + since it reduces the number of round trips required to obtain an + access token. However, this convenience should be weighed against + the security implications of using implicit grants, especially when + the authorization code grant type is available. + +1.3.3. Resource Owner Password Credentials + + The resource owner password credentials (i.e. username and password) + can be used directly as an authorization grant to obtain an access + token. The credentials should only be used when there is a high + degree of trust between the resource owner and the client (e.g. the + client is part of the device operating system or a highly privileged + application), and when other authorization grant types are not + available (such as an authorization code). + + Even though this grant type requires direct client access to the + resource owner credentials, the resource owner credentials are used + for a single request and are exchanged for an access token. This + grant type can eliminate the need for the client to store the + resource owner credentials for future use, by exchanging the + credentials with a long-lived access token or refresh token. + + + + + +Hammer, et al. Expires July 24, 2012 [Page 8] + +Internet-Draft OAuth 2.0 January 2012 + + +1.3.4. Client Credentials + + The client credentials (or other forms of client authentication) can + be used as an authorization grant when the authorization scope is + limited to the protected resources under the control of the client, + or to protected resources previously arranged with the authorization + server. Client credentials are used as an authorization grant + typically when the client is acting on its own behalf (the client is + also the resource owner), or is requesting access to protected + resources based on an authorization previously arranged with the + authorization server. + +1.4. Access Token + + Access tokens are credentials used to access protected resources. An + access token is a string representing an authorization issued to the + client. The string is usually opaque to the client. Tokens + represent specific scopes and durations of access, granted by the + resource owner, and enforced by the resource server and authorization + server. + + The token may denote an identifier used to retrieve the authorization + information, or self-contain the authorization information in a + verifiable manner (i.e. a token string consisting of some data and a + signature). Additional authentication credentials, which are beyond + the scope of this specification, may be required in order for the + client to use a token. + + The access token provides an abstraction layer, replacing different + authorization constructs (e.g. username and password) with a single + token understood by the resource server. This abstraction enables + issuing access tokens more restrictive than the authorization grant + used to obtain them, as well as removing the resource server's need + to understand a wide range of authentication methods. + + Access tokens can have different formats, structures, and methods of + utilization (e.g. cryptographic properties) based on the resource + server security requirements. Access token attributes and the + methods used to access protected resources are beyond the scope of + this specification and are defined by companion specifications. + +1.5. Refresh Token + + Refresh tokens are credentials used to obtain access tokens. Refresh + tokens are issued to the client by the authorization server and are + used to obtain a new access token when the current access token + becomes invalid or expires, or to obtain additional access tokens + with identical or narrower scope (access tokens may have a shorter + + + +Hammer, et al. Expires July 24, 2012 [Page 9] + +Internet-Draft OAuth 2.0 January 2012 + + + lifetime and fewer permissions than authorized by the resource + owner). Issuing a refresh token is optional at the discretion of the + authorization server. If the authorization server issues a refresh + token, it is included when issuing an access token. + + A refresh token is a string representing the authorization granted to + the client by the resource owner. The string is usually opaque to + the client. The token denotes an identifier used to retrieve the + authorization information. Unlike access tokens, refresh tokens are + intended for use only with authorization servers and are never sent + to resource servers. + + + +--------+ +---------------+ + | |--(A)------- Authorization Grant --------->| | + | | | | + | |<-(B)----------- Access Token -------------| | + | | & Refresh Token | | + | | | | + | | +----------+ | | + | |--(C)---- Access Token ---->| | | | + | | | | | | + | |<-(D)- Protected Resource --| Resource | | Authorization | + | Client | | Server | | Server | + | |--(E)---- Access Token ---->| | | | + | | | | | | + | |<-(F)- Invalid Token Error -| | | | + | | +----------+ | | + | | | | + | |--(G)----------- Refresh Token ----------->| | + | | | | + | |<-(H)----------- Access Token -------------| | + +--------+ & Optional Refresh Token +---------------+ + + + Figure 2: Refreshing an Expired Access Token + + The flow illustrated in Figure 2 includes the following steps: + + (A) The client requests an access token by authenticating with the + authorization server, and presenting an authorization grant. + (B) The authorization server authenticates the client and validates + the authorization grant, and if valid issues an access token and + a refresh token. + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 10] + +Internet-Draft OAuth 2.0 January 2012 + + + (C) The client makes a protected resource request to the resource + server by presenting the access token. + (D) The resource server validates the access token, and if valid, + serves the request. + (E) Steps (C) and (D) repeat until the access token expires. If the + client knows the access token expired, it skips to step (G), + otherwise it makes another protected resource request. + (F) Since the access token is invalid, the resource server returns + an invalid token error. + (G) The client requests a new access token by authenticating with + the authorization server and presenting the refresh token. The + client authentication requirements are based on the client type + and on the authorization server policies. + (H) The authorization server authenticates the client and validates + the refresh token, and if valid issues a new access token (and + optionally, a new refresh token). + + Steps C, D, E, and F are outside the scope of this specification as + described in Section 7. + +1.6. TLS Version + + Whenever TLS is required by this specification, the appropriate + version (or versions) of TLS will vary over time, based on the + widespread deployment and known security vulnerabilities. At the + time of this writing, TLS version 1.2 [RFC5246] is the most recent + version, but has a very limited deployment base and might not be + readily available for implementation. TLS version 1.0 [RFC2246] is + the most widely deployed version, and will provide the broadest + interoperability. + + Implementations MAY also support additional transport-layer + mechanisms that meet their security requirements. + +1.7. Interoperability + + OAuth 2.0 provides a rich authorization framework with well-defined + security properties. However, as a rich and highly extensible + framework with many optional components, this specification is likely + to produce a wide range of non-interoperable implementations. In + addition, this specification leaves a few required components + partially or fully undefined (e.g. client registration, authorization + server capabilities, endpoint discovery). + + This protocol was design with the clear expectation that future work + will define prescriptive profiles and extensions necessary to achieve + full web-scale interoperability. + + + + +Hammer, et al. Expires July 24, 2012 [Page 11] + +Internet-Draft OAuth 2.0 January 2012 + + +1.8. Notational Conventions + + The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', + 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this + specification are to be interpreted as described in [RFC2119]. + + This specification uses the Augmented Backus-Naur Form (ABNF) + notation of [RFC5234]. + + Certain security-related terms are to be understood in the sense + defined in [RFC4949]. These terms include, but are not limited to, + 'attack', 'authentication', 'authorization', 'certificate', + 'confidentiality', 'credential', 'encryption', 'identity', 'sign', + 'signature', 'trust', 'validate', and 'verify'. + + Unless otherwise noted, all the protocol parameter names and values + are case sensitive. + + +2. Client Registration + + Before initiating the protocol, the client registers with the + authorization server. The means through which the client registers + with the authorization server are beyond the scope of this + specification, but typically involve end-user interaction with an + HTML registration form. + + Client registration does not require a direct interaction between the + client and the authorization server. When supported by the + authorization server, registration can rely on other means for + establishing trust and obtaining the required client properties (e.g. + redirection URI, client type). For example, registration can be + accomplished using a self-issued or third-party-issued assertion, or + by the authorization server performing client discovery using a + trusted channel. + + When registering a client, the client developer: + + o specifies the client type as described in Section 2.1, + o provides its client redirection URIs as described in + Section 3.1.2, and + o includes any other information required by the authorization + server (e.g. application name, website, description, logo image, + the acceptance of legal terms). + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 12] + +Internet-Draft OAuth 2.0 January 2012 + + +2.1. Client Types + + OAuth defines two client types, based on their ability to + authenticate securely with the authorization server (i.e. ability to + maintain the confidentiality of their client credentials): + + confidential + Clients capable of maintaining the confidentiality of their + credentials (e.g. client implemented on a secure server with + restricted access to the client credentials), or capable of secure + client authentication using other means. + public + Clients incapable of maintaining the confidentiality of their + credentials (e.g. clients executing on the device used by the + resource owner such as an installed native application or a web + browser-based application), and incapable of secure client + authentication via any other means. + + The client type designation is based on the authorization server's + definition of secure authentication and its acceptable exposure + levels of client credentials. + + The authorization server SHOULD NOT make assumptions about the client + type, nor accept the type information provided by the client + developer without first establishing trust. + + A client application consisting of multiple components, each with its + own client type (e.g. a distributed client with both a confidential + server-based component and a public browser-based component), MUST + register each component separately as a different client to ensure + proper handling by the authorization server. The authorization + server MAY provider tools to manage such complex clients through a + single administration interface. + + This specification has been designed around the following client + profiles: + + web application + A web application is a confidential client running on a web + server. Resource owners access the client via an HTML user + interface rendered in a user-agent on the device used by the + resource owner. The client credentials as well as any access + token issued to the client are stored on the web server and are + not exposed to or accessible by the resource owner. + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 13] + +Internet-Draft OAuth 2.0 January 2012 + + + user-agent-based application + A user-agent-based application is a public client in which the + client code is downloaded from a web server and executes within a + user-agent (e.g. web browser) on the device used by the resource + owner. Protocol data and credentials are easily accessible (and + often visible) to the resource owner. Since such applications + reside within the user-agent, they can make seamless use of the + user-agent capabilities when requesting authorization. + native application + A native application is a public client installed and executed on + the device used by the resource owner. Protocol data and + credentials are accessible to the resource owner. It is assumed + that any client authentication credentials included in the + application can be extracted. On the other hand, dynamically + issued credentials such as access tokens or refresh tokens can + receive an acceptable level of protection. At a minimum, these + credentials are protected from hostile servers with which the + application may interact with. On some platforms these + credentials might be protected from other applications residing on + the same device. + +2.2. Client Identifier + + The authorization server issues the registered client a client + identifier - a unique string representing the registration + information provided by the client. The client identifier is not a + secret, it is exposed to the resource owner, and MUST NOT be used + alone for client authentication. + +2.3. Client Authentication + + If the client type is confidential, the client and authorization + server establish a client authentication method suitable for the + security requirements of the authorization server. The authorization + server MAY accept any form of client authentication meeting its + security requirements. + + Confidential clients are typically issued (or establish) a set of + client credentials used for authenticating with the authorization + server (e.g. password, public/private key pair). + + The authorization server MAY establish a client authentication method + with public clients. However, the authorization server MUST NOT rely + on public client authentication for the purpose of identifying the + client. + + The client MUST NOT use more than one authentication method in each + request. + + + +Hammer, et al. Expires July 24, 2012 [Page 14] + +Internet-Draft OAuth 2.0 January 2012 + + +2.3.1. Client Password + + Clients in possession of a client password MAY use the HTTP Basic + authentication scheme as defined in [RFC2617] to authenticate with + the authorization server. The client identifier is used as the + username, and the client password is used as the password. The + authorization server MUST support the HTTP Basic authentication + scheme for authenticating clients which were issued a client + password. + + For example (extra line breaks are for display purposes only): + + + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW + + + Alternatively, the authorization server MAY support including the + client credentials in the request body using the following + parameters: + + client_id + REQUIRED. The client identifier issued to the client during + the registration process described by Section 2.2. + client_secret + REQUIRED. The client secret. The client MAY omit the + parameter if the client secret is an empty string. + + Including the client credentials in the request body using the two + parameters is NOT RECOMMENDED, and should be limited to clients + unable to directly utilize the HTTP Basic authentication scheme (or + other password-based HTTP authentication schemes). The parameters + can only be transmitted in the request body and MUST NOT be included + in the request URI. + + For example, requesting to refresh an access token (Section 6) using + the body parameters (extra line breaks are for display purposes + only): + + + POST /token HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded;charset=UTF-8 + + grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA + &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw + + + The authorization server MUST require TLS as described in Section 1.6 + + + +Hammer, et al. Expires July 24, 2012 [Page 15] + +Internet-Draft OAuth 2.0 January 2012 + + + when sending requests using password authentication. + + Since this client authentication method involves a password, the + authorization server MUST protect any endpoint utilizing it against + brute force attacks. + +2.3.2. Other Authentication Methods + + The authorization server MAY support any suitable HTTP authentication + scheme matching its security requirements. When using other + authentication methods, the authorization server MUST define a + mapping between the client identifier (registration record) and + authentication scheme. + +2.4. Unregistered Clients + + This specification does not exclude the use of unregistered clients. + However, the use with such clients is beyond the scope of this + specification, and requires additional security analysis and review + of its interoperability impact. + + +3. Protocol Endpoints + + The authorization process utilizes two authorization server endpoints + (HTTP resources): + + o Authorization endpoint - used to obtain authorization from the + resource owner via user-agent redirection. + o Token endpoint - used to exchange an authorization grant for an + access token, typically with client authentication. + + As well as one client endpoint: + + o Redirection endpoint - used to return authorization credentials + responses from the authorization server to the client via the + resource owner user-agent. + + Not every authorization grant type utilizes both endpoints. + Extension grant types MAY define additional endpoints as needed. + +3.1. Authorization Endpoint + + The authorization endpoint is used to interact with the resource + owner and obtain an authorization grant. The authorization server + MUST first verify the identity of the resource owner. The way in + which the authorization server authenticates the resource owner (e.g. + username and password login, session cookies) is beyond the scope of + + + +Hammer, et al. Expires July 24, 2012 [Page 16] + +Internet-Draft OAuth 2.0 January 2012 + + + this specification. + + The means through which the client obtains the location of the + authorization endpoint are beyond the scope of this specification, + but the location is typically provided in the service documentation. + + The endpoint URI MAY include an "application/x-www-form-urlencoded" + formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] + section 3.4), which MUST be retained when adding additional query + parameters. The endpoint URI MUST NOT include a fragment component. + + Since requests to the authorization endpoint result in user + authentication and the transmission of clear-text credentials (in the + HTTP response), the authorization server MUST require TLS as + described in Section 1.6 when sending requests to the authorization + endpoint. + + The authorization server MUST support the use of the HTTP "GET" + method [RFC2616] for the authorization endpoint, and MAY support the + use of the "POST" method as well. + + Parameters sent without a value MUST be treated as if they were + omitted from the request. The authorization server MUST ignore + unrecognized request parameters. Request and response parameters + MUST NOT be included more than once. + +3.1.1. Response Type + + The authorization endpoint is used by the authorization code grant + type and implicit grant type flows. The client informs the + authorization server of the desired grant type using the following + parameter: + + response_type + REQUIRED. The value MUST be one of "code" for requesting an + authorization code as described by Section 4.1.1, "token" for + requesting an access token (implicit grant) as described by + Section 4.2.1, or a registered extension value as described by + Section 8.4. + + Extension response types MAY contain a space-delimited (%x20) list of + values, where the order of values does not matter (e.g. response type + "a b" is the same as "b a"). The meaning of such composite response + types is defined by their respective specifications. + + If an authorization request is missing the "response_type" parameter, + the authorization server MUST return an error response as described + in Section 4.1.2.1. + + + +Hammer, et al. Expires July 24, 2012 [Page 17] + +Internet-Draft OAuth 2.0 January 2012 + + +3.1.2. Redirection Endpoint + + After completing its interaction with the resource owner, the + authorization server directs the resource owner's user-agent back to + the client. The authorization server redirects the user-agent to the + client's redirection endpoint previously established with the + authorization server during the client registration process or when + making the authorization request. + + The redirection endpoint URI MUST be an absolute URI as defined by + [RFC3986] section 4.3. The endpoint URI MAY include an + "application/x-www-form-urlencoded" formatted + ([W3C.REC-html401-19991224]) query component ([RFC3986] section 3.4), + which MUST be retained when adding additional query parameters. The + endpoint URI MUST NOT include a fragment component. + +3.1.2.1. Endpoint Request Confidentiality + + The redirection endpoint SHOULD require the use of TLS as described + in Section 1.6 when the requested response type is "code" or "token", + or when the redirection request will result in the transmission of + sensitive credentials over an open network. This specification does + not mandate the use of TLS because at the time of this writing, + requiring clients to deploy TLS is a significant hurdle for most + client developers. + + Lack of transport-layer security can have a severe impact on the + security of the client and the protected resources it is authorized + to access. The use of transport-layer security is particularly + critical when the authorization process is used as a form of + delegated end-user authentication by the client (e.g. third-party + sign-in service). + +3.1.2.2. Registration Requirements + + The authorization server MUST require the following clients to + register their redirection endpoint: + + o Public clients. + o Confidential clients utilizing the implicit grant type. + + The authorization server SHOULD require all clients to register their + redirection endpoint prior to utilizing the authorization endpoint + + The authorization server SHOULD require the client to provide the + complete redirection URI (the client MAY use the "state" request + parameter to achieve per-request customization). If requiring the + registration of the complete redirection URI is not possible, the + + + +Hammer, et al. Expires July 24, 2012 [Page 18] + +Internet-Draft OAuth 2.0 January 2012 + + + authorization server SHOULD require the registration of the URI + scheme, authority, and path (allowing the client to dynamically vary + only the query component of the redirection URI when requesting + authorization). + + The authorization server MAY allow the client to register multiple + redirection endpoints. + + Lack of a redirection URI registration requirement can enable an + attacker to use the authorization endpoint as open redirector as + described in Section 10.15. + +3.1.2.3. Dynamic Configuration + + If multiple redirection URIs have been registered, if only part of + the redirection URI has been registered, or if no redirection URI has + been registered, the client MUST include a redirection URI with the + authorization request using the "redirect_uri" request parameter. + + When a redirection URI is included in an authorization request, the + authorization server MUST compare and match the value received + against at least one of the registered redirection URIs (or URI + components) as defined in [RFC3986] section 6, if any redirection + URIs were registered. If the client registration included the full + redirection URI, the authorization server MUST compare the two URIs + using simple string comparison as defined in [RFC3986] section 6.2.1. + +3.1.2.4. Invalid Endpoint + + If an authorization request fails validation due to a missing, + invalid, or mismatching redirection URI, the authorization server + SHOULD inform the resource owner of the error, and MUST NOT + automatically redirect the user-agent to the invalid redirection URI. + +3.1.2.5. Endpoint Content + + The redirection request to the client's endpoint typically results in + an HTML document response, processed by the user-agent. If the HTML + response is served directly as the result of the redirection request, + any script included in the HTML document will execute with full + access to the redirection URI and the credentials it contains. + + The client MUST NOT include any untrusted third-party scripts in the + redirection endpoint response (e.g. third-party analytics, social + plug-ins, ad networks) without first ensuring that its own scripts + used to extract and remove the credentials from the URI will execute + first. + + + + +Hammer, et al. Expires July 24, 2012 [Page 19] + +Internet-Draft OAuth 2.0 January 2012 + + + The client SHOULD NOT include any third-party scripts in the + redirection endpoint response. Instead, it should extract the + credentials from the URI and redirect the user-agent again to another + endpoint without the credentials in the URI. + +3.2. Token Endpoint + + The token endpoint is used by the client to obtain an access token by + presenting its authorization grant or refresh token. The token + endpoint is used with every authorization grant except for the + implicit grant type (since an access token is issued directly). + + The means through which the client obtains the location of the token + endpoint are beyond the scope of this specification but is typically + provided in the service documentation. + + The endpoint URI MAY include an "application/x-www-form-urlencoded" + formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] + section 3.4), which MUST be retained when adding additional query + parameters. The endpoint URI MUST NOT include a fragment component. + + Since requests to the token endpoint result in the transmission of + clear-text credentials (in the HTTP request and response), the + authorization server MUST require TLS as described in Section 1.6 + when sending requests to the token endpoint. + + The client MUST use the HTTP "POST" method when making access token + requests. + + Parameters sent without a value MUST be treated as if they were + omitted from the request. The authorization server MUST ignore + unrecognized request parameters. Request and response parameters + MUST NOT be included more than once. + +3.2.1. Client Authentication + + Confidential clients or other clients issued client credentials MUST + authenticate with the authorization server as described in + Section 2.3 when making requests to the token endpoint. Client + authentication is used for: + + o Enforcing the binding of refresh tokens and authorization codes to + the client they were issued to. Client authentication is critical + when an authorization code is transmitted to the redirection + endpoint over an insecure channel, or when the redirection URI has + not been registered in full. + + + + + +Hammer, et al. Expires July 24, 2012 [Page 20] + +Internet-Draft OAuth 2.0 January 2012 + + + o Recovering from a compromised client by disabling the client or + changing its credentials, thus preventing an attacker from abusing + stolen refresh tokens. Changing a single set of client + credentials is significantly faster than revoking an entire set of + refresh tokens. + o Implementing authentication management best practices which + require periodic credential rotation. Rotation of an entire set + of refresh tokens can be challenging, while rotation of a single + set of client credentials is significantly easier. + + A public client that was not issued a client password MAY use the + "client_id" request parameter to identify itself when sending + requests to the token endpoint. + +3.3. Access Token Scope + + The authorization and token endpoints allow the client to specify the + scope of the access request using the "scope" request parameter. In + turn, the authorization server uses the "scope" response parameter to + inform the client of the scope of the access token issued. + + The value of the scope parameter is expressed as a list of space- + delimited, case sensitive strings. The strings are defined by the + authorization server. If the value contains multiple space-delimited + strings, their order does not matter, and each string adds an + additional access range to the requested scope. + + + scope = scope-token *( SP scope-token ) + scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) + + + The authorization server MAY fully or partially ignore the scope + requested by the client based on the authorization server policy or + the resource owner's instructions. If the issued access token scope + is different from the one requested by the client, the authorization + server MUST include the "scope" response parameter to inform the + client of the actual scope granted. + + If the client omits the scope parameter when requesting + authorization, the authorization server MUST either process the + request using a pre-defined default value, or fail the request + indicating an invalid scope. The authorization server SHOULD + document its scope requirements and default value (if defined). + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 21] + +Internet-Draft OAuth 2.0 January 2012 + + +4. Obtaining Authorization + + To request an access token, the client obtains authorization from the + resource owner. The authorization is expressed in the form of an + authorization grant which the client uses to request the access + token. OAuth defines four grant types: authorization code, implicit, + resource owner password credentials, and client credentials. It also + provides an extension mechanism for defining additional grant types. + +4.1. Authorization Code Grant + + The authorization code grant type is used to obtain both access + tokens and refresh tokens and is optimized for confidential clients. + As a redirection-based flow, the client must be capable of + interacting with the resource owner's user-agent (typically a web + browser) and capable of receiving incoming requests (via redirection) + from the authorization server. + + + +----------+ + | resource | + | owner | + | | + +----------+ + ^ + | + (B) + +----|-----+ Client Identifier +---------------+ + | -+----(A)-- & Redirection URI ---->| | + | User- | | Authorization | + | Agent -+----(B)-- User authenticates --->| Server | + | | | | + | -+----(C)-- Authorization Code ---<| | + +-|----|---+ +---------------+ + | | ^ v + (A) (C) | | + | | | | + ^ v | | + +---------+ | | + | |>---(D)-- Authorization Code ---------' | + | Client | & Redirection URI | + | | | + | |<---(E)----- Access Token -------------------' + +---------+ (w/ Optional Refresh Token) + + + Note: The lines illustrating steps A, B, and C are broken into two + parts as they pass through the user-agent. + + + +Hammer, et al. Expires July 24, 2012 [Page 22] + +Internet-Draft OAuth 2.0 January 2012 + + + Figure 3: Authorization Code Flow + + The flow illustrated in Figure 3 includes the following steps: + + (A) The client initiates the flow by directing the resource owner's + user-agent to the authorization endpoint. The client includes + its client identifier, requested scope, local state, and a + redirection URI to which the authorization server will send the + user-agent back once access is granted (or denied). + (B) The authorization server authenticates the resource owner (via + the user-agent) and establishes whether the resource owner + grants or denies the client's access request. + (C) Assuming the resource owner grants access, the authorization + server redirects the user-agent back to the client using the + redirection URI provided earlier (in the request or during + client registration). The redirection URI includes an + authorization code and any local state provided by the client + earlier. + (D) The client requests an access token from the authorization + server's token endpoint by including the authorization code + received in the previous step. When making the request, the + client authenticates with the authorization server. The client + includes the redirection URI used to obtain the authorization + code for verification. + (E) The authorization server authenticates the client, validates the + authorization code, and ensures the redirection URI received + matches the URI used to redirect the client in step (C). If + valid, the authorization server responds back with an access + token and optionally, a refresh token. + +4.1.1. Authorization Request + + The client constructs the request URI by adding the following + parameters to the query component of the authorization endpoint URI + using the "application/x-www-form-urlencoded" format as defined by + [W3C.REC-html401-19991224]: + + response_type + REQUIRED. Value MUST be set to "code". + client_id + REQUIRED. The client identifier as described in Section 2.2. + redirect_uri + OPTIONAL. As described in Section 3.1.2. + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. + + + + + +Hammer, et al. Expires July 24, 2012 [Page 23] + +Internet-Draft OAuth 2.0 January 2012 + + + state + RECOMMENDED. An opaque value used by the client to maintain + state between the request and callback. The authorization + server includes this value when redirecting the user-agent back + to the client. The parameter SHOULD be used for preventing + cross-site request forgery as described in Section 10.12. + + The client directs the resource owner to the constructed URI using an + HTTP redirection response, or by other means available to it via the + user-agent. + + For example, the client directs the user-agent to make the following + HTTP request using TLS (extra line breaks are for display purposes + only): + + + GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz + &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 + Host: server.example.com + + + The authorization server validates the request to ensure all required + parameters are present and valid. If the request is valid, the + authorization server authenticates the resource owner and obtains an + authorization decision (by asking the resource owner or by + establishing approval via other means). + + When a decision is established, the authorization server directs the + user-agent to the provided client redirection URI using an HTTP + redirection response, or by other means available to it via the user- + agent. + +4.1.2. Authorization Response + + If the resource owner grants the access request, the authorization + server issues an authorization code and delivers it to the client by + adding the following parameters to the query component of the + redirection URI using the "application/x-www-form-urlencoded" format: + + code + REQUIRED. The authorization code generated by the + authorization server. The authorization code MUST expire + shortly after it is issued to mitigate the risk of leaks. A + maximum authorization code lifetime of 10 minutes is + RECOMMENDED. The client MUST NOT use the authorization code + more than once. If an authorization code is used more than + once, the authorization server MUST deny the request and SHOULD + revoke (when possible) all tokens previously issued based on + + + +Hammer, et al. Expires July 24, 2012 [Page 24] + +Internet-Draft OAuth 2.0 January 2012 + + + that authorization code. The authorization code is bound to + the client identifier and redirection URI. + state + REQUIRED if the "state" parameter was present in the client + authorization request. The exact value received from the + client. + + For example, the authorization server redirects the user-agent by + sending the following HTTP response: + + + HTTP/1.1 302 Found + Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA + &state=xyz + + + The client MUST ignore unrecognized response parameters. The + authorization code string size is left undefined by this + specification. The client should avoid making assumptions about code + value sizes. The authorization server should document the size of + any value it issues. + +4.1.2.1. Error Response + + If the request fails due to a missing, invalid, or mismatching + redirection URI, or if the client identifier is missing or invalid, + the authorization server SHOULD inform the resource owner of the + error, and MUST NOT automatically redirect the user-agent to the + invalid redirection URI. + + If the resource owner denies the access request or if the request + fails for reasons other than a missing or invalid redirection URI, + the authorization server informs the client by adding the following + parameters to the query component of the redirection URI using the + "application/x-www-form-urlencoded" format: + + error + REQUIRED. A single error code from the following: + invalid_request + The request is missing a required parameter, includes an + invalid parameter value, or is otherwise malformed. + unauthorized_client + The client is not authorized to request an authorization + code using this method. + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 25] + +Internet-Draft OAuth 2.0 January 2012 + + + access_denied + The resource owner or authorization server denied the + request. + unsupported_response_type + The authorization server does not support obtaining an + authorization code using this method. + invalid_scope + The requested scope is invalid, unknown, or malformed. + server_error + The authorization server encountered an unexpected + condition which prevented it from fulfilling the request. + temporarily_unavailable + The authorization server is currently unable to handle + the request due to a temporary overloading or maintenance + of the server. + error_description + OPTIONAL. A human-readable UTF-8 encoded text providing + additional information, used to assist the client developer in + understanding the error that occurred. + error_uri + OPTIONAL. A URI identifying a human-readable web page with + information about the error, used to provide the client + developer with additional information about the error. + state + REQUIRED if a "state" parameter was present in the client + authorization request. The exact value received from the + client. + + For example, the authorization server redirects the user-agent by + sending the following HTTP response: + + + HTTP/1.1 302 Found + Location: https://client.example.com/cb?error=access_denied&state=xyz + + +4.1.3. Access Token Request + + The client makes a request to the token endpoint by adding the + following parameters using the "application/x-www-form-urlencoded" + format in the HTTP request entity-body: + + grant_type + REQUIRED. Value MUST be set to "authorization_code". + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 26] + +Internet-Draft OAuth 2.0 January 2012 + + + code + REQUIRED. The authorization code received from the + authorization server. + redirect_uri + REQUIRED, if the "redirect_uri" parameter was included in the + authorization request as described in Section 4.1.1, and their + values MUST be identical. + + If the client type is confidential or the client was issued client + credentials (or assigned other authentication requirements), the + client MUST authenticate with the authorization server as described + in Section 3.2.1. + + For example, the client makes the following HTTP request using TLS + (extra line breaks are for display purposes only): + + + POST /token HTTP/1.1 + Host: server.example.com + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW + Content-Type: application/x-www-form-urlencoded;charset=UTF-8 + + grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA + &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb + + + The authorization server MUST: + + o require client authentication for confidential clients or for any + client that was issued client credentials (or with other + authentication requirements), + o authenticate the client if client authentication is included and + ensure the authorization code was issued to the authenticated + client, + o verify that the authorization code is valid, and + o ensure that the "redirect_uri" parameter is present if the + "redirect_uri" parameter was included in the initial authorization + request as described in Section 4.1.1, and if included ensure + their values are identical. + +4.1.4. Access Token Response + + If the access token request is valid and authorized, the + authorization server issues an access token and optional refresh + token as described in Section 5.1. If the request client + authentication failed or is invalid, the authorization server returns + an error response as described in Section 5.2. + + + + +Hammer, et al. Expires July 24, 2012 [Page 27] + +Internet-Draft OAuth 2.0 January 2012 + + + An example successful response: + + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "access_token":"2YotnFZFEjr1zCsicMWpAA", + "token_type":"example", + "expires_in":3600, + "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", + "example_parameter":"example_value" + } + + +4.2. Implicit Grant + + The implicit grant type is used to obtain access tokens (it does not + support the issuance of refresh tokens) and is optimized for public + clients known to operate a particular redirection URI. These clients + are typically implemented in a browser using a scripting language + such as JavaScript. + + As a redirection-based flow, the client must be capable of + interacting with the resource owner's user-agent (typically a web + browser) and capable of receiving incoming requests (via redirection) + from the authorization server. + + Unlike the authorization code grant type in which the client makes + separate requests for authorization and access token, the client + receives the access token as the result of the authorization request. + + The implicit grant type does not include client authentication, and + relies on the presence of the resource owner and the registration of + the redirection URI. Because the access token is encoded into the + redirection URI, it may be exposed to the resource owner and other + applications residing on the same device. + + + + + + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 28] + +Internet-Draft OAuth 2.0 January 2012 + + + +----------+ + | Resource | + | Owner | + | | + +----------+ + ^ + | + (B) + +----|-----+ Client Identifier +---------------+ + | -+----(A)-- & Redirection URI --->| | + | User- | | Authorization | + | Agent -|----(B)-- User authenticates -->| Server | + | | | | + | |<---(C)--- Redirection URI ----<| | + | | with Access Token +---------------+ + | | in Fragment + | | +---------------+ + | |----(D)--- Redirection URI ---->| Web-Hosted | + | | without Fragment | Client | + | | | Resource | + | (F) |<---(E)------- Script ---------<| | + | | +---------------+ + +-|--------+ + | | + (A) (G) Access Token + | | + ^ v + +---------+ + | | + | Client | + | | + +---------+ + + + Note: The lines illustrating steps A and B are broken into two parts + as they pass through the user-agent. + + Figure 4: Implicit Grant Flow + + The flow illustrated in Figure 4 includes the following steps: + + (A) The client initiates the flow by directing the resource owner's + user-agent to the authorization endpoint. The client includes + its client identifier, requested scope, local state, and a + redirection URI to which the authorization server will send the + user-agent back once access is granted (or denied). + + + + + +Hammer, et al. Expires July 24, 2012 [Page 29] + +Internet-Draft OAuth 2.0 January 2012 + + + (B) The authorization server authenticates the resource owner (via + the user-agent) and establishes whether the resource owner + grants or denies the client's access request. + (C) Assuming the resource owner grants access, the authorization + server redirects the user-agent back to the client using the + redirection URI provided earlier. The redirection URI includes + the access token in the URI fragment. + (D) The user-agent follows the redirection instructions by making a + request to the web-hosted client resource (which does not + include the fragment per [RFC2616]). The user-agent retains the + fragment information locally. + (E) The web-hosted client resource returns a web page (typically an + HTML document with an embedded script) capable of accessing the + full redirection URI including the fragment retained by the + user-agent, and extracting the access token (and other + parameters) contained in the fragment. + (F) The user-agent executes the script provided by the web-hosted + client resource locally, which extracts the access token and + passes it to the client. + +4.2.1. Authorization Request + + The client constructs the request URI by adding the following + parameters to the query component of the authorization endpoint URI + using the "application/x-www-form-urlencoded" format: + + response_type + REQUIRED. Value MUST be set to "token". + client_id + REQUIRED. The client identifier as described in Section 2.2. + redirect_uri + OPTIONAL. As described in Section 3.1.2. + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. + state + RECOMMENDED. An opaque value used by the client to maintain + state between the request and callback. The authorization + server includes this value when redirecting the user-agent back + to the client. The parameter SHOULD be used for preventing + cross-site request forgery as described in Section 10.12. + + The client directs the resource owner to the constructed URI using an + HTTP redirection response, or by other means available to it via the + user-agent. + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 30] + +Internet-Draft OAuth 2.0 January 2012 + + + For example, the client directs the user-agent to make the following + HTTP request using TLS (extra line breaks are for display purposes + only): + + + GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz + &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 + Host: server.example.com + + + The authorization server validates the request to ensure all required + parameters are present and valid. The authorization server MUST + verify that the redirection URI to which it will redirect the access + token matches a redirection URI registered by the client as described + in Section 3.1.2. + + If the request is valid, the authorization server authenticates the + resource owner and obtains an authorization decision (by asking the + resource owner or by establishing approval via other means). + + When a decision is established, the authorization server directs the + user-agent to the provided client redirection URI using an HTTP + redirection response, or by other means available to it via the user- + agent. + +4.2.2. Access Token Response + + If the resource owner grants the access request, the authorization + server issues an access token and delivers it to the client by adding + the following parameters to the fragment component of the redirection + URI using the "application/x-www-form-urlencoded" format: + + access_token + REQUIRED. The access token issued by the authorization server. + token_type + REQUIRED. The type of the token issued as described in + Section 7.1. Value is case insensitive. + expires_in + RECOMMENDED. The lifetime in seconds of the access token. For + example, the value "3600" denotes that the access token will + expire in one hour from the time the response was generated. + If omitted, the authorization server SHOULD provide the + expiration time via other means or document the default value. + scope + OPTIONAL, if identical to the scope requested by the client, + otherwise REQUIRED. The scope of the access token as described + by Section 3.3. + + + + +Hammer, et al. Expires July 24, 2012 [Page 31] + +Internet-Draft OAuth 2.0 January 2012 + + + state + REQUIRED if the "state" parameter was present in the client + authorization request. The exact value received from the + client. + + The authorization server MUST NOT issue a refresh token. + + For example, the authorization server redirects the user-agent by + sending the following HTTP response (URI extra line breaks are for + display purposes only): + + + HTTP/1.1 302 Found + Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA + &state=xyz&token_type=example&expires_in=3600 + + + Developers should note that some user-agents do not support the + inclusion of a fragment component in the HTTP "Location" response + header field. Such clients will require using other methods for + redirecting the client than a 3xx redirection response. For example, + returning an HTML page which includes a 'continue' button with an + action linked to the redirection URI. + + The client MUST ignore unrecognized response parameters. The access + token string size is left undefined by this specification. The + client should avoid making assumptions about value sizes. The + authorization server should document the size of any value it issues. + +4.2.2.1. Error Response + + If the request fails due to a missing, invalid, or mismatching + redirection URI, or if the client identifier is missing or invalid, + the authorization server SHOULD inform the resource owner of the + error, and MUST NOT automatically redirect the user-agent to the + invalid redirection URI. + + If the resource owner denies the access request or if the request + fails for reasons other than a missing or invalid redirection URI, + the authorization server informs the client by adding the following + parameters to the fragment component of the redirection URI using the + "application/x-www-form-urlencoded" format: + + error + REQUIRED. A single error code from the following: + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 32] + +Internet-Draft OAuth 2.0 January 2012 + + + invalid_request + The request is missing a required parameter, includes an + invalid parameter value, or is otherwise malformed. + unauthorized_client + The client is not authorized to request an access token + using this method. + access_denied + The resource owner or authorization server denied the + request. + unsupported_response_type + The authorization server does not support obtaining an + access token using this method. + invalid_scope + The requested scope is invalid, unknown, or malformed. + server_error + The authorization server encountered an unexpected + condition which prevented it from fulfilling the request. + temporarily_unavailable + The authorization server is currently unable to handle + the request due to a temporary overloading or maintenance + of the server. + error_description + OPTIONAL. A human-readable UTF-8 encoded text providing + additional information, used to assist the client developer in + understanding the error that occurred. + error_uri + OPTIONAL. A URI identifying a human-readable web page with + information about the error, used to provide the client + developer with additional information about the error. + state + REQUIRED if a "state" parameter was present in the client + authorization request. The exact value received from the + client. + + For example, the authorization server redirects the user-agent by + sending the following HTTP response: + + + HTTP/1.1 302 Found + Location: https://client.example.com/cb#error=access_denied&state=xyz + + +4.3. Resource Owner Password Credentials Grant + + The resource owner password credentials grant type is suitable in + cases where the resource owner has a trust relationship with the + client, such as the device operating system or a highly privileged + application. The authorization server should take special care when + + + +Hammer, et al. Expires July 24, 2012 [Page 33] + +Internet-Draft OAuth 2.0 January 2012 + + + enabling this grant type, and only allow it when other flows are not + viable. + + The grant type is suitable for clients capable of obtaining the + resource owner's credentials (username and password, typically using + an interactive form). It is also used to migrate existing clients + using direct authentication schemes such as HTTP Basic or Digest + authentication to OAuth by converting the stored credentials to an + access token. + + + +----------+ + | Resource | + | Owner | + | | + +----------+ + v + | Resource Owner + (A) Password Credentials + | + v + +---------+ +---------------+ + | |>--(B)---- Resource Owner ------->| | + | | Password Credentials | Authorization | + | Client | | Server | + | |<--(C)---- Access Token ---------<| | + | | (w/ Optional Refresh Token) | | + +---------+ +---------------+ + + + Figure 5: Resource Owner Password Credentials Flow + + The flow illustrated in Figure 5 includes the following steps: + + (A) The resource owner provides the client with its username and + password. + (B) The client requests an access token from the authorization + server's token endpoint by including the credentials received + from the resource owner. When making the request, the client + authenticates with the authorization server. + (C) The authorization server authenticates the client and validates + the resource owner credentials, and if valid issues an access + token. + +4.3.1. Authorization Request and Response + + The method through which the client obtains the resource owner + credentials is beyond the scope of this specification. The client + + + +Hammer, et al. Expires July 24, 2012 [Page 34] + +Internet-Draft OAuth 2.0 January 2012 + + + MUST discard the credentials once an access token has been obtained. + +4.3.2. Access Token Request + + The client makes a request to the token endpoint by adding the + following parameters using the "application/x-www-form-urlencoded" + format in the HTTP request entity-body: + + grant_type + REQUIRED. Value MUST be set to "password". + username + REQUIRED. The resource owner username, encoded as UTF-8. + password + REQUIRED. The resource owner password, encoded as UTF-8. + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. + + If the client type is confidential or the client was issued client + credentials (or assigned other authentication requirements), the + client MUST authenticate with the authorization server as described + in Section 3.2.1. + + For example, the client makes the following HTTP request using + transport-layer security (extra line breaks are for display purposes + only): + + + POST /token HTTP/1.1 + Host: server.example.com + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW + Content-Type: application/x-www-form-urlencoded;charset=UTF-8 + + grant_type=password&username=johndoe&password=A3ddj3w + + + The authorization server MUST: + + o require client authentication for confidential clients or for any + client that was issued client credentials (or with other + authentication requirements), + o authenticate the client if client authentication is included, and + o validate the resource owner password credentials. + + Since this access token request utilizes the resource owner's + password, the authorization server MUST protect the endpoint against + brute force attacks (e.g. using rate-limitation or generating + alerts). + + + +Hammer, et al. Expires July 24, 2012 [Page 35] + +Internet-Draft OAuth 2.0 January 2012 + + +4.3.3. Access Token Response + + If the access token request is valid and authorized, the + authorization server issues an access token and optional refresh + token as described in Section 5.1. If the request failed client + authentication or is invalid, the authorization server returns an + error response as described in Section 5.2. + + An example successful response: + + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "access_token":"2YotnFZFEjr1zCsicMWpAA", + "token_type":"example", + "expires_in":3600, + "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", + "example_parameter":"example_value" + } + + +4.4. Client Credentials Grant + + The client can request an access token using only its client + credentials (or other supported means of authentication) when the + client is requesting access to the protected resources under its + control, or those of another resource owner which has been previously + arranged with the authorization server (the method of which is beyond + the scope of this specification). + + The client credentials grant type MUST only be used by confidential + clients. + + + +---------+ +---------------+ + | | | | + | |>--(A)- Client Authentication --->| Authorization | + | Client | | Server | + | |<--(B)---- Access Token ---------<| | + | | | | + +---------+ +---------------+ + + + Figure 6: Client Credentials Flow + + + +Hammer, et al. Expires July 24, 2012 [Page 36] + +Internet-Draft OAuth 2.0 January 2012 + + + The flow illustrated in Figure 6 includes the following steps: + + (A) The client authenticates with the authorization server and + requests an access token from the token endpoint. + (B) The authorization server authenticates the client, and if valid + issues an access token. + +4.4.1. Authorization Request and Response + + Since the client authentication is used as the authorization grant, + no additional authorization request is needed. + +4.4.2. Access Token Request + + The client makes a request to the token endpoint by adding the + following parameters using the "application/x-www-form-urlencoded" + format in the HTTP request entity-body: + + grant_type + REQUIRED. Value MUST be set to "client_credentials". + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. + + The client MUST authenticate with the authorization server as + described in Section 3.2.1. + + For example, the client makes the following HTTP request using + transport-layer security (extra line breaks are for display purposes + only): + + + POST /token HTTP/1.1 + Host: server.example.com + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW + Content-Type: application/x-www-form-urlencoded;charset=UTF-8 + + grant_type=client_credentials + + + The authorization server MUST authenticate the client. + +4.4.3. Access Token Response + + If the access token request is valid and authorized, the + authorization server issues an access token as described in + Section 5.1. A refresh token SHOULD NOT be included. If the request + failed client authentication or is invalid, the authorization server + + + +Hammer, et al. Expires July 24, 2012 [Page 37] + +Internet-Draft OAuth 2.0 January 2012 + + + returns an error response as described in Section 5.2. + + An example successful response: + + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "access_token":"2YotnFZFEjr1zCsicMWpAA", + "token_type":"example", + "expires_in":3600, + "example_parameter":"example_value" + } + + +4.5. Extension Grants + + The client uses an extension grant type by specifying the grant type + using an absolute URI (defined by the authorization server) as the + value of the "grant_type" parameter of the token endpoint, and by + adding any additional parameters necessary. + + For example, to request an access token using a SAML 2.0 assertion + grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client + makes the following HTTP request using TLS (line breaks are for + display purposes only): + + + POST /token HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded;charset=UTF-8 + + grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- + bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU + [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- + + + If the access token request is valid and authorized, the + authorization server issues an access token and optional refresh + token as described in Section 5.1. If the request failed client + authentication or is invalid, the authorization server returns an + error response as described in Section 5.2. + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 38] + +Internet-Draft OAuth 2.0 January 2012 + + +5. Issuing an Access Token + + If the access token request is valid and authorized, the + authorization server issues an access token and optional refresh + token as described in Section 5.1. If the request failed client + authentication or is invalid, the authorization server returns an + error response as described in Section 5.2. + +5.1. Successful Response + + The authorization server issues an access token and optional refresh + token, and constructs the response by adding the following parameters + to the entity body of the HTTP response with a 200 (OK) status code: + + access_token + REQUIRED. The access token issued by the authorization server. + token_type + REQUIRED. The type of the token issued as described in + Section 7.1. Value is case insensitive. + expires_in + RECOMMENDED. The lifetime in seconds of the access token. For + example, the value "3600" denotes that the access token will + expire in one hour from the time the response was generated. + If omitted, the authorization server SHOULD provide the + expiration time via other means or document the default value. + refresh_token + OPTIONAL. The refresh token which can be used to obtain new + access tokens using the same authorization grant as described + in Section 6. + scope + OPTIONAL, if identical to the scope requested by the client, + otherwise REQUIRED. The scope of the access token as described + by Section 3.3. + + The parameters are included in the entity body of the HTTP response + using the "application/json" media type as defined by [RFC4627]. The + parameters are serialized into a JSON structure by adding each + parameter at the highest structure level. Parameter names and string + values are included as JSON strings. Numerical values are included + as JSON numbers. The order of parameters does not matter and can + vary. + + The authorization server MUST include the HTTP "Cache-Control" + response header field [RFC2616] with a value of "no-store" in any + response containing tokens, credentials, or other sensitive + information, as well as the "Pragma" response header field [RFC2616] + with a value of "no-cache". + + + + +Hammer, et al. Expires July 24, 2012 [Page 39] + +Internet-Draft OAuth 2.0 January 2012 + + + For example: + + + HTTP/1.1 200 OK + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "access_token":"2YotnFZFEjr1zCsicMWpAA", + "token_type":"example", + "expires_in":3600, + "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", + "example_parameter":"example_value" + } + + + The client MUST ignore unrecognized value names in the response. The + sizes of tokens and other values received from the authorization + server are left undefined. The client should avoid making + assumptions about value sizes. The authorization server should + document the size of any value it issues. + +5.2. Error Response + + The authorization server responds with an HTTP 400 (Bad Request) + status code and includes the following parameters with the response: + + error + REQUIRED. A single error code from the following: + invalid_request + The request is missing a required parameter, includes an + unsupported parameter value, repeats a parameter, + includes multiple credentials, utilizes more than one + mechanism for authenticating the client, or is otherwise + malformed. + invalid_client + Client authentication failed (e.g. unknown client, no + client authentication included, or unsupported + authentication method). The authorization server MAY + return an HTTP 401 (Unauthorized) status code to indicate + which HTTP authentication schemes are supported. If the + client attempted to authenticate via the "Authorization" + request header field, the authorization server MUST + respond with an HTTP 401 (Unauthorized) status code, and + include the "WWW-Authenticate" response header field + matching the authentication scheme used by the client. + + + + +Hammer, et al. Expires July 24, 2012 [Page 40] + +Internet-Draft OAuth 2.0 January 2012 + + + invalid_grant + The provided authorization grant (e.g. authorization + code, resource owner credentials) is invalid, expired, + revoked, does not match the redirection URI used in the + authorization request, or was issued to another client. + unauthorized_client + The authenticated client is not authorized to use this + authorization grant type. + unsupported_grant_type + The authorization grant type is not supported by the + authorization server. + invalid_scope + The requested scope is invalid, unknown, malformed, or + exceeds the scope granted by the resource owner. + error_description + OPTIONAL. A human-readable UTF-8 encoded text providing + additional information, used to assist the client developer in + understanding the error that occurred. + error_uri + OPTIONAL. A URI identifying a human-readable web page with + information about the error, used to provide the client + developer with additional information about the error. + + The parameters are included in the entity body of the HTTP response + using the "application/json" media type as defined by [RFC4627]. The + parameters are serialized into a JSON structure by adding each + parameter at the highest structure level. Parameter names and string + values are included as JSON strings. Numerical values are included + as JSON numbers. The order of parameters does not matter and can + vary. + + For example: + + + HTTP/1.1 400 Bad Request + Content-Type: application/json;charset=UTF-8 + Cache-Control: no-store + Pragma: no-cache + + { + "error":"invalid_request" + } + + + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 41] + +Internet-Draft OAuth 2.0 January 2012 + + +6. Refreshing an Access Token + + If the authorization server issued a refresh token to the client, the + client makes a refresh request to the token endpoint by adding the + following parameters using the "application/x-www-form-urlencoded" + format in the HTTP request entity-body: + + grant_type + REQUIRED. Value MUST be set to "refresh_token". + refresh_token + REQUIRED. The refresh token issued to the client. + scope + OPTIONAL. The scope of the access request as described by + Section 3.3. The requested scope MUST NOT include any scope + not originally granted by the resource owner, and if omitted is + treated as equal to the scope originally granted by the + resource owner. + + Because refresh tokens are typically long-lasting credentials used to + request additional access tokens, the refresh token is bound to the + client which it was issued. If the client type is confidential or + the client was issued client credentials (or assigned other + authentication requirements), the client MUST authenticate with the + authorization server as described in Section 3.2.1. + + For example, the client makes the following HTTP request using + transport-layer security (extra line breaks are for display purposes + only): + + + POST /token HTTP/1.1 + Host: server.example.com + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW + Content-Type: application/x-www-form-urlencoded;charset=UTF-8 + + grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA + + + The authorization server MUST: + + o require client authentication for confidential clients or for any + client that was issued client credentials (or with other + authentication requirements), + o authenticate the client if client authentication is included and + ensure the refresh token was issued to the authenticated client, + and + + + + + +Hammer, et al. Expires July 24, 2012 [Page 42] + +Internet-Draft OAuth 2.0 January 2012 + + + o validate the refresh token. + + If valid and authorized, the authorization server issues an access + token as described in Section 5.1. If the request failed + verification or is invalid, the authorization server returns an error + response as described in Section 5.2. + + The authorization server MAY issue a new refresh token, in which case + the client MUST discard the old refresh token and replace it with the + new refresh token. The authorization server MAY revoke the old + refresh token after issuing a new refresh token to the client. If a + new refresh token is issued, the refresh token scope MUST be + identical to that of the refresh token included by the client in the + request. + + +7. Accessing Protected Resources + + The client accesses protected resources by presenting the access + token to the resource server. The resource server MUST validate the + access token and ensure it has not expired and that its scope covers + the requested resource. The methods used by the resource server to + validate the access token (as well as any error responses) are beyond + the scope of this specification, but generally involve an interaction + or coordination between the resource server and the authorization + server. + + The method in which the client utilized the access token to + authenticate with the resource server depends on the type of access + token issued by the authorization server. Typically, it involves + using the HTTP "Authorization" request header field [RFC2617] with an + authentication scheme defined by the access token type specification. + +7.1. Access Token Types + + The access token type provides the client with the information + required to successfully utilize the access token to make a protected + resource request (along with type-specific attributes). The client + MUST NOT use an access token if it does not understand the token + type. + + For example, the "bearer" token type defined in + [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access + token string in the request: + + + GET /resource/1 HTTP/1.1 + Host: example.com + + + +Hammer, et al. Expires July 24, 2012 [Page 43] + +Internet-Draft OAuth 2.0 January 2012 + + + Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw + + + while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is + utilized by issuing a MAC key together with the access token which is + used to sign certain components of the HTTP requests: + + + GET /resource/1 HTTP/1.1 + Host: example.com + Authorization: MAC id="h480djs93hd8", + nonce="274312:dj83hs9s", + mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" + + + The above examples are provided for illustration purposes only. + Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and + [I-D.ietf-oauth-v2-http-mac] specifications before use. + + Each access token type definition specifies the additional attributes + (if any) sent to the client together with the "access_token" response + parameter. It also defines the HTTP authentication method used to + include the access token when making a protected resource request. + + +8. Extensibility + +8.1. Defining Access Token Types + + Access token types can be defined in one of two ways: registered in + the access token type registry (following the procedures in + Section 11.1), or by using a unique absolute URI as its name. + + Types utilizing a URI name SHOULD be limited to vendor-specific + implementations that are not commonly applicable, and are specific to + the implementation details of the resource server where they are + used. + + All other types MUST be registered. Type names MUST conform to the + type-name ABNF. If the type definition includes a new HTTP + authentication scheme, the type name SHOULD be identical to the HTTP + authentication scheme name (as defined by [RFC2617]). The token type + "example" is reserved for use in examples. + + + type-name = 1*name-char + name-char = "-" / "." / "_" / DIGIT / ALPHA + + + + +Hammer, et al. Expires July 24, 2012 [Page 44] + +Internet-Draft OAuth 2.0 January 2012 + + +8.2. Defining New Endpoint Parameters + + New request or response parameters for use with the authorization + endpoint or the token endpoint are defined and registered in the + parameters registry following the procedure in Section 11.2. + + Parameter names MUST conform to the param-name ABNF and parameter + values syntax MUST be well-defined (e.g., using ABNF, or a reference + to the syntax of an existing parameter). + + + param-name = 1*name-char + name-char = "-" / "." / "_" / DIGIT / ALPHA + + + Unregistered vendor-specific parameter extensions that are not + commonly applicable, and are specific to the implementation details + of the authorization server where they are used SHOULD utilize a + vendor-specific prefix that is not likely to conflict with other + registered values (e.g. begin with 'companyname_'). + +8.3. Defining New Authorization Grant Types + + New authorization grant types can be defined by assigning them a + unique absolute URI for use with the "grant_type" parameter. If the + extension grant type requires additional token endpoint parameters, + they MUST be registered in the OAuth parameters registry as described + by Section 11.2. + +8.4. Defining New Authorization Endpoint Response Types + + New response types for use with the authorization endpoint are + defined and registered in the authorization endpoint response type + registry following the procedure in Section 11.3. Response type + names MUST conform to the response-type ABNF. + + + response-type = response-name *( SP response-name ) + response-name = 1*response-char + response-char = "_" / DIGIT / ALPHA + + + If a response type contains one or more space characters (%x20), it + is compared as a space-delimited list of values in which the order of + values does not matter. Only one order of values can be registered, + which covers all other arrangements of the same set of values. + + For example, the response type "token code" is left undefined by this + + + +Hammer, et al. Expires July 24, 2012 [Page 45] + +Internet-Draft OAuth 2.0 January 2012 + + + specification. However, an extension can define and register the + "token code" response type. Once registered, the same combination + cannot be registered as "code token", but both values can be used to + denote the same response type. + +8.5. Defining Additional Error Codes + + In cases where protocol extensions (i.e. access token types, + extension parameters, or extension grant types) require additional + error codes to be used with the authorization code grant error + response (Section 4.1.2.1), the implicit grant error response + (Section 4.2.2.1), or the token error response (Section 5.2), such + error codes MAY be defined. + + Extension error codes MUST be registered (following the procedures in + Section 11.4) if the extension they are used in conjunction with is a + registered access token type, a registered endpoint parameter, or an + extension grant type. Error codes used with unregistered extensions + MAY be registered. + + Error codes MUST conform to the error-code ABNF, and SHOULD be + prefixed by an identifying name when possible. For example, an error + identifying an invalid value set to the extension parameter "example" + should be named "example_invalid". + + + error-code = ALPHA *error-char + error-char = "-" / "." / "_" / DIGIT / ALPHA + + + +9. Native Applications + + Native applications are clients installed and executed on the device + used by the resource owner (i.e. desktop application, native mobile + application). Native applications require special consideration + related to security, platform capabilities, and overall end-user + experience. + + The authorization endpoint requires interaction between the client + and the resource owner's user-agent. Native applications can invoke + an external user-agent or embed a user-agent within the application. + For example: + + o External user-agent - the native application can capture the + response from the authorization server using a redirection URI + with a scheme registered with the operating system to invoke the + client as the handler, manual copy-and-paste of the credentials, + + + +Hammer, et al. Expires July 24, 2012 [Page 46] + +Internet-Draft OAuth 2.0 January 2012 + + + running a local web server, installing a user-agent extension, or + by providing a redirection URI identifying a server-hosted + resource under the client's control, which in turn makes the + response available to the native application. + o Embedded user-agent - the native application obtains the response + by directly communicating with the embedded user-agent by + monitoring state changes emitted during the resource load, or + accessing the user-agent's cookies storage. + + When choosing between an external or embedded user-agent, developers + should consider: + + o External user-agents may improve completion rate as the resource + owner may already have an active session with the authorization + server removing the need to re-authenticate. It provides a + familiar end-user experience and functionality. The resource + owner may also rely on user-agent features or extensions to assist + with authentication (e.g. password manager, 2-factor device + reader). + o Embedded user-agents may offer improved usability, as they remove + the need to switch context and open new windows. + o Embedded user-agents pose a security challenge because resource + owners are authenticating in an unidentified window without access + to the visual protections found in most external user-agents. + Embedded user-agents educate end-user to trust unidentified + requests for authentication (making phishing attacks easier to + execute). + + When choosing between the implicit grant type and the authorization + code grant type, the following should be considered: + + o Native applications that use the authorization code grant type + SHOULD do so without using client credentials, due to the native + application's inability to keep client credentials confidential. + o When using the implicit grant type flow a refresh token is not + returned which requires repeating the authorization process once + the access token expires. + + +10. Security Considerations + + As a flexible and extensible framework, OAuth's security + considerations depend on many factors. The following sections + provide implementers with security guidelines focused on the three + client profiles described in Section 2.1: web application, user- + agent-based application, and native application. + + A comprehensive OAuth security model and analysis, as well as + + + +Hammer, et al. Expires July 24, 2012 [Page 47] + +Internet-Draft OAuth 2.0 January 2012 + + + background for the protocol design is provided by + [I-D.ietf-oauth-v2-threatmodel]. + +10.1. Client Authentication + + The authorization server establishes client credentials with web + application clients for the purpose of client authentication. The + authorization server is encouraged to consider stronger client + authentication means than a client password. Web application clients + MUST ensure confidentiality of client passwords and other client + credentials. + + The authorization server MUST NOT issue client passwords or other + client credentials to native application or user-agent-based + application clients for the purpose of client authentication. The + authorization server MAY issue a client password or other credentials + for a specific installation of a native application client on a + specific device. + + When client authentication is not possible, the authorization server + SHOULD employ other means to validate the client's identity. For + example, by requiring the registration of the client redirection URI + or enlisting the resource owner to confirm identity. A valid + redirection URI is not sufficient to verify the client's identity + when asking for end-user authorization, but can be used to prevent + delivering credentials to a counterfeit client after obtaining end- + user authorization. + + The authorization server must consider the security implications of + interacting with unauthenticated clients and take measures to limit + the potential exposure of other credentials (e.g. refresh tokens) + issued to such clients. + +10.2. Client Impersonation + + A malicious client can impersonate another client and obtain access + to protected resources, if the impersonated client fails to, or is + unable to, keep its client credentials confidential. + + The authorization server MUST authenticate the client whenever + possible. If the authorization server cannot authenticate the client + due to the client's nature, the authorization server MUST require the + registration of any redirection URI used for receiving authorization + responses, and SHOULD utilize other means to protect resource owners + from such potentially malicious clients. For example, the + authorization server can engage the resource owner to assist in + identifying the client and its origin. + + + + +Hammer, et al. Expires July 24, 2012 [Page 48] + +Internet-Draft OAuth 2.0 January 2012 + + + The authorization server SHOULD enforce explicit resource owner + authentication and provide the resource owner with information about + the client and the requested authorization scope and lifetime. It is + up to the resource owner to review the information in the context of + the current client, and authorize or deny the request. + + The authorization server SHOULD NOT process repeated authorization + requests automatically (without active resource owner interaction) + without authenticating the client or relying on other measures to + ensure the repeated request comes from the original client and not an + impersonator. + +10.3. Access Tokens + + Access token credentials (as well as any confidential access token + attributes) MUST be kept confidential in transit and storage, and + only shared among the authorization server, the resource servers the + access token is valid for, and the client to whom the access token is + issued. Access token credentials MUST only be transmitted using TLS + as described in Section 1.6 with server authentication as defined by + [RFC2818]. + + When using the implicit grant type, the access token is transmitted + in the URI fragment, which can expose it to unauthorized parties. + + The authorization server MUST ensure that access tokens cannot be + generated, modified, or guessed to produce valid access tokens by + unauthorized parties. + + The client SHOULD request access tokens with the minimal scope and + lifetime necessary. The authorization server SHOULD take the client + identity into account when choosing how to honor the requested scope + and lifetime, and MAY issue an access token with a less rights than + requested. + +10.4. Refresh Tokens + + Authorization servers MAY issue refresh tokens to web application + clients and native application clients. + + Refresh tokens MUST be kept confidential in transit and storage, and + shared only among the authorization server and the client to whom the + refresh tokens were issued. The authorization server MUST maintain + the binding between a refresh token and the client to whom it was + issued. Refresh tokens MUST only be transmitted using TLS as + described in Section 1.6 with server authentication as defined by + [RFC2818]. + + + + +Hammer, et al. Expires July 24, 2012 [Page 49] + +Internet-Draft OAuth 2.0 January 2012 + + + The authorization server MUST verify the binding between the refresh + token and client identity whenever the client identity can be + authenticated. When client authentication is not possible, the + authorization server SHOULD deploy other means to detect refresh + token abuse. + + For example, the authorization server could employ refresh token + rotation in which a new refresh token is issued with every access + token refresh response. The previous refresh token is invalidated + but retained by the authorization server. If a refresh token is + compromised and subsequently used by both the attacker and the + legitimate client, one of them will present an invalidated refresh + token which will inform the authorization server of the breach. + + The authorization server MUST ensure that refresh tokens cannot be + generated, modified, or guessed to produce valid refresh tokens by + unauthorized parties. + +10.5. Authorization Codes + + The transmission of authorization codes SHOULD be made over a secure + channel, and the client SHOULD implement TLS for use with its + redirection URI if the URI identifies a network resource. Since + authorization codes are transmitted via user-agent redirections, they + could potentially be disclosed through user-agent history and HTTP + referrer headers. + + Authorization codes operate as plaintext bearer credentials, used to + verify that the resource owner who granted authorization at the + authorization server is the same resource owner returning to the + client to complete the process. Therefore, if the client relies on + the authorization code for its own resource owner authentication, the + client redirection endpoint MUST require TLS. + + Authorization codes MUST be short lived and single use. If the + authorization server observes multiple attempts to exchange an + authorization code for an access token, the authorization server + SHOULD attempt to revoke all access tokens already granted based on + the compromised authorization code. + + If the client can be authenticated, the authorization servers MUST + authenticate the client and ensure that the authorization code was + issued to the same client. + +10.6. Authorization Code Redirection URI Manipulation + + When requesting authorization using the authorization code grant + type, the client can specify a redirection URI via the "redirect_uri" + + + +Hammer, et al. Expires July 24, 2012 [Page 50] + +Internet-Draft OAuth 2.0 January 2012 + + + parameter. If an attacker can manipulate the value of the + redirection URI, it can cause the authorization server to redirect + the resource owner user-agent to a URI under the control of the + attacker with the authorization code. + + An attacker can create an account at a legitimate client and initiate + the authorization flow. When the attacker is sent to the + authorization server to grant access, the attacker grabs the + authorization URI provided by the legitimate client, and replaces the + client's redirection URI with a URI under the control of the + attacker. The attacker then tricks the victim into following the + manipulated link to authorize access to the legitimate client. + + Once at the authorization server, the victim is prompted with a + normal, valid request on behalf of a legitimate and trusted client, + and authorizes the request. The victim is then redirected to an + endpoint under the control of the attacker with the authorization + code. The attacker completes the authorization flow by sending the + authorization code to the client using the original redirection URI + provided by the client. The client exchanges the authorization code + with an access token and links it to the attacker's client account + which can now gain access to the protected resources authorized by + the victim (via the client). + + In order to prevent such an attack, the authorization server MUST + ensure that the redirection URI used to obtain the authorization code + is identical to the redirection URI provided when exchanging the + authorization code for an access token. The authorization server + MUST require public clients and SHOULD require confidential clients + to register their redirection URIs. If a redirection URI is provided + in the request, the authorization server MUST validate it against the + registered value. + +10.7. Resource Owner Password Credentials + + The resource owner password credentials grant type is often used for + legacy or migration reasons. It reduces the overall risk of storing + username and password by the client, but does not eliminate the need + to expose highly privileged credentials to the client. + + This grant type carries a higher risk than other grant types because + it maintains the password anti-pattern this protocol seeks to avoid. + The client could abuse the password or the password could + unintentionally be disclosed to an attacker (e.g. via log files or + other records kept by the client). + + Additionally, because the resource owner does not have control over + the authorization process (the resource owner involvement ends when + + + +Hammer, et al. Expires July 24, 2012 [Page 51] + +Internet-Draft OAuth 2.0 January 2012 + + + it hands over its credentials to the client), the client can obtain + access tokens with a broader scope and longer lifetime than desired + by the resource owner. The authorization server should consider the + scope and lifetime of access tokens issued via this grant type. + + The authorization server and client SHOULD minimize use of this grant + type and utilize other grant types whenever possible. + +10.8. Request Confidentiality + + Access tokens, refresh tokens, resource owner passwords, and client + credentials MUST NOT be transmitted in the clear. Authorization + codes SHOULD NOT be transmitted in the clear. + + The "state" and "scope" parameters SHOULD NOT include sensitive + client or resource owner information in plain text as they can be + transmitted over insecure channels or stored insecurely. + +10.9. Endpoints Authenticity + + In order to prevent man-in-the-middle attacks, the authorization + server MUST implement and require TLS with server authentication as + defined by [RFC2818] for any request sent to the authorization and + token endpoints. The client MUST validate the authorization server's + TLS certificate in accordance with its requirements for server + identity authentication. + +10.10. Credentials Guessing Attacks + + The authorization server MUST prevent attackers from guessing access + tokens, authorization codes, refresh tokens, resource owner + passwords, and client credentials. + + Generated tokens and other credentials not intended for handling by + end-users MUST be constructed from a cryptographically strong random + or pseudo-random number sequence ([RFC1750]) generated by the + authorization server. The probability of any two values being + identical MUST be less than or equal to 2^(-128) and SHOULD be less + than or equal to 2^(-160). + + The authorization server MUST utilize other means to protect + credentials intended for end-user usage. + +10.11. Phishing Attacks + + Wide deployment of this and similar protocols may cause end-users to + become inured to the practice of being redirected to websites where + they are asked to enter their passwords. If end-users are not + + + +Hammer, et al. Expires July 24, 2012 [Page 52] + +Internet-Draft OAuth 2.0 January 2012 + + + careful to verify the authenticity of these websites before entering + their credentials, it will be possible for attackers to exploit this + practice to steal resource owners' passwords. + + Service providers should attempt to educate end-users about the risks + phishing attacks pose, and should provide mechanisms that make it + easy for end-users to confirm the authenticity of their sites. + Client developers should consider the security implications of how + they interact with the user-agent (e.g., external, embedded), and the + ability of the end-user to verify the authenticity of the + authorization server. + + To reduce the risk of phishing attacks, the authorization servers + MUST utilize TLS on every endpoint used for end-user interaction. + +10.12. Cross-Site Request Forgery + + Cross-site request forgery (CSRF) is an exploit in which an attacker + causes the user-agent of a victim end-user to follow a malicious URI + (e.g. provided to the user-agent as a misleading link, image, or + redirection) to a trusting server (usually established via the + presence of a valid session cookie). + + A CSRF attack against the client's redirection URI allows an attacker + to inject their own authorization code or access token, which can + result in the client using an access token associated with the + attacker's protected resources rather than the victim's (e.g. save + the victim's bank account information to a protected resource + controlled by the attacker). + + The client MUST implement CSRF protection for its redirection URI. + This is typically accomplished by requiring any request sent to the + redirection URI endpoint to include a value that binds the request to + the user-agent's authenticated state (e.g. a hash of the session + cookie used to authenticate the user-agent). The client SHOULD + utilize the "state" request parameter to deliver this value to the + authorization server when making an authorization request. + + Once authorization has been obtained from the end-user, the + authorization server redirects the end-user's user-agent back to the + client with the required binding value contained in the "state" + parameter. The binding value enables the client to verify the + validity of the request by matching the binding value to the user- + agent's authenticated state. The binding value used for CSRF + protection MUST contain a non-guessable value (as described in + Section 10.10), and the user-agent's authenticated state (e.g. + session cookie, HTML5 local storage) MUST be kept in a location + accessible only to the client and the user-agent (i.e., protected by + + + +Hammer, et al. Expires July 24, 2012 [Page 53] + +Internet-Draft OAuth 2.0 January 2012 + + + same-origin policy). + + A CSRF attack against the authorization server's authorization + endpoint can result in an attacker obtaining end-user authorization + for a malicious client without involving or alerting the end-user. + + The authorization server MUST implement CSRF protection for its + authorization endpoint, and ensure that a malicious client cannot + obtain authorization without the awareness and explicit consent of + the resource owner. + +10.13. Clickjacking + + In a clickjacking attack, an attacker registers a legitimate client + and then constructs a malicious site in which it loads the + authorization server's authorization endpoint web page in a + transparent iframe overlaid on top of a set of dummy buttons which + are carefully constructed to be placed directly under important + buttons on the authorization page. When an end-user clicks a + misleading visible button, the end-user is actually clicking an + invisible button on the authorization page (such as an "Authorize" + button). This allows an attacker to trick a resource owner into + granting its client access without their knowledge. + + To prevent this form of attack, native applications SHOULD use + external browsers instead of embedding browsers within the + application when requesting end-user authorization. For most newer + browsers, avoidance of iframes can be enforced by the authorization + server using the (non-standard) "x-frame-options" header. This + header can have two values, "deny" and "sameorigin", which will block + any framing, or framing by sites with a different origin, + respectively. For older browsers, javascript framebusting techniques + can be used but may not be effective in all browsers. + +10.14. Code Injection and Input Validation + + A code injection attack occurs when an input or otherwise external + variable is used by an application unsanitized and causes + modification to the application logic. This may allow an attacker to + gain access to the application device or its data, cause denial of + service, or a wide range of malicious side-effects. + + The Authorization server and client MUST validate and sanitize any + value received, and in particular, the value of the "state" and + "redirect_uri" parameters. + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 54] + +Internet-Draft OAuth 2.0 January 2012 + + +10.15. Open Redirectors + + The authorization server authorization endpoint and the client + redirection endpoint can be improperly configured and operate as open + redirectors. An open redirector is an endpoint using a parameter to + automatically redirect a user-agent to the location specified by the + parameter value without any validation. + + Open redirectors can be used in phishing attacks, or by an attacker + to get end-users to visit malicious sites by making the URI's + authority look like a familiar and trusted destination. In addition, + if the authorization server allows the client to register only part + of the redirection URI, an attacker can use an open redirector + operated by the client to construct a redirection URI that will pass + the authorization server validation but will send the authorization + code or access token to an endpoint under the control of the + attacker. + + +11. IANA Considerations + +11.1. The OAuth Access Token Type Registry + + This specification establishes the OAuth access token type registry. + + Access token types are registered on the advice of one or more + Designated Experts (appointed by the IESG or their delegate), with a + Specification Required (using terminology from [RFC5226]). However, + to allow for the allocation of values prior to publication, the + Designated Expert(s) may approve registration once they are satisfied + that such a specification will be published. + + Registration requests should be sent to the [TBD]@ietf.org mailing + list for review and comment, with an appropriate subject (e.g., + "Request for access token type: example"). [[ Note to RFC-EDITOR: The + name of the mailing list should be determined in consultation with + the IESG and IANA. Suggested name: oauth-ext-review. ]] + + Within at most 14 days of the request, 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. + + Decisions (or lack thereof) made by the Designated Expert(s) can be + first appealed to Security Area Directors (contactable using + app-ads@tools.ietf.org email address or directly by looking up their + email addresses on http://www.iesg.org/ website) and, if the + + + +Hammer, et al. Expires July 24, 2012 [Page 55] + +Internet-Draft OAuth 2.0 January 2012 + + + appellant is not satisfied with the response, to the full IESG (using + the iesg@iesg.org mailing list). + + IANA should only accept registry updates from the Designated + Expert(s), and should direct all requests for registration to the + review mailing list. + +11.1.1. Registration Template + + Type name: + The name requested (e.g., "example"). + Additional Token Endpoint Response Parameters: + Additional response parameters returned together with the + "access_token" parameter. New parameters MUST be separately + registered in the OAuth parameters registry as described by + Section 11.2. + HTTP Authentication Scheme(s): + The HTTP authentication scheme name(s), if any, used to + authenticate protected resources requests using access tokens of + this type. + Change controller: + For standards-track RFCs, state "IETF". For others, give the name + of the responsible party. Other details (e.g., postal address, + e-mail address, home page URI) may also be included. + Specification document(s): + Reference to the document that specifies the parameter, preferably + including a URI that can be used to retrieve a copy of the + document. An indication of the relevant sections may also be + included, but is not required. + +11.2. The OAuth Parameters Registry + + This specification establishes the OAuth parameters registry. + + Additional parameters for inclusion in the authorization endpoint + request, the authorization endpoint response, the token endpoint + request, or the token endpoint response are registered on the advice + of one or more Designated Experts (appointed by the IESG or their + delegate), with a Specification Required (using terminology from + [RFC5226]). However, to allow for the allocation of values prior to + publication, the Designated Expert(s) may approve registration once + they are satisfied that such a specification will be published. + + Registration requests should be sent to the [TBD]@ietf.org mailing + list for review and comment, with an appropriate subject (e.g., + "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of + the mailing list should be determined in consultation with the IESG + and IANA. Suggested name: oauth-ext-review. ]] + + + +Hammer, et al. Expires July 24, 2012 [Page 56] + +Internet-Draft OAuth 2.0 January 2012 + + + Within at most 14 days of the request, 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. + + Decisions (or lack thereof) made by the Designated Expert(s) can be + first appealed to Security Area Directors (contactable using + app-ads@tools.ietf.org email address or directly by looking up their + email addresses on http://www.iesg.org/ website) and, if the + appellant is not satisfied with the response, to the full IESG (using + the iesg@iesg.org mailing list). + + IANA should only accept registry updates from the Designated + Expert(s), and should direct all requests for registration to the + review mailing list. + +11.2.1. Registration Template + + Parameter name: + The name requested (e.g., "example"). + Parameter usage location: + The location(s) where parameter can be used. The possible + locations are: authorization request, authorization response, + token request, or token response. + Change controller: + For standards-track RFCs, state "IETF". For others, give the name + of the responsible party. Other details (e.g., postal address, + e-mail address, home page URI) may also be included. + Specification document(s): + Reference to the document that specifies the parameter, preferably + including a URI that can be used to retrieve a copy of the + document. An indication of the relevant sections may also be + included, but is not required. + +11.2.2. Initial Registry Contents + + The OAuth Parameters Registry's initial contents are: + + o Parameter name: client_id + o Parameter usage location: authorization request, token request + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: client_secret + o Parameter usage location: token request + + + + + +Hammer, et al. Expires July 24, 2012 [Page 57] + +Internet-Draft OAuth 2.0 January 2012 + + + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: response_type + o Parameter usage location: authorization request + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: redirect_uri + o Parameter usage location: authorization request, token request + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: scope + o Parameter usage location: authorization request, authorization + response, token request, token response + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: state + o Parameter usage location: authorization request, authorization + response + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: code + o Parameter usage location: authorization response, token request + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: error_description + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: error_uri + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: grant_type + o Parameter usage location: token request + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: access_token + + + + + +Hammer, et al. Expires July 24, 2012 [Page 58] + +Internet-Draft OAuth 2.0 January 2012 + + + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: token_type + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: expires_in + o Parameter usage location: authorization response, token response + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: username + o Parameter usage location: token request + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: password + o Parameter usage location: token request + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Parameter name: refresh_token + o Parameter usage location: token request, token response + o Change controller: IETF + o Specification document(s): [[ this document ]] + +11.3. The OAuth Authorization Endpoint Response Type Registry + + This specification establishes the OAuth authorization endpoint + response type registry. + + Additional response type for use with the authorization endpoint are + registered on the advice of one or more Designated Experts (appointed + by the IESG or their delegate), with a Specification Required (using + terminology from [RFC5226]). However, to allow for the allocation of + values prior to publication, the Designated Expert(s) may approve + registration once they are satisfied that such a specification will + be published. + + Registration requests should be sent to the [TBD]@ietf.org mailing + list for review and comment, with an appropriate subject (e.g., + "Request for response type: example"). [[ Note to RFC-EDITOR: The + name of the mailing list should be determined in consultation with + the IESG and IANA. Suggested name: oauth-ext-review. ]] + + + + +Hammer, et al. Expires July 24, 2012 [Page 59] + +Internet-Draft OAuth 2.0 January 2012 + + + Within at most 14 days of the request, 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. + + Decisions (or lack thereof) made by the Designated Expert(s) can be + first appealed to Security Area Directors (contactable using + app-ads@tools.ietf.org email address or directly by looking up their + email addresses on http://www.iesg.org/ website) and, if the + appellant is not satisfied with the response, to the full IESG (using + the iesg@iesg.org mailing list). + + IANA should only accept registry updates from the Designated + Expert(s), and should direct all requests for registration to the + review mailing list. + +11.3.1. Registration Template + + Response type name: + The name requested (e.g., "example"). + Change controller: + For standards-track RFCs, state "IETF". For others, give the name + of the responsible party. Other details (e.g., postal address, + e-mail address, home page URI) may also be included. + Specification document(s): + Reference to the document that specifies the type, preferably + including a URI that can be used to retrieve a copy of the + document. An indication of the relevant sections may also be + included, but is not required. + +11.3.2. Initial Registry Contents + + The OAuth Authorization Endpoint Response Type Registry's initial + contents are: + + o Response type name: code + o Change controller: IETF + o Specification document(s): [[ this document ]] + + o Response type name: token + o Change controller: IETF + o Specification document(s): [[ this document ]] + +11.4. The OAuth Extensions Error Registry + + This specification establishes the OAuth extensions error registry. + + + + +Hammer, et al. Expires July 24, 2012 [Page 60] + +Internet-Draft OAuth 2.0 January 2012 + + + Additional error codes used together with other protocol extensions + (i.e. extension grant types, access token types, or extension + parameters) are registered on the advice of one or more Designated + Experts (appointed by the IESG or their delegate), with a + Specification Required (using terminology from [RFC5226]). However, + to allow for the allocation of values prior to publication, the + Designated Expert(s) may approve registration once they are satisfied + that such a specification will be published. + + Registration requests should be sent to the [TBD]@ietf.org mailing + list for review and comment, with an appropriate subject (e.g., + "Request for error code: example"). [[ Note to RFC-EDITOR: The name + of the mailing list should be determined in consultation with the + IESG and IANA. Suggested name: oauth-ext-review. ]] + + Within at most 14 days of the request, 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. + + Decisions (or lack thereof) made by the Designated Expert(s) can be + first appealed to Security Area Directors (contactable using + app-ads@tools.ietf.org email address or directly by looking up their + email addresses on http://www.iesg.org/ website) and, if the + appellant is not satisfied with the response, to the full IESG (using + the iesg@iesg.org mailing list). + + IANA should only accept registry updates from the Designated + Expert(s), and should direct all requests for registration to the + review mailing list. + +11.4.1. Registration Template + + Error name: + The name requested (e.g., "example"). + Error usage location: + The location(s) where the error can be used. The possible + locations are: authorization code grant error response + (Section 4.1.2.1), implicit grant error response + (Section 4.2.2.1), or token error response (Section 5.2). + Related protocol extension: + The name of the extension grant type, access token type, or + extension parameter, the error code is used in conjunction with. + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 61] + +Internet-Draft OAuth 2.0 January 2012 + + + Change controller: + For standards-track RFCs, state "IETF". For others, give the name + of the responsible party. Other details (e.g., postal address, + e-mail address, home page URI) may also be included. + Specification document(s): + Reference to the document that specifies the error code, + preferably including a URI that can be used to retrieve a copy of + the document. An indication of the relevant sections may also be + included, but is not required. + + +12. Acknowledgements + + The initial OAuth 2.0 protocol specification was edited by David + Recordon, based on two previous publications: the OAuth 1.0 community + specification [RFC5849], and OAuth WRAP (OAuth Web Resource + Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security + Considerations section was drafted by Torsten Lodderstedt, Mark + McGloin, Phil Hunt, and Anthony Nadalin. + + The OAuth 1.0 community specification was edited by Eran Hammer and + authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. + Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, + Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris + Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, + Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. + + The OAuth WRAP specification was edited by Dick Hardt and authored by + Brian Eaton, Yaron Goland, Dick Hardt, and Allen Tom. + + This specification is the work of the OAuth Working Group which + includes dozens of active and dedicated participants. In particular, + the following individuals contributed ideas, feedback, and wording + which shaped and formed the final specification: + + Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden + Bell, Brian Campbell, Scott Cantor, Marcos Caceres, Blaine Cook, + Roger Crew, Brian Eaton, Leah Culver, Bill de h ra, Andr DeMarre, + Brian Eaton, Wolter Eldering, Brian Ellin, Igor Faynberg, George + Fletcher, Tim Freeman, Evan Gilbert, Yaron Goland, Brent Goldman, + Kristoffer Gronowski, Justin Hart, Dick Hardt, Craig Heath, Phil + Hunt, Michael B. Jones, Terry Jones, John Kemp, Mark Kent, Raffi + Krikorian, Chasen Le Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui- + Lan Lu, Casey Lucas, Paul Madsen, Alastair Mair, Eve Maler, James + Manger, Mark McGloin, Laurence Miao, William Mills, Chuck Mortimore, + Anthony Nadalin, Julian Reschke, Justin Richer, Peter Saint-Andre, + Nat Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, Luke Shepard, + Vlad Skvortsov, Justin Smith, Niv Steingarten, Christian St bner, + + + +Hammer, et al. Expires July 24, 2012 [Page 62] + +Internet-Draft OAuth 2.0 January 2012 + + + Jeremy Suriel, Paul Tarjan, Allen Tom, Franklin Tse, Nick Walker, + Shane Weeden, and Skylar Woodward. + + This document was produced under the chairmanship of Blaine Cook, + Peter Saint-Andre, Hannes Tschofenig, and Barry Leiba. The area + directors included Lisa Dusseault, Peter Saint-Andre, and Stephen + Farrell. + + +Appendix A. Editor's Notes + + While many people contributed to this specification throughout its + long journey, the editor would like to acknowledge and thank a few + individuals for their outstanding and invaluable efforts leading up + to the publication of this specification. It is these individuals + without whom this work would not have existed or reached its + successful conclusion. + + David Recordon for continuously being one of OAuth s most valuable + assets, bringing pragmatism and urgency to the work, and helping + shape it from its very beginning, as well as being one of the best + collaborators I had the pleasure of working with. + + James Manger for his creative ideas and always insightful feedback. + Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, + Marius Scurtescu, and Luke Shepard for their continued participation + and valuable feedback. + + Special thanks goes to Mike Curtis and Yahoo! for their unconditional + support of this work for over three years. + + +13. References + +13.1. Normative References + + [RFC1750] Eastlake, D., Crocker, S., and J. Schiller, "Randomness + Recommendations for Security", RFC 1750, December 1994. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", + RFC 2246, January 1999. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + + +Hammer, et al. Expires July 24, 2012 [Page 63] + +Internet-Draft OAuth 2.0 January 2012 + + + [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., + Leach, P., Luotonen, A., and L. Stewart, "HTTP + Authentication: Basic and Digest Access Authentication", + RFC 2617, June 1999. + + [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC4627] Crockford, D., "The application/json Media Type for + JavaScript Object Notation (JSON)", RFC 4627, July 2006. + + [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", + RFC 4949, August 2007. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008. + + [W3C.REC-html401-19991224] + Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 + Specification", World Wide Web Consortium + Recommendation REC-html401-19991224, December 1999, + <http://www.w3.org/TR/1999/REC-html401-19991224>. + +13.2. Informative References + + [I-D.draft-hardt-oauth-01] + Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth + Web Resource Authorization Profiles", January 2010. + + [I-D.ietf-oauth-saml2-bearer] + Mortimore, C., "SAML 2.0 Bearer Assertion Profiles for + OAuth 2.0", draft-ietf-oauth-saml2-bearer-08 (work in + progress), August 2011. + + [I-D.ietf-oauth-v2-bearer] + Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 + Protocol: Bearer Tokens", draft-ietf-oauth-v2-bearer-08 + (work in progress), July 2011. + + + +Hammer, et al. Expires July 24, 2012 [Page 64] + +Internet-Draft OAuth 2.0 January 2012 + + + [I-D.ietf-oauth-v2-http-mac] + Hammer-Lahav, E., Barth, A., and B. Adida, "HTTP + Authentication: MAC Access Authentication", + draft-ietf-oauth-v2-http-mac-00 (work in progress), + May 2011. + + [I-D.ietf-oauth-v2-threatmodel] + Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 + Threat Model and Security Considerations", + draft-ietf-oauth-v2-threatmodel-00 (work in progress), + July 2011. + + [OASIS.saml-core-2.0-os] + Cantor, S., Kemp, J., Philpott, R., and E. Maler, + "Assertions and Protocol for the OASIS Security Assertion + Markup Language (SAML) V2.0", OASIS Standard saml-core- + 2.0-os, March 2005. + + [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, + April 2010. + + +Authors' Addresses + + Eran Hammer (editor) + + Email: eran@hueniverse.com + URI: http://hueniverse.com + + + David Recordon + Facebook + + Email: dr@fb.com + URI: http://www.davidrecordon.com/ + + + Dick Hardt + Microsoft + + Email: dick.hardt@gmail.com + URI: http://dickhardt.org/ + + + + + + + + + +Hammer, et al. Expires July 24, 2012 [Page 65] + diff --git a/doc/specs/draft-ietf-oauth-v2-bearer-05.txt b/doc/specs/draft-ietf-oauth-v2-bearer-05.txt deleted file mode 100644 index a446893..0000000 --- a/doc/specs/draft-ietf-oauth-v2-bearer-05.txt +++ /dev/null @@ -1,952 +0,0 @@ - - - -Network Working Group M. Jones -Internet-Draft Microsoft -Intended status: Standards Track D. Hardt -Expires: November 22, 2011 independent - D. Recordon - Facebook - May 21, 2011 - - - The OAuth 2.0 Protocol: Bearer Tokens - draft-ietf-oauth-v2-bearer-05 - -Abstract - - This specification describes how to use bearer tokens when accessing - OAuth 2.0 protected resources. - -Status of this Memo - - This Internet-Draft is submitted in full conformance with the - provisions of BCP 78 and BCP 79. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF). Note that other groups may also distribute - working documents as Internet-Drafts. The list of current Internet- - Drafts is at http://datatracker.ietf.org/drafts/current/. - - 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." - - This Internet-Draft will expire on November 22, 2011. - -Copyright Notice - - Copyright (c) 2011 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 - 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. - - - -Jones, et al. Expires November 22, 2011 [Page 1] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 - 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 - 1.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Authenticated Requests . . . . . . . . . . . . . . . . . . . . 4 - 2.1. The Authorization Request Header Field . . . . . . . . . . 5 - 2.2. Form-Encoded Body Parameter . . . . . . . . . . . . . . . 5 - 2.3. URI Query Parameter . . . . . . . . . . . . . . . . . . . 6 - 2.4. The WWW-Authenticate Response Header Field . . . . . . . . 7 - 2.4.1. Error Codes . . . . . . . . . . . . . . . . . . . . . 8 - 3. Security Considerations . . . . . . . . . . . . . . . . . . . 9 - 3.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 9 - 3.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 9 - 3.3. Summary of Recommendations . . . . . . . . . . . . . . . . 11 - 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 - 4.1. OAuth Access Token Type Registration . . . . . . . . . . . 11 - 4.1.1. The "Bearer" OAuth Access Token Type . . . . . . . . . 12 - 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 5.1. Normative References . . . . . . . . . . . . . . . . . . . 12 - 5.2. Informative References . . . . . . . . . . . . . . . . . . 13 - Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 13 - Appendix B. Document History . . . . . . . . . . . . . . . . . . 14 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 - - - - - - - - - - - - - - - - - - - - - - - - - - -Jones, et al. Expires November 22, 2011 [Page 2] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - -1. Introduction - - OAuth enables clients to access protected resources by obtaining an - access token, which is defined in [I-D.ietf-oauth-v2] as "a string - representing an access authorization issued to the client", rather - than using the resource owner's credentials. - - Tokens are issued to clients by an authorization server with the - approval of the resource owner. The client uses the access token to - access the protected resources hosted by the resource server. This - specification describes how to make protected resource requests when - the OAuth access token is a bearer token. - - This specification defines the use of bearer tokens with OAuth over - HTTP [RFC2616] using TLS [RFC5246]. Other specifications may extend - it for use with other transport protocols. - -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 [RFC2119]. - - This document uses the Augmented Backus-Naur Form (ABNF) notation of - [I-D.ietf-httpbis-p1-messaging], which is based upon the Augmented - Backus-Naur Form (ABNF) notation of [RFC5234]. Additionally, the - following rules are included from [RFC2617]: auth-param and realm; - from [RFC3986]: URI-Reference; and from - [I-D.ietf-httpbis-p1-messaging]: RWS and quoted-string. - - Unless otherwise noted, all the protocol parameter names and values - are case sensitive. - -1.2. Terminology - - Bearer Token - A security token with the property that any party in possession of - the token (a "bearer") can use the token in any way that any other - party in possession of it can. Using a bearer token does not - require a bearer to prove possession of cryptographic key material - (proof-of-possession). - - All other terms are as defined in [I-D.ietf-oauth-v2]. - -1.3. Overview - - OAuth provides a method for clients to access a protected resource on - behalf of a resource owner. Before a client can access a protected - - - -Jones, et al. Expires November 22, 2011 [Page 3] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - resource, it must first obtain authorization (access grant) from the - resource owner and then exchange the access grant for an access token - (representing the grant's scope, duration, and other attributes). - The client accesses the protected resource by presenting the access - token to the resource server. - - The access token provides an abstraction layer, replacing different - authorization constructs (e.g. username and password, assertion) for - a single token understood by the resource server. This abstraction - enables issuing access tokens valid for a short time period, as well - as removing the resource server's need to understand a wide range of - authentication schemes. - - +--------+ +---------------+ - | |--(A)- Authorization Request ->| Resource | - | | | Owner | - | |<-(B)----- Access Grant -------| | - | | +---------------+ - | | - | | Access Grant & +---------------+ - | |--(C)--- Client Credentials -->| Authorization | - | Client | | Server | - | |<-(D)----- Access Token -------| | - | | +---------------+ - | | - | | +---------------+ - | |--(E)----- Access Token ------>| Resource | - | | | Server | - | |<-(F)--- Protected Resource ---| | - +--------+ +---------------+ - - Figure 1: Abstract Protocol Flow - - The abstract flow illustrated in Figure 1 describes the overall OAuth - 2.0 protocol architecture. The following steps are specified within - this document: - - E) The client makes a protected resource request to the resource - server by presenting the access token. - - F) The resource server validates the access token, and if valid, - serves the request. - - -2. Authenticated Requests - - Clients SHOULD make authenticated requests with a bearer token using - the "Authorization" request header field defined by [RFC2617]. - - - -Jones, et al. Expires November 22, 2011 [Page 4] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - Resource servers MUST accept authenticated requests using the - "Bearer" HTTP authorization scheme as described in Section 2.1, and - MAY support additional methods. - - Alternatively, clients MAY transmit the access token in the HTTP body - when using the "application/x-www-form-urlencoded" content type as - described in Section 2.2; or clients MAY transmit the access token in - the HTTP request URI in the query component as described in - Section 2.3. Resource servers MAY support these alternative methods. - - Clients SHOULD NOT use the request body or URI unless the - "Authorization" request header field is not available, and MUST NOT - use more than one method to transmit the token in each request. - Because of the Security Considerations (Section 3) associated with - the URI method, it SHOULD NOT be used unless no other method is - feasible. - -2.1. The Authorization Request Header Field - - The "Authorization" request header field is used by clients to make - authenticated requests with bearer tokens. The client uses the - "Bearer" authentication scheme to transmit the access token in the - request. - - For example: - - GET /resource HTTP/1.1 - Host: server.example.com - Authorization: Bearer vF9dft4qmT - - The "Authorization" header field uses the framework defined by - [RFC2617] as follows: - - credentials = "Bearer" RWS access-token - access-token = 1*( quoted-char / <"> ) - - quoted-char = ALPHA / DIGIT / - "!" / "#" / "$" / "%" / "&" / "'" / "(" / ")" / - "*" / "+" / "-" / "." / "/" / ":" / "<" / "=" / - ">" / "?" / "@" / "[" / "]" / "^" / "_" / "`" / - "{" / "|" / "}" / "~" / "\" / "," / ";" - -2.2. Form-Encoded Body Parameter - - When including the access token in the HTTP request entity-body, the - client adds the access token to the request body using the - "bearer_token" parameter. The client MUST NOT use this method unless - the following conditions are met: - - - -Jones, et al. Expires November 22, 2011 [Page 5] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - o The HTTP request entity-body is single-part. - - o The entity-body follows the encoding requirements of the - "application/x-www-form-urlencoded" content-type as defined by - [W3C.REC-html401-19991224]. - - o The HTTP request entity-header includes the "Content-Type" header - field set to "application/x-www-form-urlencoded". - - o The HTTP request method is one for which a body is permitted to be - present in the request. In particular, this means that the "GET" - method MUST NOT be used. - - The entity-body can include other request-specific parameters, in - which case, the "bearer_token" parameter MUST be properly separated - from the request-specific parameters by an "&" character (ASCII code - 38). - - For example, the client makes the following HTTP request using - transport-layer security: - - POST /resource HTTP/1.1 - Host: server.example.com - Content-Type: application/x-www-form-urlencoded - - bearer_token=vF9dft4qmT - - The "application/x-www-form-urlencoded" method SHOULD NOT be used - except in application contexts where participating browsers do not - have access to the "Authorization" request header field. - -2.3. URI Query Parameter - - When including the access token in the HTTP request URI, the client - adds the access token to the request URI query component as defined - by [RFC3986] using the "bearer_token" parameter. - - For example, the client makes the following HTTP request using - transport-layer security: - - GET /resource?bearer_token=vF9dft4qmT HTTP/1.1 - Host: server.example.com - - The HTTP request URI query can include other request-specific - parameters, in which case, the "bearer_token" parameter MUST be - properly separated from the request-specific parameters by an "&" - character (ASCII code 38). - - - - -Jones, et al. Expires November 22, 2011 [Page 6] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - For example: - - http://example.com/resource?x=y&bearer_token=vF9dft4qmT - - Because of the Security Considerations (Section 3) associated with - the URI method, it SHOULD NOT be used unless no other method is - feasible. - -2.4. The WWW-Authenticate Response Header Field - - If the protected resource request does not include authentication - credentials or contains an invalid access token, the resource server - MUST include the HTTP "WWW-Authenticate" response header field; it - MAY include it in response to other conditions as well. The - "WWW-Authenticate" header field uses the framework defined by - [RFC2617] as follows: - - challenge = "Bearer" [ RWS 1#param ] - - param = realm / scope / - error / error-desc / error-uri / - auth-param - - scope = "scope" "=" <"> scope-v *( SP scope-v ) <"> - scope-v = 1*quoted-char - - quoted-char = ALPHA / DIGIT / - "!" / "#" / "$" / "%" / "&" / "'" / "(" / ")" / - "*" / "+" / "-" / "." / "/" / ":" / "<" / "=" / - ">" / "?" / "@" / "[" / "]" / "^" / "_" / "`" / - "{" / "|" / "}" / "~" / "\" / "," / ";" - - error = "error" "=" quoted-string - error-desc = "error_description" "=" quoted-string - error-uri = "error_uri" "=" <"> URI-reference <"> - - The "scope" attribute is a space-delimited list of scope values - indicating the required scope of the access token for accessing the - requested resource. The "scope" attribute MUST NOT appear more than - once. - - If the protected resource request included an access token and failed - authentication, the resource server SHOULD include the "error" - attribute to provide the client with the reason why the access - request was declined. The parameter value is described in - Section 2.4.1. In addition, the resource server MAY include the - "error_description" attribute to provide a human-readable - explanation, and the "error_uri" attribute with an absolute URI - - - -Jones, et al. Expires November 22, 2011 [Page 7] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - identifying a human-readable web page explaining the error. The - "error", "error_description", and "error_uri" attribute MUST NOT - appear more than once. [[ add language and encoding information to - error_description if the core specification does ]] - - For example, in response to a protected resource request without - authentication: - - HTTP/1.1 401 Unauthorized - WWW-Authenticate: Bearer realm="example" - - And in response to a protected resource request with an - authentication attempt using an expired access token: - - HTTP/1.1 401 Unauthorized - WWW-Authenticate: Bearer realm="example" - error="invalid_token", - error_description="The access token expired" - -2.4.1. Error Codes - - When a request fails, the resource server responds using the - appropriate HTTP status code (typically, 400, 401, or 403), and - includes one of the following error codes in the response: - - invalid_request - The request is missing a required parameter, includes an - unsupported parameter or parameter value, repeats the same - parameter, uses more than one method for including an access - token, or is otherwise malformed. The resource server SHOULD - respond with the HTTP 401 (Unauthorized) status code. - - invalid_token - The access token provided is expired, revoked, malformed, or - invalid for other reasons. The resource SHOULD respond with - the HTTP 401 (Unauthorized) status code. The client MAY - request a new access token and retry the protected resource - request. - - insufficient_scope - The request requires higher privileges than provided by the - access token. The resource server SHOULD respond with the HTTP - 403 (Forbidden) status code and MAY include the "scope" - attribute with the scope necessary to access the protected - resource. - - If the request lacks any authentication information (i.e. the client - was unaware authentication is necessary or attempted using an - - - -Jones, et al. Expires November 22, 2011 [Page 8] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - unsupported authentication method), the resource server SHOULD NOT - include an error code or other error information. - - For example: - - HTTP/1.1 401 Unauthorized - WWW-Authenticate: Bearer realm="example" - - -3. Security Considerations - - This section describes the relevant security threats regarding token - handling when using bearer tokens and describes how to mitigate these - threats. - -3.1. Security Threats - - The following list presents several common threats against protocols - utilizing some form of tokens. This list of threats is based on NIST - Special Publication 800-63 [NIST800-63]. Since this document builds - on the OAuth 2.0 specification, we exclude a discussion of threats - that are described there or in related documents. - - Token manufacture/modification: An attacker may generate a bogus - token or modify the token contents (such as the authentication or - attribute statements) of an existing token, causing the resource - server to grant inappropriate access to the client. For example, - an attacker may modify the token to extend the validity period; a - malicious client may modify the assertion to gain access to - information that they should not be able to view. - - Token disclosure: Tokens may contain authentication and attribute - statements that include sensitive information. - - Token redirect: An attacker uses the token generated for consumption - by resource server to obtain access to another resource server. - - Token replay: An attacker attempts to use a token that has already - been used with that resource server in the past. - -3.2. Threat Mitigation - - A large range of threats can be mitigated by protecting the contents - of the token by using a digital signature or a Message Authentication - Code (MAC). Alternatively, a bearer token can contain a reference to - authorization information, rather than encoding the information - directly. Such references MUST be infeasible for an attacker to - guess; using a reference may require an extra interaction between a - - - -Jones, et al. Expires November 22, 2011 [Page 9] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - server and the token issuer to resolve the reference to the - authorization information. - - This document does not specify the encoding or the contents of the - token; hence detailed recommendations for token integrity protection - are outside the scope of this document. We assume that the token - integrity protection is sufficient to prevent the token from being - modified. - - To deal with token redirect, it is important for the authorization - server to include the identity of the intended recipients (the - audience), typically a single resource server (or a list of resource - servers), in the token. Restricting the use of the token to a - specific scope is also recommended. - - To provide protection against token disclosure, confidentiality - protection is applied via TLS [RFC5246] with a ciphersuite that - offers confidentiality protection. This requires that the - communication interaction between the client and the authorization - server, as well as the interaction between the client and the - resource server, utilize confidentiality protection. Since TLS is - mandatory to implement and to use with this specification, it is the - preferred approach for preventing token disclosure via the - communication channel. For those cases where the client is prevented - from observing the contents of the token, token encryption has to be - applied in addition to the usage of TLS protection. - - To deal with token capture and replay, the following recommendations - are made: First, the lifetime of the token has to be limited by - putting a validity time field inside the protected part of the token. - Note that using short-lived (one hour or less) tokens significantly - reduces the impact of one of them being leaked. Second, - confidentiality protection of the exchanges between the client and - the authorization server and between the client and the resource - server MUST be applied, for instance, through the use of TLS - [RFC5246]. As a consequence, no eavesdropper along the communication - path is able to observe the token exchange. Consequently, such an - on-path adversary cannot replay the token. Furthermore, when - presenting the token to a resource server, the client MUST verify the - identity of that resource server, as per [RFC2818]. Note that the - client MUST validate the TLS certificate chain when making these - requests to protected resources. Presenting the token to an - unauthenticated and unauthorized resource server or failing to - validate the certificate chain will allow adversaries to steal the - token and gain unauthorized access to protected resources. - - - - - - -Jones, et al. Expires November 22, 2011 [Page 10] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - -3.3. Summary of Recommendations - - Safeguard bearer tokens Client implementations MUST ensure that - bearer tokens are not leaked to unintended parties, as they will - be able to use them to gain access to protected resources. This - is the primary security consideration when using bearer tokens and - underlies all the more specific recommendations that follow. - - Validate SSL certificate chains The client must validate the TLS - certificate chain when making requests to protected resources. - Failing to do so may enable DNS hijacking attacks to steal the - token and gain unintended access. - - Always use TLS (https) Clients MUST always use TLS [RFC5246] (https) - when making requests with bearer tokens. Failing to do so exposes - the token to numerous attacks that could give attackers unintended - access. - - Don't store bearer tokens in cookies Implementations MUST NOT store - bearer tokens within cookies that can be sent in the clear (which - is the default transmission mode for cookies). - - Issue short-lived bearer tokens Using short-lived (one hour or less) - bearer tokens can reduce the impact of one of them being leaked. - In particular, only short-lived bearer tokens should be issued to - clients that run within a web browser or other environments where - information leakage may occur. - - Issue scoped bearer tokens Issue bearer tokens that contain an - audience restriction, scoping their use to the intended relying - party or set of relying parties. - - Don't pass bearer tokens in page URLs Browsers, web servers, and - other software may not adequately secure URLs in the browser - history, web server logs, and other data structures. If bearer - tokens are passed in page URLs (typically as query string - parameters), attackers might be able to steal them from the - history data, logs, or other unsecured locations. Instead, pass - bearer tokens in HTTP message headers or message bodies for which - confidentiality measures are taken. - - -4. IANA Considerations - -4.1. OAuth Access Token Type Registration - - This specification registers the following access token type in the - OAuth Access Token Type Registry. - - - -Jones, et al. Expires November 22, 2011 [Page 11] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - -4.1.1. The "Bearer" OAuth Access Token Type - - Type name: - Bearer - - Additional Token Endpoint Response Parameters: - (none) - - HTTP Authentication Scheme(s): - Bearer - - Change controller: - IETF - - Specification document(s): - [[ this document ]] - - -5. References - -5.1. Normative References - - [I-D.ietf-httpbis-p1-messaging] - Fielding, R., Gettys, J., Mogul, J., Nielsen, H., - Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, - "HTTP/1.1, part 1: URIs, Connections, and Message - Parsing", draft-ietf-httpbis-p1-messaging-14 (work in - progress), April 2011. - - [I-D.ietf-oauth-v2] - Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth - 2.0 Authorization Protocol", draft-ietf-oauth-v2-16 (work - in progress), May 2011. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., - Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext - Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. - - [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., - Leach, P., Luotonen, A., and L. Stewart, "HTTP - Authentication: Basic and Digest Access Authentication", - RFC 2617, June 1999. - - [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. - - - - -Jones, et al. Expires November 22, 2011 [Page 12] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifier (URI): Generic Syntax", STD 66, - RFC 3986, January 2005. - - [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", STD 68, RFC 5234, January 2008. - - [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security - (TLS) Protocol Version 1.2", RFC 5246, August 2008. - - [W3C.REC-html401-19991224] - Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 - Specification", World Wide Web Consortium - Recommendation REC-html401-19991224, December 1999, - <http://www.w3.org/TR/1999/REC-html401-19991224>. - -5.2. Informative References - - [I-D.ietf-httpbis-p7-auth] - Fielding, R., Gettys, J., Mogul, J., Nielsen, H., - Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, - "HTTP/1.1, part 7: Authentication", - draft-ietf-httpbis-p7-auth-13 (work in progress), - March 2011. - - [NIST800-63] - Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., - and E. Nabbus, "NIST Special Publication 800-63-1, - INFORMATION SECURITY", December 2008. - - -Appendix A. Acknowledgements - - The following people contributed to preliminary versions of this - document: Blaine Cook (BT), Brian Eaton (Google), Yaron Goland - (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), - Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and - concepts within are a product of the OAuth community, the WRAP - community, and the OAuth Working Group. - - The OAuth Working Group has dozens of very active contributors who - proposed ideas and wording for this document, including: Michael - Adams, Andrew Arnott, Dirk Balfanz, Brian Campbell, Leah Culver, Bill - de hOra, Brian Ellin, Igor Faynberg, George Fletcher, Tim Freeman, - Evan Gilbert, Justin Hart, John Kemp, Eran Hammer-Lahav, Chasen Le - Hara, Michael B. Jones, Torsten Lodderstedt, Eve Maler, James Manger, - Laurence Miao, Chuck Mortimore, Anthony Nadalin, Justin Richer, Peter - Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, - - - -Jones, et al. Expires November 22, 2011 [Page 13] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - Justin Smith, Jeremy Suriel, Christian Stuebner, Paul Tarjan, and - Franklin Tse. - - -Appendix B. Document History - - [[ to be removed by the RFC editor before publication as an RFC ]] - - -05 - - o Removed OAuth Errors Registry, per design team input. - - o Changed HTTP status code for "invalid_request" error code from - HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP - usage [[ change pending working group consensus ]]. - - o Added missing quotation marks in error-uri definition. - - o Added note to add language and encoding information to - error_description if the core specification does. - - o Explicitly reference the Augmented Backus-Naur Form (ABNF) defined - in [RFC5234]. - - o Use auth-param instead of repeating its definition, which is ( - token "=" ( token / quoted-string ) ). - - o Clarify security considerations about including an audience - restriction in the token and include a recommendation to issue - scoped bearer tokens in the summary of recommendations. - - -04 - - o Edits responding to working group last call feedback on -03. - Specific edits enumerated below. - - o Added Bearer Token definition in Terminology section. - - o Changed parameter name "oauth_token" to "bearer_token". - - o Added realm parameter to "WWW-Authenticate" response to comply - with [RFC2617]. - - o Removed "[ RWS 1#auth-param ]" from "credentials" definition since - it did not comply with the ABNF in [I-D.ietf-httpbis-p7-auth]. - - o Removed restriction that the "bearer_token" (formerly - "oauth_token") parameter be the last parameter in the entity-body - - - -Jones, et al. Expires November 22, 2011 [Page 14] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - and the HTTP request URI query. - - o Do not require WWW-Authenticate Response in a reply to a malformed - request, as an HTTP 400 Bad Request response without a WWW- - Authenticate header is likely the right response in some cases of - malformed requests. - - o Removed OAuth Parameters registry extension. - - o Numerous editorial improvements suggested by working group - members. - - -03 - - o Restored the WWW-Authenticate response header functionality - deleted from the framework specification in draft 12 based upon - the specification text from draft 11. - - o Augmented the OAuth Parameters registry by adding two additional - parameter usage locations: "resource request" and "resource - response". - - o Registered the "oauth_token" OAuth parameter with usage location - "resource request". - - o Registered the "error" OAuth parameter. - - o Created the OAuth Error registry and registered errors. - - o Changed the "OAuth2" OAuth access token type name to "Bearer". - - -02 - - o Incorporated feedback received on draft 01. Most changes were to - the security considerations section. No normative changes were - made. Specific changes included: - - o Changed terminology from "token reuse" to "token capture and - replay". - - o Removed sentence "Encrypting the token contents is another - alternative" from the security considerations since it was - redundant and potentially confusing. - - o Corrected some references to "resource server" to be - "authorization server" in the security considerations. - - - - - -Jones, et al. Expires November 22, 2011 [Page 15] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - o Generalized security considerations language about obtaining - consent of the resource owner. - - o Broadened scope of security considerations description for - recommendation "Don't pass bearer tokens in page URLs". - - o Removed unused reference to OAuth 1.0. - - o Updated reference to framework specification and updated David - Recordon's e-mail address. - - o Removed security considerations text on authenticating clients. - - o Registered the "OAuth2" OAuth access token type and "oauth_token" - parameter. - - -01 - - o First public draft, which incorporates feedback received on -00 - including enhanced Security Considerations content. This version - is intended to accompany OAuth 2.0 draft 11. - - -00 - - o Initial draft based on preliminary version of OAuth 2.0 draft 11. - - -Authors' Addresses - - Michael B. Jones - Microsoft - - Email: mbj@microsoft.com - URI: http://self-issued.info/ - - - Dick Hardt - independent - - Email: dick.hardt@gmail.com - URI: http://dickhardt.org/ - - - - - - - - - - -Jones, et al. Expires November 22, 2011 [Page 16] - -Internet-Draft OAuth 2.0 Bearer Tokens May 2011 - - - David Recordon - Facebook - - Email: dr@fb.com - URI: http://www.davidrecordon.com/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Jones, et al. Expires November 22, 2011 [Page 17] - diff --git a/doc/specs/draft-ietf-oauth-v2-bearer.htm b/doc/specs/draft-ietf-oauth-v2-bearer.htm new file mode 100644 index 0000000..27c78be --- /dev/null +++ b/doc/specs/draft-ietf-oauth-v2-bearer.htm @@ -0,0 +1,1748 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html lang="en"><head><title>The OAuth 2.0 Authorization Protocol: Bearer Tokens</title> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<meta name="description" content="The OAuth 2.0 Authorization Protocol: Bearer Tokens"> +<meta name="generator" content="xml2rfc v1.36 (http://xml.resource.org/)"> +<style type='text/css'><!-- + body { + font-family: verdana, charcoal, helvetica, arial, sans-serif; + font-size: small; color: #000; background-color: #FFF; + margin: 2em; + } + h1, h2, h3, h4, h5, h6 { + font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif; + font-weight: bold; font-style: normal; + } + h1 { color: #900; background-color: transparent; text-align: right; } + h3 { color: #333; background-color: transparent; } + + td.RFCbug { + font-size: x-small; text-decoration: none; + width: 30px; height: 30px; padding-top: 2px; + text-align: justify; vertical-align: middle; + background-color: #000; + } + td.RFCbug span.RFC { + font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; + font-weight: bold; color: #666; + } + td.RFCbug span.hotText { + font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; + font-weight: normal; text-align: center; color: #FFF; + } + + table.TOCbug { width: 30px; height: 15px; } + td.TOCbug { + text-align: center; width: 30px; height: 15px; + color: #FFF; background-color: #900; + } + td.TOCbug a { + font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif; + font-weight: bold; font-size: x-small; text-decoration: none; + color: #FFF; background-color: transparent; + } + + td.header { + font-family: arial, helvetica, sans-serif; font-size: x-small; + vertical-align: top; width: 33%; + color: #FFF; background-color: #666; + } + td.author { font-weight: bold; font-size: x-small; margin-left: 4em; } + td.author-text { font-size: x-small; } + + /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */ + a.info { + /* This is the key. */ + position: relative; + z-index: 24; + text-decoration: none; + } + a.info:hover { + z-index: 25; + color: #FFF; background-color: #900; + } + a.info span { display: none; } + a.info:hover span.info { + /* The span will display just on :hover state. */ + display: block; + position: absolute; + font-size: smaller; + top: 2em; left: -5em; width: 15em; + padding: 2px; border: 1px solid #333; + color: #900; background-color: #EEE; + text-align: left; + } + + a { font-weight: bold; } + a:link { color: #900; background-color: transparent; } + a:visited { color: #633; background-color: transparent; } + a:active { color: #633; background-color: transparent; } + + p { margin-left: 2em; margin-right: 2em; } + p.copyright { font-size: x-small; } + p.toc { font-size: small; font-weight: bold; margin-left: 3em; } + table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; } + td.toc { font-size: small; font-weight: bold; vertical-align: text-top; } + + ol.text { margin-left: 2em; margin-right: 2em; } + ul.text { margin-left: 2em; margin-right: 2em; } + li { margin-left: 3em; } + + /* RFC-2629 <spanx>s and <artwork>s. */ + em { font-style: italic; } + strong { font-weight: bold; } + dfn { font-weight: bold; font-style: normal; } + cite { font-weight: normal; font-style: normal; } + tt { color: #036; } + tt, pre, pre dfn, pre em, pre cite, pre span { + font-family: "Courier New", Courier, monospace; font-size: small; + } + pre { + text-align: left; padding: 4px; + color: #000; background-color: #CCC; + } + pre dfn { color: #900; } + pre em { color: #66F; background-color: #FFC; font-weight: normal; } + pre .key { color: #33C; font-weight: bold; } + pre .id { color: #900; } + pre .str { color: #000; background-color: #CFF; } + pre .val { color: #066; } + pre .rep { color: #909; } + pre .oth { color: #000; background-color: #FCF; } + pre .err { background-color: #FCC; } + + /* RFC-2629 <texttable>s. */ + table.all, table.full, table.headers, table.none { + font-size: small; text-align: center; border-width: 2px; + vertical-align: top; border-collapse: collapse; + } + table.all, table.full { border-style: solid; border-color: black; } + table.headers, table.none { border-style: none; } + th { + font-weight: bold; border-color: black; + border-width: 2px 2px 3px 2px; + } + table.all th, table.full th { border-style: solid; } + table.headers th { border-style: none none solid none; } + table.none th { border-style: none; } + table.all td { + border-style: solid; border-color: #333; + border-width: 1px 2px; + } + table.full td, table.headers td, table.none td { border-style: none; } + + hr { height: 1px; } + hr.insert { + width: 80%; border-style: none; border-width: 0; + color: #CCC; background-color: #CCC; + } +--></style> +</head> +<body> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1"> +<tr><td class="header">OAuth Working Group</td><td class="header">M. Jones</td></tr> +<tr><td class="header">Internet-Draft</td><td class="header">Microsoft</td></tr> +<tr><td class="header">Intended status: Standards Track</td><td class="header">D. Hardt</td></tr> +<tr><td class="header">Expires: August 2, 2012</td><td class="header">independent</td></tr> +<tr><td class="header"> </td><td class="header">D. Recordon</td></tr> +<tr><td class="header"> </td><td class="header">Facebook</td></tr> +<tr><td class="header"> </td><td class="header">January 30, 2012</td></tr> +</table></td></tr></table> +<h1><br />The OAuth 2.0 Authorization Protocol: Bearer Tokens<br />draft-ietf-oauth-v2-bearer-16</h1> + +<h3>Abstract</h3> + +<p> + This specification describes how to use bearer tokens in HTTP + requests to access OAuth 2.0 protected resources. Any party + in possession of a bearer token (a "bearer") can use it to get + access to the associated resources (without demonstrating possession + of a cryptographic key). To prevent misuse, bearer tokens + need to be protected from disclosure in storage and in transport. + +</p> +<h3>Status of this Memo</h3> +<p> +This Internet-Draft is submitted in full +conformance with the provisions of BCP 78 and BCP 79.</p> +<p> +Internet-Drafts are working documents of the Internet Engineering +Task Force (IETF). Note that other groups may also distribute +working documents as Internet-Drafts. The list of current +Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</p> +<p> +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.”</p> +<p> +This Internet-Draft will expire on August 2, 2012.</p> + +<h3>Copyright Notice</h3> +<p> +Copyright (c) 2012 IETF Trust and the persons identified as the +document authors. All rights reserved.</p> +<p> +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.</p> +<a name="toc"></a><br /><hr /> +<h3>Table of Contents</h3> +<p class="toc"> +<a href="#anchor1">1.</a> +Introduction<br /> + <a href="#anchor2">1.1.</a> +Notational Conventions<br /> + <a href="#anchor3">1.2.</a> +Terminology<br /> + <a href="#anchor4">1.3.</a> +Overview<br /> +<a href="#anchor5">2.</a> +Authenticated Requests<br /> + <a href="#authz-header">2.1.</a> +Authorization Request Header Field<br /> + <a href="#body-param">2.2.</a> +Form-Encoded Body Parameter<br /> + <a href="#query-param">2.3.</a> +URI Query Parameter<br /> +<a href="#authn-header">3.</a> +The WWW-Authenticate Response Header Field<br /> + <a href="#resource-error-codes">3.1.</a> +Error Codes<br /> +<a href="#sec-con">4.</a> +Security Considerations<br /> + <a href="#threats">4.1.</a> +Security Threats<br /> + <a href="#mitigation">4.2.</a> +Threat Mitigation<br /> + <a href="#anchor6">4.3.</a> +Summary of Recommendations<br /> +<a href="#anchor7">5.</a> +IANA Considerations<br /> + <a href="#anchor8">5.1.</a> +OAuth Access Token Type Registration<br /> + <a href="#anchor9">5.1.1.</a> +The "Bearer" OAuth Access Token Type<br /> + <a href="#anchor10">5.2.</a> +Authentication Scheme Registration<br /> + <a href="#anchor11">5.2.1.</a> +The "Bearer" Authentication Scheme<br /> +<a href="#rfc.references1">6.</a> +References<br /> + <a href="#rfc.references1">6.1.</a> +Normative References<br /> + <a href="#rfc.references2">6.2.</a> +Informative References<br /> +<a href="#anchor14">Appendix A.</a> +Acknowledgements<br /> +<a href="#anchor15">Appendix B.</a> +Document History<br /> +<a href="#rfc.authors">§</a> +Authors' Addresses<br /> +</p> +<br clear="all" /> + +<a name="anchor1"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1"></a><h3>1. +Introduction</h3> + +<p> + OAuth enables clients to access protected resources by + obtaining an access token, which is defined in + OAuth 2.0 Authorization <a class='info' href='#I-D.ietf-oauth-v2'>[I‑D.ietf‑oauth‑v2]<span> (</span><span class='info'>Hammer, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” January 2012.</span><span>)</span></a> + as "a string representing an access + authorization issued to the client", rather than using the + resource owner's credentials directly. + +</p> +<p> + Tokens are issued to clients by an authorization server with the approval of + the resource owner. The client uses the access token to access the protected resources + hosted by the resource server. This specification describes how to make protected resource + requests when the OAuth access token is a bearer token. + +</p> +<p> + This specification defines the use of bearer tokens over + HTTP/1.1 <a class='info' href='#I-D.ietf-httpbis-p1-messaging'>[I‑D.ietf‑httpbis‑p1‑messaging]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 1: URIs, Connections, and Message Parsing,” January 2012.</span><span>)</span></a> + using + TLS <a class='info' href='#RFC5246'>[RFC5246]<span> (</span><span class='info'>Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.</span><span>)</span></a> to access protected resources. + TLS is mandatory to implement + and use with this specification; other specifications may + extend this specification for use with other transport + protocols. + While designed for use with access tokens resulting from + OAuth 2.0 Authorization <a class='info' href='#I-D.ietf-oauth-v2'>[I‑D.ietf‑oauth‑v2]<span> (</span><span class='info'>Hammer, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” January 2012.</span><span>)</span></a> + flows to access OAuth protected resources, this + specification actually defines a general HTTP authorization + method that can be used with bearer tokens from any source + to access any resources protected by those bearer tokens. + +</p> +<a name="anchor2"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1.1"></a><h3>1.1. +Notational Conventions</h3> + +<p> + 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 + Key words for use in RFCs to Indicate Requirement Levels <a class='info' href='#RFC2119'>[RFC2119]<span> (</span><span class='info'>Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.</span><span>)</span></a>. + +</p> +<p> + This document uses the Augmented Backus-Naur Form (ABNF) + notation of + HTTP/1.1, Part 1 <a class='info' href='#I-D.ietf-httpbis-p1-messaging'>[I‑D.ietf‑httpbis‑p1‑messaging]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 1: URIs, Connections, and Message Parsing,” January 2012.</span><span>)</span></a>, + which is based upon the + Augmented Backus-Naur Form (ABNF) <a class='info' href='#RFC5234'>[RFC5234]<span> (</span><span class='info'>Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.</span><span>)</span></a> + notation. Additionally, the following rules are included from + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>: + auth-param, auth-scheme, and b64token; and from + Uniform Resource Identifier (URI) <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a>: + URI-Reference. + +</p> +<p> + Unless otherwise noted, all the protocol parameter names and values are case sensitive. + +</p> +<a name="anchor3"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1.2"></a><h3>1.2. +Terminology</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>Bearer Token</dt> +<dd> + + A security token with the property that any party in + possession of the token (a "bearer") can use the token + in any way that any other party in possession of it can. + Using a bearer token does not require a bearer to prove + possession of cryptographic key material + (proof-of-possession). + +</dd> +</dl></blockquote><p> + +</p> +<p> + All other terms are as defined in + OAuth 2.0 Authorization <a class='info' href='#I-D.ietf-oauth-v2'>[I‑D.ietf‑oauth‑v2]<span> (</span><span class='info'>Hammer, E., Recordon, D., and D. Hardt, “The OAuth 2.0 Authorization Protocol,” January 2012.</span><span>)</span></a>. + +</p> +<a name="anchor4"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1.3"></a><h3>1.3. +Overview</h3> + +<p> + OAuth provides a method for clients to access a protected resource on behalf of a + resource owner. In the general case, + before a client can access a protected resource, it must first obtain + an authorization grant from the resource owner and then exchange the authorization grant for + an access token. + The access token represents the grant's scope, duration, and + other attributes granted by the authorization grant. The + client accesses the protected resource by presenting the + access token to the resource server. + In some cases, a client can directly present its own + credentials to an authorization server to obtain an access + token without having to first obtain an authorization grant from a + resource owner. + +</p> +<p> + The access token provides an abstraction, replacing different authorization + constructs (e.g. username and password, assertion) for a single token understood by the + resource server. This abstraction enables issuing access tokens valid for a short time + period, as well as removing the resource server's need to understand a wide range of + authentication schemes. + +</p><br /><hr class="insert" /> +<a name="Figure-1"></a> +<div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> ++--------+ +---------------+ +| |--(A)- Authorization Request ->| Resource | +| | | Owner | +| |<-(B)-- Authorization Grant ---| | +| | +---------------+ +| | +| | Authorization Grant & +---------------+ +| |--(C)--- Client Credentials -->| Authorization | +| Client | | Server | +| |<-(D)----- Access Token -------| | +| | +---------------+ +| | +| | +---------------+ +| |--(E)----- Access Token ------>| Resource | +| | | Server | +| |<-(F)--- Protected Resource ---| | ++--------+ +---------------+ +</pre></div><table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Figure 1: Abstract Protocol Flow </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + The abstract flow illustrated in <a class='info' href='#Figure-1'>Figure 1<span> (</span><span class='info'>Abstract Protocol Flow</span><span>)</span></a> describes the overall + OAuth 2.0 protocol architecture. The following steps are specified within this + document: + + </p> +<blockquote class="text"> +<p> + E) The client makes a protected resource request to the resource server by presenting + the access token. + +</p> +<p> + F) The resource server validates the access token, and if valid, serves the request. + +</p> +</blockquote><p> + +</p> +<a name="anchor5"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2"></a><h3>2. +Authenticated Requests</h3> + +<p> + This section defines three + methods of sending bearer access tokens in resource requests + to resource servers. Clients MUST NOT use more than one + method to transmit the token in each request. + +</p> +<a name="authz-header"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.1"></a><h3>2.1. +Authorization Request Header Field</h3> + +<p> + When sending the access token in the <tt>Authorization</tt> request header field + defined by + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>, + the + client uses the <tt>Bearer</tt> + authentication scheme to transmit the access token. + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +GET /resource HTTP/1.1 +Host: server.example.com +Authorization: Bearer vF9dft4qmT +</pre></div> +<p> + The <tt>Authorization</tt> header field uses the framework defined by + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a> + as follows: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +credentials = "Bearer" 1*SP b64token +</pre></div> +<p> + The b64token syntax was chosen over the alternative + #auth-param syntax also defined by + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a> + both for simplicity + and for compatibility with existing implementations. + If additional parameters are needed in the future, a + different scheme would need to be defined. + +</p> +<p> + Clients SHOULD make authenticated requests with a bearer + token using the <tt>Authorization</tt> + request header field with the <tt>Bearer</tt> HTTP authorization scheme. + Resource servers MUST support this method. + +</p> +<a name="body-param"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.2"></a><h3>2.2. +Form-Encoded Body Parameter</h3> + +<p> + When sending the access token in the HTTP request + entity-body, the client adds the access token to the request + body using the <tt>access_token</tt> + parameter. The client MUST NOT use this method unless + all of the following conditions are met: + </p> +<ul class="text"> +<li> + The HTTP request entity-header includes the <tt>Content-Type</tt> + header field set to <tt>application/x-www-form-urlencoded</tt>. + +</li> +<li> + The entity-body follows the encoding requirements of the + <tt>application/x-www-form-urlencoded</tt> content-type as + defined by + HTML 4.01 <a class='info' href='#W3C.REC-html401-19991224'>[W3C.REC‑html401‑19991224]<span> (</span><span class='info'>Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” December 1999.</span><span>)</span></a>. + +</li> +<li> + The HTTP request entity-body is single-part. + +</li> +<li> + The content to be encoded in the entity-body MUST + consist entirely of ASCII <a class='info' href='#USASCII'>[USASCII]<span> (</span><span class='info'>American National Standards Institute, “Coded Character Set -- 7-bit American Standard Code for Information Interchange,” 1986.</span><span>)</span></a> characters. + +</li> +<li> + The HTTP request method is one for which the request + body has defined semantics. In particular, + this means that the <tt>GET</tt> + method MUST NOT be used. + +</li> +</ul><p> + +</p> +<p> + The entity-body MAY include other request-specific + parameters, in which case, the <tt>access_token</tt> parameter MUST be properly + separated from the request-specific parameters using <tt>&</tt> character(s) (ASCII code 38). + +</p> +<p> + For example, the client makes the following HTTP request using transport-layer + security: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +POST /resource HTTP/1.1 +Host: server.example.com +Content-Type: application/x-www-form-urlencoded + +access_token=vF9dft4qmT +</pre></div> +<p> + The <tt>application/x-www-form-urlencoded</tt> + method SHOULD NOT be used except in application contexts + where participating browsers do not have access to the + <tt>Authorization</tt> request header + field. Resource servers MAY support this method. + +</p> +<a name="query-param"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2.3"></a><h3>2.3. +URI Query Parameter</h3> + +<p> + When sending the access token in the HTTP request URI, the client adds the access + token to the request URI query component as defined by + Uniform Resource Identifier (URI) <a class='info' href='#RFC3986'>[RFC3986]<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a> + using + the <tt>access_token</tt> parameter. + +</p> +<p> + For example, the client makes the following HTTP request using transport-layer + security: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +GET /resource?access_token=vF9dft4qmT HTTP/1.1 +Host: server.example.com +</pre></div> +<p> + The HTTP request URI query can include other + request-specific parameters, in which case, the <tt>access_token</tt> parameter MUST be properly + separated from the request-specific parameters using <tt>&</tt> character(s) (ASCII code 38). + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +https://server.example.com/resource?x=y&access_token=vF9dft4qmT&p=q +</pre></div> +<p> + Because of the security weaknesses associated with the URI + method (see <a class='info' href='#sec-con'>Section 4<span> (</span><span class='info'>Security Considerations</span><span>)</span></a>), including the high + likelihood that the URL containing the access token will be + logged, it SHOULD NOT be used unless it is impossible to + transport the access token in the <tt>Authorization</tt> request header field or + the HTTP request entity-body. Resource servers MAY support + this method. + +</p> +<a name="authn-header"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3"></a><h3>3. +The WWW-Authenticate Response Header Field</h3> + +<p> + If the protected resource request does not include + authentication credentials or does not contain an access + token that enables access to the protected resource, + the resource server MUST include the HTTP <tt>WWW-Authenticate</tt> response header field; + it MAY include it in response to other conditions as well. + The <tt>WWW-Authenticate</tt> header + field uses the framework defined by + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</p> +<p> + All challenges defined by this specification MUST use the + auth-scheme value <tt>Bearer</tt>. This + scheme MUST be followed by one or more auth-param values. The + auth-param attributes used or defined by this specification + are as follows. Other auth-param attributes MAY be used as + well. + +</p> +<p> + A <tt>realm</tt> attribute MAY be included + to indicate the scope of protection in the manner described in + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + The <tt>realm</tt> attribute MUST NOT appear more than once. + +</p> +<p> + The <tt>scope</tt> attribute is a space-delimited list of scope values + indicating the required scope of the access token for accessing the requested resource. + In some cases, the <tt>scope</tt> value + will be used when requesting a new access token with + sufficient scope of access to utilize the protected resource. + Use of the <tt>scope</tt> attribute is OPTIONAL. + The <tt>scope</tt> attribute MUST NOT appear more than once. + The <tt>scope</tt> value is intended for + programmatic use and is not meant to be displayed to + end users. + +</p> +<p> + If the protected resource request included an access token and failed authentication, the + resource server SHOULD include the <tt>error</tt> attribute to provide + the client with the reason why the access request was declined. The parameter value is + described in <a class='info' href='#resource-error-codes'>Section 3.1<span> (</span><span class='info'>Error Codes</span><span>)</span></a>. + In addition, the resource server MAY include the <tt>error_description</tt> attribute to provide + developers a human-readable explanation that is not meant + to be displayed to end users. + It also MAY include + the <tt>error_uri</tt> attribute with + an absolute URI identifying a human-readable web page explaining the error. + The <tt>error</tt>, <tt>error_description</tt>, and + <tt>error_uri</tt> attributes MUST NOT appear more than once. + +</p> +<p> + Values for the <tt>scope</tt> attribute MUST NOT include + characters outside the set %x21 / %x23-5B / %x5D-7E + for representing scope values and %x20 for delimiters between scope values. + Values for the <tt>error</tt> and <tt>error_description</tt> attributes MUST NOT include + characters outside the set %x20-21 / %x23-5B / %x5D-7E. + Values for the <tt>error_uri</tt> attribute + MUST conform to the URI-Reference syntax, and thus MUST NOT include + characters outside the set %x21 / %x23-5B / %x5D-7E. + +</p> +<p> + For example, in response to a protected resource request without authentication: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Bearer realm="example" +</pre></div> +<p> + And in response to a protected resource request with an authentication attempt using an + expired access token: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Bearer realm="example", + error="invalid_token", + error_description="The access token expired" +</pre></div> +<a name="resource-error-codes"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.1"></a><h3>3.1. +Error Codes</h3> + +<p> + When a request fails, the resource server responds using the appropriate HTTP status + code (typically, 400, 401, 403, or 405), + and includes one of the following error codes in + the response: + + </p> +<blockquote class="text"><dl> +<dt>invalid_request</dt> +<dd> + + The request is missing a required parameter, includes an unsupported parameter or + parameter value, repeats the same parameter, uses more than one method for + including an access token, or is otherwise malformed. The resource server SHOULD + respond with the HTTP 400 (Bad Request) status code. + +</dd> +<dt>invalid_token</dt> +<dd> + + The access token provided is expired, revoked, malformed, or invalid for other + reasons. The resource SHOULD respond with the HTTP 401 (Unauthorized) status + code. The client MAY request a new access token and retry the protected resource + request. + +</dd> +<dt>insufficient_scope</dt> +<dd> + + The request requires higher privileges than provided by the access token. The + resource server SHOULD respond with the HTTP 403 (Forbidden) status code and MAY + include the <tt>scope</tt> attribute with the scope necessary to + access the protected resource. + +</dd> +</dl></blockquote><p> + +</p> +<p> + If the request lacks any authentication information (i.e. the client was unaware + authentication is necessary or attempted using an unsupported authentication method), + the resource server SHOULD NOT include an error code or other error information. + +</p> +<p> + For example: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre> +HTTP/1.1 401 Unauthorized +WWW-Authenticate: Bearer realm="example" +</pre></div> +<a name="sec-con"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4"></a><h3>4. +Security Considerations</h3> + +<p> + This section describes the relevant security threats regarding + token handling when using bearer tokens and describes how to + mitigate these threats. + +</p> +<a name="threats"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4.1"></a><h3>4.1. +Security Threats</h3> + +<p> + The following list presents several common threats against + protocols utilizing some form of tokens. This list of + threats is based on + NIST Special Publication 800-63 <a class='info' href='#NIST800-63'>[NIST800‑63]<span> (</span><span class='info'>Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., and E. Nabbus, “NIST Special Publication 800-63-1, INFORMATION SECURITY,” December 2008.</span><span>)</span></a>. + Since this document builds on the + OAuth 2.0 specification, we exclude a discussion of threats + that are described there or in related documents. + +</p> +<p> + </p> +<blockquote class="text"><dl> +<dt>Token manufacture/modification:</dt> +<dd> + An attacker may generate a bogus token or modify the + token contents (such as the authentication or attribute + statements) of an existing token, causing the resource + server to grant inappropriate access to the client. + For example, an attacker may modify the token to extend + the validity period; a malicious client may modify the + assertion to gain access to information that they + should not be able to view. + +</dd> +<dt>Token disclosure:</dt> +<dd> + Tokens may contain authentication and attribute + statements that include sensitive information. + +</dd> +<dt>Token redirect:</dt> +<dd> + An attacker uses a token generated for consumption by + one resource server to gain access to a different + resource server that mistakenly believes the token to be + for it. + +</dd> +<dt>Token replay:</dt> +<dd> + An attacker attempts to use a token that has already + been used with that resource server in the past. + +</dd> +</dl></blockquote><p> + +</p> +<a name="mitigation"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4.2"></a><h3>4.2. +Threat Mitigation</h3> + +<p> + A large range of threats can be mitigated by protecting the + contents of the token by using a digital signature or a + Message Authentication Code (MAC). + Alternatively, a bearer token can contain a reference to + authorization information, rather than encoding the + information directly. Such references MUST be infeasible for + an attacker to guess; using a reference may require an extra + interaction between a server and the token issuer to resolve + the reference to the authorization information. + The mechanics of such an interaction are not defined by this + specification. + +</p> +<p> + This document does not specify the encoding or the contents + of the token; hence detailed recommendations about the means + of guaranteeing token integrity protection are outside the + scope of this document. The token integrity protection MUST + be sufficient to prevent the token from being modified. + +</p> +<p> + To deal with token redirect, it is important for the + authorization server to include the identity of the intended + recipients (the audience), typically a single resource + server (or a list of resource servers), in the token. + Restricting the use of the token to a specific scope is also + RECOMMENDED. + +</p> +<p> + The authorization server MUST implement TLS. + Which version(s) ought to be implemented will vary over + time, and depend on the widespread deployment and known + security vulnerabilities at the time of implementation. + At the time of this writing, + TLS version 1.2 <a class='info' href='#RFC5246'>[RFC5246]<span> (</span><span class='info'>Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.</span><span>)</span></a> + is the most recent version, but has very limited actual + deployment, and might not be readily available in + implementation toolkits. + TLS version 1.0 <a class='info' href='#RFC2246'>[RFC2246]<span> (</span><span class='info'>Dierks, T. and C. Allen, “The TLS Protocol Version 1.0,” January 1999.</span><span>)</span></a> + is the most widely deployed version, and will give the + broadest interoperability. + +</p> +<p> + To protect against token disclosure, confidentiality + protection MUST be applied using + TLS <a class='info' href='#RFC5246'>[RFC5246]<span> (</span><span class='info'>Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.</span><span>)</span></a> + with a ciphersuite that provides confidentiality and + integrity protection. This + requires that the communication interaction between the + client and the authorization server, as well as the + interaction between the client and the resource server, + utilize confidentiality and integrity protection. + Since TLS is mandatory to + implement and to use with this specification, it is the + preferred approach for preventing token disclosure via the + communication channel. For those cases where the client + is prevented from observing the contents of the token, token + encryption MUST be applied in addition to the usage of TLS + protection. + As a further defense against token disclosure, the client + MUST validate the TLS certificate chain when making requests + to protected resources. + +</p> +<p> + Cookies are typically transmitted in the clear. Thus, any + information contained in them is at risk of disclosure. + Therefore, bearer tokens MUST NOT be stored in cookies that + can be sent in the clear. + +</p> +<p> + In some deployments, including those utilizing load + balancers, the TLS connection to the resource server + terminates prior to the actual server that provides the + resource. This could leave the token unprotected between + the front end server where the TLS connection terminates and + the back end server that provides the resource. In such + deployments, sufficient measures MUST be employed to ensure + confidentiality of the token between the front end and + back end servers; encryption of the token is one possible + such measure. + +</p> +<p> + To deal with token capture and replay, + the following recommendations are + made: First, the lifetime of the token MUST be limited; + one means of achieving this is by + putting a validity time field inside the protected part of + the token. Note that using short-lived (one hour or less) + tokens reduces the impact of them being + leaked. Second, confidentiality protection of the exchanges + between the client and the authorization server and between + the client and the resource server MUST be applied. + As a + consequence, no eavesdropper along the communication path is + able to observe the token exchange. Consequently, such an + on-path adversary cannot replay the token. + Furthermore, when + presenting the token to a resource server, the client MUST + verify the identity of that resource server, as per + 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) + <a class='info' href='#RFC6125'>[RFC6125]<span> (</span><span class='info'>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),” March 2011.</span><span>)</span></a>. + Note that the + client MUST validate the TLS certificate chain when making + these requests to protected resources. Presenting the token + to an unauthenticated and unauthorized resource server or + failing to validate the certificate chain will allow + adversaries to steal the token and gain unauthorized access + to protected resources. + +</p> +<a name="anchor6"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4.3"></a><h3>4.3. +Summary of Recommendations</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>Safeguard bearer tokens:</dt> +<dd> + Client implementations MUST ensure that bearer tokens + are not leaked to unintended parties, as they will be + able to use them to gain access to protected resources. + This is the primary security consideration when using + bearer tokens and underlies all the more + specific recommendations that follow. + +</dd> +<dt>Validate SSL certificate chains:</dt> +<dd> + The client MUST validate the TLS certificate chain when + making requests to protected resources. Failing to do + so may enable DNS hijacking attacks to steal the token + and gain unintended access. + +</dd> +<dt>Always use TLS (https):</dt> +<dd> + Clients MUST always use + TLS <a class='info' href='#RFC5246'>[RFC5246]<span> (</span><span class='info'>Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.</span><span>)</span></a> + (https) or equivalent transport security when making requests + with bearer tokens. Failing to do so exposes the token + to numerous attacks that could give attackers unintended + access. + +</dd> +<dt>Don't store bearer tokens in cookies:</dt> +<dd> + Implementations MUST NOT store bearer tokens within + cookies that can be sent in the clear (which is the + default transmission mode for cookies). + Implementations that do store bearer tokens in cookies + MUST take precautions against cross site request forgery. + +</dd> +<dt>Issue short-lived bearer tokens:</dt> +<dd> + Token servers SHOULD issue short-lived (one hour or + less) bearer tokens, particularly when issuing tokens to + clients that run within a web browser or other + environments where information leakage may occur. Using + short-lived bearer tokens can reduce the impact of them + being leaked. + +</dd> +<dt>Issue scoped bearer tokens:</dt> +<dd> + Token servers SHOULD issue bearer tokens that contain an audience + restriction, scoping their use to the intended relying + party or set of relying parties. + +</dd> +<dt>Don't pass bearer tokens in page URLs:</dt> +<dd> + Bearer tokens SHOULD NOT be passed in page URLs (for + example as query string parameters). Instead, bearer + tokens SHOULD be passed in HTTP message headers or + message bodies for which confidentiality measures are + taken. Browsers, web servers, and other software may not + adequately secure URLs in the browser history, web + server logs, and other data structures. If bearer tokens + are passed in page URLs, attackers might be able to + steal them from the history data, logs, or other + unsecured locations. + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor7"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5"></a><h3>5. +IANA Considerations</h3> + +<a name="anchor8"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.1"></a><h3>5.1. +OAuth Access Token Type Registration</h3> + +<p> + This specification registers the following access token type in the OAuth Access Token + Type Registry. + +</p> +<a name="anchor9"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.1.1"></a><h3>5.1.1. +The "Bearer" OAuth Access Token Type</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>Type name:</dt> +<dd> + + Bearer + +</dd> +<dt>Additional Token Endpoint Response Parameters:</dt> +<dd> + + (none) + +</dd> +<dt>HTTP Authentication Scheme(s):</dt> +<dd> + + Bearer + +</dd> +<dt>Change controller:</dt> +<dd> + + IETF + +</dd> +<dt>Specification document(s):</dt> +<dd> + + [[ this document ]] + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor10"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.2"></a><h3>5.2. +Authentication Scheme Registration</h3> + +<p> + This specification registers the following authentication + scheme in the Authentication Scheme Registry defined in + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</p> +<a name="anchor11"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5.2.1"></a><h3>5.2.1. +The "Bearer" Authentication Scheme</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>Authentication Scheme Name:</dt> +<dd> + + Bearer + +</dd> +<dt>Pointer to specification text:</dt> +<dd> + + [[ this document ]] + +</dd> +<dt>Notes (optional):</dt> +<dd> + + (none) + +</dd> +</dl></blockquote><p> + +</p> +<a name="rfc.references"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6"></a><h3>6. +References</h3> + +<a name="rfc.references1"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>6.1. Normative References</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><a name="I-D.ietf-httpbis-p1-messaging">[I-D.ietf-httpbis-p1-messaging]</a></td> +<td class="author-text">Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “<a href="http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-18">HTTP/1.1, part 1: URIs, Connections, and Message Parsing</a>,” draft-ietf-httpbis-p1-messaging-18 (work in progress), January 2012 (<a href="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p1-messaging-18.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="I-D.ietf-httpbis-p7-auth">[I-D.ietf-httpbis-p7-auth]</a></td> +<td class="author-text">Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “<a href="http://tools.ietf.org/html/draft-ietf-httpbis-p7-auth-18">HTTP/1.1, part 7: Authentication</a>,” draft-ietf-httpbis-p7-auth-18 (work in progress), January 2012 (<a href="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p7-auth-18.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="I-D.ietf-oauth-v2">[I-D.ietf-oauth-v2]</a></td> +<td class="author-text">Hammer, E., Recordon, D., and D. Hardt, “<a href="http://tools.ietf.org/html/draft-ietf-oauth-v2-23">The OAuth 2.0 Authorization Protocol</a>,” draft-ietf-oauth-v2-23 (work in progress), January 2012 (<a href="http://www.ietf.org/internet-drafts/draft-ietf-oauth-v2-23.txt">TXT</a>, <a href="http://www.ietf.org/internet-drafts/draft-ietf-oauth-v2-23.pdf">PDF</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td> +<td class="author-text"><a href="mailto:sob@harvard.edu">Bradner, S.</a>, “<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,” BCP 14, RFC 2119, March 1997 (<a href="http://www.rfc-editor.org/rfc/rfc2119.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2119.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2119.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2246">[RFC2246]</a></td> +<td class="author-text"><a href="mailto:tdierks@certicom.com">Dierks, T.</a> and <a href="mailto:callen@certicom.com">C. Allen</a>, “<a href="http://tools.ietf.org/html/rfc2246">The TLS Protocol Version 1.0</a>,” RFC 2246, January 1999 (<a href="http://www.rfc-editor.org/rfc/rfc2246.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC3986">[RFC3986]</a></td> +<td class="author-text"><a href="mailto:timbl@w3.org">Berners-Lee, T.</a>, <a href="mailto:fielding@gbiv.com">Fielding, R.</a>, and <a href="mailto:LMM@acm.org">L. Masinter</a>, “<a href="http://tools.ietf.org/html/rfc3986">Uniform Resource Identifier (URI): Generic Syntax</a>,” STD 66, RFC 3986, January 2005 (<a href="http://www.rfc-editor.org/rfc/rfc3986.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc3986.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc3986.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC5234">[RFC5234]</a></td> +<td class="author-text">Crocker, D. and P. Overell, “<a href="http://tools.ietf.org/html/rfc5234">Augmented BNF for Syntax Specifications: ABNF</a>,” STD 68, RFC 5234, January 2008 (<a href="http://www.rfc-editor.org/rfc/rfc5234.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC5246">[RFC5246]</a></td> +<td class="author-text">Dierks, T. and E. Rescorla, “<a href="http://tools.ietf.org/html/rfc5246">The Transport Layer Security (TLS) Protocol Version 1.2</a>,” RFC 5246, August 2008 (<a href="http://www.rfc-editor.org/rfc/rfc5246.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC6125">[RFC6125]</a></td> +<td class="author-text">Saint-Andre, P. and J. Hodges, “<a href="http://tools.ietf.org/html/rfc6125">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)</a>,” RFC 6125, March 2011 (<a href="http://www.rfc-editor.org/rfc/rfc6125.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="USASCII">[USASCII]</a></td> +<td class="author-text">American National Standards Institute, “Coded Character Set -- 7-bit American Standard Code for Information Interchange,” ANSI X3.4, 1986.</td></tr> +<tr><td class="author-text" valign="top"><a name="W3C.REC-html401-19991224">[W3C.REC-html401-19991224]</a></td> +<td class="author-text">Hors, A., Raggett, D., and I. Jacobs, “<a href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML 4.01 Specification</a>,” World Wide Web Consortium Recommendation REC-html401-19991224, December 1999 (<a href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML</a>).</td></tr> +</table> + +<a name="rfc.references2"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>6.2. Informative References</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><a name="NIST800-63">[NIST800-63]</a></td> +<td class="author-text">Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., and E. Nabbus, “<a href="http://csrc.nist.gov/publications/PubsDrafts.html#SP-800-63-Rev.%201">NIST Special Publication 800-63-1, INFORMATION SECURITY</a>,” December 2008.</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2616">[RFC2616]</a></td> +<td class="author-text"><a href="mailto:fielding@ics.uci.edu">Fielding, R.</a>, <a href="mailto:jg@w3.org">Gettys, J.</a>, <a href="mailto:mogul@wrl.dec.com">Mogul, J.</a>, <a href="mailto:frystyk@w3.org">Frystyk, H.</a>, <a href="mailto:masinter@parc.xerox.com">Masinter, L.</a>, <a href="mailto:paulle@microsoft.com">Leach, P.</a>, and <a href="mailto:timbl@w3.org">T. Berners-Lee</a>, “<a href="http://tools.ietf.org/html/rfc2616">Hypertext Transfer Protocol -- HTTP/1.1</a>,” RFC 2616, June 1999 (<a href="http://www.rfc-editor.org/rfc/rfc2616.txt">TXT</a>, <a href="http://www.rfc-editor.org/rfc/rfc2616.ps">PS</a>, <a href="http://www.rfc-editor.org/rfc/rfc2616.pdf">PDF</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2616.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2616.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2617">[RFC2617]</a></td> +<td class="author-text"><a href="mailto:john@math.nwu.edu">Franks, J.</a>, <a href="mailto:pbaker@verisign.com">Hallam-Baker, P.</a>, <a href="mailto:jeff@AbiSource.com">Hostetler, J.</a>, <a href="mailto:lawrence@agranat.com">Lawrence, S.</a>, <a href="mailto:paulle@microsoft.com">Leach, P.</a>, Luotonen, A., and <a href="mailto:stewart@OpenMarket.com">L. Stewart</a>, “<a href="http://tools.ietf.org/html/rfc2617">HTTP Authentication: Basic and Digest Access Authentication</a>,” RFC 2617, June 1999 (<a href="http://www.rfc-editor.org/rfc/rfc2617.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2617.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2617.xml">XML</a>).</td></tr> +</table> + +<a name="anchor14"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.A"></a><h3>Appendix A. +Acknowledgements</h3> + +<p> + The following people contributed to preliminary versions of this document: + Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland (Microsoft), Brent Goldman (Facebook), + Raffi Krikorian (Twitter), Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and + concepts within are a product of the OAuth community, the WRAP community, and the OAuth Working + Group. + +</p> +<p> + The OAuth Working Group has dozens of very active contributors who proposed ideas and + wording for this document, including: + Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, + John Bradley, Brian Campbell, Leah Culver, Bill de hÓra, + Brian Ellin, Igor Faynberg, Stephen Farrell, George Fletcher, + Tim Freeman, Evan Gilbert, Yaron Y. Goland, Thomas Hardjono, + Justin Hart, Phil Hunt, John Kemp, Eran Hammer-Lahav, + Chasen Le Hara, Barry Leiba, Michael B. Jones, + Torsten Lodderstedt, Eve Maler, James Manger, Laurence Miao, + William J. Mills, Chuck Mortimore, Anthony Nadalin, + Julian Reschke, Justin Richer, Peter Saint-Andre, Nat Sakimura, + Rob Sayre, Marius Scurtescu, Naitik Shah, Justin Smith, + Jeremy Suriel, Christian Stübner, Paul Tarjan, + Hannes Tschofenig, Franklin Tse, and Shane Weeden. + +</p> +<a name="anchor15"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.B"></a><h3>Appendix B. +Document History</h3> + +<p> + [[ to be removed by the RFC editor before publication as an RFC ]] + +</p> +<p> + -16 + </p> +<ul class="text"> +<li> + Use the HTTPbis auth-param syntax for Bearer challenge + attributes. + +</li> +<li> + Dropped the sentence "The <tt>realm</tt> value is intended for + programmatic use and is not meant to be displayed to end + users". + +</li> +<li> + Reordered form-encoded body parameter description bullets + for better readability. + +</li> +<li> + Added <a class='info' href='#USASCII'>[USASCII]<span> (</span><span class='info'>American National Standards Institute, “Coded Character Set -- 7-bit American Standard Code for Information Interchange,” 1986.</span><span>)</span></a> reference. + +</li> +</ul><p> + +</p> +<p> + -15 + </p> +<ul class="text"> +<li> + Clarified that form-encoded content must consist entirely + of ASCII characters. + +</li> +<li> + Added TLS version requirements. + +</li> +<li> + Applied editorial improvements suggested by Mark + Nottingham during the APPS area review. + +</li> +</ul><p> + +</p> +<p> + -14 + </p> +<ul class="text"> +<li> + Changes made in response to review comments by Security + Area Director Stephen Farrell. Specifically: + +</li> +<li> + Strengthened warnings about passing an access token as a + query parameter and more precisely described the + limitations placed upon the use of this method. + +</li> +<li> + Clarified that the <tt>realm</tt> + attribute MAY included to indicate the scope of protection + in the manner described in + HTTP/1.1, Part 7 <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</li> +<li> + Normatively stated that "the token integrity protection + MUST be sufficient to prevent the token from being + modified". + +</li> +<li> + Added statement that "TLS is mandatory to implement and + use with this specification" to the introduction. + +</li> +<li> + Stated that TLS MUST be used with "a ciphersuite that + provides confidentiality and integrity protection". + +</li> +<li> + Added "As a further defense against token disclosure, the + client MUST validate the TLS certificate chain when making + requests to protected resources" to the Threat Mitigation + section. + +</li> +<li> + Clarified that putting a validity time field inside the + protected part of the token is one means, but not the only + means, of limiting the lifetime of the token. + +</li> +<li> + Dropped the confusing phrase "for instance, through the + use of TLS" from the sentence about confidentiality + protection of the exchanges. + +</li> +<li> + Reference RFC 6125 for identity verification, rather than + RFC 2818. + +</li> +<li> + Stated that the token MUST be protected between front end + and back end servers when the TLS connection terminates at + a front end server that is distinct from the actual server + that provides the resource. + +</li> +<li> + Stated that bearer tokens MUST NOT be stored in cookies + that can be sent in the clear in the Threat Mitigation + section. + +</li> +<li> + Replaced sole remaining reference to <a class='info' href='#RFC2616'>[RFC2616]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.</span><span>)</span></a> with + HTTPbis <a class='info' href='#I-D.ietf-httpbis-p1-messaging'>[I‑D.ietf‑httpbis‑p1‑messaging]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 1: URIs, Connections, and Message Parsing,” January 2012.</span><span>)</span></a> + reference. + +</li> +<li> + Replaced all references where the reference is used as if + it were part of the sentence (such as "defined by + [I-D.whatever]") with ones where the specification name is + used, followed by the reference (such as "defined by + Whatever [I-D.whatever]"). + +</li> +<li> + Other on-normative editorial improvements. + +</li> +</ul><p> + +</p> +<p> + -13 + </p> +<ul class="text"> +<li> + At the request of Hannes Tschofenig, made ABNF changes to + make it clear that no special WWW-Authenticate response + header field parsers are needed. The <tt>scope</tt>, <tt>error-description</tt>, and <tt>error-uri</tt> parameters are all now + defined as quoted-string in the ABNF (as <tt>error</tt> already was). Restrictions on + these values that were formerly described in the ABNFs are + now described in normative text instead. + +</li> +</ul><p> + +</p> +<p> + -12 + </p> +<ul class="text"> +<li> + Made non-normative editorial changes that Hannes + Tschofenig requested be applied prior to forwarding the + specification to the IESG. + +</li> +<li> + Added rationale for the choice of the b64token syntax. + +</li> +<li> + Added rationale stating that receivers are free to parse + the <tt>scope</tt> attribute using a + standard quoted-string parser, since it will correctly + process all legal <tt>scope</tt> + values. + +</li> +<li> + Added additional active working group contributors to the + Acknowledgements section. + +</li> +</ul><p> + +</p> +<p> + -11 + </p> +<ul class="text"> +<li> + Replaced uses of <"> with DQUOTE to pass ABNF syntax check. + +</li> +</ul><p> + +</p> +<p> + -10 + </p> +<ul class="text"> +<li> + Removed the #auth-param option from Authorization header + syntax (leaving only the b64token syntax). + +</li> +<li> + Restricted the <tt>scope</tt> value + character set to %x21 / %x23-5B / %x5D-7E (printable ASCII + characters excluding double-quote and backslash). + Indicated that scope is intended for programmatic use and + is not meant to be displayed to end users. + +</li> +<li> + Restricted the character set for <tt>error_description</tt> strings to SP / + VCHAR and indicated that they are not meant to be + displayed to end users. + +</li> +<li> + Included more description in the Abstract, since Hannes + Tschofenig indicated that the RFC editor would require + this. + +</li> +<li> + Changed "Access Grant" to "Authorization Grant", as was + done in the core spec. + +</li> +<li> + Simplified the introduction to the Authenticated Requests + section. + +</li> +</ul><p> + +</p> +<p> + -09 + </p> +<ul class="text"> +<li> + Incorporated working group last call comments. Specific changes were: + +</li> +<li> + Use definitions from <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a> rather than <a class='info' href='#RFC2617'>[RFC2617]<span> (</span><span class='info'>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</span><span>)</span></a>. + +</li> +<li> + Update credentials definition to conform to <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</li> +<li> + Further clarified that query parameters may occur in any order. + +</li> +<li> + Specify that error_description is UTF-8 encoded + (matching the core specification). + +</li> +<li> + Registered "Bearer" Authentication Scheme in + Authentication Scheme Registry defined by + <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</li> +<li> + Updated references to oauth-v2, httpbis-p1-messaging, and + httpbis-p7-auth drafts. + +</li> +<li> + Other wording improvements not introducing normative changes. + +</li> +</ul><p> + +</p> +<p> + -08 + </p> +<ul class="text"> +<li> + Updated references to oauth-v2 and HTTPbis drafts. + +</li> +</ul><p> + +</p> +<p> + -07 + </p> +<ul class="text"> +<li> + Added missing comma in error response example. + +</li> +</ul><p> + +</p> +<p> + -06 + </p> +<ul class="text"> +<li> + Changed parameter name <tt>bearer_token</tt> to <tt>access_token</tt>, per working group + consensus. + +</li> +<li> + Changed HTTP status code for <tt>invalid_request</tt> error code from HTTP + 401 (Unauthorized) back to HTTP 400 (Bad Request), per + input from HTTP working group experts. + +</li> +</ul><p> + +</p> +<p> + -05 + </p> +<ul class="text"> +<li> + Removed OAuth Errors Registry, per design team input. + +</li> +<li> + Changed HTTP status code for <tt>invalid_request</tt> error code from HTTP + 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP + usage [[ change pending working group consensus ]]. + +</li> +<li> + Added missing quotation marks in error-uri definition. + +</li> +<li> + Added note to add language and encoding information to + error_description if the core specification does. + +</li> +<li> + Explicitly reference the Augmented Backus-Naur Form (ABNF) + defined in <a class='info' href='#RFC5234'>[RFC5234]<span> (</span><span class='info'>Crocker, D. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” January 2008.</span><span>)</span></a>. + +</li> +<li> + Use auth-param instead of repeating its definition, which + is ( token "=" ( token / quoted-string ) ). + +</li> +<li> + Clarify security considerations about including an + audience restriction in the token and include a + recommendation to issue scoped bearer tokens in the + summary of recommendations. + +</li> +</ul><p> + +</p> +<p> + -04 + </p> +<ul class="text"> +<li> + Edits responding to working group last call feedback on + -03. Specific edits enumerated below. + +</li> +<li> + Added Bearer Token definition in Terminology section. + +</li> +<li> + Changed parameter name <tt>oauth_token</tt> to <tt>bearer_token</tt>. + +</li> +<li> + Added realm parameter to <tt>WWW-Authenticate</tt> response to comply + with <a class='info' href='#RFC2617'>[RFC2617]<span> (</span><span class='info'>Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</span><span>)</span></a>. + +</li> +<li> + Removed "[ RWS 1#auth-param ]" from <tt>credentials</tt> definition since it did + not comply with the ABNF in <a class='info' href='#I-D.ietf-httpbis-p7-auth'>[I‑D.ietf‑httpbis‑p7‑auth]<span> (</span><span class='info'>Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and J. Reschke, “HTTP/1.1, part 7: Authentication,” January 2012.</span><span>)</span></a>. + +</li> +<li> + Removed restriction that the <tt>bearer_token</tt> (formerly <tt>oauth_token</tt>) parameter be the last + parameter in the entity-body and the HTTP request URI + query. + +</li> +<li> + Do not require WWW-Authenticate Response in a reply to a + malformed request, as an HTTP 400 Bad Request response + without a WWW-Authenticate header is likely the right + response in some cases of malformed requests. + +</li> +<li> + Removed OAuth Parameters registry extension. + +</li> +<li> + Numerous editorial improvements suggested by working group + members. + +</li> +</ul><p> + +</p> +<p> + -03 + </p> +<ul class="text"> +<li> + Restored the WWW-Authenticate response header + functionality deleted from the framework specification in + draft 12 based upon the specification text from draft 11. + +</li> +<li> + Augmented the OAuth Parameters registry by adding two + additional parameter usage locations: "resource request" + and "resource response". + +</li> +<li> + Registered the "oauth_token" OAuth parameter with usage + location "resource request". + +</li> +<li> + Registered the "error" OAuth parameter. + +</li> +<li> + Created the OAuth Error registry and registered errors. + +</li> +<li> + Changed the "OAuth2" OAuth access token type name to + "Bearer". + +</li> +</ul><p> + +</p> +<p> + -02 + </p> +<ul class="text"> +<li> + Incorporated feedback received on draft 01. Most changes + were to the security considerations section. No normative + changes were made. Specific changes included: + +</li> +<li> + Changed terminology from "token reuse" to "token capture + and replay". + +</li> +<li> + Removed sentence "Encrypting the token contents is another + alternative" from the security considerations since it was + redundant and potentially confusing. + +</li> +<li> + Corrected some references to "resource server" to be + "authorization server" in the security considerations. + +</li> +<li> + Generalized security considerations language about + obtaining consent of the resource owner. + +</li> +<li> + Broadened scope of security considerations description for + recommendation "Don't pass bearer tokens in page URLs". + +</li> +<li> + Removed unused reference to OAuth 1.0. + +</li> +<li> + Updated reference to framework specification and updated + David Recordon's e-mail address. + +</li> +<li> + Removed security considerations text on authenticating + clients. + +</li> +<li> + Registered the "OAuth2" OAuth access token type and + "oauth_token" parameter. + +</li> +</ul><p> + +</p> +<p> + -01 + </p> +<ul class="text"> +<li> + First public draft, which incorporates feedback received + on -00 including enhanced Security Considerations content. + This version is intended to accompany OAuth 2.0 draft 11. + +</li> +</ul><p> + +</p> +<p> + -00 + </p> +<ul class="text"> +<li> + Initial draft based on preliminary version of OAuth 2.0 draft 11. + +</li> +</ul><p> + +</p> +<a name="rfc.authors"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>Authors' Addresses</h3> +<table width="99%" border="0" cellpadding="0" cellspacing="0"> +<tr><td class="author-text"> </td> +<td class="author-text">Michael B. Jones</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Microsoft</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:mbj@microsoft.com">mbj@microsoft.com</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://self-issued.info/">http://self-issued.info/</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Dick Hardt</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">independent</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:dick.hardt@gmail.com">dick.hardt@gmail.com</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://dickhardt.org/">http://dickhardt.org/</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">David Recordon</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Facebook</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:dr@fb.com">dr@fb.com</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://www.davidrecordon.com/">http://www.davidrecordon.com/</a></td></tr> +</table> +</body></html> diff --git a/doc/specs/draft-ietf-oauth-v2-bearer.txt b/doc/specs/draft-ietf-oauth-v2-bearer.txt new file mode 100644 index 0000000..fe7a42d --- /dev/null +++ b/doc/specs/draft-ietf-oauth-v2-bearer.txt @@ -0,0 +1,1232 @@ + + + +OAuth Working Group M. Jones +Internet-Draft Microsoft +Intended status: Standards Track D. Hardt +Expires: August 2, 2012 independent + D. Recordon + Facebook + January 30, 2012 + + + The OAuth 2.0 Authorization Protocol: Bearer Tokens + draft-ietf-oauth-v2-bearer-16 + +Abstract + + This specification describes how to use bearer tokens in HTTP + requests to access OAuth 2.0 protected resources. Any party in + possession of a bearer token (a "bearer") can use it to get access to + the associated resources (without demonstrating possession of a + cryptographic key). To prevent misuse, bearer tokens need to be + protected from disclosure in storage and in transport. + +Status of this Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + 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." + + This Internet-Draft will expire on August 2, 2012. + +Copyright Notice + + Copyright (c) 2012 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 + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + + + +Jones, et al. Expires August 2, 2012 [Page 1] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + 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 + 1.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Authenticated Requests . . . . . . . . . . . . . . . . . . . . 5 + 2.1. Authorization Request Header Field . . . . . . . . . . . . 5 + 2.2. Form-Encoded Body Parameter . . . . . . . . . . . . . . . 6 + 2.3. URI Query Parameter . . . . . . . . . . . . . . . . . . . 7 + 3. The WWW-Authenticate Response Header Field . . . . . . . . . . 7 + 3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 9 + 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 + 4.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 10 + 4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 10 + 4.3. Summary of Recommendations . . . . . . . . . . . . . . . . 12 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 + 5.1. OAuth Access Token Type Registration . . . . . . . . . . . 13 + 5.1.1. The "Bearer" OAuth Access Token Type . . . . . . . . . 13 + 5.2. Authentication Scheme Registration . . . . . . . . . . . . 14 + 5.2.1. The "Bearer" Authentication Scheme . . . . . . . . . . 14 + 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 6.1. Normative References . . . . . . . . . . . . . . . . . . . 14 + 6.2. Informative References . . . . . . . . . . . . . . . . . . 15 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 + Appendix B. Document History . . . . . . . . . . . . . . . . . . 16 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 + + + + + + + + + + + + + + + + + + +Jones, et al. Expires August 2, 2012 [Page 2] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + +1. Introduction + + OAuth enables clients to access protected resources by obtaining an + access token, which is defined in OAuth 2.0 Authorization + [I-D.ietf-oauth-v2] as "a string representing an access authorization + issued to the client", rather than using the resource owner's + credentials directly. + + Tokens are issued to clients by an authorization server with the + approval of the resource owner. The client uses the access token to + access the protected resources hosted by the resource server. This + specification describes how to make protected resource requests when + the OAuth access token is a bearer token. + + This specification defines the use of bearer tokens over HTTP/1.1 + [I-D.ietf-httpbis-p1-messaging] using TLS [RFC5246] to access + protected resources. TLS is mandatory to implement and use with this + specification; other specifications may extend this specification for + use with other transport protocols. While designed for use with + access tokens resulting from OAuth 2.0 Authorization + [I-D.ietf-oauth-v2] flows to access OAuth protected resources, this + specification actually defines a general HTTP authorization method + that can be used with bearer tokens from any source to access any + resources protected by those bearer tokens. + +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 Key words for use in + RFCs to Indicate Requirement Levels [RFC2119]. + + This document uses the Augmented Backus-Naur Form (ABNF) notation of + HTTP/1.1, Part 1 [I-D.ietf-httpbis-p1-messaging], which is based upon + the Augmented Backus-Naur Form (ABNF) [RFC5234] notation. + Additionally, the following rules are included from HTTP/1.1, Part 7 + [I-D.ietf-httpbis-p7-auth]: auth-param, auth-scheme, and b64token; + and from Uniform Resource Identifier (URI) [RFC3986]: URI-Reference. + + Unless otherwise noted, all the protocol parameter names and values + are case sensitive. + +1.2. Terminology + + + + + + + + +Jones, et al. Expires August 2, 2012 [Page 3] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + Bearer Token + A security token with the property that any party in possession of + the token (a "bearer") can use the token in any way that any other + party in possession of it can. Using a bearer token does not + require a bearer to prove possession of cryptographic key material + (proof-of-possession). + + All other terms are as defined in OAuth 2.0 Authorization + [I-D.ietf-oauth-v2]. + +1.3. Overview + + OAuth provides a method for clients to access a protected resource on + behalf of a resource owner. In the general case, before a client can + access a protected resource, it must first obtain an authorization + grant from the resource owner and then exchange the authorization + grant for an access token. The access token represents the grant's + scope, duration, and other attributes granted by the authorization + grant. The client accesses the protected resource by presenting the + access token to the resource server. In some cases, a client can + directly present its own credentials to an authorization server to + obtain an access token without having to first obtain an + authorization grant from a resource owner. + + The access token provides an abstraction, replacing different + authorization constructs (e.g. username and password, assertion) for + a single token understood by the resource server. This abstraction + enables issuing access tokens valid for a short time period, as well + as removing the resource server's need to understand a wide range of + authentication schemes. + + + + + + + + + + + + + + + + + + + + + +Jones, et al. Expires August 2, 2012 [Page 4] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + +--------+ +---------------+ + | |--(A)- Authorization Request ->| Resource | + | | | Owner | + | |<-(B)-- Authorization Grant ---| | + | | +---------------+ + | | + | | Authorization Grant & +---------------+ + | |--(C)--- Client Credentials -->| Authorization | + | Client | | Server | + | |<-(D)----- Access Token -------| | + | | +---------------+ + | | + | | +---------------+ + | |--(E)----- Access Token ------>| Resource | + | | | Server | + | |<-(F)--- Protected Resource ---| | + +--------+ +---------------+ + + Figure 1: Abstract Protocol Flow + + The abstract flow illustrated in Figure 1 describes the overall OAuth + 2.0 protocol architecture. The following steps are specified within + this document: + + E) The client makes a protected resource request to the resource + server by presenting the access token. + + F) The resource server validates the access token, and if valid, + serves the request. + + +2. Authenticated Requests + + This section defines three methods of sending bearer access tokens in + resource requests to resource servers. Clients MUST NOT use more + than one method to transmit the token in each request. + +2.1. Authorization Request Header Field + + When sending the access token in the "Authorization" request header + field defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth], the + client uses the "Bearer" authentication scheme to transmit the access + token. + + + + + + + + +Jones, et al. Expires August 2, 2012 [Page 5] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + For example: + + GET /resource HTTP/1.1 + Host: server.example.com + Authorization: Bearer vF9dft4qmT + + The "Authorization" header field uses the framework defined by + HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] as follows: + + credentials = "Bearer" 1*SP b64token + + The b64token syntax was chosen over the alternative #auth-param + syntax also defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] + both for simplicity and for compatibility with existing + implementations. If additional parameters are needed in the future, + a different scheme would need to be defined. + + Clients SHOULD make authenticated requests with a bearer token using + the "Authorization" request header field with the "Bearer" HTTP + authorization scheme. Resource servers MUST support this method. + +2.2. Form-Encoded Body Parameter + + When sending the access token in the HTTP request entity-body, the + client adds the access token to the request body using the + "access_token" parameter. The client MUST NOT use this method unless + all of the following conditions are met: + + o The HTTP request entity-header includes the "Content-Type" header + field set to "application/x-www-form-urlencoded". + + o The entity-body follows the encoding requirements of the + "application/x-www-form-urlencoded" content-type as defined by + HTML 4.01 [W3C.REC-html401-19991224]. + + o The HTTP request entity-body is single-part. + + o The content to be encoded in the entity-body MUST consist entirely + of ASCII [USASCII] characters. + + o The HTTP request method is one for which the request body has + defined semantics. In particular, this means that the "GET" + method MUST NOT be used. + + The entity-body MAY include other request-specific parameters, in + which case, the "access_token" parameter MUST be properly separated + from the request-specific parameters using "&" character(s) (ASCII + code 38). + + + +Jones, et al. Expires August 2, 2012 [Page 6] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + For example, the client makes the following HTTP request using + transport-layer security: + + POST /resource HTTP/1.1 + Host: server.example.com + Content-Type: application/x-www-form-urlencoded + + access_token=vF9dft4qmT + + The "application/x-www-form-urlencoded" method SHOULD NOT be used + except in application contexts where participating browsers do not + have access to the "Authorization" request header field. Resource + servers MAY support this method. + +2.3. URI Query Parameter + + When sending the access token in the HTTP request URI, the client + adds the access token to the request URI query component as defined + by Uniform Resource Identifier (URI) [RFC3986] using the + "access_token" parameter. + + For example, the client makes the following HTTP request using + transport-layer security: + + GET /resource?access_token=vF9dft4qmT HTTP/1.1 + Host: server.example.com + + The HTTP request URI query can include other request-specific + parameters, in which case, the "access_token" parameter MUST be + properly separated from the request-specific parameters using "&" + character(s) (ASCII code 38). + + For example: + + https://server.example.com/resource?x=y&access_token=vF9dft4qmT&p=q + + Because of the security weaknesses associated with the URI method + (see Section 4), including the high likelihood that the URL + containing the access token will be logged, it SHOULD NOT be used + unless it is impossible to transport the access token in the + "Authorization" request header field or the HTTP request entity-body. + Resource servers MAY support this method. + + +3. The WWW-Authenticate Response Header Field + + If the protected resource request does not include authentication + credentials or does not contain an access token that enables access + + + +Jones, et al. Expires August 2, 2012 [Page 7] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + to the protected resource, the resource server MUST include the HTTP + "WWW-Authenticate" response header field; it MAY include it in + response to other conditions as well. The "WWW-Authenticate" header + field uses the framework defined by HTTP/1.1, Part 7 + [I-D.ietf-httpbis-p7-auth]. + + All challenges defined by this specification MUST use the auth-scheme + value "Bearer". This scheme MUST be followed by one or more auth- + param values. The auth-param attributes used or defined by this + specification are as follows. Other auth-param attributes MAY be + used as well. + + A "realm" attribute MAY be included to indicate the scope of + protection in the manner described in HTTP/1.1, Part 7 + [I-D.ietf-httpbis-p7-auth]. The "realm" attribute MUST NOT appear + more than once. + + The "scope" attribute is a space-delimited list of scope values + indicating the required scope of the access token for accessing the + requested resource. In some cases, the "scope" value will be used + when requesting a new access token with sufficient scope of access to + utilize the protected resource. Use of the "scope" attribute is + OPTIONAL. The "scope" attribute MUST NOT appear more than once. The + "scope" value is intended for programmatic use and is not meant to be + displayed to end users. + + If the protected resource request included an access token and failed + authentication, the resource server SHOULD include the "error" + attribute to provide the client with the reason why the access + request was declined. The parameter value is described in + Section 3.1. In addition, the resource server MAY include the + "error_description" attribute to provide developers a human-readable + explanation that is not meant to be displayed to end users. It also + MAY include the "error_uri" attribute with an absolute URI + identifying a human-readable web page explaining the error. The + "error", "error_description", and "error_uri" attributes MUST NOT + appear more than once. + + Values for the "scope" attribute MUST NOT include characters outside + the set %x21 / %x23-5B / %x5D-7E for representing scope values and + %x20 for delimiters between scope values. Values for the "error" and + "error_description" attributes MUST NOT include characters outside + the set %x20-21 / %x23-5B / %x5D-7E. Values for the "error_uri" + attribute MUST conform to the URI-Reference syntax, and thus MUST NOT + include characters outside the set %x21 / %x23-5B / %x5D-7E. + + + + + + +Jones, et al. Expires August 2, 2012 [Page 8] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + For example, in response to a protected resource request without + authentication: + + HTTP/1.1 401 Unauthorized + WWW-Authenticate: Bearer realm="example" + + And in response to a protected resource request with an + authentication attempt using an expired access token: + + HTTP/1.1 401 Unauthorized + WWW-Authenticate: Bearer realm="example", + error="invalid_token", + error_description="The access token expired" + +3.1. Error Codes + + When a request fails, the resource server responds using the + appropriate HTTP status code (typically, 400, 401, 403, or 405), and + includes one of the following error codes in the response: + + invalid_request + The request is missing a required parameter, includes an + unsupported parameter or parameter value, repeats the same + parameter, uses more than one method for including an access + token, or is otherwise malformed. The resource server SHOULD + respond with the HTTP 400 (Bad Request) status code. + + invalid_token + The access token provided is expired, revoked, malformed, or + invalid for other reasons. The resource SHOULD respond with + the HTTP 401 (Unauthorized) status code. The client MAY + request a new access token and retry the protected resource + request. + + insufficient_scope + The request requires higher privileges than provided by the + access token. The resource server SHOULD respond with the HTTP + 403 (Forbidden) status code and MAY include the "scope" + attribute with the scope necessary to access the protected + resource. + + If the request lacks any authentication information (i.e. the client + was unaware authentication is necessary or attempted using an + unsupported authentication method), the resource server SHOULD NOT + include an error code or other error information. + + + + + + +Jones, et al. Expires August 2, 2012 [Page 9] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + For example: + + HTTP/1.1 401 Unauthorized + WWW-Authenticate: Bearer realm="example" + + +4. Security Considerations + + This section describes the relevant security threats regarding token + handling when using bearer tokens and describes how to mitigate these + threats. + +4.1. Security Threats + + The following list presents several common threats against protocols + utilizing some form of tokens. This list of threats is based on NIST + Special Publication 800-63 [NIST800-63]. Since this document builds + on the OAuth 2.0 specification, we exclude a discussion of threats + that are described there or in related documents. + + Token manufacture/modification: An attacker may generate a bogus + token or modify the token contents (such as the authentication or + attribute statements) of an existing token, causing the resource + server to grant inappropriate access to the client. For example, + an attacker may modify the token to extend the validity period; a + malicious client may modify the assertion to gain access to + information that they should not be able to view. + + Token disclosure: Tokens may contain authentication and attribute + statements that include sensitive information. + + Token redirect: An attacker uses a token generated for consumption + by one resource server to gain access to a different resource + server that mistakenly believes the token to be for it. + + Token replay: An attacker attempts to use a token that has already + been used with that resource server in the past. + +4.2. Threat Mitigation + + A large range of threats can be mitigated by protecting the contents + of the token by using a digital signature or a Message Authentication + Code (MAC). Alternatively, a bearer token can contain a reference to + authorization information, rather than encoding the information + directly. Such references MUST be infeasible for an attacker to + guess; using a reference may require an extra interaction between a + server and the token issuer to resolve the reference to the + authorization information. The mechanics of such an interaction are + + + +Jones, et al. Expires August 2, 2012 [Page 10] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + not defined by this specification. + + This document does not specify the encoding or the contents of the + token; hence detailed recommendations about the means of guaranteeing + token integrity protection are outside the scope of this document. + The token integrity protection MUST be sufficient to prevent the + token from being modified. + + To deal with token redirect, it is important for the authorization + server to include the identity of the intended recipients (the + audience), typically a single resource server (or a list of resource + servers), in the token. Restricting the use of the token to a + specific scope is also RECOMMENDED. + + The authorization server MUST implement TLS. Which version(s) ought + to be implemented will vary over time, and depend on the widespread + deployment and known security vulnerabilities at the time of + implementation. At the time of this writing, TLS version 1.2 + [RFC5246] is the most recent version, but has very limited actual + deployment, and might not be readily available in implementation + toolkits. TLS version 1.0 [RFC2246] is the most widely deployed + version, and will give the broadest interoperability. + + To protect against token disclosure, confidentiality protection MUST + be applied using TLS [RFC5246] with a ciphersuite that provides + confidentiality and integrity protection. This requires that the + communication interaction between the client and the authorization + server, as well as the interaction between the client and the + resource server, utilize confidentiality and integrity protection. + Since TLS is mandatory to implement and to use with this + specification, it is the preferred approach for preventing token + disclosure via the communication channel. For those cases where the + client is prevented from observing the contents of the token, token + encryption MUST be applied in addition to the usage of TLS + protection. As a further defense against token disclosure, the + client MUST validate the TLS certificate chain when making requests + to protected resources. + + Cookies are typically transmitted in the clear. Thus, any + information contained in them is at risk of disclosure. Therefore, + bearer tokens MUST NOT be stored in cookies that can be sent in the + clear. + + In some deployments, including those utilizing load balancers, the + TLS connection to the resource server terminates prior to the actual + server that provides the resource. This could leave the token + unprotected between the front end server where the TLS connection + terminates and the back end server that provides the resource. In + + + +Jones, et al. Expires August 2, 2012 [Page 11] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + such deployments, sufficient measures MUST be employed to ensure + confidentiality of the token between the front end and back end + servers; encryption of the token is one possible such measure. + + To deal with token capture and replay, the following recommendations + are made: First, the lifetime of the token MUST be limited; one means + of achieving this is by putting a validity time field inside the + protected part of the token. Note that using short-lived (one hour + or less) tokens reduces the impact of them being leaked. Second, + confidentiality protection of the exchanges between the client and + the authorization server and between the client and the resource + server MUST be applied. As a consequence, no eavesdropper along the + communication path is able to observe the token exchange. + Consequently, such an on-path adversary cannot replay the token. + Furthermore, when presenting the token to a resource server, the + client MUST verify the identity of that resource server, as per + 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) + [RFC6125]. Note that the client MUST validate the TLS certificate + chain when making these requests to protected resources. Presenting + the token to an unauthenticated and unauthorized resource server or + failing to validate the certificate chain will allow adversaries to + steal the token and gain unauthorized access to protected resources. + +4.3. Summary of Recommendations + + Safeguard bearer tokens: Client implementations MUST ensure that + bearer tokens are not leaked to unintended parties, as they will + be able to use them to gain access to protected resources. This + is the primary security consideration when using bearer tokens and + underlies all the more specific recommendations that follow. + + Validate SSL certificate chains: The client MUST validate the TLS + certificate chain when making requests to protected resources. + Failing to do so may enable DNS hijacking attacks to steal the + token and gain unintended access. + + Always use TLS (https): Clients MUST always use TLS [RFC5246] + (https) or equivalent transport security when making requests with + bearer tokens. Failing to do so exposes the token to numerous + attacks that could give attackers unintended access. + + Don't store bearer tokens in cookies: Implementations MUST NOT store + bearer tokens within cookies that can be sent in the clear (which + is the default transmission mode for cookies). Implementations + that do store bearer tokens in cookies MUST take precautions + against cross site request forgery. + + + +Jones, et al. Expires August 2, 2012 [Page 12] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + Issue short-lived bearer tokens: Token servers SHOULD issue short- + lived (one hour or less) bearer tokens, particularly when issuing + tokens to clients that run within a web browser or other + environments where information leakage may occur. Using short- + lived bearer tokens can reduce the impact of them being leaked. + + Issue scoped bearer tokens: Token servers SHOULD issue bearer tokens + that contain an audience restriction, scoping their use to the + intended relying party or set of relying parties. + + Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be + passed in page URLs (for example as query string parameters). + Instead, bearer tokens SHOULD be passed in HTTP message headers or + message bodies for which confidentiality measures are taken. + Browsers, web servers, and other software may not adequately + secure URLs in the browser history, web server logs, and other + data structures. If bearer tokens are passed in page URLs, + attackers might be able to steal them from the history data, logs, + or other unsecured locations. + + +5. IANA Considerations + +5.1. OAuth Access Token Type Registration + + This specification registers the following access token type in the + OAuth Access Token Type Registry. + +5.1.1. The "Bearer" OAuth Access Token Type + + Type name: + Bearer + + Additional Token Endpoint Response Parameters: + (none) + + HTTP Authentication Scheme(s): + Bearer + + Change controller: + IETF + + Specification document(s): + [[ this document ]] + + + + + + + +Jones, et al. Expires August 2, 2012 [Page 13] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + +5.2. Authentication Scheme Registration + + This specification registers the following authentication scheme in + the Authentication Scheme Registry defined in HTTP/1.1, Part 7 + [I-D.ietf-httpbis-p7-auth]. + +5.2.1. The "Bearer" Authentication Scheme + + Authentication Scheme Name: + Bearer + + Pointer to specification text: + [[ this document ]] + + Notes (optional): + (none) + + +6. References + +6.1. Normative References + + [I-D.ietf-httpbis-p1-messaging] + Fielding, R., Gettys, J., Mogul, J., Nielsen, H., + Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and + J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and + Message Parsing", draft-ietf-httpbis-p1-messaging-18 (work + in progress), January 2012. + + [I-D.ietf-httpbis-p7-auth] + Fielding, R., Gettys, J., Mogul, J., Nielsen, H., + Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and + J. Reschke, "HTTP/1.1, part 7: Authentication", + draft-ietf-httpbis-p7-auth-18 (work in progress), + January 2012. + + [I-D.ietf-oauth-v2] + Hammer, E., Recordon, D., and D. Hardt, "The OAuth 2.0 + Authorization Protocol", draft-ietf-oauth-v2-23 (work in + progress), January 2012. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", + RFC 2246, January 1999. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + + + +Jones, et al. Expires August 2, 2012 [Page 14] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008. + + [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, March 2011. + + [USASCII] American National Standards Institute, "Coded Character + Set -- 7-bit American Standard Code for Information + Interchange", ANSI X3.4, 1986. + + [W3C.REC-html401-19991224] + Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 + Specification", World Wide Web Consortium + Recommendation REC-html401-19991224, December 1999, + <http://www.w3.org/TR/1999/REC-html401-19991224>. + +6.2. Informative References + + [NIST800-63] + Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., + and E. Nabbus, "NIST Special Publication 800-63-1, + INFORMATION SECURITY", December 2008. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., + Leach, P., Luotonen, A., and L. Stewart, "HTTP + Authentication: Basic and Digest Access Authentication", + RFC 2617, June 1999. + + +Appendix A. Acknowledgements + + The following people contributed to preliminary versions of this + document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland + (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), + Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and + + + +Jones, et al. Expires August 2, 2012 [Page 15] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + concepts within are a product of the OAuth community, the WRAP + community, and the OAuth Working Group. + + The OAuth Working Group has dozens of very active contributors who + proposed ideas and wording for this document, including: Michael + Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, John Bradley, + Brian Campbell, Leah Culver, Bill de hOra, Brian Ellin, Igor + Faynberg, Stephen Farrell, George Fletcher, Tim Freeman, Evan + Gilbert, Yaron Y. Goland, Thomas Hardjono, Justin Hart, Phil Hunt, + John Kemp, Eran Hammer-Lahav, Chasen Le Hara, Barry Leiba, Michael B. + Jones, Torsten Lodderstedt, Eve Maler, James Manger, Laurence Miao, + William J. Mills, Chuck Mortimore, Anthony Nadalin, Julian Reschke, + Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius + Scurtescu, Naitik Shah, Justin Smith, Jeremy Suriel, Christian + Stuebner, Paul Tarjan, Hannes Tschofenig, Franklin Tse, and Shane + Weeden. + + +Appendix B. Document History + + [[ to be removed by the RFC editor before publication as an RFC ]] + + -16 + + o Use the HTTPbis auth-param syntax for Bearer challenge attributes. + + o Dropped the sentence "The "realm" value is intended for + programmatic use and is not meant to be displayed to end users". + + o Reordered form-encoded body parameter description bullets for + better readability. + + o Added [USASCII] reference. + + -15 + + o Clarified that form-encoded content must consist entirely of ASCII + characters. + + o Added TLS version requirements. + + o Applied editorial improvements suggested by Mark Nottingham during + the APPS area review. + + -14 + + o Changes made in response to review comments by Security Area + Director Stephen Farrell. Specifically: + + + +Jones, et al. Expires August 2, 2012 [Page 16] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + o Strengthened warnings about passing an access token as a query + parameter and more precisely described the limitations placed upon + the use of this method. + + o Clarified that the "realm" attribute MAY included to indicate the + scope of protection in the manner described in HTTP/1.1, Part 7 + [I-D.ietf-httpbis-p7-auth]. + + o Normatively stated that "the token integrity protection MUST be + sufficient to prevent the token from being modified". + + o Added statement that "TLS is mandatory to implement and use with + this specification" to the introduction. + + o Stated that TLS MUST be used with "a ciphersuite that provides + confidentiality and integrity protection". + + o Added "As a further defense against token disclosure, the client + MUST validate the TLS certificate chain when making requests to + protected resources" to the Threat Mitigation section. + + o Clarified that putting a validity time field inside the protected + part of the token is one means, but not the only means, of + limiting the lifetime of the token. + + o Dropped the confusing phrase "for instance, through the use of + TLS" from the sentence about confidentiality protection of the + exchanges. + + o Reference RFC 6125 for identity verification, rather than RFC + 2818. + + o Stated that the token MUST be protected between front end and back + end servers when the TLS connection terminates at a front end + server that is distinct from the actual server that provides the + resource. + + o Stated that bearer tokens MUST NOT be stored in cookies that can + be sent in the clear in the Threat Mitigation section. + + o Replaced sole remaining reference to [RFC2616] with HTTPbis + [I-D.ietf-httpbis-p1-messaging] reference. + + o Replaced all references where the reference is used as if it were + part of the sentence (such as "defined by [I-D.whatever]") with + ones where the specification name is used, followed by the + reference (such as "defined by Whatever [I-D.whatever]"). + + + + +Jones, et al. Expires August 2, 2012 [Page 17] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + o Other on-normative editorial improvements. + + -13 + + o At the request of Hannes Tschofenig, made ABNF changes to make it + clear that no special WWW-Authenticate response header field + parsers are needed. The "scope", "error-description", and + "error-uri" parameters are all now defined as quoted-string in the + ABNF (as "error" already was). Restrictions on these values that + were formerly described in the ABNFs are now described in + normative text instead. + + -12 + + o Made non-normative editorial changes that Hannes Tschofenig + requested be applied prior to forwarding the specification to the + IESG. + + o Added rationale for the choice of the b64token syntax. + + o Added rationale stating that receivers are free to parse the + "scope" attribute using a standard quoted-string parser, since it + will correctly process all legal "scope" values. + + o Added additional active working group contributors to the + Acknowledgements section. + + -11 + + o Replaced uses of <"> with DQUOTE to pass ABNF syntax check. + + -10 + + o Removed the #auth-param option from Authorization header syntax + (leaving only the b64token syntax). + + o Restricted the "scope" value character set to %x21 / %x23-5B / + %x5D-7E (printable ASCII characters excluding double-quote and + backslash). Indicated that scope is intended for programmatic use + and is not meant to be displayed to end users. + + o Restricted the character set for "error_description" strings to SP + / VCHAR and indicated that they are not meant to be displayed to + end users. + + o Included more description in the Abstract, since Hannes Tschofenig + indicated that the RFC editor would require this. + + + + +Jones, et al. Expires August 2, 2012 [Page 18] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + o Changed "Access Grant" to "Authorization Grant", as was done in + the core spec. + + o Simplified the introduction to the Authenticated Requests section. + + -09 + + o Incorporated working group last call comments. Specific changes + were: + + o Use definitions from [I-D.ietf-httpbis-p7-auth] rather than + [RFC2617]. + + o Update credentials definition to conform to + [I-D.ietf-httpbis-p7-auth]. + + o Further clarified that query parameters may occur in any order. + + o Specify that error_description is UTF-8 encoded (matching the core + specification). + + o Registered "Bearer" Authentication Scheme in Authentication Scheme + Registry defined by [I-D.ietf-httpbis-p7-auth]. + + o Updated references to oauth-v2, httpbis-p1-messaging, and httpbis- + p7-auth drafts. + + o Other wording improvements not introducing normative changes. + + -08 + + o Updated references to oauth-v2 and HTTPbis drafts. + + -07 + + o Added missing comma in error response example. + + -06 + + o Changed parameter name "bearer_token" to "access_token", per + working group consensus. + + o Changed HTTP status code for "invalid_request" error code from + HTTP 401 (Unauthorized) back to HTTP 400 (Bad Request), per input + from HTTP working group experts. + + -05 + + + + +Jones, et al. Expires August 2, 2012 [Page 19] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + o Removed OAuth Errors Registry, per design team input. + + o Changed HTTP status code for "invalid_request" error code from + HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP + usage [[ change pending working group consensus ]]. + + o Added missing quotation marks in error-uri definition. + + o Added note to add language and encoding information to + error_description if the core specification does. + + o Explicitly reference the Augmented Backus-Naur Form (ABNF) defined + in [RFC5234]. + + o Use auth-param instead of repeating its definition, which is ( + token "=" ( token / quoted-string ) ). + + o Clarify security considerations about including an audience + restriction in the token and include a recommendation to issue + scoped bearer tokens in the summary of recommendations. + + -04 + + o Edits responding to working group last call feedback on -03. + Specific edits enumerated below. + + o Added Bearer Token definition in Terminology section. + + o Changed parameter name "oauth_token" to "bearer_token". + + o Added realm parameter to "WWW-Authenticate" response to comply + with [RFC2617]. + + o Removed "[ RWS 1#auth-param ]" from "credentials" definition since + it did not comply with the ABNF in [I-D.ietf-httpbis-p7-auth]. + + o Removed restriction that the "bearer_token" (formerly + "oauth_token") parameter be the last parameter in the entity-body + and the HTTP request URI query. + + o Do not require WWW-Authenticate Response in a reply to a malformed + request, as an HTTP 400 Bad Request response without a WWW- + Authenticate header is likely the right response in some cases of + malformed requests. + + o Removed OAuth Parameters registry extension. + + + + + +Jones, et al. Expires August 2, 2012 [Page 20] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + o Numerous editorial improvements suggested by working group + members. + + -03 + + o Restored the WWW-Authenticate response header functionality + deleted from the framework specification in draft 12 based upon + the specification text from draft 11. + + o Augmented the OAuth Parameters registry by adding two additional + parameter usage locations: "resource request" and "resource + response". + + o Registered the "oauth_token" OAuth parameter with usage location + "resource request". + + o Registered the "error" OAuth parameter. + + o Created the OAuth Error registry and registered errors. + + o Changed the "OAuth2" OAuth access token type name to "Bearer". + + -02 + + o Incorporated feedback received on draft 01. Most changes were to + the security considerations section. No normative changes were + made. Specific changes included: + + o Changed terminology from "token reuse" to "token capture and + replay". + + o Removed sentence "Encrypting the token contents is another + alternative" from the security considerations since it was + redundant and potentially confusing. + + o Corrected some references to "resource server" to be + "authorization server" in the security considerations. + + o Generalized security considerations language about obtaining + consent of the resource owner. + + o Broadened scope of security considerations description for + recommendation "Don't pass bearer tokens in page URLs". + + o Removed unused reference to OAuth 1.0. + + o Updated reference to framework specification and updated David + Recordon's e-mail address. + + + +Jones, et al. Expires August 2, 2012 [Page 21] + +Internet-Draft OAuth 2.0 Bearer Tokens January 2012 + + + o Removed security considerations text on authenticating clients. + + o Registered the "OAuth2" OAuth access token type and "oauth_token" + parameter. + + -01 + + o First public draft, which incorporates feedback received on -00 + including enhanced Security Considerations content. This version + is intended to accompany OAuth 2.0 draft 11. + + -00 + + o Initial draft based on preliminary version of OAuth 2.0 draft 11. + + +Authors' Addresses + + Michael B. Jones + Microsoft + + Email: mbj@microsoft.com + URI: http://self-issued.info/ + + + Dick Hardt + independent + + Email: dick.hardt@gmail.com + URI: http://dickhardt.org/ + + + David Recordon + Facebook + + Email: dr@fb.com + URI: http://www.davidrecordon.com/ + + + + + + + + + + + + + + +Jones, et al. Expires August 2, 2012 [Page 22] + diff --git a/doc/specs/draft-ietf-oauth.html b/doc/specs/draft-ietf-oauth.html deleted file mode 100644 index 6cc7582..0000000 --- a/doc/specs/draft-ietf-oauth.html +++ /dev/null @@ -1,3072 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<!-- saved from url=(0052)http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html --> -<HTML lang="en"><HEAD><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><TITLE>The OAuth 2.0 Protocol</TITLE> - -<META name="description" content="The OAuth 2.0 Protocol"> -<META name="generator" content="xml2rfc v1.35 (http://xml.resource.org/)"> -<META name="viewport" content="width=600;"> -<STYLE type="text/css"><!-- - body { - font-family: verdana, charcoal, helvetica, arial, sans-serif; - font-size: 85%; - max-width: 80ex; - color: #000; background-color: #FFF; - margin: 2em; - } - h1, h2, h3, h4, h5, h6 { - font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif; - font-weight: bold; font-style: normal; - } - h1 { color: #900; background-color: transparent; text-align: right; } - h3 { color: #333; background-color: transparent; } - - td.RFCbug { - font-size: x-small; text-decoration: none; - width: 30px; height: 30px; padding-top: 2px; - text-align: justify; vertical-align: middle; - background-color: #000; - } - td.RFCbug span.RFC { - font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; - font-weight: bold; color: #666; - } - td.RFCbug span.hotText { - font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; - font-weight: normal; text-align: center; color: #FFF; - } - - table.TOCbug { width: 30px; height: 15px; } - td.TOCbug { - text-align: center; width: 30px; height: 15px; - color: #FFF; background-color: #900; - } - td.TOCbug a { - font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif; - font-weight: bold; font-size: x-small; text-decoration: none; - color: #FFF; background-color: transparent; - } - - td.header { - font-family: arial, helvetica, sans-serif; font-size: x-small; - vertical-align: top; width: 33%; - color: #FFF; background-color: #666; - } - td.author { font-weight: bold; font-size: x-small; margin-left: 4em; } - td.author-text { font-size: x-small; } - - /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */ - a.info { - /* This is the key. */ - position: relative; - z-index: 24; - text-decoration: none; - } - a.info:hover { - z-index: 25; - color: #FFF; background-color: #900; - } - a.info span { display: none; } - a.info:hover span.info { - /* The span will display just on :hover state. */ - display: block; - position: absolute; - font-size: smaller; - top: 2em; left: -5em; width: 15em; - padding: 2px; border: 1px solid #333; - color: #900; background-color: #EEE; - text-align: left; - } - - a { font-weight: bold; } - a:link { color: #900; background-color: transparent; } - a:visited { color: #633; background-color: transparent; } - a:active { color: #633; background-color: transparent; } - - p { margin-left: 2em; margin-right: 2em; } - p.copyright { font-size: x-small; } - p.toc { font-size: 85%; - max-width: 80ex; - font-weight: bold; margin-left: 3em; } - table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; } - td.toc { font-size: 85%; - max-width: 80ex; - font-weight: bold; vertical-align: text-top; } - - ol.text { margin-left: 2em; margin-right: 2em; } - ul.text { margin-left: 2em; margin-right: 2em; } - li { margin-left: 3em; } - - /* RFC-2629 <spanx>s and <artwork>s. */ - em { font-style: italic; } - strong { font-weight: bold; } - dfn { font-weight: bold; font-style: normal; } - cite { font-weight: normal; font-style: normal; } - tt { color: #036; } - tt, pre, pre dfn, pre em, pre cite, pre span { - font-family: "Courier New", Courier, monospace; font-size: small; - } - pre { - text-align: left; padding: 4px; - color: #000; background-color: #CCC; - } - pre dfn { color: #900; } - pre em { color: #66F; background-color: #FFC; font-weight: normal; } - pre .key { color: #33C; font-weight: bold; } - pre .id { color: #900; } - pre .str { color: #000; background-color: #CFF; } - pre .val { color: #066; } - pre .rep { color: #909; } - pre .oth { color: #000; background-color: #FCF; } - pre .err { background-color: #FCC; } - - /* RFC-2629 <texttable>s. */ - table.all, table.full, table.headers, table.none { - font-size: 85%; - max-width: 80ex; - text-align: center; border-width: 2px; - vertical-align: top; border-collapse: collapse; - } - table.all, table.full { border-style: solid; border-color: black; } - table.headers, table.none { border-style: none; } - th { - font-weight: bold; border-color: black; - border-width: 2px 2px 3px 2px; - } - table.all th, table.full th { border-style: solid; } - table.headers th { border-style: none none solid none; } - table.none th { border-style: none; } - table.all td { - border-style: solid; border-color: #333; - border-width: 1px 2px; - } - table.full td, table.headers td, table.none td { border-style: none; } - - hr { height: 1px; } - hr.insert { - width: 80%; border-style: none; border-width: 0; - color: #CCC; background-color: #CCC; - } ---></STYLE> -</HEAD><BODY> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<TABLE summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><TBODY><TR><TD><TABLE summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1"> -<TBODY><TR><TD class="header">Network Working Group</TD><TD class="header">E. Hammer-Lahav, Ed.</TD></TR> -<TR><TD class="header">Internet-Draft</TD><TD class="header">Yahoo!</TD></TR> -<TR><TD class="header">Obsoletes: <A href="http://tools.ietf.org/html/rfc5849">5849</A> (if approved)</TD><TD class="header">D. Recordon</TD></TR> -<TR><TD class="header">Intended status: Standards Track</TD><TD class="header">Facebook</TD></TR> -<TR><TD class="header">Expires: January 12, 2011</TD><TD class="header">D. Hardt</TD></TR> -<TR><TD class="header"> </TD><TD class="header">Microsoft</TD></TR> -<TR><TD class="header"> </TD><TD class="header">July 11, 2010</TD></TR> -</TBODY></TABLE></TD></TR></TBODY></TABLE> -<H1><BR>The OAuth 2.0 Protocol<BR>draft-ietf-oauth-v2-10</H1> - -<H3>Abstract</H3> - -<P> - This specification describes the OAuth 2.0 protocol. - -</P> -<H3>Status of this Memo</H3> -<P> -This Internet-Draft is submitted in full -conformance with the provisions of BCP 78 and BCP 79.</P> -<P> -Internet-Drafts are working documents of the Internet Engineering -Task Force (IETF). Note that other groups may also distribute -working documents as Internet-Drafts. The list of current -Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</P> -<P> -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.”</P> -<P> -This Internet-Draft will expire on January 12, 2011.</P> - -<H3>Copyright Notice</H3> -<P> -Copyright (c) 2010 IETF Trust and the persons identified as the -document authors. All rights reserved.</P> -<P> -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.</P> -<A name="toc"></A><BR><HR> -<H3>Table of Contents</H3> -<P class="toc"> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor1">1.</A> -Introduction<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor2">1.1.</A> -Notational Conventions<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor3">1.2.</A> -Terminology<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor4">1.3.</A> -Overview<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor5">1.4.</A> -Client Profiles<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor6">1.4.1.</A> -Web Server<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#user-agent">1.4.2.</A> -User-Agent<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor7">1.4.3.</A> -Native Application<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor8">1.4.4.</A> -Autonomous<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#client-authentication">2.</A> -Client Credentials<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor9">2.1.</A> -Client Password Credentials<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#user-authorization">3.</A> -Obtaining End-User Authorization<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor10">3.1.</A> -Authorization Response<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#auth-error">3.2.</A> -Error Response<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#auth-error-codes">3.2.1.</A> -Error Codes<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#obtaining-token">4.</A> -Obtaining an Access Token<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#access-grant-types">4.1.</A> -Access Grant Types<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor11">4.1.1.</A> -Authorization Code<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor12">4.1.2.</A> -Resource Owner Password Credentials<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor13">4.1.3.</A> -Assertion<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#token-refresh">4.1.4.</A> -Refresh Token<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#access-token-response">4.2.</A> -Access Token Response<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#token-error">4.3.</A> -Error Response<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#token-error-codes">4.3.1.</A> -Error Codes<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#access-resource">5.</A> -Accessing a Protected Resource<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor14">5.1.</A> -Authenticated Requests<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#authz-header">5.1.1.</A> -The Authorization Request Header Field<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#query-param">5.1.2.</A> -URI Query Parameter<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#body-param">5.1.3.</A> -Form-Encoded Body Parameter<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#authn-header">5.2.</A> -The WWW-Authenticate Response Header Field<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#resource-error-codes">5.2.1.</A> -Error Codes<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor15">6.</A> -Extensibility<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor16">6.1.</A> -Defining New Client Credentials Types<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor17">6.2.</A> -Defining New Endpoint Parameters<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor18">6.3.</A> -Defining New Header Field Parameters<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor19">6.4.</A> -Defining New Access Grant Types<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor20">7.</A> -Security Considerations<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor21">8.</A> -IANA Considerations<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#parameters-registry">8.1.</A> -The OAuth Parameters Registry<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor22">8.1.1.</A> -Registration Template<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor23">8.1.2.</A> -Example<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor24">Appendix A.</A> -Examples<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor25">Appendix B.</A> -Contributors<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor26">Appendix C.</A> -Acknowledgements<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#anchor27">Appendix D.</A> -Document History<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#rfc.references1">9.</A> -References<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#rfc.references1">9.1.</A> -Normative References<BR> - <A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#rfc.references2">9.2.</A> -Informative References<BR> -<A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#rfc.authors">§</A> -Authors' Addresses<BR> -</P> -<BR clear="all"> - -<A name="anchor1"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.1"></A><H3>1. -Introduction</H3> - -<P> - With the increasing use of distributed web services and cloud computing, third-party - applications require access to server-hosted resources. These resources are usually - protected and require authentication using the resource owner's credentials (typically a - username and password). - -</P> -<P> - In the traditional client-server authentication model, the client accesses a protected - resource on the server by authenticating with the server using the resource owner's - credentials. In order to provide third-party applications access to protected resources, - the resource owner shares its credentials with the third-party. This creates several - problems and limitations: - - </P> -<UL class="text"> -<LI> - Third-party applications are required to store the resource-owner's credentials - for future use, typically a password in clear-text. - -</LI> -<LI> - Servers are required to support password (symmetric) authentication, despite the - security weaknesses created by passwords. - -</LI> -<LI> - Third-party applications gain overly broad access to the resource-owner's protected - resources, leaving resource owners without any ability to restrict access to a limited - subset of resources, to limit access duration, or to limit access to the methods - supported by these resources. - -</LI> -<LI> - Resource owners cannot revoke access to an individual third-party without revoking - access to all third-parties, and must do so by changing their password. - -</LI> -</UL><P> - -</P> -<P> - OAuth address these issues by separating the role of the client from that of the - resource owner. In OAuth, the client (which is usually not the resource owner, but is - acting on the resource owner's behalf) requests access to resources controlled by the - resource owner and hosted by the resource server, and is issued a different set of - credentials than those of the resource owner. - -</P> -<P> - Instead of using the resource owner's credentials to access protected resources, clients - obtain an access token (a string which denotes a specific scope, duration, and other - attributes). The format and structure of access tokens is beyond the scope of this - specification. - -</P> -<P> - Tokens are issued to third-party clients by an authorization server with the approval of - the resource owner. The client uses the access token to access the protected resources - hosted by the resource server. The interaction between the authorization server and - resource server is beyond the scope of this specification. - -</P> -<P> - For example, a web user (resource owner) can grant a printing service (client) access to - her protected photos stored at a photo sharing service (resource server), without sharing - her username and password with the printing service. Instead, she authenticates directly - with an authentication service trusted by the photo sharing service (authorization server) - which issues the printing service delegation-specific credentials (token). - -</P> -<P> - This specification defines the use of OAuth over <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC2616">HTTP<SPAN> (</SPAN><SPAN class="info">Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.</SPAN><SPAN>)</SPAN></A> [RFC2616] - (or HTTP over TLS as defined by <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC2818">[RFC2818]<SPAN> (</SPAN><SPAN class="info">Rescorla, E., “HTTP Over TLS,” May 2000.</SPAN><SPAN>)</SPAN></A>). Other specifications may - extend it for use with other transport protocols. - -</P> -<A name="anchor2"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.1.1"></A><H3>1.1. -Notational Conventions</H3> - -<P> - 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 <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC2119">[RFC2119]<SPAN> (</SPAN><SPAN class="info">Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.</SPAN><SPAN>)</SPAN></A>. - -</P> -<P> - This document uses the Augmented Backus-Naur Form (ABNF) notation of - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#I-D.ietf-httpbis-p1-messaging">[I‑D.ietf‑httpbis‑p1‑messaging]<SPAN> (</SPAN><SPAN class="info">Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, “HTTP/1.1, part 1: URIs, Connections, and Message Parsing,” March 2010.</SPAN><SPAN>)</SPAN></A>. Additionally, the following rules are - included from <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC2617">[RFC2617]<SPAN> (</SPAN><SPAN class="info">Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</SPAN><SPAN>)</SPAN></A>: realm, auth-param; from - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC3986">[RFC3986]<SPAN> (</SPAN><SPAN class="info">Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</SPAN><SPAN>)</SPAN></A>: URI-Reference; and from - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#I-D.ietf-httpbis-p1-messaging">[I‑D.ietf‑httpbis‑p1‑messaging]<SPAN> (</SPAN><SPAN class="info">Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, “HTTP/1.1, part 1: URIs, Connections, and Message Parsing,” March 2010.</SPAN><SPAN>)</SPAN></A>: OWS, RWS, and quoted-string. - -</P> -<P> - Unless otherwise noted, all the protocol parameter names and values are case sensitive. - -</P> -<A name="anchor3"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.1.2"></A><H3>1.2. -Terminology</H3> - -<P> - </P> -<BLOCKQUOTE class="text"><DL> -<DT>protected resource</DT> -<DD> - - An access-restricted resource which can be obtained using an OAuth-authenticated - request. - -</DD> -<DT>resource server</DT> -<DD> - - A server capable of accepting and responding to protected resource requests. - -</DD> -<DT>client</DT> -<DD> - - An application obtaining authorization and making protected resource requests. - -</DD> -<DT>resource owner</DT> -<DD> - - An entity capable of granting access to a protected resource. - -</DD> -<DT>end-user</DT> -<DD> - - A human resource owner. - -</DD> -<DT>token</DT> -<DD> - - A string representing an access authorization issued to the client. The string is - usually opaque to the client. Tokens represent specific scopes and durations of - access, granted by the resource owner, and enforced by the resource server and - authorization servers. The token may denote an identifier used to retrieve the - authorization information, or self-contain the authorization information in a - verifiable manner (i.e. a token string consisting of some data and a signature). - Tokens may be pure capabilities. Specific additional authentication credentials may - be required in order for a client to use a token. - -</DD> -<DT>access token</DT> -<DD> - - A token used by the client to make authenticated requests on behalf of the resource - owner. - -</DD> -<DT>refresh token</DT> -<DD> - - A token used by the client to obtain a new access token without having to involve - the resource owner. - -</DD> -<DT>authorization code</DT> -<DD> - A short-lived token representing the access grant provided by the end-user. The - authorization code is used to obtain an access token and a refresh token. - -</DD> -<DT>authorization server</DT> -<DD> - - A server capable of issuing tokens after successfully authenticating the resource - owner and obtaining authorization. The authorization server may be the same server as - the resource server, or a separate entity. - -</DD> -<DT>end-user authorization endpoint</DT> -<DD> - - The authorization server's HTTP endpoint capable of authenticating the end-user and - obtaining authorization. The end-user authorization endpoint is described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#user-authorization">Section 3<SPAN> (</SPAN><SPAN class="info">Obtaining End-User Authorization</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>token endpoint</DT> -<DD> - - The authorization server's HTTP endpoint capable of issuing tokens and refreshing - expired tokens. The token endpoint is described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#obtaining-token">Section 4<SPAN> (</SPAN><SPAN class="info">Obtaining an Access Token</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>client identifier</DT> -<DD> - - A unique identifier issued to the client to identify itself to the authorization - server. Client identifiers may have a matching secret. The client identifier is - described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#client-authentication">Section 2<SPAN> (</SPAN><SPAN class="info">Client Credentials</SPAN><SPAN>)</SPAN></A>. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<A name="anchor4"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.1.3"></A><H3>1.3. -Overview</H3> - -<P> - OAuth provides a method for clients to access a protected resource on behalf of a - resource owner. Before a client can access a protected resource, it must first obtain - authorization from the resource owner, then exchange the access grant for an access token - (representing the grant's scope, duration, and other attributes). The client accesses the - protected resource by presenting the access token to the resource server. - -</P><BR><HR class="insert"> -<A name="Figure 1"></A> -<DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - +--------+ +---------------+ - | |--(A)-- Authorization Request --->| Resource | - | | | Owner | - | |<-(B)------ Access Grant ---------| | - | | +---------------+ - | | - | | Client Credentials & +---------------+ - | |--(C)------ Access Grant -------->| Authorization | - | Client | | Server | - | |<-(D)------ Access Token ---------| | - | | (w/ Optional Refresh Token) +---------------+ - | | - | | +---------------+ - | |--(E)------ Access Token -------->| Resource | - | | | Server | - | |<-(F)---- Protected Resource -----| | - +--------+ +---------------+ - -</PRE></DIV><TABLE border="0" cellpadding="0" cellspacing="2" align="center"><TBODY><TR><TD align="center"><FONT face="monaco, MS Sans Serif" size="1"><B> Figure 1: Abstract Protocol Flow </B></FONT><BR></TD></TR></TBODY></TABLE><HR class="insert"> - -<P> - The abstract flow illustrated in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#Figure 1">Figure 1<SPAN> (</SPAN><SPAN class="info">Abstract Protocol Flow</SPAN><SPAN>)</SPAN></A> includes the following - steps: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>(A)</DT> -<DD> - The client requests authorization from the resource owner. The client should not - request the resource owner's credentials directly. Instead, it should request - authorization via an authorization server or other entities. For example, the client - directs the resource owner to the authorization server which in turn issues it an - access grant. When unavoidable, the client interacts directly with the end-user, - asking for the end-user's username and password. If the client is acting - autonomously, the authorization request is beyond the scope of this specification. - -</DD> -<DT>(B)</DT> -<DD> - The client is issued an access grant which represents the authorization provided by - the resource owner. The access grant can be expressed as: - - -<UL class="text"> -<LI> - Authorization code - an access grant obtained via an authorization server. - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#user-authorization">Section 3<SPAN> (</SPAN><SPAN class="info">Obtaining End-User Authorization</SPAN><SPAN>)</SPAN></A> describes how to obtain an authorization - code when the end-user is present and using a user-agent. - -</LI> -<LI> - Assertion - an access grant obtained using a different trust framework. - Assertions enable the client to utilize existing trust relationships to obtain an - access token. They provide a bridge between OAuth and other trust frameworks. The - access grant represented by an assertion depends on the assertion type, its - content, and how it was issued, which are beyond the scope of this specification. - -</LI> -<LI> - Resource owner password credentials - obtained when interacting directly with a - resource-owner. Resource owner password credentials (i.e. a username and - password) should only be used when there is a high degree of trust between the - resource owner and the client (e.g. its computer operating system or a highly - privileged application). However, unlike the HTTP Basic authentication scheme - defined in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC2617">[RFC2617]<SPAN> (</SPAN><SPAN class="info">Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</SPAN><SPAN>)</SPAN></A>, the resource owner's credentials are used - for a single request and are exchanged for an access token and refresh token. - This eliminates the need for the client to store the resource-owner's credentials - for future use. - -</LI> -</UL> - -</DD> -<DT>(C)</DT> -<DD> - The client requests an access token by authenticating with the authorization server, - and presenting the access grant. The token request is described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#obtaining-token">Section 4<SPAN> (</SPAN><SPAN class="info">Obtaining an Access Token</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>(D)</DT> -<DD> - The authorization server validates the client credentials and the access grant, and - issues an access token with an optional refresh token. Access tokens usually have a - shorter lifetime than the access grant. Refresh tokens usually have a lifetime equal - to the duration of the access grant. When an access token expires, the refresh token - is used to obtain a new access token without having to request another access grant - from the resource owner. - -</DD> -<DT>(E)</DT> -<DD> - The client makes a protected resource request to the resource server, and presents - the access token in order to gain access. Accessing a protected resource is described - in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#access-resource">Section 5<SPAN> (</SPAN><SPAN class="info">Accessing a Protected Resource</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>(F)</DT> -<DD> - The resource server validates the access token, and if valid, serves the request. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - When the client is acting on its own behalf (the client is also the resource owner), - the client does not obtain an access grant. The simplified protocol flow is illustrated - in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#Figure 2">Figure 2<SPAN> (</SPAN><SPAN class="info">Protocol Flow for Client Acting On Its Own Behalf</SPAN><SPAN>)</SPAN></A>: - -</P><BR><HR class="insert"> -<A name="Figure 2"></A> -<DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - +--------+ +---------------+ - | |--(C)--- Client Credentials ----->| Authorization | - | | | Server | - | |<-(D)------ Access Token ---------| | - | | +---------------+ - | Client | - | | +---------------+ - | |--(E)------ Access Token -------->| Resource | - | | | Server | - | |<-(F)---- Protected Resource -----| | - +--------+ +---------------+ - -</PRE></DIV><TABLE border="0" cellpadding="0" cellspacing="2" align="center"><TBODY><TR><TD align="center"><FONT face="monaco, MS Sans Serif" size="1"><B> Figure 2: Protocol Flow for Client Acting On Its Own Behalf </B></FONT><BR></TD></TR></TBODY></TABLE><HR class="insert"> - -<P> - When the client uses the user-agent profile (described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#user-agent">Section 1.4.2<SPAN> (</SPAN><SPAN class="info">User-Agent</SPAN><SPAN>)</SPAN></A>), - the authorization request results in an access token, as illustrated in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#Figure 3">Figure 3<SPAN> (</SPAN><SPAN class="info">Indirect Access Grant Protocol Flow</SPAN><SPAN>)</SPAN></A>: - -</P><BR><HR class="insert"> -<A name="Figure 3"></A> -<DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - +--------+ +----------+ +---------------+ - | |--(A)-- Authorization --+- -+-->| | - | | Request | Resource | | Authorization | - | | | Owner | | Server | - | |<-(D)-- Access Token ---+- -+---| | - | | +----------+ +---------------+ - | Client | - | | +---------------+ - | |--(E)-------- Access Token ----------->| Resource | - | | | Server | - | |<-(F)------ Protected Resource --------| | - +--------+ +---------------+ - -</PRE></DIV><TABLE border="0" cellpadding="0" cellspacing="2" align="center"><TBODY><TR><TD align="center"><FONT face="monaco, MS Sans Serif" size="1"><B> Figure 3: Indirect Access Grant Protocol Flow </B></FONT><BR></TD></TR></TBODY></TABLE><HR class="insert"> - -<A name="anchor5"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.1.4"></A><H3>1.4. -Client Profiles</H3> - -<P> - OAuth supports a wide range of client types by providing a rich and extensible framework - for establishing authorization and exchanging it for an access token. The methods detailed - in this specification were designed to accommodate four client types: web servers, - user-agents, native applications, and autonomous clients. Additional authorization flows - and client profiles may be defined by other specifications to cover additional scenarios - and client types. - -</P> -<A name="anchor6"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.1.4.1"></A><H3>1.4.1. -Web Server</H3> - -<P> - The web server profile is suitable for clients capable of interacting with the end-user's - user-agent (typically a web browser) and capable of receiving incoming requests from the - authorization server (capable of acting as an HTTP server). - -</P><BR><HR class="insert"> -<A name="Figure 4"></A> -<DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - +----------+ Client Identifier +---------------+ - | -+----(A)--- & Redirect URI ------>| | - | End-user | | Authorization | - | at |<---(B)-- User authenticates --->| Server | - | Browser | | | - | -+----(C)-- Authorization Code ---<| | - +-|----|---+ +---------------+ - | | ^ v - (A) (C) | | - | | | | - ^ v | | - +---------+ | | - | |>---(D)-- Client Credentials, --------' | - | Web | Authorization Code, | - | Client | & Redirect URI | - | | | - | |<---(E)----- Access Token -------------------' - +---------+ (w/ Optional Refresh Token) - -</PRE></DIV><TABLE border="0" cellpadding="0" cellspacing="2" align="center"><TBODY><TR><TD align="center"><FONT face="monaco, MS Sans Serif" size="1"><B> Figure 4: Web Server Flow </B></FONT><BR></TD></TR></TBODY></TABLE><HR class="insert"> - -<P> - The web server flow illustrated in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#Figure 4">Figure 4<SPAN> (</SPAN><SPAN class="info">Web Server Flow</SPAN><SPAN>)</SPAN></A> includes the following - steps: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>(A)</DT> -<DD> - The web client initiates the flow by redirecting the end-user's user-agent to the - end-user authorization endpoint as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#user-authorization">Section 3<SPAN> (</SPAN><SPAN class="info">Obtaining End-User Authorization</SPAN><SPAN>)</SPAN></A>. - The client includes its client identifier, requested scope, local state, and a - redirect URI to which the authorization server will send the end-user back once - access is granted (or denied). - -</DD> -<DT>(B)</DT> -<DD> - The authorization server authenticates the end-user (via the user-agent) and - establishes whether the end-user grants or denies the client's access request. - -</DD> -<DT>(C)</DT> -<DD> - Assuming the end-user granted access, the authorization server redirects the - user-agent back to the client to the redirection URI provided earlier. The - authorization includes an authorization code for the client to use to obtain an - access token. - -</DD> -<DT>(D)</DT> -<DD> - The client requests an access token from the authorization server by authenticating - and including the authorization code received in the previous step as described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#obtaining-token">Section 4<SPAN> (</SPAN><SPAN class="info">Obtaining an Access Token</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>(E)</DT> -<DD> - The authorization server validates the client credentials and the authorization - code and responds back with the access token. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<A name="user-agent"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.1.4.2"></A><H3>1.4.2. -User-Agent</H3> - -<P> - The user-agent profile is suitable for client applications residing in a user-agent, - typically implemented in a browser using a scripting language such as JavaScript. These - clients cannot keep client secrets confidential and the authentication of the client is - based on the user-agent's same-origin policy. - -</P> -<P> - Unlike other profiles in which the client makes separate requests for end-user - authorization and access token, the client receives the access token as a result of the - end-user authorization request in the form of an HTTP redirection. The client requests - the authorization server to redirect the user-agent to another web server or local - resource accessible to the user-agent which is capable of extracting the access token - from the response and passing it to the client. - -</P> -<P> - This user-agent profile does not utilize the client secret since the client executables - reside on the end-user's computer or device which makes the client secret accessible - and exploitable. Because the access token is encoded into the redirection URI, it may - be exposed to the end-user and other applications residing on the computer or device. - -</P><BR><HR class="insert"> -<A name="Figure 5"></A> -<DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - +----------+ Client Identifier +----------------+ - | |>---(A)-- & Redirection URI --->| | - | | | | - End <--+ - - - +----(B)-- User authenticates -->| Authorization | - User | | | Server | - | |<---(C)--- Redirect URI -------<| | - | Client | with Access Token | | - | in | in Fragment +----------------+ - | Browser | - | | +----------------+ - | |>---(D)--- Redirect URI ------->| | - | | without Fragment | Web Server | - | | | with Client | - | (F) |<---(E)--- Web Page with ------<| Resource | - | Access | Script | | - | Token | +----------------+ - +----------+ - -</PRE></DIV><TABLE border="0" cellpadding="0" cellspacing="2" align="center"><TBODY><TR><TD align="center"><FONT face="monaco, MS Sans Serif" size="1"><B> Figure 5: User-Agent Flow </B></FONT><BR></TD></TR></TBODY></TABLE><HR class="insert"> - -<P> - The user-agent flow illustrated in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#Figure 5">Figure 5<SPAN> (</SPAN><SPAN class="info">User-Agent Flow</SPAN><SPAN>)</SPAN></A> includes the following - steps: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>(A)</DT> -<DD> - The client sends the user-agent to the end-user authorization endpoint as described - in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#user-authorization">Section 3<SPAN> (</SPAN><SPAN class="info">Obtaining End-User Authorization</SPAN><SPAN>)</SPAN></A>. The client includes its client identifier, - requested scope, local state, and a redirect URI to which the authorization server - will send the end-user back once authorization is granted (or denied). - -</DD> -<DT>(B)</DT> -<DD> - The authorization server authenticates the end-user (via the user-agent) and - establishes whether the end-user grants or denies the client's access request. - -</DD> -<DT>(C)</DT> -<DD> - If the end-user granted access, the authorization server redirects the - user-agent to the redirection URI provided earlier. The redirection URI includes - the access token in the URI fragment. - -</DD> -<DT>(D)</DT> -<DD> - The user-agent follows the redirection instructions by making a request to the web - server which does not include the fragment. The user-agent retains the fragment - information locally. - -</DD> -<DT>(E)</DT> -<DD> - The web server returns a web page (typically an HTML page with an embedded script) - capable of accessing the full redirection URI including the fragment retained by the - user-agent, and extracting the access token (and other parameters) contained in the - fragment. - -</DD> -<DT>(F)</DT> -<DD> - The user-agent executes the script provided by the web server locally, which - extracts the access token and passes it to the client. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<A name="anchor7"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.1.4.3"></A><H3>1.4.3. -Native Application</H3> - -<P> - Native application are clients running as native code on the end-user's computer or - device (i.e. executing outside a user-agent or as a desktop program). These clients are - often capable of interacting with (or embedding) the end-user's user-agent but are - limited in how such interaction affects their end-user experience. In many cases, - native applications are incapable of receiving direct callback requests from the - server (e.g. firewall, operating system restrictions). - -</P> -<P> - Native application clients can be implemented in different ways based on their - requirements and desired end-user experience. Native application clients can: - - </P> -<UL class="text"> -<LI> - Utilize the end-user authorization endpoint as described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#user-authorization">Section 3<SPAN> (</SPAN><SPAN class="info">Obtaining End-User Authorization</SPAN><SPAN>)</SPAN></A> by launching an external user-agent. The - client can capture the response by providing a redirection URI with a custom URI - scheme (registered with the operating system to invoke the client application), or - by providing a redirection URI pointing to a server-hosted resource under the - client's control which makes the response available to the client (e.g. using the - window title or other locations accessible from outside the user-agent). - -</LI> -<LI> - Utilize the end-user authorization endpoint as described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#user-authorization">Section 3<SPAN> (</SPAN><SPAN class="info">Obtaining End-User Authorization</SPAN><SPAN>)</SPAN></A> by using an embedded user-agent. The client - obtains the response by directly communicating with the embedded user-agent. - -</LI> -<LI> - Prompt end-users for their password and use them directly to obtain an access - token. This is generally discouraged, as it hands the end-user's password directly - to the third-party client which in turn has to store it in clear-text. It also - requires the server to support password-based authentication. - -</LI> -</UL><P> - -</P> -<P> - When choosing between launching an external browser and an embedded user-agent, - developers should consider the following: - - </P> -<UL class="text"> -<LI> - External user-agents may improve completion rate as the end-user may already be - logged-in and not have to re-authenticate. - -</LI> -<LI> - Embedded user-agents often offer a better end-user flow, as they remove the need to - switch context and open new windows. - -</LI> -<LI> - Embedded user-agents pose a security challenge because users are authenticating in - an unidentified window without access to the visual protections offered by many - user-agents. - -</LI> -</UL><P> - -</P> -<A name="anchor8"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.1.4.4"></A><H3>1.4.4. -Autonomous</H3> - -<P> - Autonomous clients utilize an existing trust relationship or framework to establish - authorization. Autonomous clients can be implemented in different ways based on their - requirements and the existing trust framework they rely upon. Autonomous clients can: - - </P> -<UL class="text"> -<LI> - Obtain an access token by authenticating with the authorization server using their - client credentials. The scope of the access token is limited to the protected - resources under the control of the client, or that of another resource owner - previously arranged with the authorization server. - -</LI> -<LI> - Use an existing access grant expressed as an assertion using an assertion format - supported by the authorization server. Using assertions requires the client to - obtain a assertion (such as a <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#OASIS.saml-core-2.0-os">SAML<SPAN> (</SPAN><SPAN class="info">Cantor, S., Kemp, J., Philpott, R., and E. Maler, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.</SPAN><SPAN>)</SPAN></A> [OASIS.saml‑core‑2.0‑os] - assertion) from an assertion issuer or to self-issue an assertion. The assertion - format, the process by which the assertion is obtained, and the method of - validating the assertion are defined by the assertion issuer and the authorization - server, and are beyond the scope of this specification. - -</LI> -</UL><P> - -</P> -<A name="client-authentication"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.2"></A><H3>2. -Client Credentials</H3> - -<P> - When interacting with the authorization server, the client identifies itself using a client - identifier and authenticates using a set of client credentials. This specification provides - one mechanism for authenticating the client using password credentials. - -</P> -<P> - The means through which the client obtains its credentials are beyond the scope of this - specification, but usually involve registration with the authorization server. - [[ OAuth Discovery provides one way of obtaining a client password ]] - -</P> -<P> - Due to the nature of some clients, authorization servers SHOULD NOT make assumptions - about the confidentiality of client secrets without establishing trust with the - client operator. Authorization servers SHOULD NOT issue client secrets to clients - incapable of keeping their secrets confidential. - -</P> -<P> - The authorization server MAY authenticate the client using any appropriate set of - credentials and authentication scheme. The client MUST NOT utilize more than one set of - credentials or authentication mechanism with each request. - -</P> -<A name="anchor9"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.2.1"></A><H3>2.1. -Client Password Credentials</H3> - -<P> - The client password credentials use a shared symmetric secret to authenticate the client. - The client identifier and password are included in the request using the - HTTP Basic authentication scheme as defined in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC2617">[RFC2617]<SPAN> (</SPAN><SPAN class="info">Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</SPAN><SPAN>)</SPAN></A> by including the - client identifier as the username and client password as the password. - -</P> -<P> - For example (line breaks are for display purposes only): - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - POST /token HTTP/1.1 - Host: server.example.com - Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW - Content-Type: application/x-www-form-urlencoded - - grant_type=authorization_code&client_id=s6BhdRkqt3&code=i1WsRn1uB1& - redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb - -</PRE></DIV> -<P> - Alternatively, the client MAY include the password in the request body using the - following parameter: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>client_secret</DT> -<DD> - REQUIRED. The client password. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - For example (line breaks are for display purposes only): - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - POST /token HTTP/1.1 - Host: server.example.com - Content-Type: application/x-www-form-urlencoded - - grant_type=authorization_code&client_id=s6BhdRkqt3& - client_secret=gX1fBat3bV&code=i1WsRn1uB1& - redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb - -</PRE></DIV> -<P> - The authorization server MUST accept the client credentials using both the request - parameter, and the HTTP Basic authentication scheme. The authorization server MAY - support additional authentication schemes suitable for the transmission of a password. - -</P> -<A name="user-authorization"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.3"></A><H3>3. -Obtaining End-User Authorization</H3> - -<P> - When the client interacts with an end-user, the end-user MUST first grant the client - authorization to access its protected resources. Once obtained, the end-user access - grant is expressed as an authorization code which the client uses to obtain an access - token. To obtain an end-user authorization, the client sends the end-user to the - end-user authorization endpoint. - -</P> -<P> - At the end-user authorization endpoint, the end-user first authenticates with the - authorization server, and then grants or denies the access request. The way in which the - authorization server authenticates the end-user (e.g. username and password login, OpenID, - session cookies) and in which the authorization server obtains the end-user's - authorization, including whether it uses a secure channel such as TLS, is beyond the scope - of this specification. However, the authorization server MUST first verify the identity of - the end-user. - -</P> -<P> - The location of the end-user authorization endpoint can be found in the service - documentation, or can be obtained by using [[ OAuth Discovery ]]. The end-user - authorization endpoint URI MAY include a query component as defined by - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC3986">[RFC3986]<SPAN> (</SPAN><SPAN class="info">Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</SPAN><SPAN>)</SPAN></A> section 3, which must be retained when adding additional - query parameters. - -</P> -<P> - Since requests to the end-user authorization endpoint result in user authentication and - the transmission of sensitive information, the authorization server SHOULD require the - use of a transport-layer security mechanism such as TLS when sending requests to the - end-user authorization endpoint. - -</P> -<P> - In order to direct the end-user's user-agent to the authorization server, the client - constructs the request URI by adding the following parameters to the end-user - authorization endpoint URI query component using the - <TT>application/x-www-form-urlencoded</TT> format as defined by - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#W3C.REC-html401-19991224">[W3C.REC‑html401‑19991224]<SPAN> (</SPAN><SPAN class="info">Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” December 1999.</SPAN><SPAN>)</SPAN></A>: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>response_type</DT> -<DD> - - REQUIRED. The requested response: an access token, an authorization code, or both. The - parameter value MUST be set to <TT>token</TT> for requesting an - access token, <TT>code</TT> for requesting an authorization code, or - <TT>code_and_token</TT> to request both. The authorization server - MAY decline to provide one or more of these response types. [[ The 'code_and_token' - type is pending use cases and may be removed for the specification ]] - -</DD> -<DT>client_id</DT> -<DD> - - REQUIRED. The client identifier as described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#client-authentication">Section 2<SPAN> (</SPAN><SPAN class="info">Client Credentials</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>redirect_uri</DT> -<DD> - - REQUIRED, unless a redirection URI has been established between the client and - authorization server via other means. An absolute URI to which the authorization - server will redirect the user-agent to when the end-user authorization step is - completed. The authorization server SHOULD require the client to pre-register - their redirection URI. - -</DD> -<DT>scope</DT> -<DD> - - OPTIONAL. The scope of the access request expressed as a list of space-delimited - strings. The value of the <TT>scope</TT> parameter is defined - by the authorization server. If the value contains multiple space-delimited - strings, their order does not matter, and each string adds an additional access - range to the requested scope. - -</DD> -<DT>state</DT> -<DD> - - OPTIONAL. An opaque value used by the client to maintain state between the request - and callback. The authorization server includes this value when redirecting the - user-agent back to the client. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - The client directs the end-user to the constructed URI using an HTTP redirection - response, or by other means available to it via the end-user's user-agent. The - authorization server MUST support the use of the HTTP <TT>GET</TT> - method for the end-user authorization endpoint, and MAY support the use of the - <TT>POST</TT> method as well. - -</P> -<P> - For example, the client directs the end-user's user-agent to make the following HTTP - request using transport-layer security (line breaks are for display purposes only): - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - GET /authorize?response_type=code&client_id=s6BhdRkqt3& - redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 - Host: server.example.com - -</PRE></DIV> -<P> - If the client has previously registered a redirection URI with the authorization server, - the authorization server MUST verify that the redirection URI received matches the - registered URI associated with the client identifier. [[ provide guidance on how to - perform matching ]] - -</P> -<P> - Parameters sent without a value MUST be treated as if they were omitted from the request. - The authorization server SHOULD ignore unrecognized request parameters. - -</P> -<P> - The authorization server validates the request to ensure all required parameters are - present and valid. If the request is invalid, the authorization server immediately - redirects the user-agent back to the client using the redirection URI provided with the - appropriate error code as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#auth-error">Section 3.2<SPAN> (</SPAN><SPAN class="info">Error Response</SPAN><SPAN>)</SPAN></A>. - -</P> -<P> - The authorization server authenticates the end-user and obtains an authorization - decision (by asking the end-user or by establishing approval via other means). When a - decision has been established, the authorization server directs the end-user's - user-agent to the provided client redirection URI using an HTTP redirection response, - or by other means available to it via the end-user's user-agent. - -</P> -<A name="anchor10"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.3.1"></A><H3>3.1. -Authorization Response</H3> - -<P> - If the end-user grants the access request, the authorization server issues an access - token, an authorization code, or both, and delivers them to the client by adding the - following parameters to the redirection URI (as described below): - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>code</DT> -<DD> - - REQUIRED if the response type is <TT>code</TT> or - <TT>code_and_token</TT>, otherwise MUST NOT be included. The - authorization code generated by the authorization server. The authorization code - SHOULD expire shortly after it is issued. The authorization server MUST invalidate - the authorization code after a single usage. The authorization code is bound to the - client identifier and redirection URI. - -</DD> -<DT>access_token</DT> -<DD> - - REQUIRED if the response type is <TT>token</TT> or - <TT>code_and_token</TT>, otherwise MUST NOT be included. The - access token issued by the authorization server. The access token string MUST comply - with the access-token rule defined in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#authz-header">Section 5.1.1<SPAN> (</SPAN><SPAN class="info">The Authorization Request Header Field</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>expires_in</DT> -<DD> - - OPTIONAL. The duration in seconds of the access token lifetime if an access token - is included. For example, the value <TT>3600</TT> denotes that the - access token will expire in one hour from the time the response was generated by the - authorization server. - -</DD> -<DT>scope</DT> -<DD> - - OPTIONAL. The scope of the access token as a list of space-delimited strings if an - access token is included. The value of the <TT>scope</TT> - parameter is defined by the authorization server. If the value contains multiple - space-delimited strings, their order does not matter, and each string adds an - additional access range to the requested scope. The authorization server SHOULD - include the parameter if the requested scope is different from the one requested by - the client. - -</DD> -<DT>state</DT> -<DD> - - REQUIRED if the <TT>state</TT> parameter was present in the - client authorization request. Set to the exact value received from the client. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - The method in which the authorization server adds the parameter to the redirection - URI is determined by the response type requested by the client in the authorization - request using the <TT>response_type</TT> parameter. - -</P> -<P> - If the response type is <TT>code</TT>, the authorization - server adds the parameters to the redirection URI query component using the - <TT>application/x-www-form-urlencoded</TT> format as defined by - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#W3C.REC-html401-19991224">[W3C.REC‑html401‑19991224]<SPAN> (</SPAN><SPAN class="info">Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” December 1999.</SPAN><SPAN>)</SPAN></A>. - -</P> -<P> - For example, the authorization server redirects the end-user's user-agent by - sending the following HTTP response: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - HTTP/1.1 302 Found - Location: https://client.example.com/cb?code=i1WsRn1uB1 - -</PRE></DIV> -<P> - If the response type is <TT>token</TT>, the authorization - server adds the parameters to the redirection URI fragment component using the - <TT>application/x-www-form-urlencoded</TT> format as defined by - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#W3C.REC-html401-19991224">[W3C.REC‑html401‑19991224]<SPAN> (</SPAN><SPAN class="info">Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” December 1999.</SPAN><SPAN>)</SPAN></A>. - -</P> -<P> - For example, the authorization server redirects the end-user's user-agent by - sending the following HTTP response: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - HTTP/1.1 302 Found - Location: http://example.com/rd#access_token=FJQbwq9&expires_in=3600 - -</PRE></DIV> -<P> - If the response type is <TT>code_and_token</TT>, the authorization - server adds the <TT>code</TT> and <TT>state</TT> - parameters to the redirection URI query component and the - <TT>access_token</TT>, <TT>scope</TT>, and - <TT>expires_in</TT> to the redirection URI fragment using the - <TT>application/x-www-form-urlencoded</TT> format as defined by - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#W3C.REC-html401-19991224">[W3C.REC‑html401‑19991224]<SPAN> (</SPAN><SPAN class="info">Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” December 1999.</SPAN><SPAN>)</SPAN></A>. - -</P> -<P> - For example, the authorization server redirects the end-user's user-agent by - sending the following HTTP response (line breaks are for display purposes only): - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - HTTP/1.1 302 Found - Location: http://example.com/rd?code=i1WsRn1uB1 - #access_token=FJQbwq9&expires_in=3600 - -</PRE></DIV> -<P> - Clients SHOULD ignore unrecognized response parameters. The sizes of tokens and other - values received from the authorization server, are left undefined by this specification. - Clients should avoid making assumptions about value sizes. Servers should document the - expected size of any value they issue. - -</P> -<A name="auth-error"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.3.2"></A><H3>3.2. -Error Response</H3> - -<P> - If the end-user denies the access request or if the request is invalid, the authorization - server informs the client by adding the following parameters to the redirection URI query - component using the <TT>application/x-www-form-urlencoded</TT> format - as defined by <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#W3C.REC-html401-19991224">[W3C.REC‑html401‑19991224]<SPAN> (</SPAN><SPAN class="info">Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” December 1999.</SPAN><SPAN>)</SPAN></A>: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>error</DT> -<DD> - - REQUIRED. A single error code as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#auth-error-codes">Section 3.2.1<SPAN> (</SPAN><SPAN class="info">Error Codes</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>error_description</DT> -<DD> - OPTIONAL. A human-readable text providing additional information, used to assist in - the understanding and resolution of the error occurred. - -</DD> -<DT>error_uri</DT> -<DD> - OPTIONAL. A URI identifying a human-readable web page with information about the - error, used to provide the end-user with additional information about the error. - -</DD> -<DT>state</DT> -<DD> - - REQUIRED if the <TT>state</TT> parameter was present in the - client authorization request. Set to the exact value received from the client. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - For example, the authorization server redirects the end-user's user-agent by - sending the following HTTP response: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - HTTP/1.1 302 Found - Location: https://client.example.com/cb?error=access-denied - -</PRE></DIV> -<A name="auth-error-codes"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.3.2.1"></A><H3>3.2.1. -Error Codes</H3> - -<P> - The authorization server includes one of the following error codes with the error - response: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>invalid_request</DT> -<DD> - - The request is missing a required parameter, includes an unsupported parameter or - parameter value, or is otherwise malformed. - -</DD> -<DT>invalid_client</DT> -<DD> - - The client identifier provided is invalid. - -</DD> -<DT>unauthorized_client</DT> -<DD> - - The client is not authorized to use the requested response type. - -</DD> -<DT>redirect_uri_mismatch</DT> -<DD> - - The redirection URI provided does not match a pre-registered value. - -</DD> -<DT>access_denied</DT> -<DD> - - The end-user or authorization server denied the request. - -</DD> -<DT>unsupported_response_type</DT> -<DD> - - The requested response type is not supported by the authorization server. - -</DD> -<DT>invalid_scope</DT> -<DD> - - The requested scope is invalid, unknown, or malformed. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - [[ Add mechanism for extending error codes ]] - -</P> -<A name="obtaining-token"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.4"></A><H3>4. -Obtaining an Access Token</H3> - -<P> - The client obtains an access token by authenticating with the authorization server and - presenting its access grant (in the form of an authorization code, resource owner - credentials, an assertion, or a refresh token). - -</P> -<P> - Since requests to the token endpoint result in the transmission of plain text - credentials in the HTTP request and response, the authorization server MUST require the - use of a transport-layer security mechanism when sending requests to the token endpoints. - Servers MUST support TLS 1.2 as defined in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC5246">[RFC5246]<SPAN> (</SPAN><SPAN class="info">Dierks, T. and E. Rescorla, “The Transport Layer Security (TLS) Protocol Version 1.2,” August 2008.</SPAN><SPAN>)</SPAN></A>, and MAY support - additional transport-layer security mechanisms. - -</P> -<P> - The client requests an access token by making an HTTP <TT>POST</TT> - request to the token endpoint. The location of the token endpoint can be found in the - service documentation, or can be obtained by using [[ OAuth Discovery ]]. The token - endpoint URI MAY include a query component. - -</P> -<P> - The client authenticates with the authorization server by adding its client credentials to - the request as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#client-authentication">Section 2<SPAN> (</SPAN><SPAN class="info">Client Credentials</SPAN><SPAN>)</SPAN></A>. The authorization - server MAY allow unauthenticated access token requests when the client identity does not - matter (e.g. anonymous client) or when the client identity is established via other means - (e.g. using an assertion access grant). - -</P> -<P> - The client constructs the request by including the following parameters using the - <TT>application/x-www-form-urlencoded</TT> format in the HTTP request - entity-body: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>grant_type</DT> -<DD> - - REQUIRED. The access grant type included in the request. Value MUST be one of - <TT>authorization_code</TT>, - <TT>password</TT>, - <TT>assertion</TT>, - <TT>refresh_token</TT>, or <TT>none</TT>. - -</DD> -<DT>client_id</DT> -<DD> - - REQUIRED, unless the client identity can be establish via other means (e.g. assertion). - The client identifier as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#client-authentication">Section 2<SPAN> (</SPAN><SPAN class="info">Client Credentials</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>scope</DT> -<DD> - - OPTIONAL. The scope of the access request expressed as a list of space-delimited - strings. The value of the <TT>scope</TT> parameter is defined - by the authorization server. If the value contains multiple space-delimited - strings, their order does not matter, and each string adds an additional access - range to the requested scope. If the access grant being used already represents an - approved scope (e.g. authorization code, assertion), the requested scope MUST be equal - or lesser than the scope previously granted. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - In addition, the client MUST include the appropriate parameters listed for the selected - access grant type as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#access-grant-types">Section 4.1<SPAN> (</SPAN><SPAN class="info">Access Grant Types</SPAN><SPAN>)</SPAN></A>. - -</P> -<P> - Parameters sent without a value MUST be treated as if they were omitted from the request. - The authorization server SHOULD ignore unrecognized request parameters. - -</P> -<A name="access-grant-types"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.4.1"></A><H3>4.1. -Access Grant Types</H3> - -<P> - The client requests an access token using one of the four types of access grants: - authorization code, password credentials, assertion, or refresh token. - -</P> -<P> - When requesting an access token using the <TT>none</TT> access grant - type (no access grant is included), the client is requesting access to the protected - resources under its control, or those of another resource owner which has been previously - arranged with the authorization server (the method of which is beyond the scope of this - specification). - -</P> -<A name="anchor11"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.4.1.1"></A><H3>4.1.1. -Authorization Code</H3> - -<P> - The client includes the authorization code using the - <TT>authorization_code</TT> access grant type and the following - parameters: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>code</DT> -<DD> - - REQUIRED. The authorization code received from the authorization server. - -</DD> -<DT>redirect_uri</DT> -<DD> - - REQUIRED. The redirection URI used in the initial request. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - For example, the client makes the following HTTP request by including its client - credentials via the <TT>client_secret</TT> parameter described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#client-authentication">Section 2<SPAN> (</SPAN><SPAN class="info">Client Credentials</SPAN><SPAN>)</SPAN></A> and using transport-layer security (line - breaks are for display purposes only): - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - POST /token HTTP/1.1 - Host: server.example.com - Content-Type: application/x-www-form-urlencoded - - grant_type=authorization_code&client_id=s6BhdRkqt3& - client_secret=gX1fBat3bV&code=i1WsRn1uB1& - redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb - -</PRE></DIV> -<P> - The authorization server MUST: - - </P> -<UL class="text"> -<LI> - Validate the client credentials (if present) and ensure they match the - authorization code. - -</LI> -<LI> - Verify that the authorization code and redirection URI are all valid and match its - stored association. - -</LI> -</UL><P> - -</P> -<P> - If the request is valid, the authorization server issues a successful response as - described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#access-token-response">Section 4.2<SPAN> (</SPAN><SPAN class="info">Access Token Response</SPAN><SPAN>)</SPAN></A>. - -</P> -<A name="anchor12"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.4.1.2"></A><H3>4.1.2. -Resource Owner Password Credentials</H3> - -<P> - The client includes the resource owner credentials using the - <TT>password</TT> access grant type and the following - parameters: [[ add internationalization consideration for username and password ]] - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>username</DT> -<DD> - - REQUIRED. The resource owner's username. - -</DD> -<DT>password</DT> -<DD> - - REQUIRED. The resource owner's password. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - For example, the client makes the following HTTP request by including its client - credentials via the <TT>client_secret</TT> parameter described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#client-authentication">Section 2<SPAN> (</SPAN><SPAN class="info">Client Credentials</SPAN><SPAN>)</SPAN></A> and using transport-layer security (line - breaks are for display purposes only): - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - POST /token HTTP/1.1 - Host: server.example.com - Content-Type: application/x-www-form-urlencoded - - grant_type=password&client_id=s6BhdRkqt3& - client_secret=47HDu8s&username=johndoe&password=A3ddj3w - -</PRE></DIV> -<P> - The authorization server MUST validate the client credentials (if present) and end-user - credentials and if valid issue an access token response as described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#access-token-response">Section 4.2<SPAN> (</SPAN><SPAN class="info">Access Token Response</SPAN><SPAN>)</SPAN></A>. - -</P> -<A name="anchor13"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.4.1.3"></A><H3>4.1.3. -Assertion</H3> - -<P> - The client includes the assertion using the <TT>assertion</TT> access - grant type and the following parameters: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>assertion_type</DT> -<DD> - - REQUIRED. The format of the assertion as defined by the authorization server. The - value MUST be an absolute URI. - -</DD> -<DT>assertion</DT> -<DD> - - REQUIRED. The assertion. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - For example, the client makes the following HTTP request using transport-layer - security, and client authentication is achieved via the assertion (line breaks are - for display purposes only): - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - POST /token HTTP/1.1 - Host: server.example.com - Content-Type: application/x-www-form-urlencoded - - grant_type=assertion& - assertion_type=urn%3Aoasis%3Anames%3Atc%3ASAML%3A2.0%3Aassertion& - assertion=PHNhbWxwOl...[omitted for brevity]...ZT4%3D - -</PRE></DIV> -<P> - The authorization server MUST validate the client credentials (if present) and the - assertion and if valid issues an access token response as described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#access-token-response">Section 4.2<SPAN> (</SPAN><SPAN class="info">Access Token Response</SPAN><SPAN>)</SPAN></A>. The authorization server SHOULD NOT issue a - refresh token (instead, require the client to use the same or new assertion). - -</P> -<P> - Authorization servers SHOULD issue access tokens with a limited lifetime and require - clients to refresh them by requesting a new access token using the same assertion if it - is still valid. Otherwise the client MUST obtain a new valid assertion. - -</P> -<A name="token-refresh"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.4.1.4"></A><H3>4.1.4. -Refresh Token</H3> - -<P> - The client includes the refresh token using the - <TT>refresh_token</TT> access grant type and the following - parameter: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>refresh_token</DT> -<DD> - - REQUIRED. The refresh token associated with the access token to be refreshed. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - For example, the client makes the following HTTP request by including its client - credentials via the <TT>client_secret</TT> parameter described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#client-authentication">Section 2<SPAN> (</SPAN><SPAN class="info">Client Credentials</SPAN><SPAN>)</SPAN></A> and using transport-layer security (line - breaks are for display purposes only): - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - POST /token HTTP/1.1 - Host: server.example.com - Content-Type: application/x-www-form-urlencoded - - grant_type=refresh_token&client_id=s6BhdRkqt3& - client_secret=8eSEIpnqmM&refresh_token=n4E9O119d - -</PRE></DIV> -<P> - The authorization server MUST verify the client credentials (if present), the validity - of the refresh token, and that the resource owner's authorization is still valid. If - the request is valid, the authorization server issues an access token response as - described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#access-token-response">Section 4.2<SPAN> (</SPAN><SPAN class="info">Access Token Response</SPAN><SPAN>)</SPAN></A>. The authorization server MAY - issue a new refresh token. - -</P> -<A name="access-token-response"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.4.2"></A><H3>4.2. -Access Token Response</H3> - -<P> - After receiving and verifying a valid and authorized access token request from the - client, the authorization server issues the access token and optional refresh token, - and constructs the response by adding the following parameters to the entity body of - the HTTP response with a 200 (OK) status code: - -</P> -<P> - The token response contains the following parameters: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>access_token</DT> -<DD> - - REQUIRED. The access token issued by the authorization server. The access token - string MUST comply with the access-token rule defined in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#authz-header">Section 5.1.1<SPAN> (</SPAN><SPAN class="info">The Authorization Request Header Field</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>expires_in</DT> -<DD> - - OPTIONAL. The duration in seconds of the access token lifetime. For example, the - value <TT>3600</TT> denotes that the access token will expire in - one hour from the time the response was generated by the authorization server. - -</DD> -<DT>refresh_token</DT> -<DD> - - OPTIONAL. The refresh token used to obtain new access tokens using the same - end-user access grant as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#token-refresh">Section 4.1.4<SPAN> (</SPAN><SPAN class="info">Refresh Token</SPAN><SPAN>)</SPAN></A>. The - authorization server SHOULD NOT issue a refresh token when the access grant type is - set to <TT>none</TT>. - -</DD> -<DT>scope</DT> -<DD> - - OPTIONAL. The scope of the access token as a list of space-delimited strings. The - value of the <TT>scope</TT> parameter is defined by the - authorization server. If the value contains multiple space-delimited strings, - their order does not matter, and each string adds an additional access range to - the requested scope. The authorization server SHOULD include the parameter if the - requested scope is different from the one requested by the client. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - The parameters are including in the entity body of the HTTP response using the - <TT>application/json</TT> media type as defined by - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC4627">[RFC4627]<SPAN> (</SPAN><SPAN class="info">Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</SPAN><SPAN>)</SPAN></A>. The parameters are serialized into a JSON structure by - adding each parameter at the highest structure level. Parameter names and string values - are included as JSON strings. Numerical values are included as JSON numbers. - -</P> -<P> - The authorization server MUST include the HTTP <TT>Cache-Control</TT> - response header field with a value of <TT>no-store</TT> in any - response containing tokens, secrets, or other sensitive information. - -</P> -<P> - For example: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - HTTP/1.1 200 OK - Content-Type: application/json - Cache-Control: no-store - - { - "access_token":"SlAV32hkKG", - "expires_in":3600, - "refresh_token":"8xLOxBtZp8" - } - -</PRE></DIV> -<P> - Clients SHOULD ignore unrecognized response parameters. The sizes of tokens and other - values received from the authorization server, are left undefined by this specification. - Clients should avoid making assumptions about value sizes. Servers should document the - expected size of any value they issue. - -</P> -<A name="token-error"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.4.3"></A><H3>4.3. -Error Response</H3> - -<P> - If the token request is invalid or unauthorized, the authorization server constructs - the response by adding the following parameter to the entity body of the HTTP - response using the <TT>application/json</TT> media type: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>error</DT> -<DD> - - REQUIRED. A single error code as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#token-error-codes">Section 4.3.1<SPAN> (</SPAN><SPAN class="info">Error Codes</SPAN><SPAN>)</SPAN></A>. - -</DD> -<DT>error_description</DT> -<DD> - OPTIONAL. A human-readable text providing additional information, used to assist in - the understanding and resolution of the error occurred. - -</DD> -<DT>error_uri</DT> -<DD> - OPTIONAL. A URI identifying a human-readable web page with information about the - error, used to provide the end-user with additional information about the error. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - For example: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - HTTP/1.1 400 Bad Request - Content-Type: application/json - Cache-Control: no-store - - { - "error":"invalid_request" - } - -</PRE></DIV> -<P> - If the client provided invalid credentials using an HTTP authentication scheme via the - <TT>Authorization</TT> request header field, the authorization server - MUST respond with the HTTP 401 (Unauthorized) status code. Otherwise, the authorization - server SHALL respond with the HTTP 400 (Bad Request) status code. - -</P> -<A name="token-error-codes"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.4.3.1"></A><H3>4.3.1. -Error Codes</H3> - -<P> - The authorization server includes one of the following error codes with the error - response: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>invalid_request</DT> -<DD> - - The request is missing a required parameter, includes an unsupported parameter or - parameter value, repeats a parameter, includes multiple credentials, utilizes - more than one mechanism for authenticating the client, or is otherwise malformed. - -</DD> -<DT>invalid_client</DT> -<DD> - - The client identifier provided is invalid, the client failed to authenticate, the - client did not include its credentials, provided multiple client credentials, or - used unsupported credentials type. - -</DD> -<DT>unauthorized_client</DT> -<DD> - - The authenticated client is not authorized to use the access grant type provided. - -</DD> -<DT>invalid_grant</DT> -<DD> - - The provided access grant is invalid, expired, or revoked (e.g. invalid assertion, - expired authorization token, bad end-user password credentials, or mismatching - authorization code and redirection URI). - -</DD> -<DT>unsupported_grant_type</DT> -<DD> - - The access grant included - its type or another attribute - is not supported by the - authorization server. - -</DD> -<DT>invalid_scope</DT> -<DD> - - The requested scope is invalid, unknown, malformed, or exceeds the previously - granted scope. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - [[ Add mechanism for extending error codes ]] - -</P> -<A name="access-resource"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.5"></A><H3>5. -Accessing a Protected Resource</H3> - -<P> - Clients access protected resources by presenting an access token to the resource server. - Access tokens act as bearer tokens, where the token string acts as a shared symmetric - secret. This requires treating the access token with the same care as other secrets (e.g. - end-user passwords). Access tokens SHOULD NOT be sent in the clear over an insecure - channel. - -</P> -<P> - However, when it is necessary to transmit access tokens in the clear without a secure - channel, authorization servers SHOULD issue access tokens with limited scope and lifetime - to reduce the potential risk from a compromised access token. - -</P> -<P> - Clients MUST NOT make authenticated requests with an access token to unfamiliar resource - servers, regardless of the presence of a secure channel. - -</P> -<P> - The resource server MUST validate the access token and ensure it has not expired and - that its scope covers the requested resource. The methods used by the resource server - to validate the access token are beyond the scope of this specification, but generally - involve an interaction or coordination between the resource server and authorization - server. - -</P> -<A name="anchor14"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.5.1"></A><H3>5.1. -Authenticated Requests</H3> - -<P> - Clients make authenticated token requests using the - <TT>Authorization</TT> request header field. Resource servers MUST - accept authenticated requests using the <TT>OAuth</TT> HTTP - authentication scheme as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#authz-header">Section 5.1.1<SPAN> (</SPAN><SPAN class="info">The Authorization Request Header Field</SPAN><SPAN>)</SPAN></A>, and MAY support - additional methods. - -</P> -<P> - Alternatively, clients MAY attempt to include the access token using the HTTP request - URI in the query component as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#query-param">Section 5.1.2<SPAN> (</SPAN><SPAN class="info">URI Query Parameter</SPAN><SPAN>)</SPAN></A>, or in the HTTP - body when using the <TT>application/x-www-form-urlencoded</TT> content - type as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#body-param">Section 5.1.3<SPAN> (</SPAN><SPAN class="info">Form-Encoded Body Parameter</SPAN><SPAN>)</SPAN></A>. Resource server MAY support these - alternative methods. - -</P> -<P> - Clients SHOULD only use the request URI or body when the - <TT>Authorization</TT> request header field is not available, and MUST - NOT use more than one method in each request. - -</P> -<A name="authz-header"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.5.1.1"></A><H3>5.1.1. -The Authorization Request Header Field</H3> - -<P> - The <TT>Authorization</TT> request header field is used by clients - to make authenticated token requests. The client uses the - <TT>OAuth</TT> authentication scheme to include the access token in - the request. - -</P> -<P> - For example: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - GET /resource HTTP/1.1 - Host: server.example.com - Authorization: OAuth vF9dft4qmT - -</PRE></DIV> -<P> - The <TT>Authorization</TT> header field uses the framework defined by - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC2617">[RFC2617]<SPAN> (</SPAN><SPAN class="info">Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</SPAN><SPAN>)</SPAN></A> as follows: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - credentials = "OAuth" RWS access-token [ CS 1#auth-param ] - access-token = 1*( quoted-char / <"> ) - - CS = OWS "," OWS - - quoted-char = "!" / "#" / "$" / "%" / "&" / "'" / "(" - / ")" / "*" / "+" / "-" / "." / "/" / DIGIT - / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA - / "[" / "]" / "^" / "_" / "`" / "{" / "|" - / "}" / "~" / "\" / "," / ";" - -</PRE></DIV> -<P> - </P> -<BLOCKQUOTE class="text"> -<P> - NOTE: <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC5849">[RFC5849]<SPAN> (</SPAN><SPAN class="info">Hammer-Lahav, E., “The OAuth 1.0 Protocol,” April 2010.</SPAN><SPAN>)</SPAN></A> defines a different format for the - <TT>OAuth</TT> authentication scheme. Resource servers can - differentiate between the two protocol versions based on the presence of the - <TT>oauth_signature_method</TT> which is REQUIRED in the - previous version and is not supported by this specification. - -</P> -</BLOCKQUOTE><P> - -</P> -<A name="query-param"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.5.1.2"></A><H3>5.1.2. -URI Query Parameter</H3> - -<P> - When including the access token in the HTTP request URI, the client adds the access - token to the request URI query component as defined by <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC3986">[RFC3986]<SPAN> (</SPAN><SPAN class="info">Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</SPAN><SPAN>)</SPAN></A> using - the <TT>oauth_token</TT> parameter. - -</P> -<P> - For example, the client makes the following HTTP request using transport-layer - security: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - GET /resource?oauth_token=vF9dft4qmT HTTP/1.1 - Host: server.example.com - -</PRE></DIV> -<P> - The HTTP request URI query can include other request-specific parameters, in which - case, the <TT>oauth_token</TT> parameters SHOULD be appended - following the request-specific parameters, properly separated by an - <TT>&</TT> character (ASCII code 38). - -</P> -<P> - For example: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - http://example.com/resource?x=y&oauth_token=vF9dft4qmT - -</PRE></DIV> -<P> - </P> -<BLOCKQUOTE class="text"> -<P> - NOTE: The <TT>oauth_token</TT> parameter is used by the previous - version of the OAuth protocol as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC5849">[RFC5849]<SPAN> (</SPAN><SPAN class="info">Hammer-Lahav, E., “The OAuth 1.0 Protocol,” April 2010.</SPAN><SPAN>)</SPAN></A>. Resource - servers can differentiate between the two protocol versions based on the presence - of the <TT>oauth_signature_method</TT> which is REQUIRED in the - previous version and is not supported by this specification. - -</P> -</BLOCKQUOTE><P> - -</P> -<A name="body-param"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.5.1.3"></A><H3>5.1.3. -Form-Encoded Body Parameter</H3> - -<P> - When including the access token in the HTTP request entity-body, the client adds the - access token to the request body using the <TT>oauth_token</TT> - parameter. The client can use this method only if the following REQUIRED conditions are - met: - - </P> -<UL class="text"> -<LI> - The entity-body is single-part. - -</LI> -<LI> - The entity-body follows the encoding requirements of the - <TT>application/x-www-form-urlencoded</TT> content-type as - defined by <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#W3C.REC-html401-19991224">[W3C.REC‑html401‑19991224]<SPAN> (</SPAN><SPAN class="info">Raggett, D., Hors, A., and I. Jacobs, “HTML 4.01 Specification,” December 1999.</SPAN><SPAN>)</SPAN></A>. - -</LI> -<LI> - The HTTP request entity-header includes the <TT>Content-Type</TT> - header field set to <TT>application/x-www-form-urlencoded</TT>. - -</LI> -<LI> - The HTTP request method is <TT>POST</TT>, - <TT>PUT</TT>, or <TT>DELETE</TT>. - -</LI> -</UL><P> - -</P> -<P> - The entity-body can include other request-specific parameters, in which case, the - <TT>oauth_token</TT> parameters SHOULD be appended following the - request-specific parameters, properly separated by an <TT>&</TT> - character (ASCII code 38). - -</P> -<P> - For example, the client makes the following HTTP request using transport-layer - security: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - POST /resource HTTP/1.1 - Host: server.example.com - Content-Type: application/x-www-form-urlencoded - - oauth_token=vF9dft4qmT - -</PRE></DIV> -<P> - </P> -<BLOCKQUOTE class="text"> -<P> - NOTE: The <TT>oauth_token</TT> parameter is used by the previous - version of the OAuth protocol as described in <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC5849">[RFC5849]<SPAN> (</SPAN><SPAN class="info">Hammer-Lahav, E., “The OAuth 1.0 Protocol,” April 2010.</SPAN><SPAN>)</SPAN></A>. Resource - servers can differentiate between the two protocol versions based on the presence - of the <TT>oauth_signature_method</TT> which is REQUIRED in the - previous version and is not supported by this specification. - -</P> -</BLOCKQUOTE><P> - -</P> -<A name="authn-header"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.5.2"></A><H3>5.2. -The WWW-Authenticate Response Header Field</H3> - -<P> - If the protected resource request contains an invalid access token or is malformed, the - resource server MUST include the HTTP <TT>WWW-Authenticate</TT> - response header field. The <TT>WWW-Authenticate</TT> header field - uses the framework defined by <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC2617">[RFC2617]<SPAN> (</SPAN><SPAN class="info">Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</SPAN><SPAN>)</SPAN></A> as follows: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - challenge = "OAuth" RWS token-challenge - - token-challenge = realm - [ CS error ] - [ CS error-desc ] - [ CS error-uri ] - [ CS scope ] - [ CS 1#auth-param ] - - error = "error" "=" <"> token <"> - error-desc = "error_description" "=" quoted-string - error-uri = "error_uri" = <"> URI-Reference <"> - scope = quoted-value / - <"> quoted-value *( 1*SP quoted-value ) <"> - quoted-value = 1*quoted-char - -</PRE></DIV> -<P> - For example: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - HTTP/1.1 401 Unauthorized - WWW-Authenticate: OAuth realm='Example Service', error='expired-token' - -</PRE></DIV> -<P> - The <TT>realm</TT> attribute is used to provide the protected - resources partition as defined by <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC2617">[RFC2617]<SPAN> (</SPAN><SPAN class="info">Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” June 1999.</SPAN><SPAN>)</SPAN></A>. [[ add explanation ]] - -</P> -<P> - The <TT>error</TT> attribute is used to provide the client with the - reason why the access request was declined. The parameter values are described in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#resource-error-codes">Section 5.2.1<SPAN> (</SPAN><SPAN class="info">Error Codes</SPAN><SPAN>)</SPAN></A>. - -</P> -<P> - The <TT>error_description</TT> attribute provides a human-readable - text containing additional information, used to assist in the understanding and - resolution of the error occurred. - -</P> -<P> - The <TT>error_uri</TT> attribute provides a URI identifying a - human-readable web page with information about the error, used to offer the end-user - with additional information about the error. If the value is not an absolute URI, it is - relative to the URI of the requested protected resource. - -</P> -<P> - The <TT>scope</TT> attribute is a space-delimited list of scope values - indicating the required scope of the access token for accessing the requested resource. - -</P> -<A name="resource-error-codes"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.5.2.1"></A><H3>5.2.1. -Error Codes</H3> - -<P> - The authorization server includes one of the following error codes with the error - response: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>invalid_request</DT> -<DD> - - The request is missing a required parameter, includes an unsupported parameter or - parameter value, repeats the same parameter, uses more than one method for - including an access token, or is otherwise malformed. The resource server MUST - respond with the HTTP 400 (Bad Request) status code. - -</DD> -<DT>invalid_token</DT> -<DD> - - The access token provided is invalid. Resource servers SHOULD use this error code - when receiving an expired token which cannot be refreshed to indicate to the client - that a new authorization is necessary. The resource server MUST respond with the - HTTP 401 (Unauthorized) status code. - -</DD> -<DT>expired_token</DT> -<DD> - - The access token provided has expired. Resource servers SHOULD only use this error - code when the client is expected to be able to handle the response and request a - new access token using the refresh token issued with the expired access token. The - resource server MUST respond with the HTTP 401 (Unauthorized) status code. - -</DD> -<DT>insufficient_scope</DT> -<DD> - - The request requires higher privileges than provided by the access token. The - resource server SHOULD respond with the HTTP 403 (Forbidden) status code and MAY - include the <TT>scope</TT> attribute with the scope necessary to - access the protected resource. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<P> - [[ Add mechanism for extending error codes ]] - -</P> -<P> - If the request lacks any authentication information (i.e. the client was unaware - authentication is necessary or attempted using an unsupported authentication method), - the resource server SHOULD not include an error code or other error information. - -</P> -<P> - For example: - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - HTTP/1.1 401 Unauthorized - WWW-Authenticate: OAuth realm='Example Service' - -</PRE></DIV> -<A name="anchor15"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.6"></A><H3>6. -Extensibility</H3> - -<A name="anchor16"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.6.1"></A><H3>6.1. -Defining New Client Credentials Types</H3> - -<P> - [[ TBD ]] - -</P> -<A name="anchor17"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.6.2"></A><H3>6.2. -Defining New Endpoint Parameters</H3> - -<P> - Applications that wish to define new request or response parameters for use with the - end-user authorization endpoint or the token endpoint SHALL do so in one of two ways: - register them in the parameters registry (following the procedures in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#parameters-registry">Section 8.1<SPAN> (</SPAN><SPAN class="info">The OAuth Parameters Registry</SPAN><SPAN>)</SPAN></A>), or use the <TT>x_</TT> - parameter name prefix. - -</P> -<P> - Parameters utilizing the <TT>x_</TT> parameter name prefix MUST be - limited to vendor-specific extensions that are not commonly applicable, and are specific - to the implementation details of the authorization server where they are used. All other - new parameters MUST be registered, and MUST NOT use the <TT>x_</TT> - parameter name prefix. - -</P> -<P> - Parameter names MUST conform to the param-name ABNF, and parameter values syntax MUST be - well-defined (e.g., using ABNF, or a reference to the syntax of an existing parameter). - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - param-name = 1*name-char - name-char = "-" / "." / "_" / DIGIT / ALPHA - -</PRE></DIV> -<A name="anchor18"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.6.3"></A><H3>6.3. -Defining New Header Field Parameters</H3> - -<P> - Applications that wish to define new parameters for use in the OAuth - <TT>Authorization</TT> or <TT>WWW-Authenticate</TT> - header fields MUST register them in the parameters registry, following the procedures in - <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#parameters-registry">Section 8.1<SPAN> (</SPAN><SPAN class="info">The OAuth Parameters Registry</SPAN><SPAN>)</SPAN></A>. - -</P> -<P> - Parameter names MUST conform to the param-name ABNF and MUST NOT begin with - <TT>x_</TT>. Parameter values MUST conform to the param-value ABNF and - their syntax MUST be well-defined (e.g., using ABNF, or a reference to the syntax of an - existing parameter). - -</P><DIV style="display: table; width: 0; margin-left: 3em; margin-right: auto"><PRE> - param-value = quoted-value | quoted-string - -</PRE></DIV> -<A name="anchor19"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.6.4"></A><H3>6.4. -Defining New Access Grant Types</H3> - -<P> - The assertion access grant type was designed to allow the authorization server to - accept additional access grants not specified. Applications that wish to define - additional access grant types can do so by utilizing a new or existing assertion type - and format. - -</P> -<A name="anchor20"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.7"></A><H3>7. -Security Considerations</H3> - -<P> - [[ TBD ]] - -</P> -<A name="anchor21"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.8"></A><H3>8. -IANA Considerations</H3> - -<A name="parameters-registry"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.8.1"></A><H3>8.1. -The OAuth Parameters Registry</H3> - -<P> - This document establishes the OAuth parameters registry. - -</P> -<P> - Additional parameters to be use in the end-user authorization endpoint request, the - end-user authorization endpoint response, the token endpoint request, the token endpoint - response, the <TT>Authorization</TT> header field, or the - <TT>WWW-Authenticate</TT> header field, are registered on the advice - of one or more Designated Experts (appointed by the IESG or their delegate), with a - Specification Required (using terminology from <A class="info" href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#RFC5226">[RFC5226]<SPAN> (</SPAN><SPAN class="info">Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” May 2008.</SPAN><SPAN>)</SPAN></A>). However, to - allow for the allocation of values prior to publication, the Designated Expert(s) may - approve registration once they are satisfied that such a specification will be published. - -</P> -<P> - Registration requests should be sent to the [TBD]@ietf.org mailing list for review and - comment, with an appropriate subject (e.g., "Request for parameter: example"). - [[ Note to RFC-EDITOR: The name of the mailing list should be determined in consultation - with the IESG and IANA. Suggested name: oauth-ext-review. ]] - -</P> -<P> - Before a period of 14 days has passed, the Designated Expert(s) will either approve or - deny the registration request, communicating this decision both to the review list and to - IANA. Denials should include an explanation and, if applicable, suggestions as to how to - make the request successful. Registration requests that are undetermined for a period - longer than 21 days can be brought to the IESG's attention (using the iesg@iesg.org - mailing list) for resolution. - -</P> -<A name="anchor22"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.8.1.1"></A><H3>8.1.1. -Registration Template</H3> - -<P> - </P> -<BLOCKQUOTE class="text"><DL> -<DT>Parameter name:</DT> -<DD> - The name requested (e.g., "example"). - -</DD> -<DT>Parameter usage location:</DT> -<DD> - The location(s) where parameter can be used. The possible locations are: the - end-user authorization endpoint request, the end-user authorization endpoint - response, the token endpoint request, the token endpoint response, the - <TT>Authorization</TT> header field, or the - <TT>WWW-Authenticate</TT> header field. - -</DD> -<DT>Change controller:</DT> -<DD> - For standards-track RFCs, state "IETF". For others, give the name of the - responsible party. Other details (e.g., postal address, e-mail address, home page - URI) may also be included. - -</DD> -<DT>Specification document(s):</DT> -<DD> - Reference to document that specifies the parameter, preferably including a URI that - can be used to retrieve a copy of the document. An indication of the relevant - sections may also be included, but is not required. - -</DD> -<DT>Related information:</DT> -<DD> - Optionally, citations to additional documents containing further relevant - information. - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<A name="anchor23"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.8.1.2"></A><H3>8.1.2. -Example</H3> - -<P> - The following is the parameter registration request for the - <TT>scope</TT> parameter as defined in this specification: - - </P> -<BLOCKQUOTE class="text"><DL> -<DT>Parameter name:</DT> -<DD> - scope - -</DD> -<DT>Parameter usage location:</DT> -<DD> - The end-user authorization endpoint request, the end-user authorization endpoint - response, the token endpoint request, the token endpoint response, and the - <TT>WWW-Authenticate</TT> header field. - -</DD> -<DT>Change controller:</DT> -<DD> - IETF - -</DD> -<DT>Specification document(s):</DT> -<DD> - [[ this document ]] - -</DD> -<DT>Related information:</DT> -<DD> - None - -</DD> -</DL></BLOCKQUOTE><P> - -</P> -<A name="anchor24"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.A"></A><H3>Appendix A. -Examples</H3> - -<P> - [[ TBD ]] - -</P> -<A name="anchor25"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.B"></A><H3>Appendix B. -Contributors</H3> - -<P> - The following people contributed to preliminary versions of this document: - Blaine Cook (BT), Brian Eaton (Google), Yaron Goland (Microsoft), Brent Goldman (Facebook), - Raffi Krikorian (Twitter), Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and - concepts within are a product of the OAuth community, WRAP community, and the OAuth Working - Group. - -</P> -<P> - The OAuth Working Group has dozens of very active contributors who proposed ideas and - wording for this document, including: [[ If your name is missing or you think someone - should be added here, please send Eran a note - don't be shy ]] - -</P> -<P> - Michael Adams, Andrew Arnott, Dirk Balfanz, Brian Campbell, Leah Culver, Brian Ellin, - Igor Faynberg, George Fletcher, Evan Gilbert, Justin Hart, John Kemp, Chasen Le Hara, - Torsten Lodderstedt, Eve Maler, James Manger, Laurence Miao, Chuck Mortimore, - Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Justin Smith, - Jeremy Suriel, and Franklin Tse. - -</P> -<A name="anchor26"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.C"></A><H3>Appendix C. -Acknowledgements</H3> - -<P> - [[ Add OAuth 1.0a authors + WG contributors ]] - -</P> -<A name="anchor27"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.D"></A><H3>Appendix D. -Document History</H3> - -<P> - [[ to be removed by RFC editor before publication as an RFC ]] - -</P> -<P> - -10 - - </P> -<UL class="text"> -<LI> - Fixed typos. Many editorial changes. Rewrote introduction. removed terminology - grouping. - -</LI> -<LI> - Allowed POST for end-user authorization endpoint. - -</LI> -<LI> - Fixed token endpoint to not require client authentication. - -</LI> -<LI> - Made URI query and POST body 'oauth_token' parameter optional. - -</LI> -<LI> - Moved all parameter names and values to use underscores. - -</LI> -<LI> - Changed 'basic_credentials' to 'password', 'invalid_client_credentials' and - 'invalid_client_id' to 'invalid_client'. - -</LI> -<LI> - Added note that access token requests without an access grant should not include - a refresh token. - -</LI> -<LI> - Changed scheme name from 'Token' to 'OAuth', simplified request format to simple - string for token instead of key=value pair (still supported for extensions). - -</LI> -<LI> - Defined permitted access token string characters (suitable for inclusion in an HTTP - header). - -</LI> -<LI> - Added a note about conflicts with previous versions. - -</LI> -<LI> - Moved 'client_id' definition from client authentication to access token endpoint. - -</LI> -</UL><P> - -</P> -<P> - -09 - - </P> -<UL class="text"> -<LI> - Fixed typos, editorial changes. - -</LI> -<LI> - Added token expiration example. - -</LI> -<LI> - Added scope parameter to end-user authorization endpoint response. - -</LI> -<LI> - Added note about parameters with empty values (same as omitted). - -</LI> -<LI> - Changed parameter values to use '-' instead of '_'. Parameter names still use '_'. - -</LI> -<LI> - Changed authorization endpoint client type to response type with values: code, token, - and both. - -</LI> -<LI> - Complete cleanup of error codes. Added support for error description and URI. - -</LI> -<LI> - Add initial extensibility support. - -</LI> -</UL><P> - -</P> -<P> - -08 - - </P> -<UL class="text"> -<LI> - Renamed verification code to authorization code. - -</LI> -<LI> - Revised terminology, structured section, added new terms. - -</LI> -<LI> - Changed flows to profiles and moved to introduction. - -</LI> -<LI> - Added support for access token rescoping. - -</LI> -<LI> - Cleaned up client credentials section. - -</LI> -<LI> - New introduction overview. - -</LI> -<LI> - Added error code for invalid username and password, and renamed error code to be more - consistent. - -</LI> -<LI> - Added access grant type parameter to token endpoint. - -</LI> -</UL><P> - -</P> -<P> - -07 - - </P> -<UL class="text"> -<LI> - Major rewrite of entire document structure. - -</LI> -<LI> - Removed device profile. - -</LI> -<LI> - Added verification code support to user-agent flow. - -</LI> -<LI> - Removed multiple formats support, leaving JSON as the only format. - -</LI> -<LI> - Changed assertion <TT>assertion_format</TT> parameter to - <TT>assertion_type</TT>. - -</LI> -<LI> - Removed <TT>type</TT> parameter from token endpoint. - -</LI> -</UL><P> - -</P> -<P> - -06 - - </P> -<UL class="text"> -<LI> - Editorial changes, corrections, clarifications, etc. - -</LI> -<LI> - Removed conformance section. - -</LI> -<LI> - Moved authors section to contributors appendix. - -</LI> -<LI> - Added section on native applications. - -</LI> -<LI> - Changed error response to use the requested format. Added support for HTTP - <TT>Accept</TT> header. - -</LI> -<LI> - Flipped the order of the web server and user-agent flows. - -</LI> -<LI> - Renamed assertion flow <TT>format</TT> parameter name to - <TT>assertion_format</TT> to resolve conflict. - -</LI> -<LI> - Removed the term identifier from token definitions. Added a cryptographic token - definition. - -</LI> -<LI> - Added figure titles. - -</LI> -<LI> - Added server response 401 when client tried to authenticate using multiple credentials. - -</LI> -<LI> - Clarified support for TLS alternatives, and added requirement for TLS 1.2 support for - token endpoint. - -</LI> -<LI> - Removed all signature and cryptography. - -</LI> -<LI> - Removed all discovery. - -</LI> -<LI> - Updated HTML4 reference. - -</LI> -</UL><P> - -</P> -<P> - -05 - - </P> -<UL class="text"> -<LI> - Corrected device example. - -</LI> -<LI> - Added client credentials parameters to the assertion flow as OPTIONAL. - -</LI> -<LI> - Added the ability to send client credentials using an HTTP authentication scheme. - -</LI> -<LI> - Initial text for the <TT>WWW-Authenticate</TT> header (also added - scope support). - -</LI> -<LI> - Change authorization endpoint to end-user endpoint. - -</LI> -<LI> - In the device flow, change the <TT>user_uri</TT> parameter to - <TT>verification_uri</TT> to avoid confusion with the end-user - endpoint. - -</LI> -<LI> - Add <TT>format</TT> request parameter and support for XML and - form-encoded responses. - -</LI> -</UL><P> - -</P> -<P> - -04 - - </P> -<UL class="text"> -<LI> - Changed all token endpoints to use <TT>POST</TT> - -</LI> -<LI> - Clarified the authorization server's ability to issue a new refresh token when - refreshing a token. - -</LI> -<LI> - Changed the flow categories to clarify the autonomous group. - -</LI> -<LI> - Changed client credentials language not to always be server-issued. - -</LI> -<LI> - Added a <TT>scope</TT> response parameter. - -</LI> -<LI> - Fixed typos. - -</LI> -<LI> - Fixed broken document structure. - -</LI> -</UL><P> - -</P> -<P> - -03 - - </P> -<UL class="text"> -<LI> - Fixed typo in JSON error examples. - -</LI> -<LI> - Fixed general typos. - -</LI> -<LI> - Moved all flows sections up one level. - -</LI> -</UL><P> - -</P> -<P> - -02 - - </P> -<UL class="text"> -<LI> - Removed restriction on <TT>redirect_uri</TT> including a query. - -</LI> -<LI> - Added <TT>scope</TT> parameter. - -</LI> -<LI> - Initial proposal for a JSON-based token response format. - -</LI> -</UL><P> - -</P> -<P> - -01 - - </P> -<UL class="text"> -<LI> - Editorial changes based on feedback from Brian Eaton, Bill Keenan, and Chuck Mortimore. - -</LI> -<LI> - Changed device flow <TT>type</TT> parameter values and switch to use - only the token endpoint. - -</LI> -</UL><P> - -</P> -<P> - -00 - - </P> -<UL class="text"> -<LI> - Initial draft based on a combination of WRAP and OAuth 1.0a. - -</LI> -</UL><P> - -</P> -<A name="rfc.references"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<A name="rfc.section.9"></A><H3>9. -References</H3> - -<A name="rfc.references1"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<H3>9.1. Normative References</H3> -<TABLE width="99%" border="0"> -<TBODY><TR><TD class="author-text" valign="top"><A name="I-D.ietf-httpbis-p1-messaging">[I-D.ietf-httpbis-p1-messaging]</A></TD> -<TD class="author-text">Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, “<A href="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p1-messaging-09.txt">HTTP/1.1, part 1: URIs, Connections, and Message Parsing</A>,” draft-ietf-httpbis-p1-messaging-09 (work in progress), March 2010 (<A href="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p1-messaging-09.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="NIST FIPS-180-3">[NIST FIPS-180-3]</A></TD> -<TD class="author-text">National Institute of Standards and Technology, “<A href="http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf">Secure Hash Standard (SHS). FIPS PUB 180-3, October 2008</A>.”</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC2045">[RFC2045]</A></TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=ned@innosoft.com','Compose new message','width=640,height=480')" rel="noreferrer">Freed, N.</A> and <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=nsb@nsb.fv.com','Compose new message','width=640,height=480')" rel="noreferrer">N. Borenstein</A>, “<A href="http://tools.ietf.org/html/rfc2045">Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</A>,” RFC 2045, November 1996 (<A href="http://www.rfc-editor.org/rfc/rfc2045.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC2104">[RFC2104]</A></TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=hugo@watson.ibm.com','Compose new message','width=640,height=480')" rel="noreferrer">Krawczyk, H.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=mihir@cs.ucsd.edu','Compose new message','width=640,height=480')" rel="noreferrer">Bellare, M.</A>, and <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=canetti@watson.ibm.com','Compose new message','width=640,height=480')" rel="noreferrer">R. Canetti</A>, “<A href="http://tools.ietf.org/html/rfc2104">HMAC: Keyed-Hashing for Message Authentication</A>,” RFC 2104, February 1997 (<A href="http://www.rfc-editor.org/rfc/rfc2104.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC2119">[RFC2119]</A></TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=sob@harvard.edu','Compose new message','width=640,height=480')" rel="noreferrer">Bradner, S.</A>, “<A href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</A>,” BCP 14, RFC 2119, March 1997 (<A href="http://www.rfc-editor.org/rfc/rfc2119.txt">TXT</A>, <A href="http://xml.resource.org/public/rfc/html/rfc2119.html">HTML</A>, <A href="http://xml.resource.org/public/rfc/xml/rfc2119.xml">XML</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC2616">[RFC2616]</A></TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=fielding@ics.uci.edu','Compose new message','width=640,height=480')" rel="noreferrer">Fielding, R.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=jg@w3.org','Compose new message','width=640,height=480')" rel="noreferrer">Gettys, J.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=mogul@wrl.dec.com','Compose new message','width=640,height=480')" rel="noreferrer">Mogul, J.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=frystyk@w3.org','Compose new message','width=640,height=480')" rel="noreferrer">Frystyk, H.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=masinter@parc.xerox.com','Compose new message','width=640,height=480')" rel="noreferrer">Masinter, L.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=paulle@microsoft.com','Compose new message','width=640,height=480')" rel="noreferrer">Leach, P.</A>, and <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=timbl@w3.org','Compose new message','width=640,height=480')" rel="noreferrer">T. Berners-Lee</A>, “<A href="http://tools.ietf.org/html/rfc2616">Hypertext Transfer Protocol -- HTTP/1.1</A>,” RFC 2616, June 1999 (<A href="http://www.rfc-editor.org/rfc/rfc2616.txt">TXT</A>, <A href="http://www.rfc-editor.org/rfc/rfc2616.ps">PS</A>, <A href="http://www.rfc-editor.org/rfc/rfc2616.pdf">PDF</A>, <A href="http://xml.resource.org/public/rfc/html/rfc2616.html">HTML</A>, <A href="http://xml.resource.org/public/rfc/xml/rfc2616.xml">XML</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC2617">[RFC2617]</A></TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=john@math.nwu.edu','Compose new message','width=640,height=480')" rel="noreferrer">Franks, J.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=pbaker@verisign.com','Compose new message','width=640,height=480')" rel="noreferrer">Hallam-Baker, P.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=jeff@AbiSource.com','Compose new message','width=640,height=480')" rel="noreferrer">Hostetler, J.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=lawrence@agranat.com','Compose new message','width=640,height=480')" rel="noreferrer">Lawrence, S.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=paulle@microsoft.com','Compose new message','width=640,height=480')" rel="noreferrer">Leach, P.</A>, Luotonen, A., and <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=stewart@OpenMarket.com','Compose new message','width=640,height=480')" rel="noreferrer">L. Stewart</A>, “<A href="http://tools.ietf.org/html/rfc2617">HTTP Authentication: Basic and Digest Access Authentication</A>,” RFC 2617, June 1999 (<A href="http://www.rfc-editor.org/rfc/rfc2617.txt">TXT</A>, <A href="http://xml.resource.org/public/rfc/html/rfc2617.html">HTML</A>, <A href="http://xml.resource.org/public/rfc/xml/rfc2617.xml">XML</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC2818">[RFC2818]</A></TD> -<TD class="author-text">Rescorla, E., “<A href="http://tools.ietf.org/html/rfc2818">HTTP Over TLS</A>,” RFC 2818, May 2000 (<A href="http://www.rfc-editor.org/rfc/rfc2818.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC3023">[RFC3023]</A></TD> -<TD class="author-text">Murata, M., St. Laurent, S., and D. Kohn, “<A href="http://tools.ietf.org/html/rfc3023">XML Media Types</A>,” RFC 3023, January 2001 (<A href="http://www.rfc-editor.org/rfc/rfc3023.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC3447">[RFC3447]</A></TD> -<TD class="author-text">Jonsson, J. and B. Kaliski, “<A href="http://tools.ietf.org/html/rfc3447">Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1</A>,” RFC 3447, February 2003 (<A href="http://www.rfc-editor.org/rfc/rfc3447.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC3629">[RFC3629]</A></TD> -<TD class="author-text">Yergeau, F., “<A href="http://tools.ietf.org/html/rfc3629">UTF-8, a transformation format of ISO 10646</A>,” STD 63, RFC 3629, November 2003 (<A href="http://www.rfc-editor.org/rfc/rfc3629.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC3986">[RFC3986]</A></TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=timbl@w3.org','Compose new message','width=640,height=480')" rel="noreferrer">Berners-Lee, T.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=fielding@gbiv.com','Compose new message','width=640,height=480')" rel="noreferrer">Fielding, R.</A>, and <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=LMM@acm.org','Compose new message','width=640,height=480')" rel="noreferrer">L. Masinter</A>, “<A href="http://tools.ietf.org/html/rfc3986">Uniform Resource Identifier (URI): Generic Syntax</A>,” STD 66, RFC 3986, January 2005 (<A href="http://www.rfc-editor.org/rfc/rfc3986.txt">TXT</A>, <A href="http://xml.resource.org/public/rfc/html/rfc3986.html">HTML</A>, <A href="http://xml.resource.org/public/rfc/xml/rfc3986.xml">XML</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC4627">[RFC4627]</A></TD> -<TD class="author-text">Crockford, D., “<A href="http://tools.ietf.org/html/rfc4627">The application/json Media Type for JavaScript Object Notation (JSON)</A>,” RFC 4627, July 2006 (<A href="http://www.rfc-editor.org/rfc/rfc4627.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC5226">[RFC5226]</A></TD> -<TD class="author-text">Narten, T. and H. Alvestrand, “<A href="http://tools.ietf.org/html/rfc5226">Guidelines for Writing an IANA Considerations Section in RFCs</A>,” BCP 26, RFC 5226, May 2008 (<A href="http://www.rfc-editor.org/rfc/rfc5226.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC5246">[RFC5246]</A></TD> -<TD class="author-text">Dierks, T. and E. Rescorla, “<A href="http://tools.ietf.org/html/rfc5246">The Transport Layer Security (TLS) Protocol Version 1.2</A>,” RFC 5246, August 2008 (<A href="http://www.rfc-editor.org/rfc/rfc5246.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="RFC5849">[RFC5849]</A></TD> -<TD class="author-text">Hammer-Lahav, E., “<A href="http://tools.ietf.org/html/rfc5849">The OAuth 1.0 Protocol</A>,” RFC 5849, April 2010 (<A href="http://www.rfc-editor.org/rfc/rfc5849.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="W3C.REC-html401-19991224">[W3C.REC-html401-19991224]</A></TD> -<TD class="author-text">Raggett, D., Hors, A., and I. Jacobs, “<A href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML 4.01 Specification</A>,” World Wide Web Consortium Recommendation REC-html401-19991224, December 1999 (<A href="http://www.w3.org/TR/1999/REC-html401-19991224">HTML</A>).</TD></TR> -</TBODY></TABLE> - -<A name="rfc.references2"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<H3>9.2. Informative References</H3> -<TABLE width="99%" border="0"> -<TBODY><TR><TD class="author-text" valign="top"><A name="I-D.hammer-oauth">[I-D.hammer-oauth]</A></TD> -<TD class="author-text">Hammer-Lahav, E., “<A href="http://www.ietf.org/internet-drafts/draft-hammer-oauth-10.txt">The OAuth 1.0 Protocol</A>,” draft-hammer-oauth-10 (work in progress), February 2010 (<A href="http://www.ietf.org/internet-drafts/draft-hammer-oauth-10.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="I-D.hardt-oauth">[I-D.hardt-oauth]</A></TD> -<TD class="author-text">Hardt, D., Tom, A., Eaton, B., and Y. Goland, “<A href="http://www.ietf.org/internet-drafts/draft-hardt-oauth-01.txt">OAuth Web Resource Authorization Profiles</A>,” draft-hardt-oauth-01 (work in progress), January 2010 (<A href="http://www.ietf.org/internet-drafts/draft-hardt-oauth-01.txt">TXT</A>).</TD></TR> -<TR><TD class="author-text" valign="top"><A name="OASIS.saml-core-2.0-os">[OASIS.saml-core-2.0-os]</A></TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=cantor.2@osu.edu','Compose new message','width=640,height=480')" rel="noreferrer">Cantor, S.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=John.Kemp@nokia.com','Compose new message','width=640,height=480')" rel="noreferrer">Kemp, J.</A>, <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=rphilpott@rsasecurity.com','Compose new message','width=640,height=480')" rel="noreferrer">Philpott, R.</A>, and <A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=eve.maler@sun.com','Compose new message','width=640,height=480')" rel="noreferrer">E. Maler</A>, “<A href="http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf">Assertions and Protocol for the OASIS Security Assertion Markup Language - (SAML) V2.0</A>,” OASIS Standard saml-core-2.0-os, March 2005.</TD></TR> -</TBODY></TABLE> - -<A name="rfc.authors"></A><BR><HR> -<TABLE summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><TBODY><TR><TD class="TOCbug"><A href="http://tools.ietf.org/id/draft-ietf-oauth-v2-10.html#toc"> TOC </A></TD></TR></TBODY></TABLE> -<H3>Authors' Addresses</H3> -<TABLE width="99%" border="0" cellpadding="0" cellspacing="0"> -<TBODY><TR><TD class="author-text"> </TD> -<TD class="author-text">Eran Hammer-Lahav (editor)</TD></TR> -<TR><TD class="author-text"> </TD> -<TD class="author-text">Yahoo!</TD></TR> -<TR><TD class="author" align="right">Email: </TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=eran@hueniverse.com','Compose new message','width=640,height=480')" rel="noreferrer">eran@hueniverse.com</A></TD></TR> -<TR><TD class="author" align="right">URI: </TD> -<TD class="author-text"><A href="http://hueniverse.com/">http://hueniverse.com</A></TD></TR> -<TR cellpadding="3"><TD> </TD><TD> </TD></TR> -<TR><TD class="author-text"> </TD> -<TD class="author-text">David Recordon</TD></TR> -<TR><TD class="author-text"> </TD> -<TD class="author-text">Facebook</TD></TR> -<TR><TD class="author" align="right">Email: </TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=davidrecordon@facebook.com','Compose new message','width=640,height=480')" rel="noreferrer">davidrecordon@facebook.com</A></TD></TR> -<TR><TD class="author" align="right">URI: </TD> -<TD class="author-text"><A href="http://www.davidrecordon.com/">http://www.davidrecordon.com/</A></TD></TR> -<TR cellpadding="3"><TD> </TD><TD> </TD></TR> -<TR><TD class="author-text"> </TD> -<TD class="author-text">Dick Hardt</TD></TR> -<TR><TD class="author-text"> </TD> -<TD class="author-text">Microsoft</TD></TR> -<TR><TD class="author" align="right">Email: </TD> -<TD class="author-text"><A href="javascript:void(0)" onclick="window.open('http://mail.google.com/mail/?view=cm&fs=1&tf=1&to=dick.hardt@gmail.com','Compose new message','width=640,height=480')" rel="noreferrer">dick.hardt@gmail.com</A></TD></TR> -<TR><TD class="author" align="right">URI: </TD> -<TD class="author-text"><A href="http://dickhardt.org/">http://dickhardt.org/</A></TD></TR> -</TBODY></TABLE> - -</BODY><STYLE type="text/css">#AdContainer,#RadAd_Skyscraper,#ad-frame,#bbccom_leaderboard,#bbccom_mpu,#center_banner,#footer_adcode,#hbBHeaderSpon,#header_adcode,#hiddenHeaderSpon,#navbar_adcode,#pagelet_adbox,#rightAds,#rightcolumn_adcode,#top-advertising,#topMPU,#tracker_advertorial,.ad-now,.adbox,.adspot,.dfpad,.prWrap,.sponsored,[id^="ad_block"],[id^="adbrite"],[id^="dclkAds"],[id^="konaLayer"],[id^="ew"][id$="_bannerDiv"],a.kLink span[id^="preLoadWrap"][class="preLoadWrap"],A[href^="http://adserver.adpredictive.com"],A[href^="http://ad."][href*=".doubleclick.net/"],div[class^="dms_ad_IDS"],DIV[id="adxLeaderboard"],DIV[id="rm_container"],div[id^="sponsorads"],div[id^="y5_direct"],DIV[id="FFN_Banner_Holder"],DIV[id="FFN_imBox_Container"],DIV[id="p360-format-box"],div[id="tooltipbox"][class^="itxt"],div[id^="adKontekst_"],div[id^="google_ads_div"],div[id^="kona_"][id$="_wrapper"],div[class="wnDVUtilityBlock"],embed[flashvars*="AdID"],embed[id="Advertisement"][name="Advertisement"],iframe[class="chitikaAdBlock"],iframe[id^="dapIfM"],iframe[name^="AdBrite"],iframe[name^="google_ads_"],iframe[src*="clicksor.com"],img[src*="clicksor.com"],IMG[src^="http://cdn.adnxs.com"],ispan#ab_pointer,object[id="flashad"],object[id="ve_threesixty_swf"][name="ve_threesixty_swf"],[src*="sixsigmatraffic.com"],div#dir_ads_site,div#tads table[align="center"][width="100%"],div#rhs div#rhs_block table#mbEnd,#A9AdsMiddleBoxTop,#A9AdsOutOfStockWidgetTop,#A9AdsServicesWidgetTop,#AD_CONTROL_22,#ADsmallWrapper,#Ad1,#Ad2,#Ad3Left,#Ad3Right,#AdBanner_F1,#AdBar1,#AdContainerTop,#AdHeader,#AdMiddle,#AdRectangle,#AdSenseDiv,#AdShowcase_F1,#AdSky23,#AdSkyscraper,#AdSponsor_SF,#AdTargetControl1_iframe,#AdText,#Ad_Block,#Ad_Center1,#Ad_Top,#Adbanner,#Adrectangle,#AdsContent,#AdsWrap,#AdvertMPU23b,#AdvertiseFrame,#Advertisement,#Advertorial,#BannerAdvert,#BigBoxAd,#CompanyDetailsNarrowGoogleAdsPresentationControl,#CompanyDetailsWideGoogleAdsPresentationControl,#ContentAd,#ContentAd1,#ContentAd2,#ContentAdPlaceHolder1,#ContentAdPlaceHolder2,#ContentAdXXL,#ContentPolepositionAds_Result,#FooterAd,#FooterAdContainer,#GoogleAdsense,#HEADERAD,#HOME_TOP_RIGHT_BOXAD,#HeaderAdsBlock,#HeaderAdsBlockFront,#HeaderBannerAdSpacer,#HeaderTextAd,#HeroAd,#HomeAd1,#HouseAd,#ID_Ad_Sky,#Journal_Ad_125,#Journal_Ad_300,#LeftAd,#LeftAdF1,#LeftAdF2,#LowerContentAd,#PREFOOTER_LEFT_BOXAD,#PREFOOTER_RIGHT_BOXAD,#PageLeaderAd,#RightAd,#RightSponsoredAd,#SectionAd300-250,#SidebarAdContainer,#SkyAd,#SpecialAds,#SponsoredAd,#TOP_ADROW,#TOP_RIGHT_BOXAD,#TopAdPos,#VM-MPU-adspace,#VM-footer-adspace,#VM-header-adspace,#VM-header-adwrap,#XEadLeaderboard,#XEadSkyscraper,#_ads,#ad-120x600-sidebar,#ad-160x600,#ad-160x600-sidebar,#ad-250x300,#ad-300,#ad-300x250,#ad-300x250-sidebar,#ad-300x250Div,#ad-728,#ad-article,#ad-banner,#ad-bottom,#ad-bottom-wrapper,#ad-colB-1,#ad-column,#ad-container,#ad-footer,#ad-footprint-160x600,#ad-front-footer,#ad-front-sponsoredlinks,#ad-halfpage,#ad-label,#ad-leaderboard,#ad-leaderboard-bottom,#ad-leaderboard-spot,#ad-leaderboard-top,#ad-left,#ad-list-row,#ad-lrec,#ad-medium-rectangle,#ad-middlethree,#ad-middletwo,#ad-module,#ad-mpu,#ad-mpu1-spot,#ad-mpu2-spot,#ad-placard,#ad-rectangle,#ad-righttop,#ad-side-text,#ad-skyscraper,#ad-slug-wrapper,#ad-space,#ad-splash,#ad-spot,#ad-target,#ad-target-Leaderbord,#ad-teaser,#ad-top,#ad-top-text-low,#ad-tower,#ad-trailerboard-spot,#ad-typ1,#ad-west,#ad-wrap,#ad-wrap-right,#ad-wrapper,#ad-wrapper1,#ad-yahoo-simple,#ad1,#ad125BL,#ad125BR,#ad125TL,#ad125TR,#ad125x125,#ad160x600,#ad160x600right,#ad1Sp,#ad2,#ad2Sp,#ad3,#ad300,#ad300-250,#ad300X250,#ad300_x_250,#ad300x150,#ad300x250,#ad300x250Module,#ad300x60,#ad300x600,#ad300x600_callout,#ad336,#ad336x280,#ad375x85,#ad468,#ad468x60,#ad526x250,#ad600,#ad7,#ad728,#ad728Wrapper,#ad728x90,#adB,#adBadges,#adBanner,#adBanner120x600,#adBannerTable,#adBannerTop,#adBar,#adBlock125,#adBlocks,#adBox,#adContainer,#adDiv,#adFps,#adFtofrs,#adGallery,#adGroup1,#adHeader,#adL,#adLB,#adLeaderboard,#adMPU,#adMiddle0Frontpage,#adMiniPremiere,#adP,#adPlaceHolderRight,#adRight,#adSenseModule,#adServer_marginal,#adSidebar,#adSidebarSq,#adSky,#adSkyscraper,#adSlider,#adSpace3,#adSpace300_ifrMain,#adSpace4,#adSpace5,#adSpace6,#adSpace7,#adSpace_footer,#adSpace_top,#adSpecial,#adSpot-Leader,#adSpot-banner,#adSpot-mrec1,#adSpot-sponsoredlinks,#adSpot-textbox1,#adSpot-widestrip,#adSpotAdvertorial,#adSpotIsland,#adSpotSponsoredLinks,#adSquare,#adStaticA,#adStrip,#adSuperPremiere,#adTableCell,#adTag1,#adTag2,#adText,#adText_container,#adTop,#adTopboxright,#adUnit,#adWrapper,#adZoneTop,#ad_160x160,#ad_160x600,#ad_190x90,#ad_300,#ad_300_250,#ad_300x250,#ad_468_60,#ad_5,#ad_728_foot,#ad_728x90,#ad_A,#ad_B,#ad_Banner,#ad_C,#ad_C2,#ad_D,#ad_E,#ad_F,#ad_G,#ad_H,#ad_I,#ad_J,#ad_K,#ad_L,#ad_M,#ad_N,#ad_O,#ad_P,#ad_YieldManager-300x250,#ad_anchor,#ad_banner,#ad_banner_top,#ad_bar,#ad_block_1,#ad_block_2,#ad_bottom,#ad_box_colspan,#ad_branding,#ad_bs_area,#ad_center_monster,#ad_container,#ad_content_wrap,#ad_feature,#ad_footer,#ad_haha_1,#ad_haha_4,#ad_halfpage,#ad_head,#ad_header,#ad_horseshoe_left,#ad_horseshoe_right,#ad_horseshoe_spacer,#ad_horseshoe_top,#ad_hotpots,#ad_island,#ad_label,#ad_layer2,#ad_leader,#ad_leaderBoard,#ad_leaderboard,#ad_lwr_square,#ad_medium_rectangle,#ad_medium_rectangular,#ad_middle,#ad_mpu,#ad_mrcontent,#ad_overlay,#ad_play_300,#ad_rect,#ad_rect_body,#ad_rect_bottom,#ad_rectangle,#ad_related_links_div,#ad_related_links_div_program,#ad_replace_div_1,#ad_report_leaderboard,#ad_report_rectangle,#ad_right,#ad_right_main,#ad_ros_tower,#ad_rr_1,#ad_sidebar1,#ad_sidebar2,#ad_sidebar3,#ad_skyscraper,#ad_slot_livesky,#ad_space,#ad_square,#ad_ss,#ad_term_bottom_place,#ad_top,#ad_top_holder,#ad_tp_banner_1,#ad_tp_banner_2,#ad_vertical,#ad_window,#ad_wrapper,#adbanner,#adbnr,#adboard,#adbottom,#adbox,#adbox2,#adclear,#adcode1,#adcode2,#adcode3,#adcode4,#adcolumnwrapper,#adcontainer,#adcontainsm,#adcontrolPushSite,#addiv-bottom,#addiv-top,#adfooter_728x90,#adframe:not(frameset),#adhead,#adhead_g,#adheader,#adhome,#adiframe1_iframe,#adiframe2_iframe,#adiframe3_iframe,#adimg,#adition_content_ad,#adlabel,#adlabelFooter,#adleaderboard,#adlinks,#adlinkws,#admid,#admiddle3center,#admiddle3left,#adposition,#adposition-C,#adposition-FPMM,#adposition2,#adposition3,#adposition4,#adrectanglea,#adrectangleb,#adright,#adright2,#ads,#ads-468,#ads-area,#ads-block,#ads-bot,#ads-bottom,#ads-dell,#ads-horizontal,#ads-indextext,#ads-leaderboard1,#ads-lrec,#ads-prices,#ads-rhs,#ads-top,#ads160left,#ads2,#ads300,#ads336x280,#ads7,#ads728bottom,#ads728top,#ads790,#adsDisplay,#adsID,#ads_160,#ads_300,#ads_728,#ads_belowforumlist,#ads_belownav,#ads_bottom_outer,#ads_catDiv,#ads_footer,#ads_right,#ads_sidebar_roadblock,#ads_top,#adsbottom,#adscolumn,#adsense,#adsense-text,#adsenseWrap,#adsense_inline,#adsense_leaderboard,#adsense_placeholder_2,#adsensetopplay,#adskyscraper,#adslot,#adsonar,#adspace,#adspace-300x250,#adspace300x250,#adspaceBox,#adspaceBox300,#adspace_header,#adspot-a,#adsright,#adstop,#adt,#adtech_googleslot_03c,#adtech_takeover,#adtop,#adv-masthead,#adv_google_300,#adv_google_728,#adv_top_banner_wrapper,#adv_wide_banner,#adver1,#adver2,#adver3,#adver4,#advert,#advert-1,#advert-boomer,#advert-display,#advert-header,#advert-leaderboard,#advert-top,#advert1,#advertBanner,#advert_250x250,#advert_box,#advert_leaderboard,#advert_lrec_format,#advert_mpu,#advertbox,#advertbox2,#advertbox3,#advertbox4,#adverthome,#advertise,#advertise-now,#advertise1,#advertisement,#advertisement160x600,#advertisement728x90,#advertisementLigatus,#advertisementPrio2,#advertiser-container,#advertiserLinks,#advertising,#advertising-skyscraper,#advertisingModule160x600,#advertisingModule728x90,#advertorial,#adwhitepaperwidget,#adwin_rec,#adwith,#adwords-4-container,#adwrapper,#adxtop,#adzerk,#adzoneBANNER,#agi-ad300x250,#agi-ad300x250overlay,#agi-sponsored,#anchorAd,#annoying_ad,#ap_adframe,#araHealthSponsorAd,#article-ad-container,#article-box-ad,#articleAdReplacement,#articleSideAd,#article_ad,#article_box_ad,#asinglead,#atlasAdDivGame,#banner-ad,#banner-ad-container,#banner-ads,#banner468x60,#banner728x90,#bannerAd,#bannerAdTop,#bannerAd_ctr,#banner_ad,#banner_ads,#banner_topad,#bannerad,#bannerad2,#bbccom_mpu,#bbo_ad1,#bg_YieldManager-300x250,#bigAd,#bigBoxAd,#bigadbox,#bigadspot,#billboard_ad,#block-ad_cube-1,#block-thewrap_ads_250x300-0,#block_advert,#blox-big-ad,#blox-halfpage-ad,#blox-tile-ad,#botad,#bott_ad2,#bott_ad2_300,#bottom-ad-container,#bottom-ads,#bottomAd,#bottomAdCCBucket,#bottomAdContainer,#bottomAdSense,#bottomAdSenseDiv,#bottomAds,#bottomRightAd,#bottomRightAdSpace,#bottom_ad,#bottom_ad_area,#bottom_ads,#bottom_banner_ad,#bottom_overture,#bottom_sponsor_ads,#bottom_sponsored_links,#bottom_text_ad,#bottomad,#bottomadsense,#box-googleadsense-1,#box-googleadsense-r,#box1ad,#boxAd300,#boxAdContainer,#box_ad,#box_mod_googleadsense,#boxad1,#boxad2,#boxad3,#boxad4,#boxad5,#bps-header-ad-container,#btr_horiz_ad,#burn_header_ad,#button-ads-horizontal,#button-ads-vertical,#button_ad_container,#button_ad_wrap,#cellAd,#channel_ad,#channel_ads,#ciHomeRHSAdslot,#circ_ad,#cnnRR336ad,#cnnTopAd,#colRightAd,#column4-google-ads,#commercial_ads,#common_right_lower_player_adspace,#common_right_player_adspace,#common_top_adspace,#containerLocalAds,#containerMrecAd,#content-ad-header,#contentAd,#content_ad,#content_ad_square,#content_ad_top,#content_ads_content,#content_box_300body_sponsoredoffers,#content_box_adright300_google,#contentad,#contentad_imtext,#contentad_right,#contentads,#contentinlineAd,#contextual-ads-block,#contextualad,#coverads,#ctl00_BottomAd,#ctl00_LHTowerAd,#ctl00_LeftHandAd,#ctl00_MasterHolder_IBanner_adHolder,#ctl00_TopAd,#ctl00_TowerAd,#ctl00_VBanner_adHolder,#ctl00_adFooter,#ctl00_atop_bt,#ctl00_cphMain_hlAd1,#ctl00_cphMain_hlAd2,#ctl00_cphMain_hlAd3,#ctl00_ctl00_MainPlaceHolder_itvAdSkyscraper,#ctl00_ctl00_ctl00_Main_Main_PlaceHolderGoogleTopBanner_MPTopBannerAd,#ctl00_ctl00_ctl00_Main_Main_SideBar_MPSideAd,#ctl00_ctl00_ctl00_tableAdsTop,#ctl00_m_skinTracker_m_adLBL,#ctl00_phCrackerMain_ucAffiliateAdvertDisplayMiddle_pnlAffiliateAdvert,#ctl00_phCrackerMain_ucAffiliateAdvertDisplayRight_pnlAffiliateAdvert,#ctrlsponsored,#cubeAd,#cube_ads,#cube_ads_inner,#cubead,#cubead-2,#dc-display-right-ad-1,#dcol-sponsored,#defer-adright,#detail_page_vid_topads,#divAd,#divAdBox,#divWrapper_Ad,#div_video_ads,#dlads,#dni-header-ad,#download_ads,#ds-mpu,#editorsmpu,#evotopTen_advert,#exads,#featuread,#featuredAdContainer2,#featuredAds,#feed_links_ad_container,#first_ad_unit,#firstad,#fl_hdrAd,#footer-ad,#footer-sponsored,#footerAd,#footerAdDiv,#footerAds,#footerAdverts,#footer_ad,#footer_ad_block,#footer_ads,#footer_adspace,#footer_text_ad,#footerad,#fr_ad_center,#frnContentAd,#from_our_sponsors,#front_advert,#front_mpu,#ft-ad,#ft-ad-1,#ft-ad-container,#ft_mpu,#fusionad,#fw-advertisement,#g_ad,#g_adsense,#ga_300x250,#gad,#gallery-ad-m0,#gallery_ads,#game-info-ad,#global_header_ad_area,#gmi-ResourcePageAd,#gmi-ResourcePageLowerAd,#google-ad,#google-ad-art,#google-ad-tower,#google-ads,#google-ads-bottom,#google-ads-left-side,#google-adsense-mpusize,#googleAd,#googleAds,#googleAdsense,#googleAdsenseBanner,#googleAdsenseBannerBlog,#googleAdwordsModule,#googleAfcContainer,#googleShoppingAdsRight,#googleShoppingAdsTop,#google_ad,#google_ad_test,#google_ads,#google_ads_frame1,#google_ads_test,#googlead,#googleads,#googlesponsor,#grid_ad,#gsyadrectangleload,#gsyadrightload,#gsyadtop,#gsyadtopload,#gtopadvts,#halfPageAd,#halfe-page-ad-box,#hdtv_ad_ss,#head-ad,#head_advert,#header-ad,#header-ads,#header-advert,#headerAd,#headerAdBackground,#headerAdContainer,#headerAdWrap,#headerAdsWrapper,#headerTopAd,#header_ad,#header_adcode,#header_ads,#header_advertisement_top,#header_leaderboard_ad_container,#headerad,#headeradbox,#headline_ad,#hiddenadAC,#homeTopRightAd,#home_ad,#home_contentad,#home_spensoredlinks,#homepage-ad,#homepage_right_ad,#homepage_right_ad_container,#hometop_234x60ad,#hor_ad,#horizontal-banner-ad,#horizontal_ad,#horizontal_ad_top,#horizontalads,#houseAd,#hp-store-ad,#hpV2_300x250Ad,#hpV2_googAds,#icePage_SearchLinks_AdRightDiv,#icePage_SearchLinks_DownloadToolbarAdRightDiv,#indexad,#inlinead,#inlinegoogleads,#inner-advert-row,#insider_ad_wrapper,#instoryad,#int-ad,#interstitial_ad_wrapper,#islandAd,#j_ad,#jmp-ad-buttons,#joead,#joead2,#ka_adRightSkyscraperWide,#landing-adserver,#largead,#lateAd,#lb-sponsor-left,#lb-sponsor-right,#leader-board-ad,#leader-sponsor,#leaderAdContainer,#leaderad,#leaderad_section,#leaderboard-ad,#leaderboard-bottom-ad,#leaderboard_ad,#left-ad-skin,#leftAdContainer,#leftAd_rdr,#leftAdvert,#leftSectionAd300-100,#left_ad,#left_adspace,#leftad,#leftads,#lg-banner-ad,#linkAds,#live-ad,#longAdSpace,#lowerthirdad,#mBannerAd,#main-ad,#main-ad160x600,#main-ad160x600-img,#main-ad728x90,#mainAd,#mainAdUnit,#mainAdvert,#main_ad,#main_rec_ad,#mastAdvert,#mastad,#masthead_ad,#masthead_topad,#medRecAd,#media_ad,#menuAds,#mi_story_assets_ad,#mid-ad300x250,#mid-table-ad,#mid_ad_title,#mid_mpu,#middlead,#middleads,#midrect_ad,#midstrip_ad,#mini-ad,#module-google_ads,#module_ad,#module_box_ad,#moogleAd,#most_popular_ad,#mpu,#mpu-advert,#mpuAd,#mpuDiv,#mpuWrapper,#mpuWrapperAd,#mpu_banner,#mpu_holder,#mpu_text_ad,#mpuad,#mrecAdContainer,#ms_ad,#msad,#multiLinkAdContainer,#n_sponsor_ads,#namecom_ad_hosting_main,#narrow_ad_unit,#natadad300x250,#national_microlink_ads,#navi_banner_ad_780,#nba300Ad,#nbaMidAds,#nbaVid300Ad,#new_topad,#ng_rtcol_ad,#noresultsads,#northad,#oanda_ads,#onespot-ads,#p-googleadsense,#page-header-ad,#pageAds,#pageAdsDiv,#page_content_top_ad,#pcworldAdBottom,#pcworldAdTop,#pinball_ad,#player_ad,#player_ads,#portlet-advertisement-left,#portlet-advertisement-right,#post5_adbox,#post_ad,#priceGrabberAd,#print_ads,#printads,#product-adsense,#promo-ad,#promoAds,#ps-vertical-ads,#pub468x60,#publicidad,#pushdown_ad,#r1SoftAd,#rail_ad1,#rail_ad2,#realEstateAds,#rect_ad,#rectangle-ad,#rectangle_ad,#refine-300-ad,#region-top-ad,#rh-ad-container,#rh_tower_ad,#rhsadvert,#right-ad,#right-ad-skin,#right-box-ad,#rightAd,#rightAd300x250,#rightAdColumn,#rightAd_rdr,#rightColAd,#rightColumnMpuAd,#rightColumnSkyAd,#right_ad_wrapper,#right_ads,#right_advertisement,#right_advertising,#right_column_ads,#rightad,#rightadvertbar-doubleclickads,#rightbar-ad,#rightside_ad,#rm_ad_text,#ros_ad,#rotatingads,#row2AdContainer,#rtMod_ad,#sAdsBox,#sb-ad-sq,#sb_advert,#search-google-ads,#search_ads,#secondBoxAdContainer,#section-container-ddc_ads,#section_advertorial_feature,#servfail-ads,#sew-ad1,#shoppingads,#show-ad,#side-ad,#side-ad-container,#sideAd,#sideBarAd,#side_ad_wrapper,#side_ads_by_google,#sidead,#sidebar-125x125-ads,#sidebar-125x125-ads-below-index,#sidebar-ad,#sidebar-ad-boxes,#sidebar-ad-space,#sidebar-ad-wrap,#sidebar-ads,#sidebar2ads,#sidebar_ad_widget,#sidebar_ads,#sidebar_sponsoredresult_body,#sidebarad,#sideline-ad,#single-mpu,#singlead,#site-leaderboard-ads,#site_top_ad,#sky-ad,#skyAd,#skyScrapperAd,#sky_ad,#sky_advert,#skyscraper-ad,#skyscraperAd,#skyscraper_ad,#skyscraper_advert,#sliderAdHolder,#slideshow_ad_300x250,#sm-banner-ad,#small_ad,#smallerAd,#speeds_ads,#speeds_ads_fstitem,#sphereAd,#splinks,#sponLinkDiv_1,#sponlink,#sponsAds,#sponsLinks,#spons_left,#sponseredlinks,#sponsor-search,#sponsorAd1,#sponsorAd2,#sponsorAdDiv,#sponsorLinks,#sponsorTextLink,#sponsor_banderole,#sponsor_box,#sponsor_deals,#sponsor_panSponsor,#sponsored,#sponsored-ads,#sponsored-features,#sponsored-links,#sponsored-resources,#sponsored1,#sponsoredBox1,#sponsoredBox2,#sponsoredLinks,#sponsoredList,#sponsoredResults,#sponsoredSiteMainline,#sponsoredSiteSidebar,#sponsored_ads_v4,#sponsored_content,#sponsored_game_row_listing,#sponsored_links,#sponsoredlinks,#sponsoredlinks_cntr,#sponsoredresults_top,#sponsorlink,#spotlightAds,#spotlightad,#squareAd,#squareAdSpace,#square_ad,#start_middle_container_advertisment,#sticky-ad,#stickyBottomAd,#story-ad-a,#story-ad-b,#story-sponsoredlinks,#storyAd,#storyAdWrap,#subpage-ad-right,#subpage-ad-top,#swads,#synch-ad,#tabAdvertising,#tblAd,#tbl_googlead,#template_ad_leaderboard,#tertiary_advertising,#text-ad,#textAd,#textAds,#text_ad,#text_advert,#the-last-ad-standing,#thefooterad,#themis-ads,#tile-ad,#tmglBannerAd,#top-ad,#top-ad-container,#top-ad-menu,#top-ads,#top-ads-tabs,#top-advertisement,#top-banner-ad,#top-search-ad-wrapper,#topAd,#topAd728x90,#topAdBanner,#topAdContainer,#topAdSenseDiv,#topAds,#topAdsContainer,#topAdvert,#topBannerAd,#topNavLeaderboardAdHolder,#top_ad,#top_ad_area,#top_ad_game,#top_ad_wrapper,#top_ads,#top_advertise,#top_advertising,#top_right_ad,#top_wide_ad,#topad,#topad_left,#topad_right,#topadblock,#topads,#topadzone,#topcustomad,#toprightAdvert,#toptextad,#towerad,#ttp_ad_slot1,#ttp_ad_slot2,#twogamesAd,#txt_link_ads,#undergameAd,#upperMpu,#upperad,#urban_contentad_article,#v_ad,#vert_ad,#vertical_ad,#vertical_ads,#video_cnv_ad,#video_overlay_ad,#walltopad,#welcomeAdsContainer,#welcome_ad_mrec,#welcome_advertisement,#wgtAd,#whatsnews_top_ad,#whitepaper-ad,#whoisRightAdContainer,#wide_ad_unit_top,#widget_advertisement,#wrapAdRight,#wrapAdTop,#y708-ad-expedia,#y708-ad-lrec,#y708-ad-partners,#y708-ad-ysm,#y708-advertorial-marketplace,#yahoo-ads,#yahoo-sponsors,#yahoo_ads,#yahoo_ads_2010,#yahooad-tbl,#yan-sponsored,#ybf-ads,#yfi_fp_ad_mort,#yfi_fp_ad_nns,#yfi_pf_ad_mort,#ygrp-sponsored-links,#ymap_adbanner,#yn-gmy-ad-lrec,#yreSponsoredLinks,#ysm_ad_iframe,#zoneAdserverMrec,#zoneAdserverSuper,.ADBAR,.ADPod,.AD_MOVIE_ITEM,.AD_MOVIE_ITEMLIST,.AD_MOVIE_ITEMROW,.Ad120x600,.Ad160x600,.Ad247x90,.Ad300x250,.Ad300x250L,.Ad728x90,.AdBox,.AdBox7,.AdContainerBox308,.AdHere,.AdInfo,.AdPlaceHolder,.AdRingtone,.AdSense,.AdSpace,.AdTitle,.AdUnit,.AdUnit300,.Ad_C,.Ad_D_Wrapper,.Ad_E_Wrapper,.Ad_Right,.Ads,.AdsBoxSection,.AdsLinks1,.AdsLinks2,.AdvertMidPage,.AdvertiseWithUs,.AdvertisementTextTag,.ArticleInlineAd,.BannerAd,.BlockAd,.BottomAffiliate,.CG_adkit_leaderboard,.CommentAd,.DeptAd,.FT_Ad,.FlatAds,.HPNewAdsBannerDiv,.HomeContentAd,.LeftTowerAd,.M2Advertisement,.MD_adZone,.MPU,.MPUHolder,.MiddleAdContainer,.OpenXad,.PU_DoubleClickAdsContent,.Post5ad,.RBboxAd,.RelatedAds,.RightRailTop300x250Ad,.RightSponsoredAdTitle,.RightTowerAd,.SidebarAd,.SponsoredAdTitle,.SponsoredContent,.SponsoredLinks,.SponsoredLinksGrayBox,.SquareAd,.StandardAdLeft,.StandardAdRight,.TextAd,.TheEagleGoogleAdSense300x250,.TopAd,.TopAdL,.TopAdR,.UIStandardFrame_SidebarAds,.UIWashFrame_SidebarAds,.UnderAd,.VerticalAd,.WidgetAdvertiser,.ad-160x600,.ad-250,.ad-300,.ad-300-block,.ad-300-blog,.ad-300x100,.ad-300x250,.ad-600,.ad-728,.ad-adlink-bottom,.ad-adlink-side,.ad-background,.ad-banner,.ad-bigsize,.ad-block,.ad-blog2biz,.ad-bottom,.ad-box,.ad-break,.ad-btn,.ad-btn-heading,.ad-button,.ad-cell,.ad-container,.ad-div,.ad-feedback,.ad-filler,.ad-footer,.ad-footer-leaderboard,.ad-google,.ad-gray,.ad-hdr,.ad-head,.ad-holder,.ad-homeleaderboard,.ad-img,.ad-island,.ad-leaderboard,.ad-links,.ad-medium,.ad-medium-two,.ad-mpu,.ad-other,.ad-permalink,.ad-placeholder,.ad-postText,.ad-poster,.ad-rect,.ad-rectangle,.ad-rectangle-text,.ad-related,.ad-rh,.ad-ri,.ad-right,.ad-right-header,.ad-right-txt,.ad-section,.ad-sidebar300,.ad-slot,.ad-slot-234-60,.ad-slot-300-250,.ad-slot-728-90,.ad-space,.ad-space-mpu-box,.ad-spot,.ad-statement,.ad-text,.ad-tile,.ad-top,.ad-top-left,.ad-unit,.ad-unit-300,.ad-unit-300-wrapper,.ad-unit-anchor,.ad-vtu,.ad-wrap,.ad-wrapper,.ad-zone-s-q-l,.ad0,.ad1,.ad10,.ad120,.ad160,.ad160x600,.ad18,.ad19,.ad2,.ad21,.ad250c,.ad3,.ad300,.ad300_250,.ad300x100,.ad300x250,.ad300x250Top,.ad300x250_container,.ad300x250box,.ad300x600,.ad310,.ad336x280,.ad343x290,.ad450,.ad468,.ad468_60,.ad468x60,.ad6,.ad620x70,.ad626X35,.ad7,.ad728,.ad728_90,.ad728x90,.ad728x90_container,.ad8,.adAgate,.adBanner,.adBannerTyp1,.adBannerTypSortableList,.adBannerTypW300,.adBgBottom,.adBgMId,.adBgTop,.adBox,.adBoxContent,.adBoxSidebar,.adBoxSingle,.adCMRight,.adColumn,.adContainer,.adContour,.adCreative,.adDiv,.adElement,.adFrame,.adFtr,.adFullWidthMiddle,.adGoogle,.adHeader,.adHeadline,.adHolder,.adHome300x250,.adInNews,.adLabel,.adLeader,.adLeaderForum,.adLeaderboard,.adLeft,.adMastheadLeft,.adMastheadRight,.adMkt2Colw,.adModule,.adNewsChannel,.adNoOutline,.adNoticeOut,.adObj,.adPageBorderL,.adPageBorderR,.adPanel,.adRect,.adRight,.adSelfServiceAdvertiseLink,.adServer,.adSlot,.adSpBelow,.adSpace,.adSpacer,.adSpot,.adSpot-searchAd,.adSpot-textBox,.adSpot-twin,.adSpotIsland,.adSquare,.adSummary,.adSuperboard,.adTag,.adText,.adTileWrap,.adTiler,.adTitle,.adTout,.adTxt,.adWithTab,.adWrap,.adWrapper,.ad_1,.ad_125,.ad_130x90,.ad_160,.ad_160x600,.ad_2,.ad_3,.ad_300,.ad_300_250,.ad_300x250,.ad_336,.ad_336x280,.ad_350x250,.ad_468,.ad_600,.ad_728,.ad_728x90,.ad_amazon,.ad_biz,.ad_block_338,.ad_bottom_leaderboard,.ad_box,.ad_box2,.ad_callout,.ad_caption,.ad_contain,.ad_container,.ad_content,.ad_content_wide,.ad_contents,.ad_descriptor,.ad_footer,.ad_framed,.ad_front_promo,.ad_header,.ad_hpm,.ad_info_block,.ad_label,.ad_launchpad,.ad_leader,.ad_leaderboard,.ad_left,.ad_linkunit,.ad_loc,.ad_lrec,.ad_medrect,.ad_mpu,.ad_mr,.ad_mrec,.ad_mrec_title_article,.ad_notice,.ad_p360,.ad_partner,.ad_partners,.ad_plus,.ad_post,.ad_power,.ad_rectangle,.ad_right,.ad_sidebar,.ad_skyscraper,.ad_slug_table,.ad_space,.ad_space_300_250,.ad_sponsor,.ad_sponsoredsection,.ad_spot_b,.ad_spot_c,.ad_square_r,.ad_square_top,.ad_text,.ad_title,.ad_top,.ad_top_leaderboard,.ad_tower,.ad_unit,.ad_unit_rail,.ad_warning,.ad_wide,.ad_wrap,.ad_wrapper,.ad_wrapper_fixed,.ad_wrapper_top,.ad_zone,.adarea,.adbanner,.adbannerright,.adbar,.adborder,.adbot,.adbottom,.adbottomright,.adbox,.adbox-outer,.adbox_366x280,.adbox_468X60,.adbox_bottom,.adboxclass,.adcode,.adcolumn_wrapper,.adcontainer,.adcopy,.addiv,.adfoot,.adfootbox,.adframe,.adhead,.adheader,.adheader100,.adhere,.adhoriz,.adi,.adinfo,.adinside,.adjlink,.adkit,.adkit-advert,.adkit-lb-footer,.adlabel-horz,.adlabel-vert,.adleft,.adline,.adlink,.adlinks,.adlist,.adlnklst,.admarker,.admedrec,.admessage,.admodule,.admpu,.adnotice,.adops,.adpadding,.adpic,.adright,.adrotate_widget,.adrow,.adrow-post,.adrule,.ads-banner,.ads-categories-bsa,.ads-favicon,.ads-links-general,.ads-mpu,.ads-profile,.ads-right,.ads-sidebar,.ads-sky,.ads-text,.ads2,.ads3,.ads:not(body),.adsArea,.adsBelowHeadingNormal,.adsBox,.adsImages,.adsTextHouse,.adsTower2,.adsTowerWrap,.adsWithUs,.ads_300,.ads_728x90,.ads_big,.ads_big-half,.ads_brace,.ads_catDiv,.ads_container,.ads_disc_anchor,.ads_disc_leader,.ads_disc_lwr_square,.ads_disc_skyscraper,.ads_disc_square,.ads_div,.ads_header,.ads_leaderboard,.ads_mpu,.ads_outer,.ads_right,.ads_sc_bl_i,.ads_sc_tl_i,.ads_side,.ads_takeover,.ads_tr,.adsborder,.adsbyyahoo,.adsc,.adscontainer,.adscreen,.adsection_a2,.adsection_c2,.adsense,.adsense-heading,.adsense-right,.adsense-title,.adsenseBlock,.adsenseContainer,.adsenseblock,.adsenselr,.adsensesq,.adsidebox,.adsingle,.adslogan,.adspace,.adspace-MR,.adspace_buysell,.adspace_rotate,.adspacer,.adspot,.adstrip,.adtag,.adtext,.adtext_gray,.adtext_onwhite,.adtop,.adtravel,.adv-mpu,.adverTag,.adver_cont_below,.advert,.advert-box,.advert-head,.advert-horizontal,.advert-mpu,.advert-skyscraper,.advert-text,.advertCont,.advertContainer,.advertHeadline,.advertRight,.advertText,.advert_468x60,.advert_box,.advert_cont,.advert_leaderboard,.advert_note,.advertise,.advertise-here,.advertise-homestrip,.advertise-horz,.advertise-leaderboard,.advertise-vert,.advertiseContainer,.advertiseText,.advertisement,.advertisement-728x90,.advertisement-block,.advertisement-top,.advertisement468,.advertisementColumnGroup,.advertisementContainer,.advertisementLabel,.advertisementPanel,.advertisement_caption,.advertisement_g,.advertisement_header,.advertisement_horizontal,.advertiser,.advertising,.advertising-header,.advertising2,.advertisingTable,.advertising_block,.advertisment,.advertisment_two,.advertize,.advertorial,.advertorial-promo-box,.adverts,.advt,.advt-banner-3,.advt300,.advt720,.adwordListings,.adwrapper,.adwrapper-lrec,.adwrapper948,.affiliate,.affiliate-link,.affiliate-sidebar,.affiliateAdvertText,.agi-adsaleslinks,.alt_ad,.anchorAd,.answer_ad_content,.aolSponsoredLinks,.aopsadvert,.article-ads,.articleAd,.articleAds,.articleAdsL,.articleEmbeddedAdBox,.article_ad,.article_adbox,.article_mpu_box,.articleads,.aseadn,.aux-ad-widget-2,.b-astro-sponsored-links_horizontal,.b-astro-sponsored-links_vertical,.banner-ad,.banner-ads,.banner-adverts,.banner300x100,.banner300x250,.banner468,.bannerAd,.bannerAdWrapper300x250,.bannerAdWrapper730x86,.banner_300x250,.banner_728x90,.banner_ad,.banner_ad_footer,.banner_ad_leaderboard,.bannerad,.barkerAd,.base-ad-mpu,.base_ad,.bgnavad,.big-ads,.bigAd,.big_ad,.big_ads,.bigad,.bigad2,.billboard_ad,.block-ad,.block-adsense,.block_ad,.block_ad_sb_text,.block_ad_sponsored_links,.block_ad_sponsored_links-wrapper,.blocked-ads,.blog-ads-container,.blogAd,.blogAdvertisement,.blogBigAd,.blog_ad,.blogads,.body_ad,.body_sponsoredresults_bottom,.body_sponsoredresults_middle,.body_sponsoredresults_top,.bookseller-header-advt,.bottomAd,.bottomAds,.bottom_ad_block,.bottom_sponsor,.bottomad,.bottomrightrailAd,.bottomvidad,.box-ad,.box-ads,.boxAd,.box_ad,.box_advertisment_62_border,.box_content_ad,.box_content_ads,.boxad,.bps-ad-wrapper,.bps-advertisement,.bps-advertisement-inline-ads,.bullet-sponsored-links,.bullet-sponsored-links-gray,.burstContentAdIndex,.buttonAd,.buttonAds,.buttonadbox,.bx_ad,.bx_ad_right,.cA-adStrap,.cColumn-TextAdsBox,.care2_adspace,.cb-ad-container,.cb_footer_sponsor,.cb_navigation_ad,.cbstv_ad_label,.cbzadvert,.cdAdTitle,.cdmainlineSearchAdParent,.cdsidebarSearchAdParent,.centerAd,.center_ad,.centerad,.clearerad,.cm_ads,.cms-Advert,.cnn160AdFooter,.cnnAd,.cnnMosaic160Container,.cnnStoreAd,.cnnStoryElementBoxAd,.cnnWCAdBox,.cnnWireAdLtgBox,.cnn_728adbin,.cnn_adcntr300x100,.cnn_adspc336cntr,.cnn_adtitle,.column2-ad,.conductor_ad,.confirm_ad_left,.confirm_ad_right,.confirm_leader_ad,.consoleAd,.container-adwords,.containerSqAd,.container_serendipity_plugin_google_adsense,.contentAd,.content_ad,.content_adsq,.contentad,.contenttextad,.contest_ad,.cp_ad,.cpmstarHeadline,.cpmstarText,.cs-mpu,.cspAd,.ct_ad,.cubeAd,.cube_ads,.currency_ad,.darla_ad,.dartAdImage,.dart_ad,.dart_tag,.dartadvert,.dartiframe,.dc-ad,.dcAdvertHeader,.deckAd,.deckads,.detail-ads,.detailMpu,.divAd,.divads,.divider_ad,.dmco_advert_iabrighttitle,.download_ad,.downloadad,.dynamic_ad,.e-ad,.ec-ads,.entryad,.ez-clientAd,.f_Ads,.featuredAds,.featuredadvertising,.flagads,.flash_advert,.flashad,.flexiad,.flipbook_v2_sponsor_ad,.footerAd,.footerAdModule,.footerTextAd,.footer_ad,.footer_ads,.footer_block_ad,.footer_line_ad,.footerad,.ft-ad,.ftdContentAd,.full_ad_box,.fullbannerad,.g3rtn-ad-site,.g_ggl_ad,.ga-textads-bottom,.ga-textads-top,.gads_cb,.gglAds,.googads,.google-ad-container,.google-ads,.google-ads-boxout,.google-ads-slim,.google-right-ad,.google-sponsored-ads,.google468_60,.googleAd,.googleAd-content,.googleAd-list,.googleAdBox,.googleAdSense,.googleAd_body,.googleAds,.googleAds_article_page_above_comments,.googleAdsense,.googleProfileAd,.google_ads_bom_title,.googlead,.googleaddiv,.googleaddiv2,.googleads,.googleads_300x250,.googleads_title,.gpAds,.gradientAd,.gsfAd,.gt_ad,.gt_ad_300x250,.gt_ad_728x90,.gt_adlabel,.gutter-ad-left,.gutter-ad-right,.h_Ads,.h_ad,.hd_advert,.header-ad,.header-advert,.headerAd,.headerAds,.headerAdvert,.header_ad,.header_ad_center,.header_advertisment,.hi5-ad,.highlightsAd,.hm_advertisment,.home-ad-links,.homeAd,.homeMediumAdGroup,.home_ad_bottom,.homead,.homepage-ad,.homepageFlexAdOuter,.homepageMPU,.hor_ad,.horiz_adspace,.horizontalAd,.horizontal_ad,.hortad,.houseAdsStyle,.hp2-adtag,.hp_ad_cont,.hp_ad_text,.hp_t_ad,.hp_w_ad,.ic-ads,.ico-adv,.idMultiAd,.image-advertisement,.imageads,.in-page-ad,.in-story-text-ad,.indy_googleads,.inline-mpu-left,.inlineSideAd,.inline_ad_title,.inlinead,.inlist-ad,.inner-advt-banner-3,.innerAds,.innerad,.inpostad,.is24-adplace,.islandAd,.islandAdvert,.islandad,.jp-advertisment-promotional,.js-advert,.kw_advert,.kw_advert_pair,.l_ad_sub,.l_banner.ads_show_if,.largeRectangleAd,.leader_ad,.leaderboardAd,.leaderboardad,.left-ad,.leftAd,.left_ads,.leftad,.leftbar_ad_160_600,.leftnavad,.lgRecAd,.lg_ad,.linead,.link_advertise,.live-search-list-ad-container,.log_ads,.lowerAds,.m4-adsbygoogle,.m_banner_ads,.macAd,.macad,.main-ad,.main-tabs-ad-block,.main_ad,.main_adbox,.map_media_banner_ad,.marginadsthin,.marketing-ad,.mdl-ad,.media-advert,.mediaAd,.mediaAdContainer,.medium-rectangle-ad,.menuItemBannerAd,.messageBoardAd,.micro_ad,.mid_ad,.midad,.min_navi_ad,.miniad,.mobile-sponsoring,.mod-ad-lrec,.mod-ad-n,.mod-adopenx,.mod_admodule,.module-ad-small,.module-ads,.moduleAdvertContent,.modulegad,.moduletable-advert,.moduletablesquaread,.mpu,.mpu-ad,.mpu-footer,.mpu-fp,.mpu-title,.mpu-top-left,.mpu-top-right,.mpuAd,.mpuBox,.mpuContainer,.mpuTextAd,.mpu_ad,.mpu_gold,.mpu_holder,.mpu_platinum,.mpu_text_ad,.mpuad,.mpuholderportalpage,.mrec_advert,.ms-ads-link,.msfg-shopping-mpu,.mwaads,.nSponsoredLcContent,.nSponsoredLcTopic,.nadvt300,.narrow_ad_unit,.narrow_ads,.naviad,.nba300Ad,.nbaT3Ad160,.nbaTVPodAd,.nbaTwo130Ads,.nbc_ad_carousel_wrp,.newTopAdContainer,.newad,.nf-adbox,.nn-mpu,.noAdForLead,.normalAds,.nrAds,.oas-bottom-ads,.oio-banner-zone,.oio-link-sidebar,.oio-zone-position,.onethirdadholder,.openx,.openx-ad,.other_adv2,.ov_spns,.pageGoogleAd,.pageGoogleAdFlat,.pageLeaderAd,.pagead,.partnersTextLinks,.pencil_ad,.player_ad_box,.player_page_ad_box,.pnp_ad,.podSponsoredLink,.post-ad,.post_ad,.post_sponsor_unit,.postbit_adbit_register,.postbit_adcode,.prebodyads,.premium_ad_container,.promoAd,.promoAds,.promo_ad,.publication-ad,.publicidad,.puff-advertorials,.qa_ad_left,.quigo-ad,.qzvAdDiv,.r_ad_box,.rad_container,.rectad,.rectangleAd,.rectanglead,.redads_cont,.regularad,.relatedAds,.remads,.result_ad,.results_sponsor,.results_sponsor_right,.reviewMidAdvertAlign,.rght300x250,.rhads,.rhs-ad,.rhs-ads-panel,.right-ad,.right-ad-holder,.right-ad2,.right-ads2,.rightAd,.right_ad,.right_ad_text,.right_ads,.right_col_ad,.right_hand_advert_column,.rightad,.rightad_1,.rightad_2,.rightads,.rightadunit,.rightcol_boxad,.rightcoladvert,.rnav_ad,.rt_ad1_300x90,.rt_ad_300x250,.rt_ad_call,.savvyad_unit,.sb-ad-sq-bg,.sbAdUnitContainer,.sb_adsN,.sb_adsNv2,.sb_adsW,.sb_adsWv2,.scanAd,.scc_advert,.sci-ad-main,.sci-ad-sub,.search-results-ad,.search-sponsor,.search-sponsored,.searchAd,.searchSponsoredResultsBox,.search_column_results_sponsored,.search_results_sponsored_top,.section-sponsor,.section_mpu_wrapper,.selfServeAds,.sidbaread,.side-ad,.side-ads,.side_ad,.side_ad2,.sidead,.sideadsbox,.sideadvert,.sidebar-ad,.sidebar-text-ad,.sidebarAd,.sidebarAdUnit,.sidebarAdvert,.sidebar_ad,.sidebar_ad_300_250,.sidebar_box_ad,.sidebarad,.sidebarad_bottom,.sideheadnarrowad,.sideheadsponsorsad,.singleAd,.singleAdsContainer,.singlead,.sitesponsor,.skinAd,.skin_ad_638,.sky-ad,.skyAd,.skyAdd,.sky_ad,.skyad,.skyscraper-ad,.slideshow-ad,.slinks,.slpBigSlimAdUnit,.slpSquareAdUnit,.sm_ad,.smallSkyAd1,.smallSkyAd2,.small_ad,.small_ads,.smallad-left,.smallsponsorad,.specialAd175x90,.speedyads,.sphereAdContainer,.spl_ad,.spl_ad2,.spl_ad_plus,.splitAd,.spons-link,.sponslink,.sponsor-ad,.sponsor-links,.sponsorArea,.sponsorPost,.sponsorPostWrap,.sponsor_ad_area,.sponsor_line,.sponsor_links,.sponsoradtitle,.sponsorbox,.sponsored,.sponsored-chunk,.sponsored-editorial,.sponsored-links,.sponsored-links-holder,.sponsored-post,.sponsored-results,.sponsored-text,.sponsoredLinks,.sponsoredLinksHeader,.sponsored_ads,.sponsored_box,.sponsored_box_search,.sponsored_by,.sponsored_links,.sponsored_links_title_container,.sponsored_links_title_container_top,.sponsored_links_top,.sponsored_results,.sponsoredibbox,.sponsoredlinks,.sponsoredtextlink_container,.sponsoredtextlink_container_ovt,.sponsorlink,.sponsorlink2,.spotlightAd,.squareAd,.square_ad,.squared_ad,.ss-ad-mpu,.staticAd,.store-ads,.story_AD,.subad,.subcontent-ad,.supercommentad_left,.supercommentad_right,.supportAdItem,.surveyad,.t10ad,.tab_ad,.tab_ad_area,.tablebordersponsor,.tadsanzeige,.tadsbanner,.tadselement,.tallad,.tblTopAds,.tbl_ad,.teaser-sponsor,.teaserAdContainer,.teaser_adtiles,.text-ad-links,.text-g-advertisement,.text-g-group-short-rec-ad,.text-g-net-grp-google-ads-article-page,.textAd,.textAds,.text_ad,.text_ads,.textad,.textad_headline,.textadbox,.textads,.textadsfoot,.textlink-ads,.thisIsAd,.thisIsAnAd,.ticket-ad,.tileAds,.title-ad,.title_adbig,.tncms-region-ads,.toolad,.toolbar-ad,.top-ad,.top-ad-space,.top-ads,.top-menu-ads,.topAdWrap,.topAds,.topAdvertisement,.topBannerAd,.top_Ad,.top_ad,.top_ad_728_90,.top_ad_disclaimer,.top_ad_wrapper,.top_ads,.top_advert,.top_advertising_lb,.top_container_ad,.top_sponsor,.topad,.topadbox,.topads,.topadspot,.topcontentadvertisement,.topic_inad,.topstoriesad,.towerAd,.towerAdLeft,.towerAds,.tower_ad_disclaimer,.ts-ad_unit_bigbox,.ts-banner_ad,.ttlAdsensel,.tto-sponsored-element,.twoColumnAd,.twoadcoll,.twoadcolr,.tx_smartadserver_pi1,.txt-ads,.txtadvertise,.type_miniad,.type_promoads,.undertimyads,.usenext,.vertad,.videoAd,.videoBoxAd,.video_ad,.view-promo-mpu-right,.wide-ad,.wide-skyscraper-ad,.wideAdTable,.wide_ad_unit_top,.wide_ads,.wide_google_ads,.widget-ad,.widget-entry-ads-160,.wikia_ad_placeholder,.withAds,.wnMultiAd,.wp125ad,.wpn_ad_content,.wsSponsoredLinksRight,.wsTopSposoredLinks,.x03-adunit,.x04-adunit,.y-ads,.y-ads-wide,.y7-advertisement,.yahoo-sponsored,.yahoo_ads,.yan-sponsored,.ygrp-ad,.yrail_ad_wrap,.yrail_ads,.ysmsponsor,.ysponsor,a[href^="http://adserving.liveuniversenetwork.com/"],a[href^="http://latestdownloads.net/download.php?"],a[href^="http://secure.signup-page.com/"],a[href^="http://secure.signup-way.com/"],a[href^="http://www.FriendlyDuck.com/AF_"],a[href^="http://www.adbrite.com/mb/commerce/purchase_form.php?"],a[href^="http://www.friendlyduck.com/AF_"],a[href^="http://www.google.com/aclk?"],a[href^="http://www.liutilities.com/aff"],a[href^="http://www.my-dirty-hobby.com/?sub="],a[href^="http://www.ringtonematcher.com/"],#mbEnd[cellspacing="0"][style="padding: 0pt; white-space: nowrap;"],div#mclip_container:first-child:last-child,div#tads.c,table.ra[align="left"][width="30%"],table.ra[align="right"][width="30%"] { visibility:hidden !important; display:none !important; }</STYLE></HTML>
\ No newline at end of file diff --git a/doc/specs/draft-jones-json-web-token.htm b/doc/specs/draft-jones-json-web-token.htm new file mode 100644 index 0000000..ee9a73b --- /dev/null +++ b/doc/specs/draft-jones-json-web-token.htm @@ -0,0 +1,1597 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html lang="en"><head><title>JSON Web Token (JWT)</title> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<meta name="description" content="JSON Web Token (JWT)"> +<meta name="keywords" content="RFC, Request for Comments, I-D, Internet-Draft, Assertion, Claim, Simple Web Token, Security Token, SWT, JavaScript Object Notation, JSON, JSON Web Token, JWT, JSON Web Signature, JWS, JSON Web Encryption, JWE"> +<meta name="generator" content="xml2rfc v1.36 (http://xml.resource.org/)"> +<style type='text/css'><!-- + body { + font-family: verdana, charcoal, helvetica, arial, sans-serif; + font-size: small; color: #000; background-color: #FFF; + margin: 2em; + } + h1, h2, h3, h4, h5, h6 { + font-family: helvetica, monaco, "MS Sans Serif", arial, sans-serif; + font-weight: bold; font-style: normal; + } + h1 { color: #900; background-color: transparent; text-align: right; } + h3 { color: #333; background-color: transparent; } + + td.RFCbug { + font-size: x-small; text-decoration: none; + width: 30px; height: 30px; padding-top: 2px; + text-align: justify; vertical-align: middle; + background-color: #000; + } + td.RFCbug span.RFC { + font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; + font-weight: bold; color: #666; + } + td.RFCbug span.hotText { + font-family: charcoal, monaco, geneva, "MS Sans Serif", helvetica, verdana, sans-serif; + font-weight: normal; text-align: center; color: #FFF; + } + + table.TOCbug { width: 30px; height: 15px; } + td.TOCbug { + text-align: center; width: 30px; height: 15px; + color: #FFF; background-color: #900; + } + td.TOCbug a { + font-family: monaco, charcoal, geneva, "MS Sans Serif", helvetica, sans-serif; + font-weight: bold; font-size: x-small; text-decoration: none; + color: #FFF; background-color: transparent; + } + + td.header { + font-family: arial, helvetica, sans-serif; font-size: x-small; + vertical-align: top; width: 33%; + color: #FFF; background-color: #666; + } + td.author { font-weight: bold; font-size: x-small; margin-left: 4em; } + td.author-text { font-size: x-small; } + + /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */ + a.info { + /* This is the key. */ + position: relative; + z-index: 24; + text-decoration: none; + } + a.info:hover { + z-index: 25; + color: #FFF; background-color: #900; + } + a.info span { display: none; } + a.info:hover span.info { + /* The span will display just on :hover state. */ + display: block; + position: absolute; + font-size: smaller; + top: 2em; left: -5em; width: 15em; + padding: 2px; border: 1px solid #333; + color: #900; background-color: #EEE; + text-align: left; + } + + a { font-weight: bold; } + a:link { color: #900; background-color: transparent; } + a:visited { color: #633; background-color: transparent; } + a:active { color: #633; background-color: transparent; } + + p { margin-left: 2em; margin-right: 2em; } + p.copyright { font-size: x-small; } + p.toc { font-size: small; font-weight: bold; margin-left: 3em; } + table.toc { margin: 0 0 0 3em; padding: 0; border: 0; vertical-align: text-top; } + td.toc { font-size: small; font-weight: bold; vertical-align: text-top; } + + ol.text { margin-left: 2em; margin-right: 2em; } + ul.text { margin-left: 2em; margin-right: 2em; } + li { margin-left: 3em; } + + /* RFC-2629 <spanx>s and <artwork>s. */ + em { font-style: italic; } + strong { font-weight: bold; } + dfn { font-weight: bold; font-style: normal; } + cite { font-weight: normal; font-style: normal; } + tt { color: #036; } + tt, pre, pre dfn, pre em, pre cite, pre span { + font-family: "Courier New", Courier, monospace; font-size: small; + } + pre { + text-align: left; padding: 4px; + color: #000; background-color: #CCC; + } + pre dfn { color: #900; } + pre em { color: #66F; background-color: #FFC; font-weight: normal; } + pre .key { color: #33C; font-weight: bold; } + pre .id { color: #900; } + pre .str { color: #000; background-color: #CFF; } + pre .val { color: #066; } + pre .rep { color: #909; } + pre .oth { color: #000; background-color: #FCF; } + pre .err { background-color: #FCC; } + + /* RFC-2629 <texttable>s. */ + table.all, table.full, table.headers, table.none { + font-size: small; text-align: center; border-width: 2px; + vertical-align: top; border-collapse: collapse; + } + table.all, table.full { border-style: solid; border-color: black; } + table.headers, table.none { border-style: none; } + th { + font-weight: bold; border-color: black; + border-width: 2px 2px 3px 2px; + } + table.all th, table.full th { border-style: solid; } + table.headers th { border-style: none none solid none; } + table.none th { border-style: none; } + table.all td { + border-style: solid; border-color: #333; + border-width: 1px 2px; + } + table.full td, table.headers td, table.none td { border-style: none; } + + hr { height: 1px; } + hr.insert { + width: 80%; border-style: none; border-width: 0; + color: #CCC; background-color: #CCC; + } +--></style> +</head> +<body> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<table summary="layout" width="66%" border="0" cellpadding="0" cellspacing="0"><tr><td><table summary="layout" width="100%" border="0" cellpadding="2" cellspacing="1"> +<tr><td class="header">Network Working Group</td><td class="header">M. Jones</td></tr> +<tr><td class="header">Internet-Draft</td><td class="header">Microsoft</td></tr> +<tr><td class="header">Intended status: Standards Track</td><td class="header">D. Balfanz</td></tr> +<tr><td class="header">Expires: June 15, 2012</td><td class="header">Google</td></tr> +<tr><td class="header"> </td><td class="header">J. Bradley</td></tr> +<tr><td class="header"> </td><td class="header">independent</td></tr> +<tr><td class="header"> </td><td class="header">Y. Goland</td></tr> +<tr><td class="header"> </td><td class="header">Microsoft</td></tr> +<tr><td class="header"> </td><td class="header">J. Panzer</td></tr> +<tr><td class="header"> </td><td class="header">Google</td></tr> +<tr><td class="header"> </td><td class="header">N. Sakimura</td></tr> +<tr><td class="header"> </td><td class="header">Nomura Research Institute</td></tr> +<tr><td class="header"> </td><td class="header">P. Tarjan</td></tr> +<tr><td class="header"> </td><td class="header">Facebook</td></tr> +<tr><td class="header"> </td><td class="header">December 13, 2011</td></tr> +</table></td></tr></table> +<h1><br />JSON Web Token (JWT)<br />draft-jones-json-web-token-07</h1> + +<h3>Abstract</h3> + +<p> + JSON Web Token (JWT) is a means of representing claims to be + transferred between two parties. The claims in a JWT are + encoded as a JSON object that is digitally signed using JSON + Web Signature (JWS) and/or encrypted using JSON Web Encryption + (JWE). + +</p> +<p> + The suggested pronunciation of JWT is the same as the English + word "jot". + +</p> +<h3>Requirements Language</h3> + +<p> + 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 <a class='info' href='#RFC2119'>RFC 2119<span> (</span><span class='info'>Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.</span><span>)</span></a> [RFC2119]. + +</p> +<h3>Status of this Memo</h3> +<p> +This Internet-Draft is submitted in full +conformance with the provisions of BCP 78 and BCP 79.</p> +<p> +Internet-Drafts are working documents of the Internet Engineering +Task Force (IETF). Note that other groups may also distribute +working documents as Internet-Drafts. The list of current +Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</p> +<p> +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.”</p> +<p> +This Internet-Draft will expire on June 15, 2012.</p> + +<h3>Copyright Notice</h3> +<p> +Copyright (c) 2011 IETF Trust and the persons identified as the +document authors. All rights reserved.</p> +<p> +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.</p> +<a name="toc"></a><br /><hr /> +<h3>Table of Contents</h3> +<p class="toc"> +<a href="#anchor1">1.</a> +Introduction<br /> +<a href="#anchor2">2.</a> +Terminology<br /> +<a href="#anchor3">3.</a> +JSON Web Token (JWT) Overview<br /> + <a href="#ExampleJWT">3.1.</a> +Example JWT<br /> +<a href="#anchor4">4.</a> +JWT Claims<br /> + <a href="#ReservedClaimName">4.1.</a> +Reserved Claim Names<br /> + <a href="#PublicClaimName">4.2.</a> +Public Claim Names<br /> + <a href="#PrivateClaimName">4.3.</a> +Private Claim Names<br /> +<a href="#anchor5">5.</a> +JWT Header<br /> +<a href="#Plaintext">6.</a> +Plaintext JWTs<br /> + <a href="#ExamplePlaintextJWT">6.1.</a> +Example Plaintext JWT<br /> +<a href="#anchor6">7.</a> +Rules for Creating and Validating a JWT<br /> +<a href="#Algorithms">8.</a> +Cryptographic Algorithms<br /> +<a href="#IANA">9.</a> +IANA Considerations<br /> +<a href="#Security">10.</a> +Security Considerations<br /> + <a href="#anchor7">10.1.</a> +Unicode Comparison Security Issues<br /> +<a href="#TBD">11.</a> +Open Issues and Things To Be Done (TBD)<br /> +<a href="#rfc.references1">12.</a> +References<br /> + <a href="#rfc.references1">12.1.</a> +Normative References<br /> + <a href="#rfc.references2">12.2.</a> +Informative References<br /> +<a href="#anchor10">Appendix A.</a> +Relationship of JWTs to SAML Tokens<br /> +<a href="#anchor11">Appendix B.</a> +Relationship of JWTs to Simple Web Tokens (SWTs)<br /> +<a href="#Acknowledgements">Appendix C.</a> +Acknowledgements<br /> +<a href="#anchor12">Appendix D.</a> +Document History<br /> +<a href="#rfc.authors">§</a> +Authors' Addresses<br /> +</p> +<br clear="all" /> + +<a name="anchor1"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.1"></a><h3>1. +Introduction</h3> + +<p> + JSON Web Token (JWT) is a compact token format intended for + space constrained environments such as HTTP Authorization + headers and URI query parameters. JWTs encode claims to be + transmitted as a JSON object (as defined in <a class='info' href='#RFC4627'>RFC 4627<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627]) that is base64url encoded + and digitally signed and/or encrypted. Signing is + accomplished using JSON Web Signature (JWS) <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a>. Encryption is accomplished using JSON Web Encryption + (JWE) <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.</span><span>)</span></a>. + +</p> +<p> + The suggested pronunciation of JWT is the same as the English + word "jot". + +</p> +<a name="anchor2"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.2"></a><h3>2. +Terminology</h3> + +<p> + </p> +<blockquote class="text"><dl> +<dt>JSON Web Token (JWT)</dt> +<dd> + A string consisting of three parts: the Encoded JWT Header, the + JWT Second Part, and the JWT Third Part, in that order, + with the parts being separated by period ('.') characters, + and each part containing base64url encoded content. + +</dd> +<dt>JWT Header</dt> +<dd> + A string representing a JSON object that + describes the cryptographic operations applied to the JWT. + When the JWT is signed, the JWT Header is the JWS Header. + When the JWT is encrypted, the JWT Header is the JWE Header. + +</dd> +<dt>Header Parameter Names</dt> +<dd> + The names of the members within the JWT Header. + +</dd> +<dt>Header Parameter Values</dt> +<dd> + The values of the members within the JWT Header. + +</dd> +<dt>JWT Second Part</dt> +<dd> + When the JWT is signed, the JWT Second Part is the Encoded JWS Payload. + When the JWT is encrypted, the JWT Second Part is the Encoded JWE Encrypted Key. + +</dd> +<dt>JWT Third Part</dt> +<dd> + When the JWT is signed, the JWT Third Part is the Encoded JWS Signature. + When the JWT is encrypted, the JWT Third Part is the Encoded JWE Ciphertext. + +</dd> +<dt>JWT Claims Set</dt> +<dd> + A string representing a JSON object that + contains the claims conveyed by the JWT. + When the JWT is signed, the bytes of the UTF-8 representation of the + JWT Claims Set are base64url encoded to create the Encoded JWS Payload. + When the JWT is encrypted, the bytes of the UTF-8 representation of the + JWT Claims Set are used as the JWE Plaintext. + +</dd> +<dt>Claim Names</dt> +<dd> + The names of the members of the JSON object represented by + the JWT Claims Set. + +</dd> +<dt>Claim Values</dt> +<dd> + The values of the members of the JSON object represented by + the JWT Claims Set. + +</dd> +<dt>Encoded JWT Header</dt> +<dd> + Base64url encoding of the bytes of the + UTF-8 <a class='info' href='#RFC3629'>RFC 3629<span> (</span><span class='info'>Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.</span><span>)</span></a> [RFC3629] + representation of the JWT Header. + +</dd> +<dt>Base64url Encoding</dt> +<dd> + For the purposes of this specification, this term always + refers to the URL- and filename-safe Base64 encoding + described in <a class='info' href='#RFC4648'>RFC 4648<span> (</span><span class='info'>Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.</span><span>)</span></a> [RFC4648], + Section 5, with the (non URL-safe) '=' padding characters + omitted, as permitted by Section 3.2. (See Appendix C of + <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a> for notes on implementing base64url + encoding without padding.) + +</dd> +</dl></blockquote><p> + +</p> +<a name="anchor3"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3"></a><h3>3. +JSON Web Token (JWT) Overview</h3> + +<p> + JWTs represent a set of claims as a JSON object that is + base64url encoded and digitally signed and/or + encrypted. The JWT Claims Set represents this JSON object. + As per <a class='info' href='#RFC4627'>RFC 4627<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627] + Section 2.2, the JSON object consists of zero or more + name/value pairs (or members), where the names are strings and + the values are arbitrary JSON values. These members are the + claims represented by the JWT. + +</p> +<p> + The member names within the JWT Claims Set are + referred to as Claim Names. The + corresponding values are referred to as Claim Values. + +</p> +<p> + The bytes of the UTF-8 representation of the JWT Claims Set + are signed in the manner described in JSON Web Signature (JWS) + <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a> and/or encrypted in the manner described + in JSON Web Encryption (JWE) <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.</span><span>)</span></a>. + +</p> +<p> + The contents of the JWT Header describe the cryptographic + operations applied to the JWT Claims Set. + If the JWT Header is a JWS Header, the claims are signed. + If the JWT Header is a JWE Header, the claims are encrypted. + +</p> +<p> + A JWT is represented as the concatenation of the Encoded JWT Header, + the JWT Second Part, and the JWT Third Part, in that order, + with the parts being separated by period ('.') characters. + When signed, the three parts of the JWT are the three parts of + a JWS used to represent the JWT. When encrypted, the three + parts of the JWT are the three parts of a JWE used to + represent the JWT. + +</p> +<a name="ExampleJWT"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.3.1"></a><h3>3.1. +Example JWT</h3> + +<p> + The following example JWT Header declares that the + encoded object is a JSON Web Token (JWT) and the JWT is + signed using the HMAC SHA-256 algorithm: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{"typ":"JWT", + "alg":"HS256"}</pre></div> +<p> + Base64url encoding the bytes of the UTF-8 representation of + the JWT Header yields this Encoded JWS Header value, + which is used as the Encoded JWT Header: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9</pre></div> +<p> + The following is an example of a JWT Claims Set: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{"iss":"joe", + "exp":1300819380, + "http://example.com/is_root":true}</pre></div> +<p> + Base64url encoding the bytes of the UTF-8 representation of + the JSON Claims Set yields this Encoded JWS Payload, + which is used as the JWT Second Part + (with line breaks for display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly +9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ</pre></div> +<p> + Signing the Encoded JWS Header and Encoded JWS Payload with + the HMAC SHA-256 algorithm and base64url encoding the + signature in the manner specified in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a>, + yields this Encoded JWS Signature, which is used as the JWT + Third Part: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk</pre></div> +<p> + Concatenating these parts in the order + Header.Second.Third with period characters between the + parts yields this complete JWT (with line breaks for + display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 +. +eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt +cGxlLmNvbS9pc19yb290Ijp0cnVlfQ +. +dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk</pre></div> +<p> + This computation is illustrated in more detail in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a>, Appendix A.1. + +</p> +<a name="anchor4"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4"></a><h3>4. +JWT Claims</h3> + +<p> + The JWT Claims Set represents a JSON object whose members + are the claims conveyed by the JWT. + The Claim Names within this object MUST be unique. + Note however, that the set of claims that a + JWT must contain to be considered valid is context-dependent + and is outside the scope of this specification. When used in + a security-related context, implementations MUST understand + and support all of the claims present; otherwise, the JWT MUST + be rejected for processing. + +</p> +<p> + There are three classes of JWT Claim Names: Reserved Claim + Names, Public Claim Names, and Private Claim Names. + +</p> +<a name="ReservedClaimName"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4.1"></a><h3>4.1. +Reserved Claim Names</h3> + +<p> + The following claim names are reserved. None of the claims + defined in the table below are intended to be mandatory, but + rather, provide a starting point for a set of useful, + interoperable claims. All the names are short because a + core goal of JWTs is for the tokens to be compact. + +</p><br /><hr class="insert" /> +<a name="ClaimTable"></a> +<table class="full" align="center" border="0" cellpadding="2" cellspacing="2"> +<col align="left"><col align="left"><col align="left"><col align="left"> +<tr><th align="left">Claim Name</th><th align="left">JSON Value Type</th><th align="left">Claim Syntax</th><th align="left">Claim Semantics</th></tr> +<tr> +<td align="left">exp</td> +<td align="left">number</td> +<td align="left">IntDate</td> +<td align="left"> + The <tt>exp</tt> (expiration time) + claim identifies the expiration time on or after which the + token MUST NOT be accepted for processing. The processing + of the <tt>exp</tt> claim requires that + the current date/time MUST be before the expiration + date/time listed in the <tt>exp</tt> + claim. Implementers MAY provide for some small leeway, + usually no more than a few minutes, to account for clock + skew. This claim is OPTIONAL. + </td> +</tr> +<tr> +<td align="left">nbf</td> +<td align="left">number</td> +<td align="left">IntDate</td> +<td align="left"> + The <tt>nbf</tt> (not before) claim + identifies the time before which the token MUST NOT be + accepted for processing. The processing of the <tt>nbf</tt> claim requires that the current + date/time MUST be after or equal to the not-before + date/time listed in the <tt>nbf</tt> + claim. Implementers MAY provide for some small leeway, + usually no more than a few minutes, to account for clock + skew. This claim is OPTIONAL. + </td> +</tr> +<tr> +<td align="left">iat</td> +<td align="left">number</td> +<td align="left">IntDate</td> +<td align="left"> + The <tt>iat</tt> (issued at) claim + identifies the time at which the JWT was issued. This + claim can be used to determine the age of the token. + This claim is OPTIONAL. + </td> +</tr> +<tr> +<td align="left">iss</td> +<td align="left">string</td> +<td align="left">StringOrURI</td> +<td align="left"> + The <tt>iss</tt> (issuer) claim + identifies the principal that issued the JWT. The + processing of this claim is generally application + specific. + The <tt>iss</tt> value is case sensitive. + This claim is OPTIONAL. + </td> +</tr> +<tr> +<td align="left">aud</td> +<td align="left">string</td> +<td align="left">StringOrURI</td> +<td align="left"> + The <tt>aud</tt> (audience) claim + identifies the audience that the JWT is intended for. The + principal intended to process the JWT MUST be identified + with the value of the audience claim. If the principal + processing the claim does not identify itself with the + identifier in the <tt>aud</tt> claim + value then the JWT MUST be rejected. The interpretation + of the audience value is generally + application specific. + The <tt>aud</tt> value is case sensitive. + This claim is OPTIONAL. + </td> +</tr> +<tr> +<td align="left">prn</td> +<td align="left">string</td> +<td align="left">StringOrURI</td> +<td align="left"> + The <tt>prn</tt> (principal) claim + identifies the subject of the JWT. The processing of this + claim is generally application specific. + The <tt>prn</tt> value is case sensitive. + This claim is OPTIONAL. + </td> +</tr> +<tr> +<td align="left">jti</td> +<td align="left">string</td> +<td align="left">String</td> +<td align="left"> + The <tt>jti</tt> (JWT ID) claim + provides a unique identifier for the JWT. The identifier + value MUST be assigned in a manner that ensures that there + is a negligible probability that the same value will be + accidentally assigned to a different data object. The + <tt>jti</tt> claim can be used to + prevent the JWT from being replayed. + The <tt>jti</tt> value is case sensitive. + This claim is OPTIONAL. + </td> +</tr> +<tr> +<td align="left">typ</td> +<td align="left">string</td> +<td align="left">String</td> +<td align="left"> + The <tt>typ</tt> (type) claim is used + to declare a type for the contents of this JWT Claims Set. + The <tt>typ</tt> value is case sensitive. + This claim is OPTIONAL. + </td> +</tr> +</table> +<br clear="all" /> +<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Table 1: Reserved Claim Definitions </b></font><br /></td></tr></table><hr class="insert" /> + +<p> + Additional reserved claim names MAY be defined via the IANA + JSON Web Token Claims registry, as per <a class='info' href='#IANA'>Section 9<span> (</span><span class='info'>IANA Considerations</span><span>)</span></a>. The syntax values used above are defined as follows: + +</p><br /><hr class="insert" /> +<a name="SyntaxDefinitions"></a> +<table class="full" align="center" border="0" cellpadding="2" cellspacing="2"> +<col align="left"><col align="left"> +<tr><th align="left">Syntax Name</th><th align="left">Syntax Definition</th></tr> +<tr> +<td align="left">IntDate</td> +<td align="left"> + The number of seconds from 1970-01-01T0:0:0Z as measured + in UTC until the desired date/time. See <a class='info' href='#RFC3339'>RFC 3339<span> (</span><span class='info'>Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.</span><span>)</span></a> [RFC3339] for details regarding + date/times in general and UTC in particular. + </td> +</tr> +<tr> +<td align="left">String</td> +<td align="left"> + Any string value MAY be used. + </td> +</tr> +<tr> +<td align="left">StringOrURI</td> +<td align="left"> + Any string value MAY be used but a value containing a ":" + character MUST be a URI as defined in <a class='info' href='#RFC3986'>RFC 3986<span> (</span><span class='info'>Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.</span><span>)</span></a> [RFC3986]. + </td> +</tr> +</table> +<br clear="all" /> +<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Table 2: Claim Syntax Definitions </b></font><br /></td></tr></table><hr class="insert" /> + +<a name="PublicClaimName"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4.2"></a><h3>4.2. +Public Claim Names</h3> + +<p> + Claim names can be defined at will by those using + JWTs. However, in order to prevent collisions, any new claim + name SHOULD either be defined in the IANA JSON Web Token + Claims registry or be defined as a URI that contains a + collision resistant namespace. Examples of collision + resistant namespaces include: + + </p> +<ul class="text"> +<li> + Domain Names, + +</li> +<li> + Object Identifiers (OIDs) as defined in the ITU-T X.660 + and X.670 Recommendation series, or + +</li> +<li> + Universally Unique IDentifier (UUID) as defined in <a class='info' href='#RFC4122'>RFC 4122<span> (</span><span class='info'>Leach, P., Mealling, M., and R. Salz, “A Universally Unique IDentifier (UUID) URN Namespace,” July 2005.</span><span>)</span></a> [RFC4122]. + +</li> +</ul><p> + + In each case, the definer of the name or value needs to take + reasonable precautions to make sure they are in control of + the part of the namespace they use to define the claim + name. +</p> +<a name="PrivateClaimName"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.4.3"></a><h3>4.3. +Private Claim Names</h3> + +<p> + A producer and consumer of a JWT may agree to any claim + name that is not a Reserved Name <a class='info' href='#ReservedClaimName'>Section 4.1<span> (</span><span class='info'>Reserved Claim Names</span><span>)</span></a> or a Public Name <a class='info' href='#PublicClaimName'>Section 4.2<span> (</span><span class='info'>Public Claim Names</span><span>)</span></a>. Unlike Public Names, + these private names are subject to collision and should be + used with caution. + +</p> +<a name="anchor5"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.5"></a><h3>5. +JWT Header</h3> + +<p> + The members of the JSON object represented by the JWT Header + describe the cryptographic operations applied to the JWT and + optionally, additional properties of the JWT. + The member names within the JWT Header are + referred to as Header Parameter Names. These names MUST be + unique. The corresponding values are referred to as Header + Parameter Values. + +</p> +<p> + Implementations MUST understand the entire contents of the + header; otherwise, the JWT MUST be rejected for processing. + +</p> +<p> + There are two ways of distinguishing whether the JWT is a JWS + or JWE. The first is by examining the <tt>alg</tt> (algorithm) header value. If the + value represents a signature algorithm, the JWT is a JWS; if + it represents an encryption algorithm, the JWT is a JWE. A + second method is determining whether an <tt>enc</tt> (encryption method) member exists. + If the <tt>enc</tt> member exists, the JWT + is a JWE; otherwise, the JWT is a JWS. Both methods will + yield the same result. + +</p> +<p> + JWS Header Parameters are defined by <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a>. + JWE Header Parameters are defined by <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.</span><span>)</span></a>. + This specification further specifies the use of the following + header parameters in both the cases where the JWT is a JWS and + where it is a JWE. + +</p><br /><hr class="insert" /> +<a name="HeaderParameterTable"></a> +<table class="full" align="center" border="0" cellpadding="2" cellspacing="2"> +<col align="left"><col align="left"><col align="left"><col align="left"> +<tr><th align="left">Header Parameter Name</th><th align="left">JSON Value Type</th><th align="left">Header Parameter Syntax</th><th align="left">Header Parameter Semantics</th></tr> +<tr> +<td align="left">typ</td> +<td align="left">string</td> +<td align="left">String</td> +<td align="left"> + The <tt>typ</tt> (type) header parameter + is used to declare structural information about the JWT. + In the normal case where nested signing or encryption + operations are not employed, the use of this header + parameter is OPTIONAL, and if present, it is RECOMMENDED that + its value be either "JWT" or + "http://openid.net/specs/jwt/1.0". + In the case that nested signing or encryption steps are + employed, the use of this header parameter is REQUIRED; in + this case, the value MUST either be "JWS", to indicate that + a nested signed JWT is carried in this JWT or "JWE", to + indicate that a nested encrypted JWT is carried in this JWT. + </td> +</tr> +</table> +<br clear="all" /> +<table border="0" cellpadding="0" cellspacing="2" align="center"><tr><td align="center"><font face="monaco, MS Sans Serif" size="1"><b> Table 3: Reserved Header Parameter Usage </b></font><br /></td></tr></table><hr class="insert" /> + +<a name="Plaintext"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6"></a><h3>6. +Plaintext JWTs</h3> + +<p> + To support use cases where the JWT content is secured by a + means other than a signature and/or encryption contained + within the token (such as a signature on a data structure + containing the token), JWTs MAY also be created without a + signature or encryption. Plaintext JWTs MUST use the <tt>alg</tt> value <tt>none</tt>, and are formatted identically to a + signed JWT with an empty signature. This means that the + base64url encoding of the bytes representing the UTF-8 + encoding of the JWT Claims Set is the JWT Second Part, and + the empty string is the JWT Third Part. + +</p> +<a name="ExamplePlaintextJWT"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.6.1"></a><h3>6.1. +Example Plaintext JWT</h3> + +<p> + The following example JWT Header declares that the + encoded object is a Plaintext JWT: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{"alg":"none"}</pre></div> +<p> + Base64url encoding the bytes of the UTF-8 representation of + the JWT Header yields this Encoded JWT Header: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJhbGciOiJub25lIn0</pre></div> +<p> + The following is an example of a JWT Claims Set: + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>{"iss":"joe", + "exp":1300819380, + "http://example.com/is_root":true}</pre></div> +<p> + Base64url encoding the bytes of the UTF-8 representation of + the JSON Claims Set yields this Encoded JWS Payload, + which is used as the JWT Second Part + (with line breaks for display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt +cGxlLmNvbS9pc19yb290Ijp0cnVlfQ</pre></div> +<p> + The JWT Third Part is the empty string. + +</p> +<p> + Concatenating these parts in the order + Header.Second.Third with period characters between the + parts yields this complete JWT (with line breaks for + display purposes only): + +</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>eyJhbGciOiJub25lIn0 +. +eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt +cGxlLmNvbS9pc19yb290Ijp0cnVlfQ +. +</pre></div> +<a name="anchor6"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.7"></a><h3>7. +Rules for Creating and Validating a JWT</h3> + +<p> + To create a JWT, one MUST perform these steps: + + </p> +<ol class="text"> +<li> + Create a JWT Claims Set containing the desired claims. + Note that white space is explicitly allowed in the + representation and no canonicalization is performed before + encoding. + +</li> +<li> + Let the Message be the bytes of the UTF-8 representation + of the JWT Claims Set. + +</li> +<li> + Create a JWT Header containing the desired set of header + parameters. If the JWT is to be signed or encrypted, they + MUST conform to either the <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a> or <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.</span><span>)</span></a> specifications, respectively. Else, if + the JWT is to be plaintext, the <tt>alg</tt> value <tt>none</tt> MUST be used. Note that white + space is explicitly allowed in the representation and no + canonicalization is performed before encoding. + +</li> +<li> + Base64url encode the bytes of the UTF-8 representation of + the JWT Header. Let this be the Encoded JWT Header. + +</li> +<li> + Depending upon whether the JWT is to be signed, encrypted, + or plaintext, there are three cases: + +<ul class="text"> +<li> + If the JWT is to be signed, create a JWS using the JWT + Header as the JWS Header and the Message as the JWS + Payload; all steps specified in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a> + for creating a JWS MUST be followed. + Let the JWT Second Part be the Encoded JWS Payload and + let the JWT Third Part be the Encoded JWS Signature. + +</li> +<li> + If the JWT is to be encrypted, create a JWE using the + JWT Header as the JWE Header and the Message as the + JWE Plaintext; all steps specified in <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.</span><span>)</span></a> for creating a JWE MUST be followed. + Let the JWT Second Part be the Encoded JWE Encrypted + Key and let the JWT Third Part be the Encoded JWS + Ciphertext. + +</li> +<li> + Else, if the JWT is to be plaintext, let the JWT + Second Part be the base64url encoding of the Message + and let the JWT Third Part be the empty string. + +</li> +</ul> + +</li> +<li> + Concatenate the Encoded JWT Header, the JWT Second Part, + and the JWT Third Part in that order, separating each by + period ('.') characters. + +</li> +<li> + If a nested signing or encryption operation will be + performed, let the Message be this concatenation, and + return to Step 3, using a <tt>typ</tt> + value of either "JWS" or "JWE" respectively in the + new JWT Header created in that step. + +</li> +<li> + Otherwise, let the resulting JWT be this concatenation. + +</li> +</ol><p> + +</p> +<p> + When validating a JWT the following steps MUST be taken. If + any of the listed steps fails then the token MUST be rejected + for processing. + +</p> +<p> + </p> +<ol class="text"> +<li> + The JWT MUST contain exactly two period characters. + +</li> +<li> + The JWT MUST be split on the two period characters + resulting in three strings. The first string is the + Encoded JWT Header; the second is the JWT Second Part; the + third is the JWT Third Part. + +</li> +<li> + The Encoded JWT Header MUST be successfully base64url + decoded following the restriction given in this + specification that no padding characters have been used. + +</li> +<li> + The JWT Header MUST be completely valid JSON syntax + conforming to <a class='info' href='#RFC4627'>RFC 4627<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627]. + +</li> +<li> + The JWT Header MUST be validated to only include + parameters and values whose syntax and semantics are both + understood and supported. + +</li> +<li> + Determine whether the JWT is signed, encrypted, or + plaintext by examining the <tt>alg</tt> + (algorithm) header value and optionally, the <tt>enc</tt> (encryption method) header value, + if present. + +</li> +<li> + Depending upon whether the JWT signed, encrypted, + or plaintext, there are three cases: + +<ul class="text"> +<li> + If the JWT is signed, all steps specified in <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a> for validating a JWS MUST be followed. + Let the Message be the result of base64url decoding + the JWS Payload. + +</li> +<li> + If the JWT is encrypted, all steps specified in <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.</span><span>)</span></a> for validating a JWE MUST be followed. + Let the Message be the JWE Plaintext. + +</li> +<li> + Else, if the JWT is plaintext, let the Message be the + result of base64url decoding the JWE Second Part. The + Third Part MUST be verified to be the empty string. + +</li> +</ul> + +</li> +<li> + If the JWT Header contains a <tt>typ</tt> value of either "JWS" or "JWE", + then the Message contains a JWT that was the subject of + nested signing or encryption operations, respectively. In + this case, return to Step 1, using the Message as the JWT. + +</li> +<li> + Otherwise, let the JWT Claims Set be the Message. + +</li> +<li> + The JWT Claims Set MUST be completely valid + JSON syntax conforming to <a class='info' href='#RFC4627'>RFC + 4627<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627]. + +</li> +<li> + When used in a security-related context, the + JWT Claims Set MUST be validated to only include claims + whose syntax and semantics are both understood and + supported. + +</li> +</ol><p> + +</p> +<p> + Processing a JWT inevitably requires comparing known strings + to values in the token. For example, in checking what the + algorithm is, the Unicode string encoding <tt>alg</tt> will be + checked against the member names in the JWT Header + to see if there is a matching header parameter + name. A similar process occurs when determining if the value + of the <tt>alg</tt> header parameter represents a supported + algorithm. + +</p> +<p> + Comparisons between JSON strings and other Unicode strings + MUST be performed as specified below: + + </p> +<ol class="text"> +<li> + Remove any JSON applied escaping to produce an array of + Unicode code points. + +</li> +<li> + <a class='info' href='#USA15'>Unicode Normalization<span> (</span><span class='info'>Davis, M., Whistler, K., and M. Dürst, “Unicode Normalization Forms,” 09 2009.</span><span>)</span></a> [USA15] MUST NOT + be applied at any point to either the JSON string or to + the string it is to be compared against. + +</li> +<li> + Comparisons between the two strings MUST be performed as a + Unicode code point to code point equality comparison. + +</li> +</ol><p> + +</p> +<a name="Algorithms"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.8"></a><h3>8. +Cryptographic Algorithms</h3> + +<p> + JWTs use JSON Web Signature (JWS) <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a> and + JSON Web Encryption (JWE) <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.</span><span>)</span></a> to sign and/or + encrypt the contents of the JWT. + +</p> +<p> + Of the JWS signing algorithms, only HMAC SHA-256 MUST be + implemented by conforming JWT implementations. It is + RECOMMENDED that implementations also support the RSA SHA-256 + and ECDSA P-256 SHA-256 algorithms. Support for other + algorithms and key sizes is OPTIONAL. + +</p> +<p> + If an implementation provides encryption capabilities, + of the JWE encryption algorithms, only RSA-PKCS1-1.5 with 2048 bit keys, + AES-128-CBC, and AES-256-CBC MUST be implemented by conforming + implementations. It is RECOMMENDED that implementations also + support ECDH-ES with 256 bit keys, AES-128-GCM, and + AES-256-GCM. Support for other algorithms and key sizes is + OPTIONAL. + +</p> +<a name="IANA"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.9"></a><h3>9. +IANA Considerations</h3> + +<p> + This specification calls for: + + </p> +<ul class="text"> +<li> + A new IANA registry entitled "JSON Web Token Claims" for + reserved claim names is defined in <a class='info' href='#ReservedClaimName'>Section 4.1<span> (</span><span class='info'>Reserved Claim Names</span><span>)</span></a>. Inclusion in the + registry is RFC Required in the <a class='info' href='#RFC5226'>RFC + 5226<span> (</span><span class='info'>Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” May 2008.</span><span>)</span></a> [RFC5226] sense for reserved JWT claim names that are + intended to be interoperable between implementations. The + registry will just record the reserved claim name and a + pointer to the RFC that defines it. This specification + defines inclusion of the claim names defined in <a class='info' href='#ClaimTable'>Table 1<span> (</span><span class='info'>Reserved Claim Definitions</span><span>)</span></a>. + +</li> +</ul><p> + +</p> +<a name="Security"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.10"></a><h3>10. +Security Considerations</h3> + +<p> + TBD: Lots of work to do here. We need to remember to look into + any issues relating to security and JSON parsing. One wonders + just how secure most JSON parsing libraries are. Were they + ever hardened for security scenarios? If not, what kind of + holes does that open up? Also, we need to walk through the + JSON standard and see what kind of issues we have especially + around comparison of names. For instance, comparisons of + claim names and other parameters must occur after they are + unescaped. Need to also put in text about: Importance of + keeping secrets secret. Rotating keys. Strengths and + weaknesses of the different algorithms. + +</p> +<p> + TBD: Need to put in text about why strict JSON validation is + necessary. Basically, that if malformed JSON is received then + the intent of the sender is impossible to reliably discern. + One example of malformed JSON that MUST be rejected is + an object in which the same member name occurs multiple times. + While in non-security contexts it's o.k. to be + generous in what one accepts, in security contexts this can + lead to serious security holes. For example, malformed JSON + might indicate that someone has managed to find a security + hole in the issuer's code and is leveraging it to get the + issuer to issue "bad" tokens whose content the attacker can + control. + +</p> +<p> + TBD: Write about the need to secure the token content if a + signature is not contained in the JWT itself. + +</p> +<a name="anchor7"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.10.1"></a><h3>10.1. +Unicode Comparison Security Issues</h3> + +<p> + Claim names in JWTs are Unicode strings. For security + reasons, the representations of these names must be compared + verbatim after performing any escape processing (as per + <a class='info' href='#RFC4627'>RFC 4627<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627], Section 2.5). + +</p> +<p> + This means, for instance, that these JSON strings must + compare as being equal ("JWT", "\u004aWT"), whereas these + must all compare as being not equal to the first set or to + each other ("jwt", "Jwt", "JW\u0074"). + +</p> +<p> + JSON strings MAY contain characters outside the Unicode + Basic Multilingual Plane. For instance, the G clef + character (U+1D11E) may be represented in a JSON string as + "\uD834\uDD1E". Ideally, JWT implementations SHOULD ensure + that characters outside the Basic Multilingual Plane are + preserved and compared correctly; alternatively, if this is + not possible due to these characters exercising limitations + present in the underlying JSON implementation, then input + containing them MUST be rejected. + +</p> +<a name="TBD"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.11"></a><h3>11. +Open Issues and Things To Be Done (TBD)</h3> + +<p> + The following items remain to be done in this draft: + + </p> +<ul class="text"> +<li> + Provide an example of an encrypted JWT. + +</li> +<li> + Clarify the optional ability to provide type information + for JWTs and/or their parts. Specifically, clarify + whether we need to specify the <tt>typ</tt> + Claim Name in addition to the Header Parameter, + whether it conveys syntax or semantics, and indeed, + whether this is the right approach. Also clarify the + relationship between these type values and <a class='info' href='#RFC2045'>MIME<span> (</span><span class='info'>Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” November 1996.</span><span>)</span></a> [RFC2045] types (if any). + +</li> +<li> + Think about how to best describe the concept currently + described as "the bytes of the UTF-8 representation of". + Possible terms to use instead of "bytes of" include "byte + sequence", "octet series", and "octet sequence". Also + consider whether we want to add an overall clarifying + statement somewhere in each spec something like "every + place we say 'the UTF-8 representation of X', we mean 'the + bytes of the UTF-8 representation of X'". That would + potentially allow us to omit the "the bytes of" part + everywhere else. + +</li> +<li> + Consider whether a media type should be proposed, such as + "application/jwt". + +</li> +<li> + Finish the Security Considerations section. + +</li> +<li> + Possibly write a companion specification that contains the former + JWT JSON Serialization. + +</li> +</ul><p> + +</p> +<a name="rfc.references"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.12"></a><h3>12. +References</h3> + +<a name="rfc.references1"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>12.1. Normative References</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><a name="JWS">[JWS]</a></td> +<td class="author-text"><a href="mailto:mbj@microsoft.com">Jones, M.</a>, <a href="mailto:balfanz@google.com">Balfanz, D.</a>, <a href="mailto:ve7jtb@ve7jtb.com">Bradley, J.</a>, <a href="mailto:yarong@microsoft.com">Goland, Y.</a>, <a href="mailto:jpanzer@google.com">Panzer, J.</a>, <a href="mailto:n-sakimura@nri.co.jp">Sakimura, N.</a>, and <a href="mailto:pt@fb.com">P. Tarjan</a>, “<a href="http://tools.ietf.org/html/draft-jones-json-web-signature">JSON Web Signature (JWS)</a>,” December 2011.</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2045">[RFC2045]</a></td> +<td class="author-text"><a href="mailto:ned@innosoft.com">Freed, N.</a> and <a href="mailto:nsb@nsb.fv.com">N. Borenstein</a>, “<a href="http://tools.ietf.org/html/rfc2045">Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</a>,” RFC 2045, November 1996 (<a href="http://www.rfc-editor.org/rfc/rfc2045.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td> +<td class="author-text"><a href="mailto:sob@harvard.edu">Bradner, S.</a>, “<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>,” BCP 14, RFC 2119, March 1997 (<a href="http://www.rfc-editor.org/rfc/rfc2119.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc2119.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc2119.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC3339">[RFC3339]</a></td> +<td class="author-text"><a href="mailto:GK@ACM.ORG">Klyne, G., Ed.</a> and <a href="mailto:chris.newman@sun.com">C. Newman</a>, “<a href="http://tools.ietf.org/html/rfc3339">Date and Time on the Internet: Timestamps</a>,” RFC 3339, July 2002 (<a href="http://www.rfc-editor.org/rfc/rfc3339.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc3339.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc3339.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC3629">[RFC3629]</a></td> +<td class="author-text">Yergeau, F., “<a href="http://tools.ietf.org/html/rfc3629">UTF-8, a transformation format of ISO 10646</a>,” STD 63, RFC 3629, November 2003 (<a href="http://www.rfc-editor.org/rfc/rfc3629.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC3986">[RFC3986]</a></td> +<td class="author-text"><a href="mailto:timbl@w3.org">Berners-Lee, T.</a>, <a href="mailto:fielding@gbiv.com">Fielding, R.</a>, and <a href="mailto:LMM@acm.org">L. Masinter</a>, “<a href="http://tools.ietf.org/html/rfc3986">Uniform Resource Identifier (URI): Generic Syntax</a>,” STD 66, RFC 3986, January 2005 (<a href="http://www.rfc-editor.org/rfc/rfc3986.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc3986.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc3986.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC4627">[RFC4627]</a></td> +<td class="author-text">Crockford, D., “<a href="http://tools.ietf.org/html/rfc4627">The application/json Media Type for JavaScript Object Notation (JSON)</a>,” RFC 4627, July 2006 (<a href="http://www.rfc-editor.org/rfc/rfc4627.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC4648">[RFC4648]</a></td> +<td class="author-text">Josefsson, S., “<a href="http://tools.ietf.org/html/rfc4648">The Base16, Base32, and Base64 Data Encodings</a>,” RFC 4648, October 2006 (<a href="http://www.rfc-editor.org/rfc/rfc4648.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC5226">[RFC5226]</a></td> +<td class="author-text">Narten, T. and H. Alvestrand, “<a href="http://tools.ietf.org/html/rfc5226">Guidelines for Writing an IANA Considerations Section in RFCs</a>,” BCP 26, RFC 5226, May 2008 (<a href="http://www.rfc-editor.org/rfc/rfc5226.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="USA15">[USA15]</a></td> +<td class="author-text"><a href="mailto:markdavis@google.com">Davis, M.</a>, <a href="mailto:ken@unicode.org">Whistler, K.</a>, and M. Dürst, “Unicode Normalization Forms,” Unicode Standard Annex 15, 09 2009.</td></tr> +</table> + +<a name="rfc.references2"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>12.2. Informative References</h3> +<table width="99%" border="0"> +<tr><td class="author-text" valign="top"><a name="CanvasApp">[CanvasApp]</a></td> +<td class="author-text">Facebook, “<a href="http://developers.facebook.com/docs/authentication/canvas">Canvas Applications</a>,” 2010.</td></tr> +<tr><td class="author-text" valign="top"><a name="JSS">[JSS]</a></td> +<td class="author-text">Bradley, J. and N. Sakimura (editor), “<a href="http://jsonenc.info/jss/1.0/">JSON Simple Sign</a>,” September 2010.</td></tr> +<tr><td class="author-text" valign="top"><a name="JWE">[JWE]</a></td> +<td class="author-text"><a href="mailto:mbj@microsoft.com">Jones, M.</a>, <a href="mailto:ekr@rtfm.com">Rescorla, E.</a>, and <a href="mailto:jhildebr@cisco.com">J. Hildebrand</a>, “<a href="http://tools.ietf.org/html/draft-jones-json-web-encryption">JSON Web Encryption (JWE)</a>,” December 2011.</td></tr> +<tr><td class="author-text" valign="top"><a name="MagicSignatures">[MagicSignatures]</a></td> +<td class="author-text">Panzer (editor), J., Laurie, B., and D. Balfanz, “<a href="http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-magicsig-experimental-00.html">Magic Signatures</a>,” August 2010.</td></tr> +<tr><td class="author-text" valign="top"><a name="OASIS.saml-core-2.0-os">[OASIS.saml-core-2.0-os]</a></td> +<td class="author-text"><a href="mailto:cantor.2@osu.edu">Cantor, S.</a>, <a href="mailto:John.Kemp@nokia.com">Kemp, J.</a>, <a href="mailto:rphilpott@rsasecurity.com">Philpott, R.</a>, and <a href="mailto:eve.maler@sun.com">E. Maler</a>, “<a href="http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf">Assertions and Protocol for the OASIS Security Assertion Markup Language + (SAML) V2.0</a>,” OASIS Standard saml-core-2.0-os, March 2005.</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC3275">[RFC3275]</a></td> +<td class="author-text">Eastlake, D., Reagle, J., and D. Solo, “<a href="http://tools.ietf.org/html/rfc3275">(Extensible Markup Language) XML-Signature Syntax and Processing</a>,” RFC 3275, March 2002 (<a href="http://www.rfc-editor.org/rfc/rfc3275.txt">TXT</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="RFC4122">[RFC4122]</a></td> +<td class="author-text"><a href="mailto:paulle@microsoft.com">Leach, P.</a>, <a href="mailto:michael@refactored-networks.com">Mealling, M.</a>, and <a href="mailto:rsalz@datapower.com">R. Salz</a>, “<a href="http://tools.ietf.org/html/rfc4122">A Universally Unique IDentifier (UUID) URN Namespace</a>,” RFC 4122, July 2005 (<a href="http://www.rfc-editor.org/rfc/rfc4122.txt">TXT</a>, <a href="http://xml.resource.org/public/rfc/html/rfc4122.html">HTML</a>, <a href="http://xml.resource.org/public/rfc/xml/rfc4122.xml">XML</a>).</td></tr> +<tr><td class="author-text" valign="top"><a name="SWT">[SWT]</a></td> +<td class="author-text">Hardt, D. and Y. Goland, “<a href="http://oauth-wrap-wg.googlegroups.com/web/SWT-v0.9.5.1.pdf?gda=Sn4MsEMAAABFB7PFAFiVedPtjcqT8uuIImHXUksNUKMXLyrSumAs_dF2tzlQ33RhT1wW8BFYO1QytiJ-HdGYYcPi_09pl8N7FWLveOaWjzbYnpnkpmxcWg">Simple Web Token (SWT)</a>,” Version 0.9.5.1, November 2009.</td></tr> +<tr><td class="author-text" valign="top"><a name="W3C.CR-xml11-20021015">[W3C.CR-xml11-20021015]</a></td> +<td class="author-text">Cowan, J., “<a href="http://www.w3.org/TR/2002/CR-xml11-20021015">Extensible Markup Language (XML) 1.1</a>,” W3C CR CR-xml11-20021015, October 2002.</td></tr> +</table> + +<a name="anchor10"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.A"></a><h3>Appendix A. +Relationship of JWTs to SAML Tokens</h3> + +<p> + <a class='info' href='#OASIS.saml-core-2.0-os'>SAML 2.0<span> (</span><span class='info'>Cantor, S., Kemp, J., Philpott, R., and E. Maler, “Assertions and Protocol for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.</span><span>)</span></a> [OASIS.saml‑core‑2.0‑os] provides + a standard for creating tokens with much greater expressivity + and more security options than supported by JWTs. However, the + cost of this flexibility and expressiveness is both size and + complexity. In addition, SAML's use of <a class='info' href='#W3C.CR-xml11-20021015'>XML<span> (</span><span class='info'>Cowan, J., “Extensible Markup Language (XML) 1.1,” October 2002.</span><span>)</span></a> [W3C.CR‑xml11‑20021015] and <a class='info' href='#RFC3275'>XML DSIG<span> (</span><span class='info'>Eastlake, D., Reagle, J., and D. Solo, “(Extensible Markup Language) XML-Signature Syntax and Processing,” March 2002.</span><span>)</span></a> [RFC3275] only contributes to the size + of SAML tokens. + +</p> +<p> + JWTs are intended to provide a simple token format that is + small enough to fit into HTTP headers and query arguments in + URIs. It does this by supporting a much simpler token model + than SAML and using the <a class='info' href='#RFC4627'>JSON<span> (</span><span class='info'>Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.</span><span>)</span></a> [RFC4627] + object encoding syntax. It also supports securing tokens using + Hash-based Message Authentication Codes (HMACs) and digital + signatures using a smaller (and less flexible) format than XML + DSIG. + +</p> +<p> + Therefore, while JWTs can do some of the things SAML tokens + do, JWTs are not intended as a full replacement for SAML + tokens, but rather as a compromise token format to be used + when space is at a premium. + +</p> +<a name="anchor11"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.B"></a><h3>Appendix B. +Relationship of JWTs to Simple Web Tokens (SWTs)</h3> + +<p> + Both JWTs and Simple Web Tokens <a class='info' href='#SWT'>SWT<span> (</span><span class='info'>Hardt, D. and Y. Goland, “Simple Web Token (SWT),” November 2009.</span><span>)</span></a> [SWT], + at their core, enable sets of claims to be communicated + between applications. For SWTs, both the claim names and + claim values are strings. For JWTs, while claim names are + strings, claim values can be any JSON type. Both token types + offer cryptographic protection of their content: SWTs with + HMAC SHA-256 and JWTs with a choice of algorithms, including + HMAC SHA-256, RSA SHA-256, and ECDSA P-256 SHA-256. + +</p> +<a name="Acknowledgements"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.C"></a><h3>Appendix C. +Acknowledgements</h3> + +<p> + The authors acknowledge that the design of JWTs was + intentionally influenced by the design and simplicity of <a class='info' href='#SWT'>Simple Web Tokens<span> (</span><span class='info'>Hardt, D. and Y. Goland, “Simple Web Token (SWT),” November 2009.</span><span>)</span></a> [SWT] and ideas for JSON + tokens that Dick Hardt discussed within the OpenID community. + +</p> +<p> + Solutions for signing JSON content were previously explored by + <a class='info' href='#MagicSignatures'>Magic Signatures<span> (</span><span class='info'>Panzer (editor), J., Laurie, B., and D. Balfanz, “Magic Signatures,” August 2010.</span><span>)</span></a> [MagicSignatures], <a class='info' href='#JSS'>JSON Simple Sign<span> (</span><span class='info'>Bradley, J. and N. Sakimura (editor), “JSON Simple Sign,” September 2010.</span><span>)</span></a> [JSS], and <a class='info' href='#CanvasApp'>Canvas Applications<span> (</span><span class='info'>Facebook, “Canvas Applications,” 2010.</span><span>)</span></a> [CanvasApp], all of which + influenced this draft. + +</p> +<a name="anchor12"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<a name="rfc.section.D"></a><h3>Appendix D. +Document History</h3> + +<p> + -07 + </p> +<ul class="text"> +<li> + Defined the <tt>prn</tt> (principal) + claim to identify the subject of the JWT. + +</li> +<li> + Defined the <tt>jti</tt> (JWT ID) + claim to enable replay protection. + +</li> +<li> + Use the term "JWT Claims Set" rather than "JWT Claims Object" + since this is actually a string representing a JSON object + and not the JSON object itself. + +</li> +<li> + Moved "MUST" requirements from the Overview to later in + the spec. + +</li> +<li> + Respect line length restrictions in examples. + +</li> +<li> + Applied other editorial improvements. + +</li> +</ul><p> + +</p> +<p> + -06 + </p> +<ul class="text"> +<li> + Reference and use content from <a class='info' href='#JWS'>[JWS]<span> (</span><span class='info'>Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, J., Sakimura, N., and P. Tarjan, “JSON Web Signature (JWS),” December 2011.</span><span>)</span></a> and + <a class='info' href='#JWE'>[JWE]<span> (</span><span class='info'>Jones, M., Rescorla, E., and J. Hildebrand, “JSON Web Encryption (JWE),” December 2011.</span><span>)</span></a>, rather than repeating it here. + +</li> +<li> + Simplified terminology to better match JWE, where the + terms "JWT Header" and "Encoded JWT Header" are now used, + for instance, rather than the previous terms "Decoded JWT + Header Segment" and "JWT Header Segment". Also changed to + "Plaintext JWT" from "Unsigned JWT". + +</li> +<li> + Describe how to perform nested encryption and signing + operations. + +</li> +<li> + Changed "integer" to "number", since that is the correct + JSON type. + +</li> +<li> + Changed StringAndURI to StringOrURI. + +</li> +</ul><p> + +</p> +<p> + -05 + </p> +<ul class="text"> +<li> + Added the <tt>nbf</tt> (not before) + claim and clarified the meaning of the <tt>iat</tt> (issued at) claim. + +</li> +</ul><p> + +</p> +<p> + -04 + </p> +<ul class="text"> +<li> + Correct typo found by John Bradley: "the JWT Claim Segment + is the empty string" -> "the JWT Crypto Segment is the + empty string". + +</li> +</ul><p> + +</p> +<p> + -03 + </p> +<ul class="text"> +<li> + Added "http://openid.net/specs/jwt/1.0" as a token type + identifier URI for JWTs. + +</li> +<li> + Added <tt>iat</tt> (issued at) claim. + +</li> +<li> + Changed RSA SHA-256 from MUST be supported to RECOMMENDED + that it be supported. Rationale: Several people have + objected to the requirement for implementing RSA SHA-256, + some because they will only be using HMACs and symmetric + keys, and others because they only want to use ECDSA when + using asymmetric keys, either for security or key length + reasons, or both. + +</li> +<li> + Defined <tt>alg</tt> value <tt>none</tt> to represent unsigned JWTs. + +</li> +</ul><p> + +</p> +<p> + -02 + </p> +<ul class="text"> +<li> + Split signature specification out into separate + draft-jones-json-web-signature-00. This split introduced + no semantic changes. + +</li> +<li> + The JWT Compact Serialization is now the only token + serialization format specified in this draft. The JWT + JSON Serialization can continue to be defined in a + companion specification. + +</li> +</ul><p> + +</p> +<p> + -01 + </p> +<ul class="text"> +<li> + Draft incorporating consensus decisions reached at IIW. + +</li> +</ul><p> + +</p> +<p> + -00 + </p> +<ul class="text"> +<li> + Public draft published before November 2010 IIW based upon + the JSON token convergence proposal incorporating input + from several implementers of related specifications. + +</li> +</ul><p> + +</p> +<a name="rfc.authors"></a><br /><hr /> +<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table> +<h3>Authors' Addresses</h3> +<table width="99%" border="0" cellpadding="0" cellspacing="0"> +<tr><td class="author-text"> </td> +<td class="author-text">Michael B. Jones</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Microsoft</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:mbj@microsoft.com">mbj@microsoft.com</a></td></tr> +<tr><td class="author" align="right">URI: </td> +<td class="author-text"><a href="http://self-issued.info/">http://self-issued.info/</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Dirk Balfanz</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Google</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:balfanz@google.com">balfanz@google.com</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">John Bradley</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">independent</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:ve7jtb@ve7jtb.com">ve7jtb@ve7jtb.com</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Yaron Y. Goland</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Microsoft</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:yarong@microsoft.com">yarong@microsoft.com</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">John Panzer</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Google</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:jpanzer@google.com">jpanzer@google.com</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Nat Sakimura</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Nomura Research Institute</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:n-sakimura@nri.co.jp">n-sakimura@nri.co.jp</a></td></tr> +<tr cellpadding="3"><td> </td><td> </td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Paul Tarjan</td></tr> +<tr><td class="author-text"> </td> +<td class="author-text">Facebook</td></tr> +<tr><td class="author" align="right">Email: </td> +<td class="author-text"><a href="mailto:pt@fb.com">pt@fb.com</a></td></tr> +</table> +</body></html> diff --git a/doc/specs/draft-jones-json-web-token.txt b/doc/specs/draft-jones-json-web-token.txt new file mode 100644 index 0000000..7e4a25c --- /dev/null +++ b/doc/specs/draft-jones-json-web-token.txt @@ -0,0 +1,1232 @@ + + + +Network Working Group M. Jones +Internet-Draft Microsoft +Intended status: Standards Track D. Balfanz +Expires: June 15, 2012 Google + J. Bradley + independent + Y. Goland + Microsoft + J. Panzer + Google + N. Sakimura + Nomura Research Institute + P. Tarjan + Facebook + December 13, 2011 + + + JSON Web Token (JWT) + draft-jones-json-web-token-07 + +Abstract + + JSON Web Token (JWT) is a means of representing claims to be + transferred between two parties. The claims in a JWT are encoded as + a JSON object that is digitally signed using JSON Web Signature (JWS) + and/or encrypted using JSON Web Encryption (JWE). + + The suggested pronunciation of JWT is the same as the English word + "jot". + +Requirements Language + + 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]. + +Status of this Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + + + +Jones, et al. Expires June 15, 2012 [Page 1] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on June 15, 2012. + +Copyright Notice + + Copyright (c) 2011 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 + 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Jones, et al. Expires June 15, 2012 [Page 2] + +Internet-Draft JSON Web Token (JWT) December 2011 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. JSON Web Token (JWT) Overview . . . . . . . . . . . . . . . . 5 + 3.1. Example JWT . . . . . . . . . . . . . . . . . . . . . . . 6 + 4. JWT Claims . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4.1. Reserved Claim Names . . . . . . . . . . . . . . . . . . . 7 + 4.2. Public Claim Names . . . . . . . . . . . . . . . . . . . . 9 + 4.3. Private Claim Names . . . . . . . . . . . . . . . . . . . 10 + 5. JWT Header . . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 6. Plaintext JWTs . . . . . . . . . . . . . . . . . . . . . . . . 11 + 6.1. Example Plaintext JWT . . . . . . . . . . . . . . . . . . 11 + 7. Rules for Creating and Validating a JWT . . . . . . . . . . . 12 + 8. Cryptographic Algorithms . . . . . . . . . . . . . . . . . . . 15 + 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 15 + 10.1. Unicode Comparison Security Issues . . . . . . . . . . . . 16 + 11. Open Issues and Things To Be Done (TBD) . . . . . . . . . . . 16 + 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 + 12.1. Normative References . . . . . . . . . . . . . . . . . . . 17 + 12.2. Informative References . . . . . . . . . . . . . . . . . . 18 + Appendix A. Relationship of JWTs to SAML Tokens . . . . . . . . . 19 + Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) . . 19 + Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 19 + Appendix D. Document History . . . . . . . . . . . . . . . . . . 20 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 + + + + + + + + + + + + + + + + + + + + + + + + +Jones, et al. Expires June 15, 2012 [Page 3] + +Internet-Draft JSON Web Token (JWT) December 2011 + + +1. Introduction + + JSON Web Token (JWT) is a compact token format intended for space + constrained environments such as HTTP Authorization headers and URI + query parameters. JWTs encode claims to be transmitted as a JSON + object (as defined in RFC 4627 [RFC4627]) that is base64url encoded + and digitally signed and/or encrypted. Signing is accomplished using + JSON Web Signature (JWS) [JWS]. Encryption is accomplished using + JSON Web Encryption (JWE) [JWE]. + + The suggested pronunciation of JWT is the same as the English word + "jot". + + +2. Terminology + + JSON Web Token (JWT) A string consisting of three parts: the Encoded + JWT Header, the JWT Second Part, and the JWT Third Part, in that + order, with the parts being separated by period ('.') characters, + and each part containing base64url encoded content. + + JWT Header A string representing a JSON object that describes the + cryptographic operations applied to the JWT. When the JWT is + signed, the JWT Header is the JWS Header. When the JWT is + encrypted, the JWT Header is the JWE Header. + + Header Parameter Names The names of the members within the JWT + Header. + + Header Parameter Values The values of the members within the JWT + Header. + + JWT Second Part When the JWT is signed, the JWT Second Part is the + Encoded JWS Payload. When the JWT is encrypted, the JWT Second + Part is the Encoded JWE Encrypted Key. + + JWT Third Part When the JWT is signed, the JWT Third Part is the + Encoded JWS Signature. When the JWT is encrypted, the JWT Third + Part is the Encoded JWE Ciphertext. + + JWT Claims Set A string representing a JSON object that contains the + claims conveyed by the JWT. When the JWT is signed, the bytes of + the UTF-8 representation of the JWT Claims Set are base64url + encoded to create the Encoded JWS Payload. When the JWT is + encrypted, the bytes of the UTF-8 representation of the JWT Claims + Set are used as the JWE Plaintext. + + + + + +Jones, et al. Expires June 15, 2012 [Page 4] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + Claim Names The names of the members of the JSON object represented + by the JWT Claims Set. + + Claim Values The values of the members of the JSON object + represented by the JWT Claims Set. + + Encoded JWT Header Base64url encoding of the bytes of the UTF-8 RFC + 3629 [RFC3629] representation of the JWT Header. + + Base64url Encoding For the purposes of this specification, this term + always refers to the URL- and filename-safe Base64 encoding + described in RFC 4648 [RFC4648], Section 5, with the (non URL- + safe) '=' padding characters omitted, as permitted by Section 3.2. + (See Appendix C of [JWS] for notes on implementing base64url + encoding without padding.) + + +3. JSON Web Token (JWT) Overview + + JWTs represent a set of claims as a JSON object that is base64url + encoded and digitally signed and/or encrypted. The JWT Claims Set + represents this JSON object. As per RFC 4627 [RFC4627] Section 2.2, + the JSON object consists of zero or more name/value pairs (or + members), where the names are strings and the values are arbitrary + JSON values. These members are the claims represented by the JWT. + + The member names within the JWT Claims Set are referred to as Claim + Names. The corresponding values are referred to as Claim Values. + + The bytes of the UTF-8 representation of the JWT Claims Set are + signed in the manner described in JSON Web Signature (JWS) [JWS] + and/or encrypted in the manner described in JSON Web Encryption (JWE) + [JWE]. + + The contents of the JWT Header describe the cryptographic operations + applied to the JWT Claims Set. If the JWT Header is a JWS Header, the + claims are signed. If the JWT Header is a JWE Header, the claims are + encrypted. + + A JWT is represented as the concatenation of the Encoded JWT Header, + the JWT Second Part, and the JWT Third Part, in that order, with the + parts being separated by period ('.') characters. When signed, the + three parts of the JWT are the three parts of a JWS used to represent + the JWT. When encrypted, the three parts of the JWT are the three + parts of a JWE used to represent the JWT. + + + + + + +Jones, et al. Expires June 15, 2012 [Page 5] + +Internet-Draft JSON Web Token (JWT) December 2011 + + +3.1. Example JWT + + The following example JWT Header declares that the encoded object is + a JSON Web Token (JWT) and the JWT is signed using the HMAC SHA-256 + algorithm: + {"typ":"JWT", + "alg":"HS256"} + + Base64url encoding the bytes of the UTF-8 representation of the JWT + Header yields this Encoded JWS Header value, which is used as the + Encoded JWT Header: + eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 + + The following is an example of a JWT Claims Set: + {"iss":"joe", + "exp":1300819380, + "http://example.com/is_root":true} + + Base64url encoding the bytes of the UTF-8 representation of the JSON + Claims Set yields this Encoded JWS Payload, which is used as the JWT + Second Part (with line breaks for display purposes only): + eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly + 9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ + + Signing the Encoded JWS Header and Encoded JWS Payload with the HMAC + SHA-256 algorithm and base64url encoding the signature in the manner + specified in [JWS], yields this Encoded JWS Signature, which is used + as the JWT Third Part: + dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk + + Concatenating these parts in the order Header.Second.Third with + period characters between the parts yields this complete JWT (with + line breaks for display purposes only): + eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9 + . + eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt + cGxlLmNvbS9pc19yb290Ijp0cnVlfQ + . + dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk + + This computation is illustrated in more detail in [JWS], Appendix + A.1. + + +4. JWT Claims + + The JWT Claims Set represents a JSON object whose members are the + claims conveyed by the JWT. The Claim Names within this object MUST + + + +Jones, et al. Expires June 15, 2012 [Page 6] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + be unique. Note however, that the set of claims that a JWT must + contain to be considered valid is context-dependent and is outside + the scope of this specification. When used in a security-related + context, implementations MUST understand and support all of the + claims present; otherwise, the JWT MUST be rejected for processing. + + There are three classes of JWT Claim Names: Reserved Claim Names, + Public Claim Names, and Private Claim Names. + +4.1. Reserved Claim Names + + The following claim names are reserved. None of the claims defined + in the table below are intended to be mandatory, but rather, provide + a starting point for a set of useful, interoperable claims. All the + names are short because a core goal of JWTs is for the tokens to be + compact. + + +-------+--------+-------------+------------------------------------+ + | Claim | JSON | Claim | Claim Semantics | + | Name | Value | Syntax | | + | | Type | | | + +-------+--------+-------------+------------------------------------+ + | exp | number | IntDate | The "exp" (expiration time) claim | + | | | | identifies the expiration time on | + | | | | or after which the token MUST NOT | + | | | | be accepted for processing. The | + | | | | processing of the "exp" claim | + | | | | requires that the current | + | | | | date/time MUST be before the | + | | | | expiration date/time listed in the | + | | | | "exp" claim. Implementers MAY | + | | | | provide for some small leeway, | + | | | | usually no more than a few | + | | | | minutes, to account for clock | + | | | | skew. This claim is OPTIONAL. | + | nbf | number | IntDate | The "nbf" (not before) claim | + | | | | identifies the time before which | + | | | | the token MUST NOT be accepted for | + | | | | processing. The processing of the | + | | | | "nbf" claim requires that the | + | | | | current date/time MUST be after or | + | | | | equal to the not-before date/time | + | | | | listed in the "nbf" claim. | + | | | | Implementers MAY provide for some | + | | | | small leeway, usually no more than | + | | | | a few minutes, to account for | + | | | | clock skew. This claim is | + | | | | OPTIONAL. | + + + +Jones, et al. Expires June 15, 2012 [Page 7] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + | iat | number | IntDate | The "iat" (issued at) claim | + | | | | identifies the time at which the | + | | | | JWT was issued. This claim can be | + | | | | used to determine the age of the | + | | | | token. This claim is OPTIONAL. | + | iss | string | StringOrURI | The "iss" (issuer) claim | + | | | | identifies the principal that | + | | | | issued the JWT. The processing of | + | | | | this claim is generally | + | | | | application specific. The "iss" | + | | | | value is case sensitive. This | + | | | | claim is OPTIONAL. | + | aud | string | StringOrURI | The "aud" (audience) claim | + | | | | identifies the audience that the | + | | | | JWT is intended for. The | + | | | | principal intended to process the | + | | | | JWT MUST be identified with the | + | | | | value of the audience claim. If | + | | | | the principal processing the claim | + | | | | does not identify itself with the | + | | | | identifier in the "aud" claim | + | | | | value then the JWT MUST be | + | | | | rejected. The interpretation of | + | | | | the audience value is generally | + | | | | application specific. The "aud" | + | | | | value is case sensitive. This | + | | | | claim is OPTIONAL. | + | prn | string | StringOrURI | The "prn" (principal) claim | + | | | | identifies the subject of the JWT. | + | | | | The processing of this claim is | + | | | | generally application specific. | + | | | | The "prn" value is case sensitive. | + | | | | This claim is OPTIONAL. | + | jti | string | String | The "jti" (JWT ID) claim provides | + | | | | a unique identifier for the JWT. | + | | | | The identifier value MUST be | + | | | | assigned in a manner that ensures | + | | | | that there is a negligible | + | | | | probability that the same value | + | | | | will be accidentally assigned to a | + | | | | different data object. The "jti" | + | | | | claim can be used to prevent the | + | | | | JWT from being replayed. The | + | | | | "jti" value is case sensitive. | + | | | | This claim is OPTIONAL. | + + + + + + +Jones, et al. Expires June 15, 2012 [Page 8] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + | typ | string | String | The "typ" (type) claim is used to | + | | | | declare a type for the contents of | + | | | | this JWT Claims Set. The "typ" | + | | | | value is case sensitive. This | + | | | | claim is OPTIONAL. | + +-------+--------+-------------+------------------------------------+ + + Table 1: Reserved Claim Definitions + + Additional reserved claim names MAY be defined via the IANA JSON Web + Token Claims registry, as per Section 9. The syntax values used + above are defined as follows: + + +-------------+-----------------------------------------------------+ + | Syntax Name | Syntax Definition | + +-------------+-----------------------------------------------------+ + | IntDate | The number of seconds from 1970-01-01T0:0:0Z as | + | | measured in UTC until the desired date/time. See | + | | RFC 3339 [RFC3339] for details regarding date/times | + | | in general and UTC in particular. | + | String | Any string value MAY be used. | + | StringOrURI | Any string value MAY be used but a value containing | + | | a ":" character MUST be a URI as defined in RFC | + | | 3986 [RFC3986]. | + +-------------+-----------------------------------------------------+ + + Table 2: Claim Syntax Definitions + +4.2. Public Claim Names + + Claim names can be defined at will by those using JWTs. However, in + order to prevent collisions, any new claim name SHOULD either be + defined in the IANA JSON Web Token Claims registry or be defined as a + URI that contains a collision resistant namespace. Examples of + collision resistant namespaces include: + + o Domain Names, + + o Object Identifiers (OIDs) as defined in the ITU-T X.660 and X.670 + Recommendation series, or + + o Universally Unique IDentifier (UUID) as defined in RFC 4122 + [RFC4122]. + + In each case, the definer of the name or value needs to take + reasonable precautions to make sure they are in control of the part + of the namespace they use to define the claim name. + + + + +Jones, et al. Expires June 15, 2012 [Page 9] + +Internet-Draft JSON Web Token (JWT) December 2011 + + +4.3. Private Claim Names + + A producer and consumer of a JWT may agree to any claim name that is + not a Reserved Name Section 4.1 or a Public Name Section 4.2. Unlike + Public Names, these private names are subject to collision and should + be used with caution. + + +5. JWT Header + + The members of the JSON object represented by the JWT Header describe + the cryptographic operations applied to the JWT and optionally, + additional properties of the JWT. The member names within the JWT + Header are referred to as Header Parameter Names. These names MUST + be unique. The corresponding values are referred to as Header + Parameter Values. + + Implementations MUST understand the entire contents of the header; + otherwise, the JWT MUST be rejected for processing. + + There are two ways of distinguishing whether the JWT is a JWS or JWE. + The first is by examining the "alg" (algorithm) header value. If the + value represents a signature algorithm, the JWT is a JWS; if it + represents an encryption algorithm, the JWT is a JWE. A second + method is determining whether an "enc" (encryption method) member + exists. If the "enc" member exists, the JWT is a JWE; otherwise, the + JWT is a JWS. Both methods will yield the same result. + + JWS Header Parameters are defined by [JWS]. JWE Header Parameters + are defined by [JWE]. This specification further specifies the use + of the following header parameters in both the cases where the JWT is + a JWS and where it is a JWE. + + + + + + + + + + + + + + + + + + + +Jones, et al. Expires June 15, 2012 [Page 10] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + +----------+--------+-----------+-----------------------------------+ + | Header | JSON | Header | Header Parameter Semantics | + | Paramete | Value | Parameter | | + | rName | Type | Syntax | | + +----------+--------+-----------+-----------------------------------+ + | typ | string | String | The "typ" (type) header parameter | + | | | | is used to declare structural | + | | | | information about the JWT. In | + | | | | the normal case where nested | + | | | | signing or encryption operations | + | | | | are not employed, the use of this | + | | | | header parameter is OPTIONAL, and | + | | | | if present, it is RECOMMENDED | + | | | | that its value be either "JWT" or | + | | | | "http://openid.net/specs/jwt/1.0" | + | | | | .In the case that nested signing | + | | | | or encryption steps are employed | + | | | | ,the use of this header parameter | + | | | | is REQUIRED; in this case, the | + | | | | value MUST either be "JWS", to | + | | | | indicate that a nested signed JW | + | | | | Tis carried in this JWT or "JWE", | + | | | | to indicate that a nested | + | | | | encrypted JWT is carried in this | + | | | | JWT. | + +----------+--------+-----------+-----------------------------------+ + + Table 3: Reserved Header Parameter Usage + + +6. Plaintext JWTs + + To support use cases where the JWT content is secured by a means + other than a signature and/or encryption contained within the token + (such as a signature on a data structure containing the token), JWTs + MAY also be created without a signature or encryption. Plaintext + JWTs MUST use the "alg" value "none", and are formatted identically + to a signed JWT with an empty signature. This means that the + base64url encoding of the bytes representing the UTF-8 encoding of + the JWT Claims Set is the JWT Second Part, and the empty string is + the JWT Third Part. + +6.1. Example Plaintext JWT + + The following example JWT Header declares that the encoded object is + a Plaintext JWT: + {"alg":"none"} + + + + +Jones, et al. Expires June 15, 2012 [Page 11] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + Base64url encoding the bytes of the UTF-8 representation of the JWT + Header yields this Encoded JWT Header: + eyJhbGciOiJub25lIn0 + + The following is an example of a JWT Claims Set: + {"iss":"joe", + "exp":1300819380, + "http://example.com/is_root":true} + + Base64url encoding the bytes of the UTF-8 representation of the JSON + Claims Set yields this Encoded JWS Payload, which is used as the JWT + Second Part (with line breaks for display purposes only): + eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt + cGxlLmNvbS9pc19yb290Ijp0cnVlfQ + + The JWT Third Part is the empty string. + + Concatenating these parts in the order Header.Second.Third with + period characters between the parts yields this complete JWT (with + line breaks for display purposes only): + eyJhbGciOiJub25lIn0 + . + eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt + cGxlLmNvbS9pc19yb290Ijp0cnVlfQ + . + + +7. Rules for Creating and Validating a JWT + + To create a JWT, one MUST perform these steps: + + 1. Create a JWT Claims Set containing the desired claims. Note that + white space is explicitly allowed in the representation and no + canonicalization is performed before encoding. + + 2. Let the Message be the bytes of the UTF-8 representation of the + JWT Claims Set. + + 3. Create a JWT Header containing the desired set of header + parameters. If the JWT is to be signed or encrypted, they MUST + conform to either the [JWS] or [JWE] specifications, + respectively. Else, if the JWT is to be plaintext, the "alg" + value "none" MUST be used. Note that white space is explicitly + allowed in the representation and no canonicalization is + performed before encoding. + + 4. Base64url encode the bytes of the UTF-8 representation of the JWT + Header. Let this be the Encoded JWT Header. + + + +Jones, et al. Expires June 15, 2012 [Page 12] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + 5. Depending upon whether the JWT is to be signed, encrypted, or + plaintext, there are three cases: + + * If the JWT is to be signed, create a JWS using the JWT Header + as the JWS Header and the Message as the JWS Payload; all + steps specified in [JWS] for creating a JWS MUST be followed. + Let the JWT Second Part be the Encoded JWS Payload and let the + JWT Third Part be the Encoded JWS Signature. + + * If the JWT is to be encrypted, create a JWE using the JWT + Header as the JWE Header and the Message as the JWE Plaintext; + all steps specified in [JWE] for creating a JWE MUST be + followed. Let the JWT Second Part be the Encoded JWE + Encrypted Key and let the JWT Third Part be the Encoded JWS + Ciphertext. + + * Else, if the JWT is to be plaintext, let the JWT Second Part + be the base64url encoding of the Message and let the JWT Third + Part be the empty string. + + 6. Concatenate the Encoded JWT Header, the JWT Second Part, and the + JWT Third Part in that order, separating each by period ('.') + characters. + + 7. If a nested signing or encryption operation will be performed, + let the Message be this concatenation, and return to Step 3, + using a "typ" value of either "JWS" or "JWE" respectively in the + new JWT Header created in that step. + + 8. Otherwise, let the resulting JWT be this concatenation. + + When validating a JWT the following steps MUST be taken. If any of + the listed steps fails then the token MUST be rejected for + processing. + + 1. The JWT MUST contain exactly two period characters. + + 2. The JWT MUST be split on the two period characters resulting in + three strings. The first string is the Encoded JWT Header; the + second is the JWT Second Part; the third is the JWT Third Part. + + 3. The Encoded JWT Header MUST be successfully base64url decoded + following the restriction given in this specification that no + padding characters have been used. + + 4. The JWT Header MUST be completely valid JSON syntax conforming + to RFC 4627 [RFC4627]. + + + + +Jones, et al. Expires June 15, 2012 [Page 13] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + 5. The JWT Header MUST be validated to only include parameters and + values whose syntax and semantics are both understood and + supported. + + 6. Determine whether the JWT is signed, encrypted, or plaintext by + examining the "alg" (algorithm) header value and optionally, the + "enc" (encryption method) header value, if present. + + 7. Depending upon whether the JWT signed, encrypted, or plaintext, + there are three cases: + + * If the JWT is signed, all steps specified in [JWS] for + validating a JWS MUST be followed. Let the Message be the + result of base64url decoding the JWS Payload. + + * If the JWT is encrypted, all steps specified in [JWE] for + validating a JWE MUST be followed. Let the Message be the + JWE Plaintext. + + * Else, if the JWT is plaintext, let the Message be the result + of base64url decoding the JWE Second Part. The Third Part + MUST be verified to be the empty string. + + 8. If the JWT Header contains a "typ" value of either "JWS" or + "JWE", then the Message contains a JWT that was the subject of + nested signing or encryption operations, respectively. In this + case, return to Step 1, using the Message as the JWT. + + 9. Otherwise, let the JWT Claims Set be the Message. + + 10. The JWT Claims Set MUST be completely valid JSON syntax + conforming to RFC 4627 [RFC4627]. + + 11. When used in a security-related context, the JWT Claims Set MUST + be validated to only include claims whose syntax and semantics + are both understood and supported. + + Processing a JWT inevitably requires comparing known strings to + values in the token. For example, in checking what the algorithm is, + the Unicode string encoding "alg" will be checked against the member + names in the JWT Header to see if there is a matching header + parameter name. A similar process occurs when determining if the + value of the "alg" header parameter represents a supported algorithm. + + Comparisons between JSON strings and other Unicode strings MUST be + performed as specified below: + + + + + +Jones, et al. Expires June 15, 2012 [Page 14] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + 1. Remove any JSON applied escaping to produce an array of Unicode + code points. + + 2. Unicode Normalization [USA15] MUST NOT be applied at any point to + either the JSON string or to the string it is to be compared + against. + + 3. Comparisons between the two strings MUST be performed as a + Unicode code point to code point equality comparison. + + +8. Cryptographic Algorithms + + JWTs use JSON Web Signature (JWS) [JWS] and JSON Web Encryption (JWE) + [JWE] to sign and/or encrypt the contents of the JWT. + + Of the JWS signing algorithms, only HMAC SHA-256 MUST be implemented + by conforming JWT implementations. It is RECOMMENDED that + implementations also support the RSA SHA-256 and ECDSA P-256 SHA-256 + algorithms. Support for other algorithms and key sizes is OPTIONAL. + + If an implementation provides encryption capabilities, of the JWE + encryption algorithms, only RSA-PKCS1-1.5 with 2048 bit keys, AES- + 128-CBC, and AES-256-CBC MUST be implemented by conforming + implementations. It is RECOMMENDED that implementations also support + ECDH-ES with 256 bit keys, AES-128-GCM, and AES-256-GCM. Support for + other algorithms and key sizes is OPTIONAL. + + +9. IANA Considerations + + This specification calls for: + + o A new IANA registry entitled "JSON Web Token Claims" for reserved + claim names is defined in Section 4.1. Inclusion in the registry + is RFC Required in the RFC 5226 [RFC5226] sense for reserved JWT + claim names that are intended to be interoperable between + implementations. The registry will just record the reserved claim + name and a pointer to the RFC that defines it. This specification + defines inclusion of the claim names defined in Table 1. + + +10. Security Considerations + + TBD: Lots of work to do here. We need to remember to look into any + issues relating to security and JSON parsing. One wonders just how + secure most JSON parsing libraries are. Were they ever hardened for + security scenarios? If not, what kind of holes does that open up? + + + +Jones, et al. Expires June 15, 2012 [Page 15] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + Also, we need to walk through the JSON standard and see what kind of + issues we have especially around comparison of names. For instance, + comparisons of claim names and other parameters must occur after they + are unescaped. Need to also put in text about: Importance of keeping + secrets secret. Rotating keys. Strengths and weaknesses of the + different algorithms. + + TBD: Need to put in text about why strict JSON validation is + necessary. Basically, that if malformed JSON is received then the + intent of the sender is impossible to reliably discern. One example + of malformed JSON that MUST be rejected is an object in which the + same member name occurs multiple times. While in non-security + contexts it's o.k. to be generous in what one accepts, in security + contexts this can lead to serious security holes. For example, + malformed JSON might indicate that someone has managed to find a + security hole in the issuer's code and is leveraging it to get the + issuer to issue "bad" tokens whose content the attacker can control. + + TBD: Write about the need to secure the token content if a signature + is not contained in the JWT itself. + +10.1. Unicode Comparison Security Issues + + Claim names in JWTs are Unicode strings. For security reasons, the + representations of these names must be compared verbatim after + performing any escape processing (as per RFC 4627 [RFC4627], Section + 2.5). + + This means, for instance, that these JSON strings must compare as + being equal ("JWT", "\u004aWT"), whereas these must all compare as + being not equal to the first set or to each other ("jwt", "Jwt", + "JW\u0074"). + + JSON strings MAY contain characters outside the Unicode Basic + Multilingual Plane. For instance, the G clef character (U+1D11E) may + be represented in a JSON string as "\uD834\uDD1E". Ideally, JWT + implementations SHOULD ensure that characters outside the Basic + Multilingual Plane are preserved and compared correctly; + alternatively, if this is not possible due to these characters + exercising limitations present in the underlying JSON implementation, + then input containing them MUST be rejected. + + +11. Open Issues and Things To Be Done (TBD) + + The following items remain to be done in this draft: + + + + + +Jones, et al. Expires June 15, 2012 [Page 16] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + o Provide an example of an encrypted JWT. + + o Clarify the optional ability to provide type information for JWTs + and/or their parts. Specifically, clarify whether we need to + specify the "typ" Claim Name in addition to the Header Parameter, + whether it conveys syntax or semantics, and indeed, whether this + is the right approach. Also clarify the relationship between + these type values and MIME [RFC2045] types (if any). + + o Think about how to best describe the concept currently described + as "the bytes of the UTF-8 representation of". Possible terms to + use instead of "bytes of" include "byte sequence", "octet series", + and "octet sequence". Also consider whether we want to add an + overall clarifying statement somewhere in each spec something like + "every place we say 'the UTF-8 representation of X', we mean 'the + bytes of the UTF-8 representation of X'". That would potentially + allow us to omit the "the bytes of" part everywhere else. + + o Consider whether a media type should be proposed, such as + "application/jwt". + + o Finish the Security Considerations section. + + o Possibly write a companion specification that contains the former + JWT JSON Serialization. + + +12. References + +12.1. Normative References + + [JWS] Jones, M., Balfanz, D., Bradley, J., Goland, Y., Panzer, + J., Sakimura, N., and P. Tarjan, "JSON Web Signature + (JWS)", December 2011. + + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the + Internet: Timestamps", RFC 3339, July 2002. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + + + +Jones, et al. Expires June 15, 2012 [Page 17] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC4627] Crockford, D., "The application/json Media Type for + JavaScript Object Notation (JSON)", RFC 4627, July 2006. + + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, October 2006. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [USA15] Davis, M., Whistler, K., and M. Duerst, "Unicode + Normalization Forms", Unicode Standard Annex 15, 09 2009. + +12.2. Informative References + + [CanvasApp] + Facebook, "Canvas Applications", 2010. + + [JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign", + September 2010. + + [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web + Encryption (JWE)", December 2011. + + [MagicSignatures] + Panzer (editor), J., Laurie, B., and D. Balfanz, "Magic + Signatures", August 2010. + + [OASIS.saml-core-2.0-os] + Cantor, S., Kemp, J., Philpott, R., and E. Maler, + "Assertions and Protocol for the OASIS Security Assertion + Markup Language (SAML) V2.0", OASIS Standard saml-core- + 2.0-os, March 2005. + + [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup + Language) XML-Signature Syntax and Processing", RFC 3275, + March 2002. + + [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally + Unique IDentifier (UUID) URN Namespace", RFC 4122, + July 2005. + + [SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", + Version 0.9.5.1, November 2009. + + + +Jones, et al. Expires June 15, 2012 [Page 18] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + [W3C.CR-xml11-20021015] + Cowan, J., "Extensible Markup Language (XML) 1.1", W3C + CR CR-xml11-20021015, October 2002. + + +Appendix A. Relationship of JWTs to SAML Tokens + + SAML 2.0 [OASIS.saml-core-2.0-os] provides a standard for creating + tokens with much greater expressivity and more security options than + supported by JWTs. However, the cost of this flexibility and + expressiveness is both size and complexity. In addition, SAML's use + of XML [W3C.CR-xml11-20021015] and XML DSIG [RFC3275] only + contributes to the size of SAML tokens. + + JWTs are intended to provide a simple token format that is small + enough to fit into HTTP headers and query arguments in URIs. It does + this by supporting a much simpler token model than SAML and using the + JSON [RFC4627] object encoding syntax. It also supports securing + tokens using Hash-based Message Authentication Codes (HMACs) and + digital signatures using a smaller (and less flexible) format than + XML DSIG. + + Therefore, while JWTs can do some of the things SAML tokens do, JWTs + are not intended as a full replacement for SAML tokens, but rather as + a compromise token format to be used when space is at a premium. + + +Appendix B. Relationship of JWTs to Simple Web Tokens (SWTs) + + Both JWTs and Simple Web Tokens SWT [SWT], at their core, enable sets + of claims to be communicated between applications. For SWTs, both + the claim names and claim values are strings. For JWTs, while claim + names are strings, claim values can be any JSON type. Both token + types offer cryptographic protection of their content: SWTs with HMAC + SHA-256 and JWTs with a choice of algorithms, including HMAC SHA-256, + RSA SHA-256, and ECDSA P-256 SHA-256. + + +Appendix C. Acknowledgements + + The authors acknowledge that the design of JWTs was intentionally + influenced by the design and simplicity of Simple Web Tokens [SWT] + and ideas for JSON tokens that Dick Hardt discussed within the OpenID + community. + + Solutions for signing JSON content were previously explored by Magic + Signatures [MagicSignatures], JSON Simple Sign [JSS], and Canvas + Applications [CanvasApp], all of which influenced this draft. + + + +Jones, et al. Expires June 15, 2012 [Page 19] + +Internet-Draft JSON Web Token (JWT) December 2011 + + +Appendix D. Document History + + -07 + + o Defined the "prn" (principal) claim to identify the subject of the + JWT. + + o Defined the "jti" (JWT ID) claim to enable replay protection. + + o Use the term "JWT Claims Set" rather than "JWT Claims Object" + since this is actually a string representing a JSON object and not + the JSON object itself. + + o Moved "MUST" requirements from the Overview to later in the spec. + + o Respect line length restrictions in examples. + + o Applied other editorial improvements. + + -06 + + o Reference and use content from [JWS] and [JWE], rather than + repeating it here. + + o Simplified terminology to better match JWE, where the terms "JWT + Header" and "Encoded JWT Header" are now used, for instance, + rather than the previous terms "Decoded JWT Header Segment" and + "JWT Header Segment". Also changed to "Plaintext JWT" from + "Unsigned JWT". + + o Describe how to perform nested encryption and signing operations. + + o Changed "integer" to "number", since that is the correct JSON + type. + + o Changed StringAndURI to StringOrURI. + + -05 + + o Added the "nbf" (not before) claim and clarified the meaning of + the "iat" (issued at) claim. + + -04 + + o Correct typo found by John Bradley: "the JWT Claim Segment is the + empty string" -> "the JWT Crypto Segment is the empty string". + + -03 + + + +Jones, et al. Expires June 15, 2012 [Page 20] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + o Added "http://openid.net/specs/jwt/1.0" as a token type identifier + URI for JWTs. + + o Added "iat" (issued at) claim. + + o Changed RSA SHA-256 from MUST be supported to RECOMMENDED that it + be supported. Rationale: Several people have objected to the + requirement for implementing RSA SHA-256, some because they will + only be using HMACs and symmetric keys, and others because they + only want to use ECDSA when using asymmetric keys, either for + security or key length reasons, or both. + + o Defined "alg" value "none" to represent unsigned JWTs. + + -02 + + o Split signature specification out into separate + draft-jones-json-web-signature-00. This split introduced no + semantic changes. + + o The JWT Compact Serialization is now the only token serialization + format specified in this draft. The JWT JSON Serialization can + continue to be defined in a companion specification. + + -01 + + o Draft incorporating consensus decisions reached at IIW. + + -00 + + o Public draft published before November 2010 IIW based upon the + JSON token convergence proposal incorporating input from several + implementers of related specifications. + + +Authors' Addresses + + Michael B. Jones + Microsoft + + Email: mbj@microsoft.com + URI: http://self-issued.info/ + + + + + + + + + +Jones, et al. Expires June 15, 2012 [Page 21] + +Internet-Draft JSON Web Token (JWT) December 2011 + + + Dirk Balfanz + Google + + Email: balfanz@google.com + + + John Bradley + independent + + Email: ve7jtb@ve7jtb.com + + + Yaron Y. Goland + Microsoft + + Email: yarong@microsoft.com + + + John Panzer + Google + + Email: jpanzer@google.com + + + Nat Sakimura + Nomura Research Institute + + Email: n-sakimura@nri.co.jp + + + Paul Tarjan + Facebook + + Email: pt@fb.com + + + + + + + + + + + + + + + + + +Jones, et al. Expires June 15, 2012 [Page 22] + |