< draft-ietf-oauth-v2-20.txt   draft-ietf-oauth-v2-21.txt >
Network Working Group E. Hammer-Lahav, Ed. Network Working Group E. Hammer-Lahav, Ed.
Internet-Draft Yahoo! Internet-Draft Yahoo!
Obsoletes: 5849 (if approved) D. Recordon Obsoletes: 5849 (if approved) D. Recordon
Intended status: Standards Track Facebook Intended status: Standards Track Facebook
Expires: January 26, 2012 D. Hardt Expires: March 8, 2012 D. Hardt
Microsoft Microsoft
July 25, 2011 September 5, 2011
The OAuth 2.0 Authorization Protocol The OAuth 2.0 Authorization Protocol
draft-ietf-oauth-v2-20 draft-ietf-oauth-v2-21
Abstract Abstract
The OAuth 2.0 authorization protocol enables a third-party The OAuth 2.0 authorization protocol enables a third-party
application to obtain limited access to an HTTP service, either on application to obtain limited access to an HTTP service, either on
behalf of a resource owner by orchestrating an approval interaction behalf of a resource owner by orchestrating an approval interaction
between the resource owner and the HTTP service, or by allowing the between the resource owner and the HTTP service, or by allowing the
third-party application to obtain access on its own behalf. third-party application to obtain access on its own behalf.
Status of this Memo Status of this Memo
skipping to change at page 1, line 37 skipping to change at page 1, line 37
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 26, 2012. This Internet-Draft will expire on March 8, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 13 skipping to change at page 2, line 13
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6
1.3. Access Token . . . . . . . . . . . . . . . . . . . . . . 7 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 7
1.4. Authorization Grant . . . . . . . . . . . . . . . . . . . 8 1.3.1. Authorization Code . . . . . . . . . . . . . . . . . . 7
1.4.1. Authorization Code . . . . . . . . . . . . . . . . . . 8 1.3.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8 1.3.3. Resource Owner Password Credentials . . . . . . . . . 8
1.4.3. Resource Owner Password Credentials . . . . . . . . . 9 1.3.4. Client Credentials . . . . . . . . . . . . . . . . . . 9
1.4.4. Client Credentials . . . . . . . . . . . . . . . . . . 9 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9
1.4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . 9
1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9
1.6. Notational Conventions . . . . . . . . . . . . . . . . . 11 1.6. Notational Conventions . . . . . . . . . . . . . . . . . 11
2. Client Registration . . . . . . . . . . . . . . . . . . . . . 11 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 11
2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 12 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 12
2.2. Registration Requirements . . . . . . . . . . . . . . . . 13 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 13
2.3. Client Identifier . . . . . . . . . . . . . . . . . . . . 13 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 13
2.4. Client Authentication . . . . . . . . . . . . . . . . . . 13 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 14
2.4.1. Client Password . . . . . . . . . . . . . . . . . . . 14 2.3.2. Other Authentication Methods . . . . . . . . . . . . . 15
2.4.2. Other Authentication Methods . . . . . . . . . . . . . 15 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 15
2.5. Unregistered Clients . . . . . . . . . . . . . . . . . . 15
3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 15 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 15
3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 15 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 15
3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 16 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 16
3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 16 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 16
3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 18 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 18
3.2.1. Client Authentication . . . . . . . . . . . . . . . . 19 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 19
4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 19 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 20
4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 20
4.1. Authorization Code . . . . . . . . . . . . . . . . . . . 20 4.1. Authorization Code . . . . . . . . . . . . . . . . . . . 20
4.1.1. Authorization Request . . . . . . . . . . . . . . . . 21 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 22
4.1.2. Authorization Response . . . . . . . . . . . . . . . . 22 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 23
4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 24 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 25
4.1.4. Access Token Response . . . . . . . . . . . . . . . . 25 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 26
4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 26 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 27
4.2.1. Authorization Request . . . . . . . . . . . . . . . . 28 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 29
4.2.2. Access Token Response . . . . . . . . . . . . . . . . 29 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 30
4.3. Resource Owner Password Credentials . . . . . . . . . . . 31 4.3. Resource Owner Password Credentials . . . . . . . . . . . 32
4.3.1. Authorization Request and Response . . . . . . . . . . 32 4.3.1. Authorization Request and Response . . . . . . . . . . 33
4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 33 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 33
4.3.3. Access Token Response . . . . . . . . . . . . . . . . 34 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 34
4.4. Client Credentials . . . . . . . . . . . . . . . . . . . 34 4.4. Client Credentials . . . . . . . . . . . . . . . . . . . 35
4.4.1. Authorization Request and Response . . . . . . . . . . 35 4.4.1. Authorization Request and Response . . . . . . . . . . 36
4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 35 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 36
4.4.3. Access Token Response . . . . . . . . . . . . . . . . 36 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 36
4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . 36 4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . 37
5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 37 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 37
5.1. Successful Response . . . . . . . . . . . . . . . . . . . 37 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 38
5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 39 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 39
6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 40 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 40
7. Accessing Protected Resources . . . . . . . . . . . . . . . . 41 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 42
7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 42 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 42
8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 43 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 43
8.1. Defining Access Token Types . . . . . . . . . . . . . . . 43 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 43
8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 43 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 44
8.3. Defining New Authorization Grant Types . . . . . . . . . 44 8.3. Defining New Authorization Grant Types . . . . . . . . . 44
8.4. Defining New Authorization Endpoint Response Types . . . 44 8.4. Defining New Authorization Endpoint Response Types . . . 44
8.5. Defining Additional Error Codes . . . . . . . . . . . . . 44 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 45
9. Native Applications . . . . . . . . . . . . . . . . . . . . . 45 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 45
10. Security Considerations . . . . . . . . . . . . . . . . . . . 46 10. Security Considerations . . . . . . . . . . . . . . . . . . . 46
10.1. Client Authentication . . . . . . . . . . . . . . . . . . 46 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 47
10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 47 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 47
10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 47 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 48
10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 48 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 48
10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 48 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 49
10.6. Authorization Code Leakage . . . . . . . . . . . . . . . 49 10.6. Authorization Code Redirection URI Manipulation . . . . . 49
10.7. Resource Owner Password Credentials . . . . . . . . . . . 49 10.7. Resource Owner Password Credentials . . . . . . . . . . . 50
10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 50 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 51
10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 50 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 51
10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 50 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 51
10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 50 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 51
10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 51 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 52
10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 51 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 53
10.14. Code Injection and Input Validation . . . . . . . . . . . 52 10.14. Code Injection and Input Validation . . . . . . . . . . . 53
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 10.15. Open Redirectors . . . . . . . . . . . . . . . . . . . . 53
11.1. The OAuth Access Token Type Registry . . . . . . . . . . 52 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54
11.1.1. Registration Template . . . . . . . . . . . . . . . . 53 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 54
11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 53 11.1.1. Registration Template . . . . . . . . . . . . . . . . 54
11.2.1. Registration Template . . . . . . . . . . . . . . . . 54 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 55
11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 54 11.2.1. Registration Template . . . . . . . . . . . . . . . . 56
11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 56
11.3. The OAuth Authorization Endpoint Response Type 11.3. The OAuth Authorization Endpoint Response Type
Registry . . . . . . . . . . . . . . . . . . . . . . . . 56 Registry . . . . . . . . . . . . . . . . . . . . . . . . 58
11.3.1. Registration Template . . . . . . . . . . . . . . . . 57 11.3.1. Registration Template . . . . . . . . . . . . . . . . 59
11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 57 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 59
11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 58 11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 59
11.4.1. Registration Template . . . . . . . . . . . . . . . . 58 11.4.1. Registration Template . . . . . . . . . . . . . . . . 60
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 59 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 61
Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 60 Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 61
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 60 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 62
13.1. Normative References . . . . . . . . . . . . . . . . . . 60 13.1. Normative References . . . . . . . . . . . . . . . . . . 62
13.2. Informative References . . . . . . . . . . . . . . . . . 61 13.2. Informative References . . . . . . . . . . . . . . . . . 63
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 62 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 64
1. Introduction 1. Introduction
In the traditional client-server authentication model, the client In the traditional client-server authentication model, the client
accesses a protected resource on the server by authenticating with accesses a protected resource on the server by authenticating with
the server using the resource owner's credentials. In order to the server using the resource owner's credentials. In order to
provide third-party applications access to protected resources, the provide third-party applications access to protected resources, the
resource owner shares its credentials with the third-party. This resource owner shares its credentials with the third-party. This
creates several problems and limitations: creates several problems and limitations:
skipping to change at page 7, line 13 skipping to change at page 7, line 13
+--------+ +---------------+ +--------+ +---------------+
Figure 1: Abstract Protocol Flow Figure 1: Abstract Protocol Flow
The abstract flow illustrated in Figure 1 describes the interaction The abstract flow illustrated in Figure 1 describes the interaction
between the four roles and includes the following steps: between the four roles and includes the following steps:
(A) The client requests authorization from the resource owner. The (A) The client requests authorization from the resource owner. The
authorization request can be made directly to the resource owner authorization request can be made directly to the resource owner
(as shown), or preferably indirectly via an intermediary such as (as shown), or preferably indirectly via an intermediary such as
an authorization server. an authorization server.
(B) The client receives an authorization grant which represents the (B) The client receives an authorization grant which is a credential
authorization provided by the resource owner. The authorization representing the resource owner's authorization, expressed using
grant type depends on the method used by the client and one of four grant types defined in this specification or using
supported by the authorization server to obtain it. 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 (C) The client requests an access token by authenticating with the
authorization server and presenting the authorization grant. authorization server and presenting the authorization grant.
(D) The authorization server authenticates the client and validates (D) The authorization server authenticates the client and validates
the authorization grant, and if valid issues an access token. the authorization grant, and if valid issues an access token.
(E) The client requests the protected resource from the resource (E) The client requests the protected resource from the resource
server and authenticates by presenting the access token. server and authenticates by presenting the access token.
(F) The resource server validates the access token, and if valid, (F) The resource server validates the access token, and if valid,
serves the request. serves the request.
1.3. Access Token 1.3. Authorization Grant
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.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, An authorization grant is a credential representing the resource
implicit, resource owner password credentials, and client owner's authorization (to access its protected resources) used by the
credentials, as well as an extensibility mechanism for defining client to obtain an access token. This specification defines four
additional types. 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 1.3.1. Authorization Code
The authorization code is obtained by using an authorization server The authorization code is obtained by using an authorization server
as an intermediary between the client and resource owner. Instead of as an intermediary between the client and resource owner. Instead of
requesting authorization directly from the resource owner, the client requesting authorization directly from the resource owner, the client
directs the resource owner to an authorization server (via its user- directs the resource owner to an authorization server (via its user-
agent as defined in [RFC2616]), which in turn directs the resource agent as defined in [RFC2616]), which in turn directs the resource
owner back to the client with the authorization code. owner back to the client with the authorization code.
Before directing the resource owner back to the client with the Before directing the resource owner back to the client with the
authorization code, the authorization server authenticates the authorization code, the authorization server authenticates the
resource owner and obtains authorization. Because the resource owner resource owner and obtains authorization. Because the resource owner
only authenticates with the authorization server, the resource only authenticates with the authorization server, the resource
owner's credentials are never shared with the client. owner's credentials are never shared with the client.
The authorization code provides a few important security benefits The authorization code provides a few important security benefits
such as the ability to authenticate the client and issuing the access such as the ability to authenticate the client, and the transmission
token directly to the client without potentially exposing it to of the the access token directly to the client without passing it
through the resource owner's user-agnet, potentially exposing it to
others, including the resource owner. others, including the resource owner.
1.4.2. Implicit 1.3.2. Implicit
The authorization grant is implicit when an access token is issued to The implicit grant is a simplified authorization code flow optimized
the client directly as the result of the resource owner for clients implemented in a browser using a scripting language such
authorization, without using intermediate credentials (such as an as JavaScript. In the implicit flow, instead of issuing the client
authorization code). 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 implicit grant, the authorization server does not When issuing an implicit grant, the authorization server does not
authenticate the client and the client identity is verified via the authenticate the client and in some cases, the client identity can be
redirection URI used to deliver the access token to the client. The verified via the redirection URI used to deliver the access token to
access token may be exposed to the resource owner or other the client. The access token may be exposed to the resource owner or
applications with access to the resource owner's user-agent. other applications with access to the resource owner's user-agent.
Implicit grants improve the responsiveness and efficiency of some Implicit grants improve the responsiveness and efficiency of some
clients (such as a client implemented as an in-browser application) clients (such as a client implemented as an in-browser application)
since it reduces the number of round trips required to obtain an since it reduces the number of round trips required to obtain an
access token. However, this convenience should be weighted against access token. However, this convenience should be weighed against
the security implications of using implicit grants, especially when the security implications of using implicit grants, especially when
the authorization code grant type is available. the authorization code grant type is available.
1.4.3. Resource Owner Password Credentials 1.3.3. Resource Owner Password Credentials
The resource owner password credentials (e.g. a username and The resource owner password credentials (e.g. a username and
password) can be used directly as an authorization grant to obtain an password) can be used directly as an authorization grant to obtain an
access token. The credentials should only be used when there is a 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. high degree of trust between the resource owner and the client (e.g.
its device operating system or a highly privileged application), and its device operating system or a highly privileged application), and
when other authorization grant types are not available (such as an when other authorization grant types are not available (such as an
authorization code). authorization code).
Even though this grant type requires direct client access to the Even though this grant type requires direct client access to the
resource owner credentials, the resource owner credentials are used resource owner credentials, the resource owner credentials are used
for a single request and are exchanged for an access token. Unlike for a single request and are exchanged for an access token. This
the HTTP Basic authentication scheme defined in [RFC2617], this grant grant type can eliminate the need for the client to store the
type (when combined with a refresh token) eliminates the need for the resource owner credentials for future use, by exchanging the
client to store the resource owner credentials for future use. credentials with a long-lived access token or refresh token.
1.4.4. Client Credentials 1.3.4. Client Credentials
The client credentials (or other forms of client authentication) can The client credentials (or other forms of client authentication) can
be used as an authorization grant when the authorization scope is be used as an authorization grant when the authorization scope is
limited to the protected resources under the control of the client, limited to the protected resources under the control of the client,
or to protected resources previously arranged with the authorization or to protected resources previously arranged with the authorization
server. Client credentials are used as an authorization grant server. Client credentials are used as an authorization grant
typically when the client is acting on its own behalf (the client is typically when the client is acting on its own behalf (the client is
also the resource owner). also the resource owner), or is requesting access to protected
resources based on an authorization previously arranged with the
authorization server.
1.4.5. Extensions 1.4. Access Token
Additional grant types may be defined to provide a bridge between Access tokens are credentials used to access protected resources. An
OAuth and other protocols. 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 1.5. Refresh Token
Refresh tokens are credentials used to obtain access tokens. Refresh Refresh tokens are credentials used to obtain access tokens. Refresh
tokens are issued to the client by the authorization server and are tokens are issued to the client by the authorization server and are
used to obtain a new access token when the current access token used to obtain a new access token when the current access token
becomes invalid or expires, or to obtain additional access tokens becomes invalid or expires, or to obtain additional access tokens
with identical or narrower scope (access tokens may have a shorter with identical or narrower scope (access tokens may have a shorter
lifetime and fewer permissions than authorized by the resource lifetime and fewer permissions than authorized by the resource
owner). Issuing a refresh token is optional and is included when owner). Issuing a refresh token is optional and is included when
skipping to change at page 10, line 43 skipping to change at page 10, line 45
Figure 2: Refreshing an Expired Access Token Figure 2: Refreshing an Expired Access Token
The flow illustrated in Figure 2 includes the following steps: The flow illustrated in Figure 2 includes the following steps:
(A) The client requests an access token by authenticating with the (A) The client requests an access token by authenticating with the
authorization server, and presenting an authorization grant. authorization server, and presenting an authorization grant.
(B) The authorization server authenticates the client and validates (B) The authorization server authenticates the client and validates
the authorization grant, and if valid issues an access token and the authorization grant, and if valid issues an access token and
a refresh token. a refresh token.
(C) The client makes a protected resource requests to the resource (C) The client makes a protected resource request to the resource
server by presenting the access token. server by presenting the access token.
(D) The resource server validates the access token, and if valid, (D) The resource server validates the access token, and if valid,
serves the request. serves the request.
(E) Steps (C) and (D) repeat until the access token expires. If the (E) Steps (C) and (D) repeat until the access token expires. If the
client knows the access token expired, it skips to step (G), client knows the access token expired, it skips to step (G),
otherwise it makes another protected resource request. otherwise it makes another protected resource request.
(F) Since the access token is invalid, the resource server returns (F) Since the access token is invalid, the resource server returns
an invalid token error. an invalid token error.
(G) The client requests a new access token by authenticating with (G) The client requests a new access token by authenticating with
the authorization server and presenting the refresh token. 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 (H) The authorization server authenticates the client and validates
the refresh token, and if valid issues a new access token (and the refresh token, and if valid issues a new access token (and
optionally, a new refresh token). optionally, a new refresh token).
1.6. Notational Conventions 1.6. Notational Conventions
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
specification are to be interpreted as described in [RFC2119]. specification are to be interpreted as described in [RFC2119].
skipping to change at page 12, line 5 skipping to change at page 12, line 7
Client registration does not require a direct interaction between the Client registration does not require a direct interaction between the
client and the authorization server. When supported by the client and the authorization server. When supported by the
authorization server, registration can rely on other means for authorization server, registration can rely on other means for
establishing trust and obtaining the required client properties (e.g. establishing trust and obtaining the required client properties (e.g.
redirection URI, client type). For example, registration can be redirection URI, client type). For example, registration can be
accomplished using a self-issued or third-party-issued assertion, or accomplished using a self-issued or third-party-issued assertion, or
by the authorization server performing client discovery using a by the authorization server performing client discovery using a
trusted channel. 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).
2.1. Client Types 2.1. Client Types
OAuth defines two client types, based on their ability to OAuth defines two client types, based on their ability to
authenticate securely with the authorization server (i.e. ability to authenticate securely with the authorization server (i.e. ability to
maintain the confidentiality of their client credentials): maintain the confidentiality of their client credentials):
confidential confidential
Clients capable of maintaining the confidentiality of their Clients capable of maintaining the confidentiality of their
credentials (e.g. client implemented on a secure server with credentials (e.g. client implemented on a secure server with
restricted access to the client credentials), or capable of secure restricted access to the client credentials), or capable of secure
client authentication using other means. client authentication using other means.
public public
Clients incapable of maintaining the confidentiality of their Clients incapable of maintaining the confidentiality of their
credentials (e.g. clients executing on the resource owner's device credentials (e.g. clients executing on the resource owner's device
such as an installed native application or a user-agent-based such as an installed native application or a web browser-based
application), and incapable of secure client authentication via application), and incapable of secure client authentication via
any other mean. any other mean.
The client type designation is based on the authorization server's The client type designation is based on the authorization server's
definition of secure authentication and its acceptable exposure definition of secure authentication and its acceptable exposure
levels of client credentials. levels of client credentials.
This specification has been designed around the following client This specification has been designed around the following client
profiles: profiles:
skipping to change at page 12, line 37 skipping to change at page 13, line 4
This specification has been designed around the following client This specification has been designed around the following client
profiles: profiles:
web application web application
A web application is a confidential client running on a web A web application is a confidential client running on a web
server. Resource owners access the client via an HTML user server. Resource owners access the client via an HTML user
interface rendered in a user-agent on the resource owner's device. interface rendered in a user-agent on the resource owner's device.
The client credentials as well as any access token issued to the 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 client are stored on the web server and are not exposed to or
accessible by the resource owner. accessible by the resource owner.
user-agent-based application user-agent-based application
A user-agent-based application is a public client in which the A user-agent-based application is a public client in which the
client code is downloaded from a web server and executes within a client code is downloaded from a web server and executes within a
user-agent on the resource owner's device. Protocol data and user-agent (e.g. web browser) on the resource owner's device.
credentials are easily accessible (and often visible) to the Protocol data and credentials are easily accessible (and often
resource owner. Since such applications reside within the user- visible) to the resource owner. Since such applications reside
agent, they can make seamless use of the user-agent capabilities within the user-agent, they can make seamless use of the user-
when requesting authorization. agent capabilities when requesting authorization.
native application native application
A native application is a public client installed and executed on A native application is a public client installed and executed on
the resource owner's device. Protocol data and credentials are the resource owner's device. Protocol data and credentials are
accessible to the resource owner. It is assumed that any client accessible to the resource owner. It is assumed that any client
authentication credentials included in the application can be authentication credentials included in the application can be
extracted. On the other hand, dynamically issued credentials such extracted. On the other hand, dynamically issued credentials such
access tokens or refresh tokens, can receive an acceptable level access tokens or refresh tokens, can receive an acceptable level
of protection. At a minimum, these credentials are protected from of protection. At a minimum, these credentials are protected from
hostile servers which the application may interact with. On some hostile servers which the application may interact with. On some
platform these credentials might be protected from other platform these credentials might be protected from other
applications residing on the same device. applications residing on the same device.
2.2. Registration Requirements 2.2. Client Identifier
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).
2.3. Client Identifier
The authorization server issues the registered client a client The authorization server issues the registered client a client
identifier - a unique string representing the registration identifier - a unique string representing the registration
information provided by the client. The client identifier is not a information provided by the client. The client identifier is not a
secret, it is exposed to the resource owner, and cannot be used alone secret, it is exposed to the resource owner, and MUST NOT be used
for client authentication. alone for client authentication.
2.4. Client Authentication 2.3. Client Authentication
If the client type is confidential, the client and authorization If the client type is confidential, the client and authorization
server establish a client authentication method suitable for the server establish a client authentication method suitable for the
security requirements of the authorization server. The authorization security requirements of the authorization server. The authorization
server MAY accept any form of client authentication meeting its server MAY accept any form of client authentication meeting its
security requirements. security requirements.
Confidential clients are typically issued (or establish) a set of Confidential clients are typically issued (or establish) a set of
client credentials used for authenticating with the authorization client credentials used for authenticating with the authorization
server (e.g. password, public/private key pair). server (e.g. password, public/private key pair).
skipping to change at page 14, line 5 skipping to change at page 14, line 6
The authorization server SHOULD NOT make assumptions about the client The authorization server SHOULD NOT make assumptions about the client
type or accept the type information provided without establishing type or accept the type information provided without establishing
trust with the client or its developer. The authorization server MAY trust with the client or its developer. The authorization server MAY
establish a client authentication method with public clients. establish a client authentication method with public clients.
However, the authorization server MUST NOT rely on public client However, the authorization server MUST NOT rely on public client
authentication for the purpose of identifying the client. authentication for the purpose of identifying the client.
The client MUST NOT use more than one authentication method in each The client MUST NOT use more than one authentication method in each
request. request.
2.4.1. Client Password 2.3.1. Client Password
Clients in possession of a client password MAY use the HTTP Basic Clients in possession of a client password MAY use the HTTP Basic
authentication scheme as defined in [RFC2617] to authenticate with authentication scheme as defined in [RFC2617] to authenticate with
the authorization server. The client identifier is used as the the authorization server. The client identifier is used as the
username, and the client password is used as the password. username, and the client password is used as the password.
For example (extra line breaks are for display purposes only): For example (extra line breaks are for display purposes only):
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Alternatively, the authorization server MAY allow including the Alternatively, the authorization server MAY allow including the
client credentials in the request body using the following client credentials in the request body using the following
parameters: parameters:
client_id client_id
REQUIRED. The client identifier issued to the client during REQUIRED. The client identifier issued to the client during
the registration process described by Section 2.3. the registration process described by Section 2.2.
client_secret client_secret
REQUIRED. The 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 Including the client credentials in the request body using the two
parameters is NOT RECOMMENDED, and should be limited to clients parameters is NOT RECOMMENDED, and should be limited to clients
unable to directly utilize the HTTP Basic authentication scheme (or unable to directly utilize the HTTP Basic authentication scheme (or
other password-based HTTP authentication schemes). other password-based HTTP authentication schemes).
For example, requesting to refresh an access token (Section 6) using For example, requesting to refresh an access token (Section 6) using
the body parameters (extra line breaks are for display purposes the body parameters (extra line breaks are for display purposes
only): only):
skipping to change at page 15, line 5 skipping to change at page 15, line 5
Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw
The authorization server MUST require the use of a transport-layer The authorization server MUST require the use of a transport-layer
security mechanism when sending requests to the token endpoint, as security mechanism when sending requests to the token endpoint, as
requests using this authentication method result in the transmission requests using this authentication method result in the transmission
of clear-text credentials. of clear-text credentials.
2.4.2. Other Authentication Methods 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 The authorization server MAY support any suitable HTTP authentication
scheme matching its security requirements. When using other scheme matching its security requirements. When using other
authentication methods, the authorization server MUST define a authentication methods, the authorization server MUST define a
mapping between the client identifier (registration record) and mapping between the client identifier (registration record) and
authentication scheme. authentication scheme.
2.5. Unregistered Clients 2.4. Unregistered Clients
This specification does not exclude the use of unregistered clients. This specification does not exclude the use of unregistered clients.
However, the use with such clients is beyond the scope of this However, the use with such clients is beyond the scope of this
specification, and requires additional security analysis and review specification, and requires additional security analysis and review
of its interoperability impact. of its interoperability impact.
3. Protocol Endpoints 3. Protocol Endpoints
The authorization process utilizes two endpoints (HTTP resources): The authorization process utilizes two endpoints (HTTP resources):
skipping to change at page 15, line 35 skipping to change at page 15, line 39
resource owner via user-agent redirection. resource owner via user-agent redirection.
o Token endpoint - used to exchange an authorization grant for an o Token endpoint - used to exchange an authorization grant for an
access token, typically with client authentication. access token, typically with client authentication.
Not every authorization grant type utilizes both endpoints. Not every authorization grant type utilizes both endpoints.
Extension grant types MAY define additional endpoints as needed. Extension grant types MAY define additional endpoints as needed.
3.1. Authorization Endpoint 3.1. Authorization Endpoint
The authorization endpoint is used to interact with the resource The authorization endpoint is used to interact with the resource
owner and obtain authorization which is expressed explicitly as an owner and obtain an authorization grant. The authorization server
authorization code (later exchanged for an access token), or MUST first verify the identity of the resource owner. The way in
implicitly by direct issuance of an access token. which the authorization server authenticates the resource owner (e.g.
username and password login, session cookies) is beyond the scope of
The authorization server MUST first verify the identity of the this specification.
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 The means through which the client obtains the location of the
authorization endpoint are beyond the scope of this specification but authorization endpoint are beyond the scope of this specification but
the location is typically provided in the service documentation. The the location is typically provided in the service documentation.
endpoint URI MAY include a query component as defined by [RFC3986]
section 3, which MUST be retained when adding additional query 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. parameters. The endpoint URI MUST NOT include a fragment component.
Since requests to the authorization endpoint result in user Since requests to the authorization endpoint result in user
authentication and the transmission of clear-text credentials (in the authentication and the transmission of clear-text credentials (in the
HTTP response), the authorization server MUST require the use of a HTTP response), the authorization server MUST require the use of a
transport-layer security mechanism when sending requests to the transport-layer security mechanism when sending requests to the
authorization endpoint. The authorization server MUST support TLS authorization endpoint. The authorization server MUST support TLS
1.2 as defined in [RFC5246], and MAY support additional transport- 1.0 ([RFC2246]), SHOULD support TLS 1.2 ([RFC5246]) and its future
layer mechanisms meeting its security requirements. replacements, and MAY support additional transport-layer mechanisms
meeting its security requirements.
The authorization server MUST support the use of the HTTP "GET" The authorization server MUST support the use of the HTTP "GET"
method [RFC2616] for the authorization endpoint, and MAY support the method [RFC2616] for the authorization endpoint, and MAY support the
use of the "POST" method as well. use of the "POST" method as well.
Parameters sent without a value MUST be treated as if they were Parameters sent without a value MUST be treated as if they were
omitted from the request. The authorization server SHOULD ignore omitted from the request. The authorization server SHOULD ignore
unrecognized request parameters. Request and response parameters unrecognized request parameters. Request and response parameters
MUST NOT be included more than once. MUST NOT be included more than once.
skipping to change at page 16, line 48 skipping to change at page 17, line 4
the authorization server SHOULD return an error response as described the authorization server SHOULD return an error response as described
in Section 4.1.2.1. in Section 4.1.2.1.
3.1.2. Redirection Endpoint 3.1.2. Redirection Endpoint
After completing its interaction with the resource owner, the After completing its interaction with the resource owner, the
authorization server directs the resource owner's user-agent back to authorization server directs the resource owner's user-agent back to
the client. The authorization server redirects the user-agent to the the client. The authorization server redirects the user-agent to the
client's redirection endpoint previously established with the client's redirection endpoint previously established with the
authorization server during the client registration process or when authorization server during the client registration process or when
initiating the authorization request. making the authorization request.
The redirection endpoint URI MUST be an absolute URI as defined by The redirection endpoint URI MUST be an absolute URI as defined by
[RFC3986] section 4.3, MAY include a query component which MUST be [RFC3986] section 4.3. The endpoint URI MAY include an
retained by the authorization server when adding additional query "application/x-www-form-urlencoded" formatted
parameters, and MUST NOT include a fragment component. ([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 3.1.2.1. Endpoint Request Confidentiality
If a redirection request will result in the transmission of an If a redirection request will result in the transmission of an
authorization code or access token over an open network (between the authorization code or access token over an open network (between the
resource owner's user-agent and the client), the client SHOULD resource owner's user-agent and the client), the client SHOULD
require the use of a transport-layer security mechanism. require the use of a transport-layer security mechanism.
Lack of transport-layer security can have a severe impact on the Lack of transport-layer security can have a severe impact on the
security of the client and the protected resources it is authorized security of the client and the protected resources it is authorized
to access. The use of transport-layer security is particularly to access. The use of transport-layer security is particularly
critical when the authorization process is used as a form of critical when the authorization process is used as a form of
delegated end-user authentication by the client (e.g. third-party delegated end-user authentication by the client (e.g. third-party
sign-in service). sign-in service).
3.1.2.2. Registration Requirements 3.1.2.2. Registration Requirements
The authorization server MUST require public clients to register The authorization server SHOULD require all clients to register their
their redirection URI, MUST require all clients to register their redirection URI prior to using the authorization endpoint, and MUST
redirection URI prior to utilizing the implicit grant type, and require the following clients to register their redirection URI:
SHOULD require all clients to register their redirection URI prior to
utilizing the authorization code grant type. o Public clients.
o Confidential clients utilizing the implicit grant type.
The authorization server SHOULD require the client to provide the The authorization server SHOULD require the client to provide the
complete redirection URI (the client MAY use the "state" request complete redirection URI (the client MAY use the "state" request
parameter to achieve per-request customization). The authorization parameter to achieve per-request customization). The authorization
server MAY allow the client to register multiple redirection URIs. server MAY allow the client to register multiple redirection URIs.
If requiring the registration of the complete redirection URI is not If requiring the registration of the complete redirection URI is not
possible, the authorization server SHOULD require the registration of possible, the authorization server SHOULD require the registration of
the URI scheme, authority, and path. the URI scheme, authority, and path (allowing the client to
dynamically change only the query component of the redirection URI
when requesting authorization).
3.1.2.3. Dynamic Configuration 3.1.2.3. Dynamic Configuration
If multiple redirection URIs have been registered, if only part of If multiple redirection URIs have been registered, if only part of
the redirection URI has been registered, or if no redirection URI has the redirection URI has been registered, or if no redirection URI has
been registered, the client MUST include a redirection URI with the been registered, the client MUST include a redirection URI with the
authorization request using the "redirect_uri" request parameter. authorization request using the "redirect_uri" request parameter.
When a redirection URI is included in an authorization request, the When a redirection URI is included in an authorization request, the
authorization server MUST compare and match the value received authorization server MUST compare and match the value received
against at least one of the registered redirection URIs (or URI against at least one of the registered redirection URIs (or URI
components) as defined in [RFC3986] section 6, if any redirection components) as defined in [RFC3986] section 6, if any redirection
URIs were registered. 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.
If the authorization server allows the client to dynamically change If the authorization server allows the client to dynamically change
the query component of the redirection URI, the client MUST ensure the query component of the redirection URI, the client MUST ensure
that manipulation of the query component by an attacker cannot lead that manipulation of the query component by an attacker cannot lead
to an abuse of the redirection endpoint as an open redirector. to an abuse of the redirection endpoint as described in
Section 10.15.
3.1.2.4. Invalid Endpoint 3.1.2.4. Invalid Endpoint
If an authorization request fails validation due to a missing, If an authorization request fails validation due to a missing,
invalid, or mismatching redirection URI, the authorization server invalid, or mismatching redirection URI, the authorization server
SHOULD inform the resource owner of the error, and MUST NOT SHOULD inform the resource owner of the error, and MUST NOT
automatically redirect the user-agent to the invalid redirection URI. automatically redirect the user-agent to the invalid redirection URI.
The authorization server SHOULD NOT redirect the user-agent to The authorization server SHOULD NOT redirect the user-agent to
unregistered or untrusted URIs to prevent the authorization endpoint unregistered or untrusted URIs to prevent the authorization endpoint
skipping to change at page 18, line 46 skipping to change at page 19, line 9
3.2. Token Endpoint 3.2. Token Endpoint
The token endpoint is used by the client to obtain an access token by The token endpoint is used by the client to obtain an access token by
presenting its authorization grant or refresh token. The token presenting its authorization grant or refresh token. The token
endpoint is used with every authorization grant except for the endpoint is used with every authorization grant except for the
implicit grant type (since an access token is issued directly). implicit grant type (since an access token is issued directly).
The means through which the client obtains the location of the token The means through which the client obtains the location of the token
endpoint are beyond the scope of this specification but is typically endpoint are beyond the scope of this specification but is typically
provided in the service documentation. The endpoint URI MAY include provided in the service documentation.
a query component, which MUST be retained when adding additional
query parameters. 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 Since requests to the token endpoint result in the transmission of
clear-text credentials (in the HTTP request and response), the clear-text credentials (in the HTTP request and response), the
authorization server MUST require the use of a transport-layer authorization server MUST require the use of a transport-layer
security mechanism when sending requests to the token endpoint. The security mechanism when sending requests to the token endpoint. The
authorization server MUST support TLS 1.2 as defined in [RFC5246], authorization server MUST support TLS 1.0 ([RFC2246]), SHOULD support
and MAY support additional transport-layer mechanisms meeting its TLS 1.2 ([RFC5246]) and its future replacements, and MAY support
security requirements. additional transport-layer mechanisms meeting its security
requirements.
The client MUST use the HTTP "POST" method when making access token The client MUST use the HTTP "POST" method when making access token
requests. requests.
Parameters sent without a value MUST be treated as if they were Parameters sent without a value MUST be treated as if they were
omitted from the request. The authorization server SHOULD ignore omitted from the request. The authorization server SHOULD ignore
unrecognized request parameters. Request and response parameters unrecognized request parameters. Request and response parameters
MUST NOT be included more than once. MUST NOT be included more than once.
3.2.1. Client Authentication 3.2.1. Client Authentication
Confidential clients, clients issued client credentials, or clients Confidential clients, clients issued client credentials, or clients
assigned other authentication requirements, MUST authenticate with assigned other authentication requirements, MUST authenticate with
the authorization server as described in Section 2.4 when making the authorization server as described in Section 2.3 when making
requests to the token endpoint. Client authentication is used for: requests to the token endpoint. Client authentication is used for:
o Enforcing the binding of refresh tokens and authorization codes to o Enforcing the binding of refresh tokens and authorization codes to
the client they are issued. Client authentication is critical the client they are issued. Client authentication is critical
when an authorization code is transmitted to the redirection when an authorization code is transmitted to the redirection
endpoint over an insecure channel, or when the redirection URI has endpoint over an insecure channel, or when the redirection URI has
not been registered in full. not been registered in full.
o Recovery from a compromised client by disabling the client or o Recovering from a compromised client by disabling the client or
changing its credentials, by preventing an attacker from abusing changing its credentials, thus preventing an attacker from abusing
stolen refresh tokens. Changing a single set of client stolen refresh tokens. Changing a single set of client
credentials is significantly faster than revoking an entire set of credentials is significantly faster than revoking an entire set of
refresh tokens. refresh tokens.
o Implementing authentication management best practices which o Implementing authentication management best practices which
require periodic credentials rotation. Rotation of an entire set require periodic credential rotation. Rotation of an entire set
of refresh tokens can be challenging, while rotation of a single of refresh tokens can be challenging, while rotation of a single
set of client credentials is significantly easier. 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.
The security ramifications of allowing unauthenticated access by The security ramifications of allowing unauthenticated access by
public clients to the token endpoint MUST be considered, as well as public clients to the token endpoint, as well as the issuance of
the issuance of refresh tokens to public clients, their scope, and refresh tokens to public clients MUST be taken into consideration.
lifetime.
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.
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 SHOULD include the "scope" response parameter to inform the
client of the actual scope granted.
4. Obtaining Authorization 4. Obtaining Authorization
To request an access token, the client obtains authorization from the To request an access token, the client obtains authorization from the
resource owner. The authorization is expressed in the form of an resource owner. The authorization is expressed in the form of an
authorization grant which the client uses to request the access authorization grant which the client uses to request the access
token. OAuth defines four grant types: authorization code, implicit, token. OAuth defines four grant types: authorization code, implicit,
resource owner password credentials, and client credentials. It also resource owner password credentials, and client credentials. It also
provides an extension mechanism for defining additional grant types. provides an extension mechanism for defining additional grant types.
skipping to change at page 21, line 13 skipping to change at page 22, line 4
The flow illustrated in Figure 3 includes the following steps: The flow illustrated in Figure 3 includes the following steps:
(A) The client initiates the flow by directing the resource owner's (A) The client initiates the flow by directing the resource owner's
user-agent to the authorization endpoint. The client includes user-agent to the authorization endpoint. The client includes
its client identifier, requested scope, local state, and a its client identifier, requested scope, local state, and a
redirection URI to which the authorization server will send the redirection URI to which the authorization server will send the
user-agent back once access is granted (or denied). user-agent back once access is granted (or denied).
(B) The authorization server authenticates the resource owner (via (B) The authorization server authenticates the resource owner (via
the user-agent) and establishes whether the resource owner the user-agent) and establishes whether the resource owner
grants or denies the client's access request. grants or denies the client's access request.
(C) Assuming the resource owner grants access, the authorization (C) Assuming the resource owner grants access, the authorization
server redirects the user-agent back to the client using the server redirects the user-agent back to the client using the
redirection URI provided earlier. The redirection URI includes redirection URI provided earlier. The redirection URI includes
an authorization code and any local state provided by the client an authorization code and any local state provided by the client
earlier. earlier.
(D) The client requests an access token from the authorization (D) The client requests an access token from the authorization
server's token endpoint by including the authorization code server's token endpoint by including the authorization code
received in the previous step. When making the request, the received in the previous step. When making the request, the
client authenticates with the authorization server. The client client authenticates with the authorization server. The client
includes the redirection URI used to obtain the authorization includes the redirection URI used to obtain the authorization
code for verification. code for verification.
(E) The authorization server authenticates the client, validates the (E) The authorization server authenticates the client, validates the
authorization code, and ensures the redirection URI received authorization code, and ensures the redirection URI received
matches the URI used to redirect the client in step (C). If matches the URI used to redirect the client in step (C). If
valid, responds back with an access token. valid, responds back with an access token and optional refresh
token.
4.1.1. Authorization Request 4.1.1. Authorization Request
The client constructs the request URI by adding the following The client constructs the request URI by adding the following
parameters to the query component of the authorization endpoint URI parameters to the query component of the authorization endpoint URI
using the "application/x-www-form-urlencoded" format as defined by using the "application/x-www-form-urlencoded" format as defined by
[W3C.REC-html401-19991224]: [W3C.REC-html401-19991224]:
response_type response_type
REQUIRED. Value MUST be set to "code". REQUIRED. Value MUST be set to "code".
client_id client_id
REQUIRED. The client identifier as described in Section 2.3. REQUIRED. The client identifier as described in Section 2.2.
redirect_uri redirect_uri
OPTIONAL, as described in Section 3.1.2. OPTIONAL, as described in Section 3.1.2.
scope scope
OPTIONAL. The scope of the access request expressed as a list OPTIONAL. The scope of the access request as described by
of space-delimited, case sensitive strings. The value is Section 3.3.
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 state
OPTIONAL. An opaque value used by the client to maintain state RECOMMENDED. An opaque value used by the client to maintain
between the request and callback. The authorization server state between the request and callback. The authorization
includes this value when redirecting the user-agent back to the server includes this value when redirecting the user-agent back
client. 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 The client directs the resource owner to the constructed URI using an
HTTP redirection response, or by other means available to it via the HTTP redirection response, or by other means available to it via the
user-agent. user-agent.
For example, the client directs the user-agent to make the following For example, the client directs the user-agent to make the following
HTTP request using transport-layer security (extra line breaks are HTTP request using transport-layer security (extra line breaks are
for display purposes only): for display purposes only):
GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
skipping to change at page 25, line 4 skipping to change at page 25, line 41
Location: https://client.example.com/cb?error=access_denied&state=xyz Location: https://client.example.com/cb?error=access_denied&state=xyz
4.1.3. Access Token Request 4.1.3. Access Token Request
The client makes a request to the token endpoint by adding the The client makes a request to the token endpoint by adding the
following parameters using the "application/x-www-form-urlencoded" following parameters using the "application/x-www-form-urlencoded"
format in the HTTP request entity-body: format in the HTTP request entity-body:
grant_type grant_type
REQUIRED. Value MUST be set to "authorization_code". REQUIRED. Value MUST be set to "authorization_code".
code code
REQUIRED. The authorization code received from the REQUIRED. The authorization code received from the
authorization server. authorization server.
redirect_uri redirect_uri
REQUIRED, if the "redirect_uri" parameter was included in the REQUIRED, if the "redirect_uri" parameter was included in the
authorization request described in Section 4.1.1, and their authorization request described in Section 4.1.1, and their
values MUST be identical. values MUST be identical.
If the client type is confidential or was issued client credentials If the client type is confidential or was issued client credentials
(or assigned other authentication requirements), the client MUST (or assigned other authentication requirements), the client MUST
authenticate with the authorization server as described in authenticate with the authorization server as described in
Section 3.2.1. Section 3.2.1.
For example, the client makes the following HTTP using transport- For example, the client makes the following HTTP request using
layer security (extra line breaks are for display purposes only): transport-layer security (extra line breaks are for display purposes
only):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
The authorization server MUST: The authorization server MUST:
skipping to change at page 28, line 31 skipping to change at page 29, line 31
4.2.1. Authorization Request 4.2.1. Authorization Request
The client constructs the request URI by adding the following The client constructs the request URI by adding the following
parameters to the query component of the authorization endpoint URI parameters to the query component of the authorization endpoint URI
using the "application/x-www-form-urlencoded" format: using the "application/x-www-form-urlencoded" format:
response_type response_type
REQUIRED. Value MUST be set to "token". REQUIRED. Value MUST be set to "token".
client_id client_id
REQUIRED. The client identifier as described in Section 2.3. REQUIRED. The client identifier as described in Section 2.2.
redirect_uri redirect_uri
OPTIONAL, as described in Section 3.1.2. OPTIONAL, as described in Section 3.1.2.
scope scope
OPTIONAL. The scope of the access request expressed as a list OPTIONAL. The scope of the access request as described by
of space-delimited, case sensitive strings. The value is Section 3.3.
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 state
OPTIONAL. An opaque value used by the client to maintain state RECOMMENDED. An opaque value used by the client to maintain
between the request and callback. The authorization server state between the request and callback. The authorization
includes this value when redirecting the user-agent back to the server includes this value when redirecting the user-agent back
client. 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 The client directs the resource owner to the constructed URI using an
HTTP redirection response, or by other means available to it via the HTTP redirection response, or by other means available to it via the
user-agent. user-agent.
For example, the client directs the user-agent to make the following For example, the client directs the user-agent to make the following
HTTP request using transport-layer security (extra line breaks are HTTP request using transport-layer security (extra line breaks are
for display purposes only): for display purposes only):
GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz
skipping to change at page 29, line 45 skipping to change at page 30, line 41
access_token access_token
REQUIRED. The access token issued by the authorization server. REQUIRED. The access token issued by the authorization server.
token_type token_type
REQUIRED. The type of the token issued as described in REQUIRED. The type of the token issued as described in
Section 7.1. Value is case insensitive. Section 7.1. Value is case insensitive.
expires_in expires_in
OPTIONAL. The lifetime in seconds of the access token. For OPTIONAL. The lifetime in seconds of the access token. For
example, the value "3600" denotes that the access token will example, the value "3600" denotes that the access token will
expire in one hour from the time the response was generated. expire in one hour from the time the response was generated.
scope scope
OPTIONAL. The scope of the access token expressed as a list of OPTIONAL. The scope of the access request as described by
space-delimited, case sensitive strings. The value is defined Section 3.3.
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
access token scope is different from the one requested by the
client.
state state
REQUIRED if the "state" parameter was present in the client REQUIRED if the "state" parameter was present in the client
authorization request. Set to the exact value received from authorization request. Set to the exact value received from
the client. the client.
For example, the authorization server redirects the user-agent by For example, the authorization server redirects the user-agent by
sending the following HTTP response (URI extra line breaks are for sending the following HTTP response (URI extra line breaks are for
display purposes only): display purposes only):
HTTP/1.1 302 Found HTTP/1.1 302 Found
skipping to change at page 32, line 5 skipping to change at page 32, line 45
HTTP/1.1 302 Found HTTP/1.1 302 Found
Location: https://client.example.com/cb#error=access_denied&state=xyz Location: https://client.example.com/cb#error=access_denied&state=xyz
4.3. Resource Owner Password Credentials 4.3. Resource Owner Password Credentials
The resource owner password credentials grant type is suitable in The resource owner password credentials grant type is suitable in
cases where the resource owner has a trust relationship with the cases where the resource owner has a trust relationship with the
client, such as its device operating system or a highly privileged client, such as its device operating system or a highly privileged
application. The authorization server should take special care when application. The authorization server should take special care when
enabling the grant type, and only when other flows are not viable. 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 The grant type is suitable for clients capable of obtaining the
resource owner credentials (username and password, typically using an resource owner's credentials (username and password, typically using
interactive form). It is also used to migrate existing clients using an interactive form). It is also used to migrate existing clients
direct authentication schemes such as HTTP Basic or Digest using direct authentication schemes such as HTTP Basic or Digest
authentication to OAuth by converting the stored credentials to an authentication to OAuth by converting the stored credentials to an
access token. access token.
+----------+ +----------+
| Resource | | Resource |
| Owner | | Owner |
| | | |
+----------+ +----------+
v v
| Resource Owner | Resource Owner
skipping to change at page 33, line 19 skipping to change at page 34, line 13
following parameters using the "application/x-www-form-urlencoded" following parameters using the "application/x-www-form-urlencoded"
format in the HTTP request entity-body: format in the HTTP request entity-body:
grant_type grant_type
REQUIRED. Value MUST be set to "password". REQUIRED. Value MUST be set to "password".
username username
REQUIRED. The resource owner username, encoded as UTF-8. REQUIRED. The resource owner username, encoded as UTF-8.
password password
REQUIRED. The resource owner password, encoded as UTF-8. REQUIRED. The resource owner password, encoded as UTF-8.
scope scope
OPTIONAL. The scope of the access request expressed as a list OPTIONAL. The scope of the access request as described by
of space-delimited, case sensitive strings. The value is Section 3.3.
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 client type is confidential or was issued client credentials If the client type is confidential or was issued client credentials
(or assigned other authentication requirements), the client MUST (or assigned other authentication requirements), the client MUST
authenticate with the authorization server as described in authenticate with the authorization server as described in
Section 3.2.1. Section 3.2.1.
For example, the client makes the following HTTP request using For example, the client makes the following HTTP request using
transport-layer security (extra line breaks are for display purposes transport-layer security (extra line breaks are for display purposes
only): only):
skipping to change at page 35, line 36 skipping to change at page 36, line 24
4.4.2. Access Token Request 4.4.2. Access Token Request
The client makes a request to the token endpoint by adding the The client makes a request to the token endpoint by adding the
following parameters using the "application/x-www-form-urlencoded" following parameters using the "application/x-www-form-urlencoded"
format in the HTTP request entity-body: format in the HTTP request entity-body:
grant_type grant_type
REQUIRED. Value MUST be set to "client_credentials". REQUIRED. Value MUST be set to "client_credentials".
scope scope
OPTIONAL. The scope of the access request expressed as a list OPTIONAL. The scope of the access request as described by
of space-delimited, case sensitive strings. The value is Section 3.3.
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 MUST authenticate with the authorization server as The client MUST authenticate with the authorization server as
described in Section 3.2.1. described in Section 3.2.1.
For example, the client makes the following HTTP request using For example, the client makes the following HTTP request using
transport-layer security (extra line breaks are for display purposes transport-layer security (extra line breaks are for display purposes
only): only):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
skipping to change at page 38, line 4 skipping to change at page 38, line 24
access_token access_token
REQUIRED. The access token issued by the authorization server. REQUIRED. The access token issued by the authorization server.
token_type token_type
REQUIRED. The type of the token issued as described in REQUIRED. The type of the token issued as described in
Section 7.1. Value is case insensitive. Section 7.1. Value is case insensitive.
expires_in expires_in
OPTIONAL. The lifetime in seconds of the access token. For OPTIONAL. The lifetime in seconds of the access token. For
example, the value "3600" denotes that the access token will example, the value "3600" denotes that the access token will
expire in one hour from the time the response was generated. expire in one hour from the time the response was generated.
refresh_token refresh_token
OPTIONAL. The refresh token which can be used to obtain new OPTIONAL. The refresh token which can be used to obtain new
access tokens using the same authorization grant as described access tokens using the same authorization grant as described
in Section 6. in Section 6.
scope scope
OPTIONAL. The scope of the access token expressed as a list of OPTIONAL. The scope of the access request as described by
space-delimited, case sensitive strings. The value is defined Section 3.3.
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
access token scope is different from the one requested by the
client.
The parameters are included in the entity body of the HTTP response The parameters are included in the entity body of the HTTP response
using the "application/json" media type as defined by [RFC4627]. The using the "application/json" media type as defined by [RFC4627]. The
parameters are serialized into a JSON structure by adding each parameters are serialized into a JSON structure by adding each
parameter at the highest structure level. Parameter names and string parameter at the highest structure level. Parameter names and string
values are included as JSON strings. Numerical values are included values are included as JSON strings. Numerical values are included
as JSON numbers. as JSON numbers. The order of parameters does not matter and can
vary.
The authorization server MUST include the HTTP "Cache-Control" The authorization server MUST include the HTTP "Cache-Control"
response header field [RFC2616] with a value of "no-store" in any response header field [RFC2616] with a value of "no-store" in any
response containing tokens, credentials, or other sensitive response containing tokens, credentials, or other sensitive
information, as well as the "Pragma" response header field [RFC2616] information, as well as the "Pragma" response header field [RFC2616]
with a value of "no-cache". with a value of "no-cache".
For example: For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
skipping to change at page 39, line 21 skipping to change at page 39, line 41
error error
REQUIRED. A single error code from the following: REQUIRED. A single error code from the following:
invalid_request invalid_request
The request is missing a required parameter, includes an The request is missing a required parameter, includes an
unsupported parameter or parameter value, repeats a unsupported parameter or parameter value, repeats a
parameter, includes multiple credentials, utilizes more parameter, includes multiple credentials, utilizes more
than one mechanism for authenticating the client, or is than one mechanism for authenticating the client, or is
otherwise malformed. otherwise malformed.
invalid_client invalid_client
Client authentication failed (e.g. unknown client, no Client authentication failed (e.g. unknown client, no
client authentication included, multiple client client authentication included, or unsupported
authentications included, or unsupported authentication authentication method). The authorization server MAY
method). The authorization server MAY return an HTTP 401 return an HTTP 401 (Unauthorized) status code to indicate
(Unauthorized) status code to indicate which HTTP which HTTP authentication schemes are supported. If the
authentication schemes are supported. If the client client attempted to authenticate via the "Authorization"
attempted to authenticate via the "Authorization" request request header field, the authorization server MUST
header field, the authorization server MUST respond with respond with an HTTP 401 (Unauthorized) status code, and
an HTTP 401 (Unauthorized) status code, and include the include the "WWW-Authenticate" response header field
"WWW-Authenticate" response header field matching the matching the authentication scheme used by the client.
authentication scheme used by the client.
invalid_grant invalid_grant
The provided authorization grant is invalid, expired, The provided authorization grant is invalid, expired,
revoked, does not match the redirection URI used in the revoked, does not match the redirection URI used in the
authorization request, or was issued to another client. authorization request, or was issued to another client.
unauthorized_client unauthorized_client
The authenticated client is not authorized to use this The authenticated client is not authorized to use this
authorization grant type. authorization grant type.
unsupported_grant_type unsupported_grant_type
The authorization grant type is not supported by the The authorization grant type is not supported by the
authorization server. authorization server.
skipping to change at page 40, line 4 skipping to change at page 40, line 22
unsupported_grant_type unsupported_grant_type
The authorization grant type is not supported by the The authorization grant type is not supported by the
authorization server. authorization server.
invalid_scope invalid_scope
The requested scope is invalid, unknown, malformed, or The requested scope is invalid, unknown, malformed, or
exceeds the scope granted by the resource owner. exceeds the scope granted by the resource owner.
error_description error_description
OPTIONAL. A human-readable UTF-8 encoded text providing OPTIONAL. A human-readable UTF-8 encoded text providing
additional information, used to assist the client developer in additional information, used to assist the client developer in
understanding the error that occurred. understanding the error that occurred.
error_uri error_uri
OPTIONAL. A URI identifying a human-readable web page with OPTIONAL. A URI identifying a human-readable web page with
information about the error, used to provide the client information about the error, used to provide the client
developer with additional information about the error. developer with additional information about the error.
The parameters are included in the entity body of the HTTP response The parameters are included in the entity body of the HTTP response
using the "application/json" media type as defined by [RFC4627]. The using the "application/json" media type as defined by [RFC4627]. The
parameters are serialized into a JSON structure by adding each parameters are serialized into a JSON structure by adding each
parameter at the highest structure level. Parameter names and string parameter at the highest structure level. Parameter names and string
values are included as JSON strings. Numerical values are included values are included as JSON strings. Numerical values are included
as JSON numbers. as JSON numbers. The order of parameters does not matter and can
vary.
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8 Content-Type: application/json;charset=UTF-8
Cache-Control: no-store Cache-Control: no-store
Pragma: no-cache Pragma: no-cache
{ {
"error":"invalid_request" "error":"invalid_request"
skipping to change at page 40, line 40 skipping to change at page 41, line 12
If the authorization server issued a refresh token to the client, the If the authorization server issued a refresh token to the client, the
client makes a refresh request to the token endpoint by adding the client makes a refresh request to the token endpoint by adding the
following parameters using the "application/x-www-form-urlencoded" following parameters using the "application/x-www-form-urlencoded"
format in the HTTP request entity-body: format in the HTTP request entity-body:
grant_type grant_type
REQUIRED. Value MUST be set to "refresh_token". REQUIRED. Value MUST be set to "refresh_token".
refresh_token refresh_token
REQUIRED. The refresh token issued to the client. REQUIRED. The refresh token issued to the client.
scope scope
OPTIONAL. The scope of the access request expressed as a list OPTIONAL. The scope of the access request as described by
of space-delimited, case sensitive strings. The value is Section 3.3. The requested scope MUST be equal or lesser than
defined by the authorization server. If the value contains the scope originally granted by the resource owner, and if
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 omitted is treated as equal to the scope originally granted by
the resource owner. the resource owner.
Because refresh tokens are typically long-lasting credentials used to Because refresh tokens are typically long-lasting credentials used to
request additional access tokens, the refresh token is bound to the request additional access tokens, the refresh token is bound to the
client it was issued. If the client type is confidential or was client it was issued. If the client type is confidential or was
issued client credentials (or assigned other authentication issued client credentials (or assigned other authentication
requirements), the client MUST authenticate with the authorization requirements), the client MUST authenticate with the authorization
server as described in Section 3.2.1. server as described in Section 3.2.1.
skipping to change at page 41, line 30 skipping to change at page 41, line 43
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA
The authorization server MUST: The authorization server MUST:
o require client authentication for confidential clients or for any o require client authentication for confidential clients or for any
client issued client credentials (or with other authentication client issued client credentials (or with other authentication
requirements), requirements),
o authenticate the client if client authentication is included and o authenticate the client if client authentication is included and
ensure the refresh token was issued to the authenticated client, ensure the refresh token was issued to the authenticated client,
o validate the refresh token, and and
o validate the refresh token.
If valid and authorized, the authorization server issues an access If valid and authorized, the authorization server issues an access
token as described in Section 5.1. If the request failed token as described in Section 5.1. If the request failed
verification or is invalid, the authorization server returns an error verification or is invalid, the authorization server returns an error
response as described in Section 5.2. response as described in Section 5.2.
The authorization server MAY issue a new refresh token, in which case 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 the client MUST discard the old refresh token and replace it with the
new refresh token. The authorization server MAY revoke the old new refresh token. The authorization server MAY revoke the old
refresh token after issuing a new refresh token to the client. If a refresh token after issuing a new refresh token to the client. If a
new refresh token is issued, its scope MUST be identical to that of new refresh token is issued, the refresh token scope MUST be
the refresh token included in the request. identical to that of the refresh token included by the client in the
request.
7. Accessing Protected Resources 7. Accessing Protected Resources
The client accesses protected resources by presenting the access The client accesses protected resources by presenting the access
token to the resource server. The resource server MUST validate the token to the resource server. The resource server MUST validate the
access token and ensure it has not expired and that its scope covers access token and ensure it has not expired and that its scope covers
the requested resource. The methods used by the resource server to the requested resource. The methods used by the resource server to
validate the access token (as well as any error responses) are beyond validate the access token (as well as any error responses) are beyond
the scope of this specification, but generally involve an interaction the scope of this specification, but generally involve an interaction
or coordination between the resource server and the authorization or coordination between the resource server and the authorization
skipping to change at page 43, line 12 skipping to change at page 43, line 30
(if any) sent to the client together with the "access_token" response (if any) sent to the client together with the "access_token" response
parameter. It also defines the HTTP authentication method used to parameter. It also defines the HTTP authentication method used to
include the access token when making a protected resource request. include the access token when making a protected resource request.
8. Extensibility 8. Extensibility
8.1. Defining Access Token Types 8.1. Defining Access Token Types
Access token types can be defined in one of two ways: registered in Access token types can be defined in one of two ways: registered in
the access token type registry (following the procedures in the access token type registry (following the procedures in
Section 11.1), or use a unique absolute URI as its name. Section 11.1), or by using a unique absolute URI as its name.
Types utilizing a URI name SHOULD be limited to vendor-specific Types utilizing a URI name SHOULD be limited to vendor-specific
implementations that are not commonly applicable, and are specific to implementations that are not commonly applicable, and are specific to
the implementation details of the resource server where they are the implementation details of the resource server where they are
used. used.
All other types MUST be registered. Type names MUST conform to the All other types MUST be registered. Type names MUST conform to the
type-name ABNF. If the type definition includes a new HTTP type-name ABNF. If the type definition includes a new HTTP
authentication scheme, the type name SHOULD be identical to the HTTP authentication scheme, the type name SHOULD be identical to the HTTP
authentication scheme name (as defined by [RFC2617]). authentication scheme name (as defined by [RFC2617]). The token type
"example" is reserved for use in examples.
type-name = 1*name-char type-name = 1*name-char
name-char = "-" / "." / "_" / DIGIT / ALPHA name-char = "-" / "." / "_" / DIGIT / ALPHA
8.2. Defining New Endpoint Parameters 8.2. Defining New Endpoint Parameters
New request or response parameters for use with the authorization New request or response parameters for use with the authorization
endpoint or the token endpoint are defined and registered in the endpoint or the token endpoint are defined and registered in the
parameters registry following the procedure in Section 11.2. parameters registry following the procedure in Section 11.2.
skipping to change at page 45, line 26 skipping to change at page 45, line 47
related to security, platform capabilities, and overall end-user related to security, platform capabilities, and overall end-user
experience. experience.
The authorization endpoint requires interaction between the client The authorization endpoint requires interaction between the client
and the resource owner's user-agent. Native applications can invoke and the resource owner's user-agent. Native applications can invoke
an external user-agent or embed a user-agent within the application. an external user-agent or embed a user-agent within the application.
For example: For example:
o External user-agent - the native application can capture the o External user-agent - the native application can capture the
response from the authorization server using a redirection URI response from the authorization server using a redirection URI
with an scheme registered with the operating system to invoke the with a scheme registered with the operating system to invoke the
client as the handler, manual copy-and-paste of the credentials, client as the handler, manual copy-and-paste of the credentials,
running a local web server, installing a user-agent extension, or running a local web server, installing a user-agent extension, or
by providing a redirection URI identifying a server-hosted by providing a redirection URI identifying a server-hosted
resource under the client's control, which in turn makes the resource under the client's control, which in turn makes the
response available to the native application. response available to the native application.
o Embedded user-agent - the native application obtains the response o Embedded user-agent - the native application obtains the response
by directly communicating with the embedded user-agent by by directly communicating with the embedded user-agent by
monitoring state changes emitted during the resource load, or monitoring state changes emitted during the resource load, or
accessing the user-agent's cookies storage. accessing the user-agent's cookies storage.
When choosing between an external or embedded user-agent, developers When choosing between an external or embedded user-agent, developers
should consider: should consider:
o External user-agents may improve completion rate as the resource o External user-agents may improve completion rate as the resource
owner may already have an active session with the authorization owner may already have an active session with the authorization
server removing the need to re-authenticate. It provides a server removing the need to re-authenticate. It provides a
familiar end-user experience and functionality. The resource familiar end-user experience and functionality. The resource
owner may also rely on user-agent features or extensions to assist owner may also rely on user-agent features or extensions to assist
with authentication (e.g. password manager, 2-factor device with authentication (e.g. password manager, 2-factor device
reader). reader).
o Embedded user-agents may offer improved usability, as they remove
o Embedded user-agents may offer an improved usability, as they the need to switch context and open new windows.
remove the need to switch context and open new windows.
o Embedded user-agents pose a security challenge because resource o Embedded user-agents pose a security challenge because resource
owners are authenticating in an unidentified window without access owners are authenticating in an unidentified window without access
to the visual protections found in most external user-agents. to the visual protections found in most external user-agents.
Embedded user-agents educate end-user to trust unidentified Embedded user-agents educate end-user to trust unidentified
requests for authentication (making phishing attacks easier to requests for authentication (making phishing attacks easier to
execute). execute).
When choosing between the implicit grant type and the authorization When choosing between the implicit grant type and the authorization
code grant type, the following should be considered: code grant type, the following should be considered:
o Native applications that use the authorization code grant type o Native applications that use the authorization code grant type
SHOULD do so without using client credentials, due to the native SHOULD do so without using client credentials, due to the native
application's inability to keep credentials confidential. application's inability to keep client credentials confidential.
o When using the implicit grant type flow a refresh token is not o When using the implicit grant type flow a refresh token is not
returned. returned which requires repeating the authorization process once
the access token expires.
10. Security Considerations 10. Security Considerations
As a flexible and extensible framework, OAuth's security As a flexible and extensible framework, OAuth's security
considerations depend on many factors. The following sections considerations depend on many factors. The following sections
provide implementers with security guidelines focused on the three provide implementers with security guidelines focused on the three
client profiles described in Section 2.1: web application, user- client profiles described in Section 2.1: web application, user-
agent-based application, and native application. agent-based application, and native application.
A comprehensive OAuth security model and analysis, as well as A comprehensive OAuth security model and analysis, as well as
skipping to change at page 47, line 6 skipping to change at page 47, line 26
The authorization server MUST NOT issue client passwords or other The authorization server MUST NOT issue client passwords or other
client credentials to native application or user-agent-based client credentials to native application or user-agent-based
application clients for the purpose of client authentication. The application clients for the purpose of client authentication. The
authorization server MAY issue a client password or other credentials authorization server MAY issue a client password or other credentials
for a specific installation of a native application client on a for a specific installation of a native application client on a
specific device. specific device.
When client authentication is not possible, the authorization server When client authentication is not possible, the authorization server
SHOULD employ other means to validate the client's identity. For SHOULD employ other means to validate the client's identity. For
example, by requiring the registration of the client redirection URI example, by requiring the registration of the client redirection URI
or enlisting the resource owner to confirm identity. The or enlisting the resource owner to confirm identity. A valid
authorization server must consider the security implications of 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 interacting with unauthenticated clients and take measures to limit
the potential exposure of other credentials (e.g. refresh tokens) the potential exposure of other credentials (e.g. refresh tokens)
issued to such clients. issued to such clients.
10.2. Client Impersonation 10.2. Client Impersonation
A malicious client can impersonate another client and obtain access A malicious client can impersonate another client and obtain access
to protected resources, if the impersonated client fails to, or is to protected resources, if the impersonated client fails to, or is
unable to, keep is client credentials confidential. unable to, keep its client credentials confidential.
The authorization server MUST authenticate the client whenever The authorization server MUST authenticate the client whenever
possible. If the authorization server cannot authenticate the client possible. If the authorization server cannot authenticate the client
due to the client nature, the authorization server MUST require the due to the client's nature, the authorization server MUST require the
registration of any redirection URI used for receiving authorization, registration of any redirection URI used for receiving authorization
and SHOULD utilize other means to protect resource owners from such responses, and SHOULD utilize other means to protect resource owners
malicious clients. For example, engage the resource owner to assist from such malicious clients. For example, engaging the resource
in identifying the client and its origin. owner to assist in identifying the client and its origin.
The authorization server SHOULD enforce explicit resource owner The authorization server SHOULD enforce explicit resource owner
authentication and provide the resource owner with information about authentication and provide the resource owner with information about
the client and the requested authorization scope and lifetime. It is the client and the requested authorization scope and lifetime. It is
up to the resource owner to review the information in the context of up to the resource owner to review the information in the context of
the current client, and authorize the request. the current client, and authorize or deny the request.
The authorization server SHOULD NOT process repeated authorization The authorization server SHOULD NOT process repeated authorization
requests automatically (without active resource owner interaction) requests automatically (without active resource owner interaction)
without authenticating the client or relying on other measures to without authenticating the client or relying on other measures to
ensure the repeated request comes from the original client and not an ensure the repeated request comes from the original client and not an
impersonator. impersonator.
10.3. Access Tokens 10.3. Access Tokens
Access token (as well as any access token type-specific attributes) Access token (as well as any access token type-specific attributes)
MUST be kept confidential in transit and storage, and only shared MUST be kept confidential in transit and storage, and only shared
among the authorization server, the resource servers the access token among the authorization server, the resource servers the access token
is valid for, and the client to whom the access token is issued. is valid for, and the client to whom the access token is issued.
When using the implicit grant type, the access token is transmitted When using the implicit grant type, the access token is transmitted
in the URI fragment, which can expose it to unauthorized parties. in the URI fragment, which can expose it to unauthorized parties.
The authorization server MUST ensure that access tokens cannot be The authorization server MUST ensure that access tokens cannot be
generated, modified, or guessed to produce valid access tokens. generated, modified, or guessed to produce valid access tokens by
unauthorized parties.
The client SHOULD request access tokens with the minimal scope and The client SHOULD request access tokens with the minimal scope and
lifetime necessary. The authorization server SHOULD take the client lifetime necessary. The authorization server SHOULD take the client
identity into account when choosing how to honor the requested scope identity into account when choosing how to honor the requested scope
and lifetime, and MAY issue an access token with a less rights than and lifetime, and MAY issue an access token with a less rights than
requested. requested.
10.4. Refresh Tokens 10.4. Refresh Tokens
Authorization servers MAY issue refresh tokens to web application Authorization servers MAY issue refresh tokens to web application
skipping to change at page 48, line 26 skipping to change at page 49, line 5
refresh tokens were issued. The authorization server MUST maintain refresh tokens were issued. The authorization server MUST maintain
the binding between a refresh token and the client to whom it was the binding between a refresh token and the client to whom it was
issued. issued.
The authorization server MUST verify the binding between the refresh The authorization server MUST verify the binding between the refresh
token and client identity whenever the client identity can be token and client identity whenever the client identity can be
authenticated. When client authentication is not possible, the authenticated. When client authentication is not possible, the
authorization server SHOULD deploy other means to detect refresh authorization server SHOULD deploy other means to detect refresh
token abuse. token abuse.
For example, the authorization server could employ refresh tokens For example, the authorization server could employ refresh token
rotation in which a new refresh token is issued with every access rotation in which a new refresh token is issued with every access
token refresh response. The previous refresh token is invalidated token refresh response. The previous refresh token is invalidated
but retained by the authorization server. If a refresh token is but retained by the authorization server. If a refresh token is
compromised and subsequently used by both the attacker and the compromised and subsequently used by both the attacker and the
legitimate client, one of them will present an invalidated refresh legitimate client, one of them will present an invalidated refresh
token which will inform the authorization server of the breach. token which will inform the authorization server of the breach.
The authorization server MUST ensure that refresh tokens cannot be The authorization server MUST ensure that refresh tokens cannot be
generated, modified, or guessed to produce valid refresh tokens. generated, modified, or guessed to produce valid refresh tokens by
unauthorized parties.
10.5. Authorization Codes 10.5. Authorization Codes
The transmission of authorization codes SHOULD be made over a secure The transmission of authorization codes SHOULD be made over a secure
channel, and the client SHOULD implement TLS for use with its channel, and the client SHOULD implement TLS for use with its
redirection URI if the URI identifies a network resource. Effort redirection URI if the URI identifies a network resource. Effort
should be made to keep authorization codes confidential. Since should be made to keep authorization codes confidential. Since
authorization codes are transmitted via user-agent redirections, they authorization codes are transmitted via user-agent redirections, they
could potentially be disclosed through user-agent history and HTTP could potentially be disclosed through user-agent history and HTTP
referrer headers. referrer headers.
skipping to change at page 49, line 16 skipping to change at page 49, line 44
Authorization codes MUST be short lived and single use. If the Authorization codes MUST be short lived and single use. If the
authorization server observes multiple attempts to exchange an authorization server observes multiple attempts to exchange an
authorization code for an access token, the authorization server authorization code for an access token, the authorization server
SHOULD attempt to revoke all access tokens already granted based on SHOULD attempt to revoke all access tokens already granted based on
the compromised authorization code. the compromised authorization code.
If the client can be authenticated, the authorization servers MUST If the client can be authenticated, the authorization servers MUST
authenticate the client and ensure that the authorization code was authenticate the client and ensure that the authorization code was
issued to the same client. issued to the same client.
10.6. Authorization Code Leakage 10.6. Authorization Code Redirection URI Manipulation
An attacker can leverage the authorization code grant type by When requesting authorization using the authorization code grant
tricking a resource owner to authorize access to a legitimate client, type, the client can specify a redirection URI via the "redirect_uri"
but using a client account under the control of the attacker. The parameter. If an attacker can manipulate the value of the
only difference between a valid request and the attack request is in redirection URI, it can cause the authorization server to redirect
how the victim reached the authorization server to grant access. 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 Once at the authorization server, the victim is prompted with a
normal, valid request on behalf of a legitimate and familiar client. normal, valid request on behalf of a legitimate and familiar client,
The attacker then uses the victim's authorization to gain access to and authorizes the request. The victim is then redirected to an
the information authorized by the victim (via the client). 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, authorization servers MUST ensure In order to prevent such an attack, the authorization server MUST
that the redirection URI used to obtain the authorization code, is ensure that the redirection URI used to obtain the authorization
the same as the redirection URI provided when exchanging the code, is the same as the redirection URI provided when exchanging the
authorization code for an access token. The authorization server authorization code for an access token. The authorization server
SHOULD require the client to register their redirection URI and if MUST require public clients and SHOULD require confidential clients
provided, MUST validate the redirection URI received in the to register their redirection URI and if provided in the request,
authorization request against the registered value. MUST validate the redirection URI received in the authorization
request against the registered value.
10.7. Resource Owner Password Credentials 10.7. Resource Owner Password Credentials
The resource owner password credentials grant type is often used for The resource owner password credentials grant type is often used for
legacy or migration reasons. It reduces the overall risk of storing legacy or migration reasons. It reduces the overall risk of storing
username and password by the client, but does not eliminate the need username and password by the client, but does not eliminate the need
to expose highly privileged credentials to the client. to expose highly privileged credentials to the client.
This grant type carries a higher risk than other grant types because This grant type carries a higher risk than other grant types because
it maintains the password anti-pattern this protocol seeks to avoid. it maintains the password anti-pattern this protocol seeks to avoid.
The client could abuse the password or the password could The client could abuse the password or the password could
unintentionally be disclosed to an attacker (e.g. via log files or unintentionally be disclosed to an attacker (e.g. via log files or
other records kept by the client). other records kept by the client).
Additionally, because the resource owner does not have control over Additionally, because the resource owner does not have control over
the authorization process (the resource owner involvement ends when the authorization process (the resource owner involvement ends when
it hands over its credentials to the client), the client can obtain it hands over its credentials to the client), the client can obtain
access tokens with a broader scope and longer lifetime than desired access tokens with a broader scope and longer lifetime than desired
by the resource owner. The authorization server SHOULD restrict the by the resource owner. The authorization server should consider the
scope and lifetime of access tokens issued via this grant type. scope and lifetime of access tokens issued via this grant type.
The authorization server and client SHOULD minimize use of this grant The authorization server and client SHOULD minimize use of this grant
type and utilize other grant types whenever possible. type and utilize other grant types whenever possible.
10.8. Request Confidentiality 10.8. Request Confidentiality
Access tokens, refresh tokens, resource owner passwords, and client Access tokens, refresh tokens, resource owner passwords, and client
credentials MUST NOT be transmitted in the clear. Authorization credentials MUST NOT be transmitted in the clear. Authorization
codes SHOULD NOT be transmitted in the clear. codes SHOULD NOT be transmitted in the clear.
skipping to change at page 51, line 13 skipping to change at page 52, line 8
Client developers should consider the security implications of how Client developers should consider the security implications of how
they interact with the user-agent (e.g., external, embedded), and the they interact with the user-agent (e.g., external, embedded), and the
ability of the end-user to verify the authenticity of the ability of the end-user to verify the authenticity of the
authorization server. authorization server.
To reduce the risk of phishing attacks, the authorization servers To reduce the risk of phishing attacks, the authorization servers
MUST utilize TLS on every endpoint used for end-user interaction. MUST utilize TLS on every endpoint used for end-user interaction.
10.12. Cross-Site Request Forgery 10.12. Cross-Site Request Forgery
Cross-site request forgery (CSRF) is a web-based attack whereby HTTP Cross-site request forgery (CSRF) is an exploit in which an attacker
requests are transmitted from the user-agent of an end-user the causes the user-agent of a victim end-user to follow a malicious URI
server trusts or has authenticated. CSRF attacks on the (e.g. provided to the user-agent as a misleading link, image, or
authorization endpoint can allow an attacker to obtain authorization redirection) to a trusting server (usually established via the
without the consent of the resource owner. presence of a valid session cookie).
The "state" request parameter SHOULD be used to mitigate against CSRF A CSRF attack against the client's redirection URI allows an attacker
attacks, particularly for login CSRF attacks. CSRF attacks against to inject their own authorization code or access token, which can
the client's redirection URI allow an attacker to inject their own result in the client using an access token associated with the
authorization code or access token, which can result in the client attacker's protected resources rather than the victim's (e.g. save
using an access token associated with the attacker's account rather the victim's bank account information to a protected resource
than the victim's. Depending on the nature of the client and the controlled by the attacker).
protected resources, this can have undesirable and damaging effects.
It is strongly RECOMMENDED that the client includes the "state" The client MUST implement CSRF protection for its redirection URI.
request parameter with authorization requests to the authorization This is typically accomplished by requiring any request sent to the
server. The "state" request parameter MUST contain a non-guessable redirection URI endpoint to include a value that binds the request to
value, and the client MUST keep it in a location accessible only by the user-agent's authenticated state (e.g. a hash of the session
the client or the user-agent (i.e., protected by same-origin policy). cookie used to authentication the user-agent). The client SHOULD
utilize the "state" request parameter to deliver this value to the
authorization server when making an authorization request.
For example, using a DOM variable, HTTP cookie, or HTML5 client-side Once authorization has been obtained from the end-user, the
storage. The authorization server includes the value of the "state" authorization server redirects the end-user's user-agent back to the
parameter when redirecting the user-agent back to the client which client with the required binding value contained in the "state"
MUST then ensure the received value matches the stored value. parameter. The binding value enables the client to validate 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, 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 same-origin policy).
A CSRF attack against the 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 10.13. Clickjacking
In a clickjacking attack, an attacker registers a legitimate client In a clickjacking attack, an attacker registers a legitimate client
and then constructs a malicious site in which it loads the and then constructs a malicious site in which it loads the
authorization server's authorization endpoint web page in a authorization server's authorization endpoint web page in a
transparent iframe overlaid on top of a set of dummy buttons which transparent iframe overlaid on top of a set of dummy buttons which
are carefully constructed to be placed directly under important are carefully constructed to be placed directly under important
buttons on the authorization page. When an end-user clicks a buttons on the authorization page. When an end-user clicks a
misleading visible button, the end-user is actually clicking an misleading visible button, the end-user is actually clicking an
skipping to change at page 52, line 26 skipping to change at page 53, line 41
variable is used by an application in which that input can cause variable is used by an application in which that input can cause
modification of the application logic when used unsanitized. This modification of the application logic when used unsanitized. This
may allow an attacker to gain access to the application device or its 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- data, cause denial of service, or a wide range of malicious side-
effects. effects.
The Authorization server and client MUST validate and sanitize any The Authorization server and client MUST validate and sanitize any
value received, and in particular, the value of the "state" and value received, and in particular, the value of the "state" and
"redirect_uri" parameters. "redirect_uri" parameters.
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. IANA Considerations
11.1. The OAuth Access Token Type Registry 11.1. The OAuth Access Token Type Registry
This specification establishes 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 Access token types are registered on the advice of one or more
Designated Experts (appointed by the IESG or their delegate), with a Designated Experts (appointed by the IESG or their delegate), with a
Specification Required (using terminology from [RFC5226]). However, Specification Required (using terminology from [RFC5226]). However,
to allow for the allocation of values prior to publication, the to allow for the allocation of values prior to publication, the
Designated Expert(s) may approve registration once they are satisfied Designated Expert(s) may approve registration once they are satisfied
that such a specification will be published. that such a specification will be published.
Registration requests should be sent to the [TBD]@ietf.org mailing Registration requests should be sent to the [TBD]@ietf.org mailing
list for review and comment, with an appropriate subject (e.g., list for review and comment, with an appropriate subject (e.g.,
"Request for access toke type: example"). [[ Note to RFC-EDITOR: The "Request for access token type: example"). [[ Note to RFC-EDITOR: The
name of the mailing list should be determined in consultation with name of the mailing list should be determined in consultation with
the IESG and IANA. Suggested name: oauth-ext-review. ]] the IESG and IANA. Suggested name: oauth-ext-review. ]]
Within at most 14 days of the request, the Designated Expert(s) will Within at most 14 days of the request, the Designated Expert(s) will
either approve or deny the registration request, communicating this either approve or deny the registration request, communicating this
decision to the review list and IANA. Denials should include an decision to the review list and IANA. Denials should include an
explanation and, if applicable, suggestions as to how to make the explanation and, if applicable, suggestions as to how to make the
request successful. request successful.
Decisions (or lack thereof) made by the Designated Expert can be Decisions (or lack thereof) made by the Designated Expert can be
skipping to change at page 53, line 17 skipping to change at page 55, line 4
app-ads@tools.ietf.org email address or directly by looking up their app-ads@tools.ietf.org email address or directly by looking up their
email addresses on http://www.iesg.org/ website) and, if the email addresses on http://www.iesg.org/ website) and, if the
appellant is not satisfied with the response, to the full IESG (using appellant is not satisfied with the response, to the full IESG (using
the iesg@iesg.org mailing list). the iesg@iesg.org mailing list).
IANA should only accept registry updates from the Designated IANA should only accept registry updates from the Designated
Expert(s), and should direct all requests for registration to the Expert(s), and should direct all requests for registration to the
review mailing list. review mailing list.
11.1.1. Registration Template 11.1.1. Registration Template
Type name: Type name:
The name requested (e.g., "example"). The name requested (e.g., "example").
Additional Token Endpoint Response Parameters: Additional Token Endpoint Response Parameters:
Additional response parameters returned together with the Additional response parameters returned together with the
"access_token" parameter. New parameters MUST be separately "access_token" parameter. New parameters MUST be separately
registered in the OAuth parameters registry as described by registered in the OAuth parameters registry as described by
Section 11.2. Section 11.2.
HTTP Authentication Scheme(s): HTTP Authentication Scheme(s):
The HTTP authentication scheme name(s), if any, used to The HTTP authentication scheme name(s), if any, used to
authenticate protected resources requests using access token of authenticate protected resources requests using access tokens of
this type. this type.
Change controller: Change controller:
For standards-track RFCs, state "IETF". For others, give the name For standards-track RFCs, state "IETF". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
e-mail address, home page URI) may also be included. e-mail address, home page URI) may also be included.
Specification document(s): Specification document(s):
Reference to document that specifies the parameter, preferably Reference to the document that specifies the parameter, preferably
including a URI that can be used to retrieve a copy of the including a URI that can be used to retrieve a copy of the
document. An indication of the relevant sections may also be document. An indication of the relevant sections may also be
included, but is not required. included, but is not required.
11.2. The OAuth Parameters Registry 11.2. The OAuth Parameters Registry
This specification establishes the OAuth parameters registry. This specification establishes the OAuth parameters registry.
Additional parameters for inclusion in the authorization endpoint Additional parameters for inclusion in the authorization endpoint
request, the authorization endpoint response, the token endpoint request, the authorization endpoint response, the token endpoint
skipping to change at page 54, line 39 skipping to change at page 56, line 26
The name requested (e.g., "example"). The name requested (e.g., "example").
Parameter usage location: Parameter usage location:
The location(s) where parameter can be used. The possible The location(s) where parameter can be used. The possible
locations are: authorization request, authorization response, locations are: authorization request, authorization response,
token request, or token response. token request, or token response.
Change controller: Change controller:
For standards-track RFCs, state "IETF". For others, give the name For standards-track RFCs, state "IETF". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
e-mail address, home page URI) may also be included. e-mail address, home page URI) may also be included.
Specification document(s): Specification document(s):
Reference to document that specifies the parameter, preferably Reference to the document that specifies the parameter, preferably
including a URI that can be used to retrieve a copy of the including a URI that can be used to retrieve a copy of the
document. An indication of the relevant sections may also be document. An indication of the relevant sections may also be
included, but is not required. included, but is not required.
11.2.2. Initial Registry Contents 11.2.2. Initial Registry Contents
The OAuth Parameters Registry's initial contents are: The OAuth Parameters Registry's initial contents are:
o Parameter name: client_id o Parameter name: client_id
o Parameter usage location: authorization request, token request o Parameter usage location: authorization request, token request
skipping to change at page 57, line 35 skipping to change at page 59, line 21
11.3.1. Registration Template 11.3.1. Registration Template
Response type name: Response type name:
The name requested (e.g., "example"). The name requested (e.g., "example").
Change controller: Change controller:
For standards-track RFCs, state "IETF". For others, give the name For standards-track RFCs, state "IETF". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
e-mail address, home page URI) may also be included. e-mail address, home page URI) may also be included.
Specification document(s): Specification document(s):
Reference to document that specifies the type, preferably Reference to the document that specifies the type, preferably
including a URI that can be used to retrieve a copy of the including a URI that can be used to retrieve a copy of the
document. An indication of the relevant sections may also be document. An indication of the relevant sections may also be
included, but is not required. included, but is not required.
11.3.2. Initial Registry Contents 11.3.2. Initial Registry Contents
The OAuth Authorization Endpoint Response Type Registry's initial The OAuth Authorization Endpoint Response Type Registry's initial
contents are: contents are:
o Response type name: code o Response type name: code
skipping to change at page 59, line 4 skipping to change at page 60, line 37
11.4.1. Registration Template 11.4.1. Registration Template
Error name: Error name:
The name requested (e.g., "example"). The name requested (e.g., "example").
Error usage location: Error usage location:
The location(s) where the error can be used. The possible The location(s) where the error can be used. The possible
locations are: authorization code grant error response locations are: authorization code grant error response
(Section 4.1.2.1), implicit grant error response (Section 4.1.2.1), implicit grant error response
(Section 4.2.2.1), or token error response (Section 5.2). (Section 4.2.2.1), or token error response (Section 5.2).
Related protocol extension: Related protocol extension:
The name of the extension grant type, access token type, or The name of the extension grant type, access token type, or
extension parameter, the error code is used in conjunction with. extension parameter, the error code is used in conjunction with.
Change controller: Change controller:
For standards-track RFCs, state "IETF". For others, give the name For standards-track RFCs, state "IETF". For others, give the name
of the responsible party. Other details (e.g., postal address, of the responsible party. Other details (e.g., postal address,
e-mail address, home page URI) may also be included. e-mail address, home page URI) may also be included.
Specification document(s): Specification document(s):
Reference to document that specifies the error code, preferably Reference to the document that specifies the error code,
including a URI that can be used to retrieve a copy of the preferably including a URI that can be used to retrieve a copy of
document. An indication of the relevant sections may also be the document. An indication of the relevant sections may also be
included, but is not required. included, but is not required.
12. Acknowledgements 12. Acknowledgements
The initial OAuth 2.0 protocol specification was edited by David The initial OAuth 2.0 protocol specification was edited by David
Recordon, based on two previous publications: the OAuth 1.0 community Recordon, based on two previous publications: the OAuth 1.0 community
specification [RFC5849], and OAuth WRAP (OAuth Web Resource specification [RFC5849], and OAuth WRAP (OAuth Web Resource
Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security
Considerations section was drafted by Torsten Lodderstedt, Mark Considerations section was drafted by Torsten Lodderstedt, Mark
McGloin, Phil Hunt, and Anthony Nadalin. McGloin, Phil Hunt, and Anthony Nadalin.
skipping to change at page 59, line 49 skipping to change at page 61, line 36
includes dozens of active and dedicated participants. In particular, includes dozens of active and dedicated participants. In particular,
the following individuals contributed ideas, feedback, and wording the following individuals contributed ideas, feedback, and wording
which shaped and formed the final specification: which shaped and formed the final specification:
Michael Adams, Andrew Arnott, Dirk Balfanz, Aiden Bell, Scott Cantor, Michael Adams, Andrew Arnott, Dirk Balfanz, Aiden Bell, Scott Cantor,
Marcos Caceres, Blaine Cook, Brian Campbell, Brian Eaton, Leah Marcos Caceres, Blaine Cook, Brian Campbell, Brian Eaton, Leah
Culver, Bill de hOra, Brian Eaton, Brian Ellin, Igor Faynberg, George Culver, Bill de hOra, Brian Eaton, Brian Ellin, Igor Faynberg, George
Fletcher, Tim Freeman, Evan Gilbert, Yaron Goland, Brent Goldman, Fletcher, Tim Freeman, Evan Gilbert, Yaron Goland, Brent Goldman,
Kristoffer Gronowski, Justin Hart, Dick Hardt, Craig Heath, Phil Kristoffer Gronowski, Justin Hart, Dick Hardt, Craig Heath, Phil
Hunt, Michael B. Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen Hunt, Michael B. Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen
Le Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Paul Le Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey
Madsen, Alastair Mair, Eve Maler, James Manger, Mark McGloin, Lucas, Paul Madsen, Alastair Mair, Eve Maler, James Manger, Mark
Laurence Miao, Chuck Mortimore, Anthony Nadalin, Justin Richer, Peter McGloin, Laurence Miao, Chuck Mortimore, Anthony Nadalin, Justin
Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu,
Luke Shepard, Vlad Skvortsov, Justin Smith, Jeremy Suriel, Christian Naitik Shah, Luke Shepard, Vlad Skvortsov, Justin Smith, Niv
Stuebner, Paul Tarjan, Allen Tom, Franklin Tse, Nick Walker, Shane Steingarten, Christian Stuebner, Jeremy Suriel, Paul Tarjan, Allen
Weeden, and Skylar Woodward. Tom, Franklin Tse, Nick Walker, Shane Weeden, and Skylar Woodward.
Appendix A. Editor's Notes Appendix A. Editor's Notes
While many people contributed to this specification throughout its While many people contributed to this specification throughout its
long journey, the editor would like to acknowledge and thank a few long journey, the editor would like to acknowledge and thank a few
individuals for their outstanding and invaluable efforts leading up individuals for their outstanding and invaluable efforts leading up
to the publication of this specification. It is these individuals to the publication of this specification. It is these individuals
without whom this work would not have existed or reached its without whom this work would not have existed or reached its
successful conclusion. successful conclusion.
skipping to change at page 60, line 43 skipping to change at page 62, line 30
Special thanks goes to Mike Curtis and Yahoo! for their unconditional Special thanks goes to Mike Curtis and Yahoo! for their unconditional
support of this work for over three years. support of this work for over three years.
13. References 13. References
13.1. Normative References 13.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. 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., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A., and L. Stewart, "HTTP Leach, P., Luotonen, A., and L. Stewart, "HTTP
Authentication: Basic and Digest Access Authentication", Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999. RFC 2617, June 1999.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
skipping to change at page 61, line 29 skipping to change at page 63, line 17
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. May 2008.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[W3C.REC-html401-19991224] [W3C.REC-html401-19991224]
Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01
Specification", World Wide Web Consortium Specification", World Wide Web Consortium
Recommendation REC-html401-19991224, December 1999, Recommendation REC-html401-19991224, December 1999,
<http://www.w3.org/TR/1999/REC-html401-19991224>. <http://www.w3.org/TR/1999/REC-html401-19991224>.
13.2. Informative References 13.2. Informative References
[I-D.draft-hardt-oauth-01] [I-D.draft-hardt-oauth-01]
Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth
Web Resource Authorization Profiles", January 2010. Web Resource Authorization Profiles", January 2010.
 End of changes. 126 change blocks. 
356 lines changed or deleted 431 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/