draft-ietf-oauth-v2-28.txt   draft-ietf-oauth-v2-29.txt 
OAuth Working Group E. Hammer, Ed. OAuth Working Group D. Hardt, Ed.
Internet-Draft Internet-Draft Microsoft
Obsoletes: 5849 (if approved) D. Recordon Obsoletes: 5849 (if approved) D. Recordon
Intended status: Standards Track Facebook Intended status: Standards Track Facebook
Expires: December 21, 2012 D. Hardt Expires: January 13, 2013 July 12, 2012
Microsoft
June 19, 2012
The OAuth 2.0 Authorization Framework The OAuth 2.0 Authorization Framework
draft-ietf-oauth-v2-28 draft-ietf-oauth-v2-29
Abstract Abstract
The OAuth 2.0 authorization framework enables a third-party The OAuth 2.0 authorization framework 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. This third-party application to obtain access on its own behalf. This
specification replaces and obsoletes the OAuth 1.0 protocol described specification replaces and obsoletes the OAuth 1.0 protocol described
in RFC 5849. in RFC 5849.
skipping to change at page 1, line 39 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 December 21, 2012. This Internet-Draft will expire on January 13, 2013.
Copyright Notice Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the Copyright (c) 2012 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 25 skipping to change at page 2, line 23
1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 8 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 8
1.3.1. Authorization Code . . . . . . . . . . . . . . . . . . 8 1.3.1. Authorization Code . . . . . . . . . . . . . . . . . . 8
1.3.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8 1.3.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.3. Resource Owner Password Credentials . . . . . . . . . 9 1.3.3. Resource Owner Password Credentials . . . . . . . . . 9
1.3.4. Client Credentials . . . . . . . . . . . . . . . . . . 9 1.3.4. Client Credentials . . . . . . . . . . . . . . . . . . 9
1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9
1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 10 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 10
1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 12 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 12
1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 12 1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 12
1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 12 1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 12
1.9. Notational Conventions . . . . . . . . . . . . . . . . . 13 1.9. Notational Conventions . . . . . . . . . . . . . . . . . 12
2. Client Registration . . . . . . . . . . . . . . . . . . . . . 13 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 13
2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 14 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 13
2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 15 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 15
2.3. Client Authentication . . . . . . . . . . . . . . . . . . 15 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 15
2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 16 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 15
2.3.2. Other Authentication Methods . . . . . . . . . . . . . 17 2.3.2. Other Authentication Methods . . . . . . . . . . . . . 17
2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 17 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 17
3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 17 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 17
3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 17 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 17
3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 18 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 18
3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 19 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 18
3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 21 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 21
3.2.1. Client Authentication . . . . . . . . . . . . . . . . 21 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 21
3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 22 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 22
4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 23 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 22
4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 23 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 23
4.1.1. Authorization Request . . . . . . . . . . . . . . . . 24 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 24
4.1.2. Authorization Response . . . . . . . . . . . . . . . . 25 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 25
4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 27 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 27
4.1.4. Access Token Response . . . . . . . . . . . . . . . . 28 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 28
4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 29 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 29
4.2.1. Authorization Request . . . . . . . . . . . . . . . . 31 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 31
4.2.2. Access Token Response . . . . . . . . . . . . . . . . 32 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 32
4.3. Resource Owner Password Credentials Grant . . . . . . . . 35 4.3. Resource Owner Password Credentials Grant . . . . . . . . 35
4.3.1. Authorization Request and Response . . . . . . . . . . 36 4.3.1. Authorization Request and Response . . . . . . . . . . 36
skipping to change at page 3, line 16 skipping to change at page 3, line 15
4.4. Client Credentials Grant . . . . . . . . . . . . . . . . 37 4.4. Client Credentials Grant . . . . . . . . . . . . . . . . 37
4.4.1. Authorization Request and Response . . . . . . . . . . 38 4.4.1. Authorization Request and Response . . . . . . . . . . 38
4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 38 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 38
4.4.3. Access Token Response . . . . . . . . . . . . . . . . 39 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 39
4.5. Extension Grants . . . . . . . . . . . . . . . . . . . . 39 4.5. Extension Grants . . . . . . . . . . . . . . . . . . . . 39
5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 40 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 40
5.1. Successful Response . . . . . . . . . . . . . . . . . . . 40 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 40
5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 41 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 41
6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 43 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 43
7. Accessing Protected Resources . . . . . . . . . . . . . . . . 44 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 44
7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 45 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 44
7.2. Error Response . . . . . . . . . . . . . . . . . . . . . 46 7.2. Error Response . . . . . . . . . . . . . . . . . . . . . 45
8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 46 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 46
8.1. Defining Access Token Types . . . . . . . . . . . . . . . 46 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 46
8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 47 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 46
8.3. Defining New Authorization Grant Types . . . . . . . . . 47 8.3. Defining New Authorization Grant Types . . . . . . . . . 47
8.4. Defining New Authorization Endpoint Response Types . . . 47 8.4. Defining New Authorization Endpoint Response Types . . . 47
8.5. Defining Additional Error Codes . . . . . . . . . . . . . 48 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 47
9. Native Applications . . . . . . . . . . . . . . . . . . . . . 48 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 48
10. Security Considerations . . . . . . . . . . . . . . . . . . . 49 10. Security Considerations . . . . . . . . . . . . . . . . . . . 49
10.1. Client Authentication . . . . . . . . . . . . . . . . . . 50 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 49
10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 50 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 50
10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 51 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 50
10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 51 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 51
10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 52 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 51
10.6. Authorization Code Redirection URI Manipulation . . . . . 53 10.6. Authorization Code Redirection URI Manipulation . . . . . 52
10.7. Resource Owner Password Credentials . . . . . . . . . . . 53 10.7. Resource Owner Password Credentials . . . . . . . . . . . 53
10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 54 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 53
10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 54 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 53
10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 54 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 54
10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 54 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 54
10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 55 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 54
10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 56 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 55
10.14. Code Injection and Input Validation . . . . . . . . . . . 56 10.14. Code Injection and Input Validation . . . . . . . . . . . 56
10.15. Open Redirectors . . . . . . . . . . . . . . . . . . . . 57 10.15. Open Redirectors . . . . . . . . . . . . . . . . . . . . 56
10.16. Misuse of Access Token to Impersonate Resource Owner
in Implicit Flow . . . . . . . . . . . . . . . . . . . . 56
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57
11.1. The OAuth Access Token Type Registry . . . . . . . . . . 57 11.1. OAuth Access Token Type Registry . . . . . . . . . . . . 57
11.1.1. Registration Template . . . . . . . . . . . . . . . . 58 11.1.1. Registration Template . . . . . . . . . . . . . . . . 58
11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 58 11.2. OAuth Parameters Registry . . . . . . . . . . . . . . . . 58
11.2.1. Registration Template . . . . . . . . . . . . . . . . 59 11.2.1. Registration Template . . . . . . . . . . . . . . . . 59
11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 59 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 59
11.3. The OAuth Authorization Endpoint Response Type 11.3. OAuth Authorization Endpoint Response Type Registry . . . 61
Registry . . . . . . . . . . . . . . . . . . . . . . . . 61 11.3.1. Registration Template . . . . . . . . . . . . . . . . 62
11.3.1. Registration Template . . . . . . . . . . . . . . . . 61
11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 62 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 62
11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 62 11.4. OAuth Extensions Error Registry . . . . . . . . . . . . . 62
11.4.1. Registration Template . . . . . . . . . . . . . . . . 63 11.4.1. Registration Template . . . . . . . . . . . . . . . . 63
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 63
12.1. Normative References . . . . . . . . . . . . . . . . . . 63 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 64
12.2. Informative References . . . . . . . . . . . . . . . . . 64 12.1. Normative References . . . . . . . . . . . . . . . . . . 64
Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 65 12.2. Informative References . . . . . . . . . . . . . . . . . 65
Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 66
A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 66 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 66
A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 66 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 66
A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 66 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 66
A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 66 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 67
A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 66 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 67
A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 66 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 67
A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 67 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 67
A.8. "error_description" Syntax . . . . . . . . . . . . . . . 67 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 67
A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 67 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 67
A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 67 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 68
A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 67 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 68
A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 67 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 68
A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 68 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 68
A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 68 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 68
A.15. "username" Syntax . . . . . . . . . . . . . . . . . . . . 68 A.15. "username" Syntax . . . . . . . . . . . . . . . . . . . . 68
A.16. "password" Syntax . . . . . . . . . . . . . . . . . . . . 68 A.16. "password" Syntax . . . . . . . . . . . . . . . . . . . . 69
A.17. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 68 A.17. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 69
A.18. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 68 A.18. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 69
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 68 Appendix B. Use of application/x-www-form-urlencoded Media
Appendix C. Editor's Notes . . . . . . . . . . . . . . . . . . . 69 Type . . . . . . . . . . . . . . . . . . . . . . . . 69
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 70 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 70
Appendix D. Document History . . . . . . . . . . . . . . . . . . 71
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 72
1. Introduction 1. Introduction
In the traditional client-server authentication model, the client In the traditional client-server authentication model, the client
requests an access restricted resource (protected resource) on the requests an access restricted resource (protected resource) on the
server by authenticating with the server using the resource owner's server by authenticating with the server using the resource owner's
credentials. In order to provide third-party applications access to credentials. In order to provide third-party applications access to
restricted resources, the resource owner shares its credentials with restricted resources, the resource owner shares its credentials with
the third-party. This creates several problems and limitations: the third-party. This creates several problems and limitations:
skipping to change at page 5, line 49 skipping to change at page 5, line 49
specific scope, lifetime, and other access attributes. Access tokens specific scope, lifetime, and other access attributes. Access tokens
are issued to third-party clients by an authorization server with the are issued to third-party clients by an authorization server with the
approval of the resource owner. The client uses the access token to approval of the resource owner. The client uses the access token to
access the protected resources hosted by the resource server. access the protected resources hosted by the resource server.
For example, an end-user (resource owner) can grant a printing For example, an end-user (resource owner) can grant a printing
service (client) access to her protected photos stored at a photo service (client) access to her protected photos stored at a photo
sharing service (resource server), without sharing her username and sharing service (resource server), without sharing her username and
password with the printing service. Instead, she authenticates password with the printing service. Instead, she authenticates
directly with a server trusted by the photo sharing service directly with a server trusted by the photo sharing service
(authorization server) which issues the printing service delegation- (authorization server), which issues the printing service delegation-
specific credentials (access token). specific credentials (access token).
This specification is designed for use with HTTP ([RFC2616]). The This specification is designed for use with HTTP ([RFC2616]). The
use of OAuth over any other protocol than HTTP is out of scope. use of OAuth over any other protocol than HTTP is out of scope.
The OAuth 1.0 protocol ([RFC5849]), published as an informational The OAuth 1.0 protocol ([RFC5849]), published as an informational
document, was the result of a small ad-hoc community effort. This document, was the result of a small ad-hoc community effort. This
standards-track specification builds on the OAuth 1.0 deployment standards-track specification builds on the OAuth 1.0 deployment
experience, as well as additional use cases and extensibility experience, as well as additional use cases and extensibility
requirements gathered from the wider IETF community. The OAuth 2.0 requirements gathered from the wider IETF community. The OAuth 2.0
skipping to change at page 7, line 27 skipping to change at page 7, line 27
| | +---------------+ | | +---------------+
| | | |
| | +---------------+ | | +---------------+
| |--(E)----- Access Token ------>| Resource | | |--(E)----- Access Token ------>| Resource |
| | | Server | | | | Server |
| |<-(F)--- Protected Resource ---| | | |<-(F)--- Protected Resource ---| |
+--------+ +---------------+ +--------+ +---------------+
Figure 1: Abstract Protocol Flow Figure 1: Abstract Protocol Flow
The abstract flow illustrated in Figure 1 describes the interaction The abstract OAuth 2.0 flow illustrated in Figure 1 describes the
between the four roles and includes the following steps: interaction 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 the authorization (as shown), or preferably indirectly via the authorization
server as an intermediary. server as an intermediary.
(B) The client receives an authorization grant which is a credential (B) The client receives an authorization grant, which is a
representing the resource owner's authorization, expressed using credential representing the resource owner's authorization,
one of four grant types defined in this specification or using expressed using one of four grant types defined in this
an extension grant type. The authorization grant type depends specification or using an extension grant type. The
on the method used by the client to request authorization and authorization grant type depends on the method used by the
the types supported by the authorization server. 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.
The preferred method for the client to obtain an authorization grant The preferred method for the client to obtain an authorization grant
from the resource owner (depicted in steps (A) and (B)) is to use the from the resource owner (depicted in steps (A) and (B)) is to use the
authorization server as an intermediary which is illustrated in authorization server as an intermediary, which is illustrated in
Figure 3. Figure 3.
1.3. Authorization Grant 1.3. Authorization Grant
An authorization grant is a credential representing the resource An authorization grant is a credential representing the resource
owner's authorization (to access its protected resources) used by the owner's authorization (to access its protected resources) used by the
client to obtain an access token. This specification defines four client to obtain an access token. This specification defines four
grant types: authorization code, implicit, resource owner password grant types: authorization code, implicit, resource owner password
credentials, and client credentials, as well as an extensibility credentials, and client credentials, as well as an extensibility
mechanism for defining additional types. mechanism for defining additional types.
skipping to change at page 9, line 10 skipping to change at page 9, line 9
authorization server does not authenticate the client. In some authorization server does not authenticate the client. In some
cases, the client identity can be verified via the redirection URI cases, the client identity can be verified via the redirection URI
used to deliver the access token to the client. The access token may used to deliver the access token to the client. The access token may
be exposed to the resource owner or other applications with access to be exposed to the resource owner or other applications with access to
the resource owner's user-agent. 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 weighed 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, such as those
the authorization code grant type is available. described in Section 10.3 and Section 10.16, especially when the
authorization code grant type is available.
1.3.3. Resource Owner Password Credentials 1.3.3. Resource Owner Password Credentials
The resource owner password credentials (i.e. username and password) The resource owner password credentials (i.e. username and password)
can be used directly as an authorization grant to obtain an access can be used directly as an authorization grant to obtain an access
token. The credentials should only be used when there is a high token. The credentials should only be used when there is a high
degree of trust between the resource owner and the client (e.g. the degree of trust between the resource owner and the client (e.g. the
client is part of the device operating system or a highly privileged client is part of the device operating system or a highly privileged
application), and when other authorization grant types are not application), and when other authorization grant types are not
available (such as an authorization code). available (such as an authorization code).
skipping to change at page 12, line 28 skipping to change at page 12, line 22
has a very limited deployment base and might not be readily available has a very limited deployment base and might not be readily available
for implementation. TLS version 1.0 [RFC2246] is the most widely for implementation. TLS version 1.0 [RFC2246] is the most widely
deployed version, and will provide the broadest interoperability. deployed version, and will provide the broadest interoperability.
Implementations MAY also support additional transport-layer security Implementations MAY also support additional transport-layer security
mechanisms that meet their security requirements. mechanisms that meet their security requirements.
1.7. HTTP Redirections 1.7. HTTP Redirections
This specification makes extensive use of HTTP redirections, in which This specification makes extensive use of HTTP redirections, in which
the client or the authorization server direct the resource owner's the client or the authorization server directs the resource owner's
user-agent to another destination. While the examples in this user-agent to another destination. While the examples in this
specification show the use of the HTTP 302 status code, any other specification show the use of the HTTP 302 status code, any other
method available via the user-agent to accomplish this redirection is method available via the user-agent to accomplish this redirection is
allowed and is considered to be an implementation detail. allowed and is considered to be an implementation detail.
1.8. Interoperability 1.8. Interoperability
OAuth 2.0 provides a rich authorization framework with well-defined OAuth 2.0 provides a rich authorization framework with well-defined
security properties. However, as a rich and highly extensible security properties. However, as a rich and highly extensible
framework with many optional components, on its own, this framework with many optional components, on its own, this
skipping to change at page 16, line 10 skipping to change at page 15, line 51
client. 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.3.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 encoded using the the authorization server. The client identifier is encoded using the
"application/x-www-form-urlencoded" content-type encoding method "application/x-www-form-urlencoded" encoding algorithm per Appendix B
defined by HTML 4.01 [W3C.REC-html401-19991224] and the encoded value and the encoded value is used as the username; the client password is
is used as the username; the client password is used as the password. encoded using the same algorithm and used as the password. The
The authorization server MUST support the HTTP Basic authentication authorization server MUST support the HTTP Basic authentication
scheme for authenticating clients that were issued a client password. scheme for authenticating clients that were issued a client password.
For example (extra line breaks are for display purposes only): For example (with extra line breaks for display purposes only):
Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
Alternatively, the authorization server MAY support including the Alternatively, the authorization server MAY support 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.2. the registration process described by Section 2.2.
skipping to change at page 16, line 39 skipping to change at page 16, line 32
parameter if the client secret is an empty string. 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). The parameters other password-based HTTP authentication schemes). The parameters
can only be transmitted in the request body and MUST NOT be included can only be transmitted in the request body and MUST NOT be included
in the request URI. in the request URI.
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 (with extra line breaks for display purposes
only): only):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Content-Type: application/x-www-form-urlencoded
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 TLS as described in The authorization server MUST require the use of TLS as described in
Section 1.6 when sending requests using password authentication. Section 1.6 when sending requests using password authentication.
Since this client authentication method involves a password, the Since this client authentication method involves a password, the
authorization server MUST protect any endpoint utilizing it against authorization server MUST protect any endpoint utilizing it against
brute force attacks. brute force attacks.
skipping to change at page 18, line 4 skipping to change at page 17, line 45
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 an authorization grant. The authorization server owner and obtain an authorization grant. The authorization server
MUST first verify the identity of the resource owner. The way in MUST first verify the identity of the resource owner. The way in
which the authorization server authenticates the resource owner (e.g. which the authorization server authenticates the resource owner (e.g.
username and password login, session cookies) is beyond the scope of username and password login, session cookies) is beyond the scope of
this specification. 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, authorization endpoint are beyond the scope of this specification,
but the location is typically provided in the service documentation. but the location is typically provided in the service documentation.
The endpoint URI MAY include an "application/x-www-form-urlencoded" The endpoint URI MAY include an "application/x-www-form-urlencoded"
formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] formatted (per Appendix B) query component ([RFC3986] section 3.4),
section 3.4), which MUST be retained when adding additional query which MUST be retained when adding additional query parameters. The
parameters. The endpoint URI MUST NOT include a fragment component. 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 TLS HTTP response), the authorization server MUST require the use of TLS
as described in Section 1.6 when sending requests to the as described in Section 1.6 when sending requests to the
authorization endpoint. authorization endpoint.
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.
skipping to change at page 19, line 17 skipping to change at page 19, line 10
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
making 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. The endpoint URI MAY include an [RFC3986] section 4.3. The endpoint URI MAY include an
"application/x-www-form-urlencoded" formatted "application/x-www-form-urlencoded" formatted (per Appendix B) query
([W3C.REC-html401-19991224]) query component ([RFC3986] section 3.4), component ([RFC3986] section 3.4), which MUST be retained when adding
which MUST be retained when adding additional query parameters. The additional query parameters. The endpoint URI MUST NOT include a
endpoint URI MUST NOT include a fragment component. fragment component.
3.1.2.1. Endpoint Request Confidentiality 3.1.2.1. Endpoint Request Confidentiality
The redirection endpoint SHOULD require the use of TLS as described The redirection endpoint SHOULD require the use of TLS as described
in Section 1.6 when the requested response type is "code" or "token", in Section 1.6 when the requested response type is "code" or "token",
or when the redirection request will result in the transmission of or when the redirection request will result in the transmission of
sensitive credentials over an open network. This specification does sensitive credentials over an open network. This specification does
not mandate the use of TLS because at the time of this writing, not mandate the use of TLS because at the time of this writing,
requiring clients to deploy TLS is a significant hurdle for many requiring clients to deploy TLS is a significant hurdle for many
client developers. If TLS is not available, the authorization server client developers. If TLS is not available, the authorization server
skipping to change at page 21, line 23 skipping to change at page 21, line 17
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. provided in the service documentation.
The endpoint URI MAY include an "application/x-www-form-urlencoded" The endpoint URI MAY include an "application/x-www-form-urlencoded"
formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] formatted (per Appendix B) query component ([RFC3986] section 3.4),
section 3.4), which MUST be retained when adding additional query which MUST be retained when adding additional query parameters. The
parameters. The endpoint URI MUST NOT include a fragment component. 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 TLS as described in authorization server MUST require the use of TLS as described in
Section 1.6 when sending requests to the token endpoint. Section 1.6 when sending requests to the token endpoint.
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
skipping to change at page 22, line 4 skipping to change at page 21, line 46
Confidential clients or other clients issued client credentials MUST Confidential clients or other clients issued client credentials MUST
authenticate with the authorization server as described in authenticate with the authorization server as described in
Section 2.3 when making requests to the token endpoint. Client Section 2.3 when making requests to the token endpoint. Client
authentication is used for: 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 were issued to. Client authentication is critical the client they were issued to. 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 Recovering from a compromised client by disabling the client or o Recovering from a compromised client by disabling the client or
changing its credentials, thus 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 credential 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 A public client that was not issued a client password MUST use the
"client_id" request parameter to identify itself when sending "client_id" request parameter to identify itself when sending
requests to the token endpoint (e.g. for the purpose of providing requests to the token endpoint. This allows the authorization server
end-user context, client usage statistics). to ensure that the code was issued to the same client. Sending
"client_id" prevents the client from inadvertently accepting a code
intended for a client with a different "client_id". This protects
the client from substitution of the authentication code. (It
provides no additional security for the protected resource.)
3.3. Access Token Scope 3.3. Access Token Scope
The authorization and token endpoints allow the client to specify the The authorization and token endpoints allow the client to specify the
scope of the access request using the "scope" request parameter. In scope of the access request using the "scope" request parameter. In
turn, the authorization server uses the "scope" response parameter to turn, the authorization server uses the "scope" response parameter to
inform the client of the scope of the access token issued. inform the client of the scope of the access token issued.
The value of the scope parameter is expressed as a list of space- The value of the scope parameter is expressed as a list of space-
delimited, case sensitive strings. The strings are defined by the delimited, case sensitive strings. The strings are defined by the
skipping to change at page 23, line 9 skipping to change at page 23, line 4
If the client omits the scope parameter when requesting If the client omits the scope parameter when requesting
authorization, the authorization server MUST either process the authorization, the authorization server MUST either process the
request using a pre-defined default value, or fail the request request using a pre-defined default value, or fail the request
indicating an invalid scope. The authorization server SHOULD indicating an invalid scope. The authorization server SHOULD
document its scope requirements and default value (if defined). document its scope requirements and default value (if defined).
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.
4.1. Authorization Code Grant 4.1. Authorization Code Grant
The authorization code grant type is used to obtain both access The authorization code grant type is used to obtain both access
tokens and refresh tokens and is optimized for confidential clients. tokens and refresh tokens and is optimized for confidential clients.
As a redirection-based flow, the client must be capable of As a redirection-based flow, the client must be capable of
interacting with the resource owner's user-agent (typically a web interacting with the resource owner's user-agent (typically a web
browser) and capable of receiving incoming requests (via redirection) browser) and capable of receiving incoming requests (via redirection)
from the authorization server. from the authorization server.
+----------+ +----------+
| resource | | Resource |
| owner | | Owner |
| | | |
+----------+ +----------+
^ ^
| |
(B) (B)
+----|-----+ Client Identifier +---------------+ +----|-----+ Client Identifier +---------------+
| -+----(A)-- & Redirection URI ---->| | | -+----(A)-- & Redirection URI ---->| |
| User- | | Authorization | | User- | | Authorization |
| Agent -+----(B)-- User authenticates --->| Server | | Agent -+----(B)-- User authenticates --->| Server |
| | | | | | | |
skipping to change at page 24, line 39 skipping to change at page 24, line 35
(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, the authorization server responds back with an access valid, the authorization server responds back with an access
token and optionally, a refresh token. token and optionally, a 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, per Appendix B:
[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.2. 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 as described by OPTIONAL. The scope of the access request as described by
Section 3.3. Section 3.3.
skipping to change at page 25, line 17 skipping to change at page 25, line 10
state between the request and callback. The authorization state between the request and callback. The authorization
server includes this value when redirecting the user-agent back server includes this value when redirecting the user-agent back
to the client. The parameter SHOULD be used for preventing to the client. The parameter SHOULD be used for preventing
cross-site request forgery as described in Section 10.12. 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 TLS (extra line breaks are for display purposes HTTP request using TLS (with extra line breaks for display purposes
only): only):
GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com Host: server.example.com
The authorization server validates the request to ensure all required The authorization server validates the request to ensure all required
parameters are present and valid. If the request is valid, the parameters are present and valid. If the request is valid, the
authorization server authenticates the resource owner and obtains an authorization server authenticates the resource owner and obtains an
authorization decision (by asking the resource owner or by authorization decision (by asking the resource owner or by
skipping to change at page 25, line 40 skipping to change at page 25, line 33
When a decision is established, the authorization server directs the When a decision is established, the authorization server directs the
user-agent to the provided client redirection URI using an HTTP user-agent to the provided client redirection URI using an HTTP
redirection response, or by other means available to it via the user- redirection response, or by other means available to it via the user-
agent. agent.
4.1.2. Authorization Response 4.1.2. Authorization Response
If the resource owner grants the access request, the authorization If the resource owner grants the access request, the authorization
server issues an authorization code and delivers it to the client by server issues an authorization code and delivers it to the client by
adding the following parameters to the query component of the adding the following parameters to the query component of the
redirection URI using the "application/x-www-form-urlencoded" format: redirection URI using the "application/x-www-form-urlencoded" format,
per Appendix B:
code code
REQUIRED. The authorization code generated by the REQUIRED. The authorization code generated by the
authorization server. The authorization code MUST expire authorization server. The authorization code MUST expire
shortly after it is issued to mitigate the risk of leaks. A shortly after it is issued to mitigate the risk of leaks. A
maximum authorization code lifetime of 10 minutes is maximum authorization code lifetime of 10 minutes is
RECOMMENDED. The client MUST NOT use the authorization code RECOMMENDED. The client MUST NOT use the authorization code
more than once. If an authorization code is used more than more than once. If an authorization code is used more than
once, the authorization server MUST deny the request and SHOULD once, the authorization server MUST deny the request and SHOULD
revoke (when possible) all tokens previously issued based on revoke (when possible) all tokens previously issued based on
skipping to change at page 26, line 36 skipping to change at page 26, line 30
If the request fails due to a missing, invalid, or mismatching If the request fails due to a missing, invalid, or mismatching
redirection URI, or if the client identifier is missing or invalid, redirection URI, or if the client identifier is missing or invalid,
the authorization server SHOULD inform the resource owner of the the authorization server SHOULD inform the resource owner of the
error, and MUST NOT automatically redirect the user-agent to the error, and MUST NOT automatically redirect the user-agent to the
invalid redirection URI. invalid redirection URI.
If the resource owner denies the access request or if the request If the resource owner denies the access request or if the request
fails for reasons other than a missing or invalid redirection URI, fails for reasons other than a missing or invalid redirection URI,
the authorization server informs the client by adding the following the authorization server informs the client by adding the following
parameters to the query component of the redirection URI using the parameters to the query component of the redirection URI using the
"application/x-www-form-urlencoded" format: "application/x-www-form-urlencoded" format, per Appendix B:
error error
REQUIRED. A single ASCII [USASCII] error code from the REQUIRED. A single ASCII [USASCII] error code from the
following: following:
invalid_request invalid_request
The request is missing a required parameter, includes an The request is missing a required parameter, includes an
invalid parameter value, includes a parameter more than invalid parameter value, includes a parameter more than
once, or is otherwise malformed. once, or is otherwise malformed.
unauthorized_client unauthorized_client
The client is not authorized to request an authorization The client is not authorized to request an authorization
skipping to change at page 27, line 4 skipping to change at page 26, line 42
error error
REQUIRED. A single ASCII [USASCII] error code from the REQUIRED. A single ASCII [USASCII] error code from the
following: following:
invalid_request invalid_request
The request is missing a required parameter, includes an The request is missing a required parameter, includes an
invalid parameter value, includes a parameter more than invalid parameter value, includes a parameter more than
once, or is otherwise malformed. once, or is otherwise malformed.
unauthorized_client unauthorized_client
The client is not authorized to request an authorization The client is not authorized to request an authorization
code using this method. code using this method.
access_denied access_denied
The resource owner or authorization server denied the The resource owner or authorization server denied the
request. request.
unsupported_response_type unsupported_response_type
The authorization server does not support obtaining an The authorization server does not support obtaining an
authorization code using this method. authorization code using this method.
invalid_scope invalid_scope
The requested scope is invalid, unknown, or malformed. The requested scope is invalid, unknown, or malformed.
server_error server_error
The authorization server encountered an unexpected The authorization server encountered an unexpected
condition which prevented it from fulfilling the request. condition that prevented it from fulfilling the request.
temporarily_unavailable temporarily_unavailable
The authorization server is currently unable to handle The authorization server is currently unable to handle
the request due to a temporary overloading or maintenance the request due to a temporary overloading or maintenance
of the server. of the server.
Values for the "error" parameter MUST NOT include characters Values for the "error" parameter MUST NOT include characters
outside the set %x20-21 / %x23-5B / %x5D-7E. outside the set %x20-21 / %x23-5B / %x5D-7E.
error_description error_description
OPTIONAL. A human-readable ASCII [USASCII] text providing OPTIONAL. A human-readable ASCII [USASCII] 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.
skipping to change at page 27, line 48 skipping to change at page 27, line 40
client. 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: sending the following HTTP response:
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.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 sending 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 per Appendix B with a character encoding of UTF-8 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 as described in Section 4.1.1, and their authorization request as described in Section 4.1.1, and their
values MUST be identical. values MUST be identical.
If the client type is confidential or the client was issued client If the client type is confidential or the client was issued client
credentials (or assigned other authentication requirements), the credentials (or assigned other authentication requirements), the
client MUST authenticate with the authorization server as described client MUST authenticate with the authorization server as described
in Section 3.2.1. in Section 3.2.1.
skipping to change at page 28, line 21 skipping to change at page 28, line 16
REQUIRED, if the "redirect_uri" parameter was included in the REQUIRED, if the "redirect_uri" parameter was included in the
authorization request as described in Section 4.1.1, and their authorization request as described in Section 4.1.1, and their
values MUST be identical. values MUST be identical.
If the client type is confidential or the client was issued client If the client type is confidential or the client was issued client
credentials (or assigned other authentication requirements), the credentials (or assigned other authentication requirements), the
client MUST authenticate with the authorization server as described client MUST authenticate with the authorization server as described
in Section 3.2.1. in Section 3.2.1.
For example, the client makes the following HTTP request using TLS For example, the client makes the following HTTP request using TLS
(extra line breaks are for display purposes only): (with extra line breaks 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
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:
o require client authentication for confidential clients or for any o require client authentication for confidential clients or for any
client that was issued client credentials (or with other client that was issued client credentials (or with other
authentication requirements), authentication requirements),
o authenticate the client if client authentication is included and o authenticate the client if client authentication is included,
ensure the authorization code was issued to the authenticated o ensure the authorization code was issued to the authenticated
client, confidential client or to the public client identified by the
"client_id" in the request,
o verify that the authorization code is valid, and o verify that the authorization code is valid, and
o ensure that the "redirect_uri" parameter is present if the o ensure that the "redirect_uri" parameter is present if the
"redirect_uri" parameter was included in the initial authorization "redirect_uri" parameter was included in the initial authorization
request as described in Section 4.1.1, and if included ensure request as described in Section 4.1.1, and if included ensure
their values are identical. their values are identical.
4.1.4. Access Token Response 4.1.4. Access Token Response
If the access token request is valid and authorized, the If the access token request is valid and authorized, the
authorization server issues an access token and optional refresh authorization server issues an access token and optional refresh
skipping to change at page 31, line 25 skipping to change at page 31, line 25
fragment information locally. fragment information locally.
(E) The web-hosted client resource returns a web page (typically an (E) The web-hosted client resource returns a web page (typically an
HTML document with an embedded script) capable of accessing the HTML document with an embedded script) capable of accessing the
full redirection URI including the fragment retained by the full redirection URI including the fragment retained by the
user-agent, and extracting the access token (and other user-agent, and extracting the access token (and other
parameters) contained in the fragment. parameters) contained in the fragment.
(F) The user-agent executes the script provided by the web-hosted (F) The user-agent executes the script provided by the web-hosted
client resource locally, which extracts the access token and client resource locally, which extracts the access token and
passes it to the client. passes it to the client.
See Section 1.3.2 and Section 9 for background on using the implicit
grant. See Section 10.3 and Section 10.16 for important security
considerations when using the implicit grant.
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, per Appendix B:
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.2. 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 as described by OPTIONAL. The scope of the access request as described by
Section 3.3. Section 3.3.
skipping to change at page 32, line 6 skipping to change at page 32, line 7
state between the request and callback. The authorization state between the request and callback. The authorization
server includes this value when redirecting the user-agent back server includes this value when redirecting the user-agent back
to the client. The parameter SHOULD be used for preventing to the client. The parameter SHOULD be used for preventing
cross-site request forgery as described in Section 10.12. 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 TLS (extra line breaks are for display purposes HTTP request using TLS (with extra line breaks for display purposes
only): only):
GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com Host: server.example.com
The authorization server validates the request to ensure all required The authorization server validates the request to ensure all required
parameters are present and valid. The authorization server MUST parameters are present and valid. The authorization server MUST
verify that the redirection URI to which it will redirect the access verify that the redirection URI to which it will redirect the access
token matches a redirection URI registered by the client as described token matches a redirection URI registered by the client as described
skipping to change at page 32, line 33 skipping to change at page 32, line 34
When a decision is established, the authorization server directs the When a decision is established, the authorization server directs the
user-agent to the provided client redirection URI using an HTTP user-agent to the provided client redirection URI using an HTTP
redirection response, or by other means available to it via the user- redirection response, or by other means available to it via the user-
agent. agent.
4.2.2. Access Token Response 4.2.2. Access Token Response
If the resource owner grants the access request, the authorization If the resource owner grants the access request, the authorization
server issues an access token and delivers it to the client by adding server issues an access token and delivers it to the client by adding
the following parameters to the fragment component of the redirection the following parameters to the fragment component of the redirection
URI using the "application/x-www-form-urlencoded" format: URI using the "application/x-www-form-urlencoded" format, per
Appendix B:
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
RECOMMENDED. The lifetime in seconds of the access token. For RECOMMENDED. 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.
skipping to change at page 32, line 46 skipping to change at page 33, line 4
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
RECOMMENDED. The lifetime in seconds of the access token. For RECOMMENDED. 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.
If omitted, the authorization server SHOULD provide the If omitted, the authorization server SHOULD provide the
expiration time via other means or document the default value. expiration time via other means or document the default value.
scope scope
OPTIONAL, if identical to the scope requested by the client, OPTIONAL, if identical to the scope requested by the client,
otherwise REQUIRED. The scope of the access token as described otherwise REQUIRED. The scope of the access token as described
by Section 3.3. by Section 3.3.
state state
REQUIRED if the "state" parameter was present in the client REQUIRED if the "state" parameter was present in the client
authorization request. The exact value received from the authorization request. The exact value received from the
client. client.
The authorization server MUST NOT issue a refresh token. The authorization server MUST NOT issue a refresh token.
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 (with extra line breaks for
display purposes only): display purposes only):
HTTP/1.1 302 Found HTTP/1.1 302 Found
Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA
&state=xyz&token_type=example&expires_in=3600 &state=xyz&token_type=example&expires_in=3600
Developers should note that some user-agents do not support the Developers should note that some user-agents do not support the
inclusion of a fragment component in the HTTP "Location" response inclusion of a fragment component in the HTTP "Location" response
header field. Such clients will require using other methods for header field. Such clients will require using other methods for
redirecting the client than a 3xx redirection response. For example, redirecting the client than a 3xx redirection response. For example,
returning an HTML page which includes a 'continue' button with an returning an HTML page that includes a 'continue' button with an
action linked to the redirection URI. action linked to the redirection URI.
The client MUST ignore unrecognized response parameters. The access The client MUST ignore unrecognized response parameters. The access
token string size is left undefined by this specification. The token string size is left undefined by this specification. The
client should avoid making assumptions about value sizes. The client should avoid making assumptions about value sizes. The
authorization server SHOULD document the size of any value it issues. authorization server SHOULD document the size of any value it issues.
4.2.2.1. Error Response 4.2.2.1. Error Response
If the request fails due to a missing, invalid, or mismatching If the request fails due to a missing, invalid, or mismatching
redirection URI, or if the client identifier is missing or invalid, redirection URI, or if the client identifier is missing or invalid,
the authorization server SHOULD inform the resource owner of the the authorization server SHOULD inform the resource owner of the
error, and MUST NOT automatically redirect the user-agent to the error, and MUST NOT automatically redirect the user-agent to the
invalid redirection URI. invalid redirection URI.
If the resource owner denies the access request or if the request If the resource owner denies the access request or if the request
fails for reasons other than a missing or invalid redirection URI, fails for reasons other than a missing or invalid redirection URI,
the authorization server informs the client by adding the following the authorization server informs the client by adding the following
parameters to the fragment component of the redirection URI using the parameters to the fragment component of the redirection URI using the
"application/x-www-form-urlencoded" format: "application/x-www-form-urlencoded" format, per Appendix B:
error error
REQUIRED. A single ASCII [USASCII] error code from the REQUIRED. A single ASCII [USASCII] error code from the
following: following:
invalid_request invalid_request
The request is missing a required parameter, includes an The request is missing a required parameter, includes an
invalid parameter value, includes a parameter more than invalid parameter value, includes a parameter more than
once, or is otherwise malformed. once, or is otherwise malformed.
unauthorized_client unauthorized_client
The client is not authorized to request an access token The client is not authorized to request an access token
using this method. using this method.
access_denied access_denied
The resource owner or authorization server denied the The resource owner or authorization server denied the
request. request.
skipping to change at page 34, line 22 skipping to change at page 34, line 25
access_denied access_denied
The resource owner or authorization server denied the The resource owner or authorization server denied the
request. request.
unsupported_response_type unsupported_response_type
The authorization server does not support obtaining an The authorization server does not support obtaining an
access token using this method. access token using this method.
invalid_scope invalid_scope
The requested scope is invalid, unknown, or malformed. The requested scope is invalid, unknown, or malformed.
server_error server_error
The authorization server encountered an unexpected The authorization server encountered an unexpected
condition which prevented it from fulfilling the request. condition that prevented it from fulfilling the request.
temporarily_unavailable temporarily_unavailable
The authorization server is currently unable to handle The authorization server is currently unable to handle
the request due to a temporary overloading or maintenance the request due to a temporary overloading or maintenance
of the server. of the server.
Values for the "error" parameter MUST NOT include characters Values for the "error" parameter MUST NOT include characters
outside the set %x20-21 / %x23-5B / %x5D-7E. outside the set %x20-21 / %x23-5B / %x5D-7E.
error_description error_description
OPTIONAL. A human-readable ASCII [USASCII] text providing OPTIONAL. A human-readable ASCII [USASCII] 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.
skipping to change at page 36, line 19 skipping to change at page 36, line 25
4.3.1. Authorization Request and Response 4.3.1. Authorization Request and Response
The method through which the client obtains the resource owner The method through which the client obtains the resource owner
credentials is beyond the scope of this specification. The client credentials is beyond the scope of this specification. The client
MUST discard the credentials once an access token has been obtained. MUST discard the credentials once an access token has been obtained.
4.3.2. Access Token Request 4.3.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 per Appendix B with a character encoding of UTF-8 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. REQUIRED. The resource owner username.
password password
REQUIRED. The resource owner password. REQUIRED. The resource owner password.
scope scope
OPTIONAL. The scope of the access request as described by OPTIONAL. The scope of the access request as described by
Section 3.3. Section 3.3.
If the client type is confidential or the client was issued client If the client type is confidential or the client was issued client
credentials (or assigned other authentication requirements), the credentials (or assigned other authentication requirements), the
client MUST authenticate with the authorization server as described client MUST authenticate with the authorization server as described
in Section 3.2.1. 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 (with extra line breaks for display purposes
only): 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
grant_type=password&username=johndoe&password=A3ddj3w grant_type=password&username=johndoe&password=A3ddj3w
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 that was issued client credentials (or with other client that was issued client credentials (or with other
authentication requirements), authentication requirements),
o authenticate the client if client authentication is included, and o authenticate the client if client authentication is included, and
o validate the resource owner password credentials using its o validate the resource owner password credentials using its
skipping to change at page 37, line 45 skipping to change at page 37, line 47
"expires_in":3600, "expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value" "example_parameter":"example_value"
} }
4.4. Client Credentials Grant 4.4. Client Credentials Grant
The client can request an access token using only its client The client can request an access token using only its client
credentials (or other supported means of authentication) when the credentials (or other supported means of authentication) when the
client is requesting access to the protected resources under its client is requesting access to the protected resources under its
control, or those of another resource owner which has been previously control, or those of another resource owner that have been previously
arranged with the authorization server (the method of which is beyond arranged with the authorization server (the method of which is beyond
the scope of this specification). the scope of this specification).
The client credentials grant type MUST only be used by confidential The client credentials grant type MUST only be used by confidential
clients. clients.
+---------+ +---------------+ +---------+ +---------------+
| | | | | | | |
| |>--(A)- Client Authentication --->| Authorization | | |>--(A)- Client Authentication --->| Authorization |
| Client | | Server | | Client | | Server |
skipping to change at page 38, line 31 skipping to change at page 38, line 31
4.4.1. Authorization Request and Response 4.4.1. Authorization Request and Response
Since the client authentication is used as the authorization grant, Since the client authentication is used as the authorization grant,
no additional authorization request is needed. no additional authorization request is needed.
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 per Appendix B with a character encoding of UTF-8 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 as described by OPTIONAL. The scope of the access request as described by
Section 3.3. Section 3.3.
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 (with extra line breaks for display purposes
only): 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
grant_type=client_credentials grant_type=client_credentials
The authorization server MUST authenticate the client. The authorization server MUST authenticate the client.
4.4.3. Access Token Response 4.4.3. Access Token Response
If the access token request is valid and authorized, the If the access token request is valid and authorized, the
authorization server issues an access token as described in authorization server issues an access token as described in
Section 5.1. A refresh token SHOULD NOT be included. If the request Section 5.1. A refresh token SHOULD NOT be included. If the request
failed client authentication or is invalid, the authorization server failed client authentication or is invalid, the authorization server
skipping to change at page 39, line 39 skipping to change at page 39, line 38
4.5. Extension Grants 4.5. Extension Grants
The client uses an extension grant type by specifying the grant type The client uses an extension grant type by specifying the grant type
using an absolute URI (defined by the authorization server) as the using an absolute URI (defined by the authorization server) as the
value of the "grant_type" parameter of the token endpoint, and by value of the "grant_type" parameter of the token endpoint, and by
adding any additional parameters necessary. adding any additional parameters necessary.
For example, to request an access token using a SAML 2.0 assertion For example, to request an access token using a SAML 2.0 assertion
grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client
makes the following HTTP request using TLS (line breaks are for could make the following HTTP request using TLS (with extra line
display purposes only): breaks for display purposes only):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8 Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-
bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU
[...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24-
If the access token request is valid and authorized, the If the access token request is valid and authorized, the
authorization server issues an access token and optional refresh authorization server issues an access token and optional refresh
token as described in Section 5.1. If the request failed client token as described in Section 5.1. If the request failed client
authentication or is invalid, the authorization server returns an authentication or is invalid, the authorization server returns an
error response as described in Section 5.2. error response as described in Section 5.2.
5. Issuing an Access Token 5. Issuing an Access Token
skipping to change at page 40, line 39 skipping to change at page 40, line 32
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
RECOMMENDED. The lifetime in seconds of the access token. For RECOMMENDED. 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.
If omitted, the authorization server SHOULD provide the If omitted, the authorization server SHOULD provide the
expiration time via other means or document the default value. expiration time via other means or document the default value.
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, if identical to the scope requested by the client, OPTIONAL, if identical to the scope requested by the client,
otherwise REQUIRED. The scope of the access token as described otherwise REQUIRED. The scope of the access token as described
by Section 3.3. by Section 3.3.
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
skipping to change at page 43, line 22 skipping to change at page 43, line 21
{ {
"error":"invalid_request" "error":"invalid_request"
} }
6. Refreshing an Access Token 6. Refreshing an Access Token
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 per Appendix B with a character encoding of UTF-8 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 as described by OPTIONAL. The scope of the access request as described by
Section 3.3. The requested scope MUST NOT include any scope Section 3.3. The requested scope MUST NOT include any scope
not originally granted by the resource owner, and if omitted is not originally granted by the resource owner, and if omitted is
treated as equal to the scope originally granted by the treated as equal to the scope originally granted by the
resource owner. 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 to which it was issued. If the client type is confidential or client to which it was issued. If the client type is confidential or
the client was issued client credentials (or assigned other the client was issued client credentials (or assigned other
authentication requirements), the client MUST authenticate with the authentication requirements), the client MUST authenticate with the
authorization server as described in Section 3.2.1. authorization server as 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 (with extra line breaks for display purposes
only): 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
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 that was issued client credentials (or with other client that was issued client credentials (or with other
authentication requirements), authentication 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,
skipping to change at page 45, line 28 skipping to change at page 45, line 14
For example, the "bearer" token type defined in For example, the "bearer" token type defined in
[I-D.ietf-oauth-v2-bearer] is utilized by simply including the access [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access
token string in the request: token string in the request:
GET /resource/1 HTTP/1.1 GET /resource/1 HTTP/1.1
Host: example.com Host: example.com
Authorization: Bearer mF_9.B5f-4.1JqM Authorization: Bearer mF_9.B5f-4.1JqM
while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is
utilized by issuing a MAC key together with the access token which is utilized by issuing a MAC key together with the access token that is
used to sign certain components of the HTTP requests: used to sign certain components of the HTTP requests:
GET /resource/1 HTTP/1.1 GET /resource/1 HTTP/1.1
Host: example.com Host: example.com
Authorization: MAC id="h480djs93hd8", Authorization: MAC id="h480djs93hd8",
nonce="274312:dj83hs9s", nonce="274312:dj83hs9s",
mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" mac="kDZvddkndxvhGRXZhvuDjEWhGeE="
The above examples are provided for illustration purposes only. The above examples are provided for illustration purposes only.
Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and
skipping to change at page 49, line 39 skipping to change at page 49, line 14
embedded user-agent educates end-users to trust unidentified embedded user-agent educates end-users 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 client 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 which requires repeating the authorization process once returned, which requires repeating the authorization process once
the access token expires. 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.
skipping to change at page 52, line 19 skipping to change at page 51, line 43
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 token 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 by generated, modified, or guessed to produce valid refresh tokens by
unauthorized parties. 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 require the use of TLS with its channel, and the client SHOULD require the use of TLS with its
redirection URI if the URI identifies a network resource. Since redirection URI if the URI identifies a network resource. Since
skipping to change at page 53, line 29 skipping to change at page 52, line 50
attacker. The attacker then tricks the victim into following the attacker. The attacker then tricks the victim into following the
manipulated link to authorize access to the legitimate client. 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 trusted client, normal, valid request on behalf of a legitimate and trusted client,
and authorizes the request. The victim is then redirected to an and authorizes the request. The victim is then redirected to an
endpoint under the control of the attacker with the authorization endpoint under the control of the attacker with the authorization
code. The attacker completes the authorization flow by sending the code. The attacker completes the authorization flow by sending the
authorization code to the client using the original redirection URI authorization code to the client using the original redirection URI
provided by the client. The client exchanges the authorization code provided by the client. The client exchanges the authorization code
with an access token and links it to the attacker's client account with an access token and links it to the attacker's client account,
which can now gain access to the protected resources authorized by which can now gain access to the protected resources authorized by
the victim (via the client). the victim (via the client).
In order to prevent such an attack, the authorization server MUST In order to prevent such an attack, the authorization server MUST
ensure that the redirection URI used to obtain the authorization code ensure that the redirection URI used to obtain the authorization code
is identical to the redirection URI provided when exchanging the is identical to 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
MUST require public clients and SHOULD require confidential clients MUST require public clients and SHOULD require confidential clients
to register their redirection URIs. If a redirection URI is provided to register their redirection URIs. If a redirection URI is provided
in the request, the authorization server MUST validate it against the in the request, the authorization server MUST validate it against the
skipping to change at page 56, line 23 skipping to change at page 55, line 44
The authorization server MUST implement CSRF protection for its The authorization server MUST implement CSRF protection for its
authorization endpoint, and ensure that a malicious client cannot authorization endpoint, and ensure that a malicious client cannot
obtain authorization without the awareness and explicit consent of obtain authorization without the awareness and explicit consent of
the resource owner. 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
invisible button on the authorization page (such as an "Authorize" invisible button on the authorization page (such as an "Authorize"
button). This allows an attacker to trick a resource owner into button). This allows an attacker to trick a resource owner into
granting its client access without their knowledge. granting its client access without their knowledge.
To prevent this form of attack, native applications SHOULD use To prevent this form of attack, native applications SHOULD use
external browsers instead of embedding browsers within the external browsers instead of embedding browsers within the
application when requesting end-user authorization. For most newer application when requesting end-user authorization. For most newer
skipping to change at page 57, line 23 skipping to change at page 56, line 45
Open redirectors can be used in phishing attacks, or by an attacker 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 to get end-users to visit malicious sites by making the URI's
authority look like a familiar and trusted destination. In addition, authority look like a familiar and trusted destination. In addition,
if the authorization server allows the client to register only part if the authorization server allows the client to register only part
of the redirection URI, an attacker can use an open redirector of the redirection URI, an attacker can use an open redirector
operated by the client to construct a redirection URI that will pass operated by the client to construct a redirection URI that will pass
the authorization server validation but will send the authorization the authorization server validation but will send the authorization
code or access token to an endpoint under the control of the code or access token to an endpoint under the control of the
attacker. attacker.
10.16. Misuse of Access Token to Impersonate Resource Owner in Implicit
Flow
For public clients using implicit flows, this specification does not
provide any method for the client to determine what client an access
token was issued to.
A Resource Owner may willingly delegate access to a resource by
granting an access token to an attacker's malicious client. This may
be due to Phishing or some other pretext. An attacker may also steal
a token via some other mechanism. An attacker may then attempt to
impersonate the resource owner by providing the access token to a
legitimate public client.
In the implicit flow (response_type=token), the attacker can easily
switch the token in the response from the authorization server,
replacing the real access_token with the one previously issued to the
attacker.
Servers communicating with native applications that rely on being
passed an access token in the back channel to identify the user of
the client may be similarly compromised by an attacker creating a
compromised application that can inject arbitrary stolen access
tokens.
Any public client that makes the assumption that only the resource
owner can present them with a valid access token for the resource is
vulnerable to this attack.
This attack may expose information about the resource owner at the
legitimate client to the attacker (malicious client). This will also
allow the attacker to perform operations at the legitimate client
with the same permissions as the resource owner who originally
granted the access token or authorization code.
Authenticating Resource Owners to clients is out of scope for this
specification. Any specification that uses the authorization process
as a form of delegated end-user authentication to the client (e.g.
third-party sign-in service) MUST NOT use the implicit flow without
additional security mechanisms such as audience restricting the
access token that enable the client to determine if the access token
was issued for its use.
11. IANA Considerations 11. IANA Considerations
11.1. The OAuth Access Token Type Registry 11.1. 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 with a Specification Required Access token types are registered with a Specification Required
([RFC5226]) after a two week review period on the [TBD]@ietf.org ([RFC5226]) after a two week review period on the [TBD]@ietf.org
mailing list, on the advice of one or more Designated Experts. mailing list, on the advice of one or more Designated Experts.
However, to allow for the allocation of values prior to publication, However, to allow for the allocation of values prior to publication,
the Designated Expert(s) may approve registration once they are the Designated Expert(s) may approve registration once they are
satisfied that such a specification will be published. satisfied that such a specification will be published.
skipping to change at page 58, line 28 skipping to change at page 58, line 44
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 the 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. 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
request, or the token endpoint response are registered with a request, or the token endpoint response are registered with a
Specification Required ([RFC5226]) after a two week review period on Specification Required ([RFC5226]) after a two week review period on
the [TBD]@ietf.org mailing list, on the advice of one or more the [TBD]@ietf.org mailing list, on the advice of one or more
Designated Experts. However, to allow for the allocation of values Designated Experts. However, to allow for the allocation of values
prior to publication, the Designated Expert(s) may approve prior to publication, the Designated Expert(s) may approve
skipping to change at page 61, line 19 skipping to change at page 61, line 37
o Parameter name: password o Parameter name: password
o Parameter usage location: token request o Parameter usage location: token request
o Change controller: IETF o Change controller: IETF
o Specification document(s): [[ this document ]] o Specification document(s): [[ this document ]]
o Parameter name: refresh_token o Parameter name: refresh_token
o Parameter usage location: token request, token response o Parameter usage location: token request, token response
o Change controller: IETF o Change controller: IETF
o Specification document(s): [[ this document ]] o Specification document(s): [[ this document ]]
11.3. The OAuth Authorization Endpoint Response Type Registry 11.3. OAuth Authorization Endpoint Response Type Registry
This specification establishes the OAuth authorization endpoint This specification establishes the OAuth authorization endpoint
response type registry. response type registry.
Additional response type for use with the authorization endpoint are Additional response type for use with the authorization endpoint are
registered with a Specification Required ([RFC5226]) after a two week registered with a Specification Required ([RFC5226]) after a two week
review period on the [TBD]@ietf.org mailing list, on the advice of review period on the [TBD]@ietf.org mailing list, on the advice of
one or more Designated Experts. However, to allow for the allocation one or more Designated Experts. However, to allow for the allocation
of values prior to publication, the Designated Expert(s) may approve of values prior to publication, the Designated Expert(s) may approve
registration once they are satisfied that such a specification will registration once they are satisfied that such a specification will
skipping to change at page 62, line 29 skipping to change at page 62, line 45
contents are: contents are:
o Response type name: code o Response type name: code
o Change controller: IETF o Change controller: IETF
o Specification document(s): [[ this document ]] o Specification document(s): [[ this document ]]
o Response type name: token o Response type name: token
o Change controller: IETF o Change controller: IETF
o Specification document(s): [[ this document ]] o Specification document(s): [[ this document ]]
11.4. The OAuth Extensions Error Registry 11.4. OAuth Extensions Error Registry
This specification establishes the OAuth extensions error registry. This specification establishes the OAuth extensions error registry.
Additional error codes used together with other protocol extensions Additional error codes used together with other protocol extensions
(i.e. extension grant types, access token types, or extension (i.e. extension grant types, access token types, or extension
parameters) are registered with a Specification Required ([RFC5226]) parameters) are registered with a Specification Required ([RFC5226])
after a two week review period on the [TBD]@ietf.org mailing list, on after a two week review period on the [TBD]@ietf.org mailing list, on
the advice of one or more Designated Experts. However, to allow for the advice of one or more Designated Experts. However, to allow for
the allocation of values prior to publication, the Designated the allocation of values prior to publication, the Designated
Expert(s) may approve registration once they are satisfied that such Expert(s) may approve registration once they are satisfied that such
skipping to change at page 64, line 9 skipping to change at page 64, line 26
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.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, January 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2", [RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
RFC 4949, August 2007. RFC 4949, August 2007.
skipping to change at page 64, line 45 skipping to change at page 65, line 16
[USASCII] American National Standards Institute, "Coded Character [USASCII] American National Standards Institute, "Coded Character
Set -- 7-bit American Standard Code for Information Set -- 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986. Interchange", ANSI X3.4, 1986.
[W3C.REC-html401-19991224] [W3C.REC-html401-19991224]
Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 Hors, A., Raggett, D., 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>.
[W3C.REC-xml-20081126]
Sperberg-McQueen, C., Yergeau, F., Bray, T., Maler, E.,
and J. Paoli, "Extensible Markup Language (XML) 1.0 (Fifth
Edition)", World Wide Web Consortium Recommendation REC-
xml-20081126, November 2008,
<http://www.w3.org/TR/2008/REC-xml-20081126>.
12.2. Informative References 12.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.
[I-D.ietf-httpbis-p7-auth]
Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part
7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in
progress), March 2012.
[I-D.ietf-oauth-saml2-bearer] [I-D.ietf-oauth-saml2-bearer]
Mortimore, C., "SAML 2.0 Bearer Assertion Profiles for Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion
OAuth 2.0", draft-ietf-oauth-saml2-bearer-12 (work in Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-13
progress), May 2012. (work in progress), July 2012.
[I-D.ietf-oauth-v2-bearer] [I-D.ietf-oauth-v2-bearer]
Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0
Authorization Framework: Bearer Token Usage", Authorization Framework: Bearer Token Usage",
draft-ietf-oauth-v2-bearer-20 (work in progress), draft-ietf-oauth-v2-bearer-21 (work in progress),
June 2012. June 2012.
[I-D.ietf-oauth-v2-http-mac] [I-D.ietf-oauth-v2-http-mac]
Hammer-Lahav, E., "HTTP Authentication: MAC Access Hammer-Lahav, E., "HTTP Authentication: MAC Access
Authentication", draft-ietf-oauth-v2-http-mac-01 (work in Authentication", draft-ietf-oauth-v2-http-mac-01 (work in
progress), February 2012. progress), February 2012.
[I-D.ietf-oauth-v2-threatmodel] [I-D.ietf-oauth-v2-threatmodel]
Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", Threat Model and Security Considerations",
draft-ietf-oauth-v2-threatmodel-05 (work in progress), draft-ietf-oauth-v2-threatmodel-06 (work in progress),
May 2012. June 2012.
[RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849,
April 2010. April 2010.
Appendix A. Augmented Backus-Naur Form (ABNF) Syntax Appendix A. Augmented Backus-Naur Form (ABNF) Syntax
This section provides Augmented Backus-Naur Form (ABNF) syntax This section provides Augmented Backus-Naur Form (ABNF) syntax
descriptions for the elements defined in this specification using the descriptions for the elements defined in this specification using the
notation of [RFC5234]. Elements are presented in the order first notation of [RFC5234]. The ABNF below is defined in terms of Unicode
defined. code points [W3C.REC-xml-20081126]; these characters are typically
encoded in UTF-8. Elements are presented in the order first defined.
Some of the definitions that follow use the "URI-reference" Some of the definitions that follow use the "URI-reference"
definition from [RFC3986]. definition from [RFC3986].
Some of the definitions that follow use these common definitions: Some of the definitions that follow use these common definitions:
VSCHAR = %20-7E VSCHAR = %x20-7E
NQCHAR = %x21 / %x23-5B / %x5D-7E NQCHAR = %x21 / %x23-5B / %x5D-7E
NQSCHAR = %x20-21 / %x23-5B / %x5D-7E NQSCHAR = %x20-21 / %x23-5B / %x5D-7E
UNICODENOCTRLCHAR = <Any Unicode character other than ( %x0-1F / %x7F )> UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF /
%xE000-FFFD / %x10000-10FFFF
(The UNICODECHARNOCRLF definition is based upon the Char definition
in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage
Return and Linefeed characters.)
A.1. "client_id" Syntax A.1. "client_id" Syntax
The "client_id" element is defined in Section 2.3.1: The "client_id" element is defined in Section 2.3.1:
client-id = *VSCHAR client-id = *VSCHAR
A.2. "client_secret" Syntax A.2. "client_secret" Syntax
The "client_secret" element is defined in Section 2.3.1: The "client_secret" element is defined in Section 2.3.1:
client-secret = *VSCHAR client-secret = *VSCHAR
A.3. "response_type" Syntax A.3. "response_type" Syntax
The "response_type" element is defined in Section 3.1.1 and The "response_type" element is defined in Section 3.1.1 and
Section 8.4: Section 8.4:
response-type = response-name *( SP response-name ) response-type = response-name *( SP response-name )
response-name = 1*response-char response-name = 1*response-char
response-char = "_" / DIGIT / ALPHA response-char = "_" / DIGIT / ALPHA
A.4. "scope" Syntax A.4. "scope" Syntax
The "scope" element is defined in Section 3.3: The "scope" element is defined in Section 3.3:
scope = scope-token *( SP scope-token ) scope = scope-token *( SP scope-token )
scope-token = 1*NQCHAR scope-token = 1*NQCHAR
A.5. "state" Syntax A.5. "state" Syntax
The "state" element is defined in Section 4.1.1, Section 4.1.2, The "state" element is defined in Section 4.1.1, Section 4.1.2,
Section 4.1.2.1, Section 4.2.1, Section 4.2.2, and Section 4.2.2.1: Section 4.1.2.1, Section 4.2.1, Section 4.2.2, and Section 4.2.2.1:
state = 1*VSCHAR state = 1*VSCHAR
A.6. "redirect_uri" Syntax A.6. "redirect_uri" Syntax
The "redirect_uri" element is defined in Section 4.1.1, The "redirect_uri" element is defined in Section 4.1.1,
Section 4.1.3, and Section 4.2.1: Section 4.1.3, and Section 4.2.1:
redirect-uri = URI-reference redirect-uri = URI-reference
A.7. "error" Syntax A.7. "error" Syntax
The "error" element is defined in Section 4.1.2.1, Section 4.2.2.1, The "error" element is defined in Section 4.1.2.1, Section 4.2.2.1,
Section 5.2, Section 7.2, and Section 8.5: Section 5.2, Section 7.2, and Section 8.5:
error = 1*NQSCHAR error = 1*NQSCHAR
A.8. "error_description" Syntax A.8. "error_description" Syntax
The "error_description" element is defined in Section 4.1.2.1, The "error_description" element is defined in Section 4.1.2.1,
Section 4.2.2.1, Section 5.2, and Section 7.2: Section 4.2.2.1, Section 5.2, and Section 7.2:
error-description = 1*NQSCHAR error-description = 1*NQSCHAR
A.9. "error_uri" Syntax A.9. "error_uri" Syntax
The "error_uri" element is defined in Section 4.1.2.1, The "error_uri" element is defined in Section 4.1.2.1,
Section 4.2.2.1, Section 5.2, and Section 7.2: Section 4.2.2.1, Section 5.2, and Section 7.2:
error-uri = URI-reference error-uri = URI-reference
A.10. "grant_type" Syntax A.10. "grant_type" Syntax
The "grant_type" element is defined in Section 4.1.3, Section 4.3.2, The "grant_type" element is defined in Section 4.1.3, Section 4.3.2,
Section 4.4.2, Section 6, and Section 4.5: Section 4.4.2, Section 6, and Section 4.5:
grant-type = grant-name / URI-reference grant-type = grant-name / URI-reference
grant-name = 1*name-char grant-name = 1*name-char
name-char = "-" / "." / "_" / DIGIT / ALPHA name-char = "-" / "." / "_" / DIGIT / ALPHA
A.11. "code" Syntax A.11. "code" Syntax
The "code" element is defined in Section 4.1.3: The "code" element is defined in Section 4.1.3:
code = 1*VSCHAR code = 1*VSCHAR
A.12. "access_token" Syntax A.12. "access_token" Syntax
The "access_token" element is defined in Section 4.2.2 and The "access_token" element is defined in Section 4.2.2 and
Section 5.1: Section 5.1:
access-token = 1*VSCHAR access-token = 1*VSCHAR
A.13. "token_type" Syntax A.13. "token_type" Syntax
The "token_type" element is defined in Section 4.2.2, Section 5.1, The "token_type" element is defined in Section 4.2.2, Section 5.1,
and Section 8.1: and Section 8.1:
token-type = type-name / URI-reference token-type = type-name / URI-reference
type-name = 1*name-char type-name = 1*name-char
name-char = "-" / "." / "_" / DIGIT / ALPHA name-char = "-" / "." / "_" / DIGIT / ALPHA
A.14. "expires_in" Syntax A.14. "expires_in" Syntax
The "expires_in" element is defined in Section 4.2.2 and Section 5.1: The "expires_in" element is defined in Section 4.2.2 and Section 5.1:
expires-in = 1*DIGIT expires-in = 1*DIGIT
A.15. "username" Syntax A.15. "username" Syntax
The "username" element is defined in Section 4.3.2: The "username" element is defined in Section 4.3.2:
username = *UNICODENOCTRLCHAR username = *UNICODECHARNOCRLF
A.16. "password" Syntax A.16. "password" Syntax
The "password" element is defined in Section 4.3.2: The "password" element is defined in Section 4.3.2:
password = *UNICODENOCTRLCHAR password = *UNICODECHARNOCRLF
A.17. "refresh_token" Syntax A.17. "refresh_token" Syntax
The "refresh_token" element is defined in Section 5.1 and Section 6: The "refresh_token" element is defined in Section 5.1 and Section 6:
refresh-token = 1*VSCHAR refresh-token = 1*VSCHAR
A.18. Endpoint Parameter Syntax A.18. Endpoint Parameter Syntax
The syntax for new endpoint parameters is defined in Section 8.2: The syntax for new endpoint parameters is defined in Section 8.2:
param-name = 1*name-char param-name = 1*name-char
name-char = "-" / "." / "_" / DIGIT / ALPHA name-char = "-" / "." / "_" / DIGIT / ALPHA
Appendix B. Acknowledgements Appendix B. Use of application/x-www-form-urlencoded Media Type
At the time of publication of this specification, the
"application/x-www-form-urlencoded" media type was defined in Section
17.13.4 of [W3C.REC-html401-19991224], but not registered in the IANA
media types registry
(<http://www.iana.org/assignments/media-types/index.html>).
Furthermore, that definition is incomplete, as it does not consider
non-US-ASCII characters.
To address this shortcoming when generating payloads using this media
type, names and values MUST be encoded using the UTF-8 character
encoding scheme [RFC3629] first; the resulting octet sequence then
needs to be further encoded using the escaping rules defined in
[W3C.REC-html401-19991224].
When parsing data from a payload using this media type, the names and
values resulting from reversing the name/value encoding consequently
need to be treated as octet sequences, to be decoded using the UTF-8
character encoding scheme.
For example, the value consisting of the six Unicode code points (1)
U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND),
(4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO
SIGN) would be encoded into the octet sequence below (using
hexadecimal notation):
20 25 26 2B C2 A3 E2 82 AC
and then represented in the payload as:
+%25%26%2B%C2%A3%E2%82%AC
Appendix C. 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]. Eran Hammer then
Considerations section was drafted by Torsten Lodderstedt, Mark edited the drafts through draft -26. The Security Considerations
McGloin, Phil Hunt, and Anthony Nadalin. The ABNF section was section was drafted by Torsten Lodderstedt, Mark McGloin, Phil Hunt,
drafted by Michael B. Jones. Anthony Nadalin, and John Bradley. The section on use of the
application/x-www-form-urlencoded media type was drafted by Julian
Reschke. The ABNF section was drafted by Michael B. Jones.
The OAuth 1.0 community specification was edited by Eran Hammer and The OAuth 1.0 community specification was edited by Eran Hammer and
authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M.
Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton,
Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris
Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler,
Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith.
The OAuth WRAP specification was edited by Dick Hardt and authored by The OAuth WRAP specification was edited by Dick Hardt and authored by
Brian Eaton, Yaron Y. Goland, Dick Hardt, and Allen Tom. Brian Eaton, Yaron Y. Goland, Dick Hardt, and Allen Tom.
This specification is the work of the OAuth Working Group which This specification is the work of the OAuth Working Group, which
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: that shaped and formed the final specification:
Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden
Bell, John Bradley, Brian Campbell, Scott Cantor, Marcos Caceres, Bell, John Bradley, Brian Campbell, Scott Cantor, Marcos Caceres,
Blaine Cook, Roger Crew, Brian Eaton, Wesley Eddy, Leah Culver, Bill Blaine Cook, Roger Crew, Brian Eaton, Wesley Eddy, Leah Culver, Bill
de hOra, Andre DeMarre, Brian Eaton, Wolter Eldering, Brian Ellin, de hOra, Andre DeMarre, Brian Eaton, Wolter Eldering, Brian Ellin,
Igor Faynberg, George Fletcher, Tim Freeman, Luca Frosini, Evan Igor Faynberg, George Fletcher, Tim Freeman, Luca Frosini, Evan
Gilbert, Yaron Y. Goland, Brent Goldman, Kristoffer Gronowski, Justin Gilbert, Yaron Y. Goland, Brent Goldman, Kristoffer Gronowski, Eran
Hart, Dick Hardt, Craig Heath, Phil Hunt, Michael B. Jones, Terry Hammer, Justin Hart, Dick Hardt, Craig Heath, Phil Hunt, Michael B.
Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen Le Hara, Rasmus Jones, Terry Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen Le
Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey Lucas, Paul Madsen, Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey Lucas,
Alastair Mair, Eve Maler, James Manger, Mark McGloin, Laurence Miao, Paul Madsen, Alastair Mair, Eve Maler, James Manger, Mark McGloin,
William Mills, Chuck Mortimore, Anthony Nadalin, Julian Reschke, Laurence Miao, William Mills, Chuck Mortimore, Anthony Nadalin,
Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius Julian Reschke, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob
Scurtescu, Naitik Shah, Luke Shepard, Vlad Skvortsov, Justin Smith, Sayre, Marius Scurtescu, Naitik Shah, Luke Shepard, Vlad Skvortsov,
Haibin Song, Niv Steingarten, Christian Stuebner, Jeremy Suriel, Paul Justin Smith, Haibin Song, Niv Steingarten, Christian Stuebner,
Tarjan, Christopher Thomas, Henry S. Thompson, Allen Tom, Franklin Jeremy Suriel, Paul Tarjan, Christopher Thomas, Henry S. Thompson,
Tse, Nick Walker, Shane Weeden, and Skylar Woodward. Allen Tom, Franklin Tse, Nick Walker, Shane Weeden, and Skylar
Woodward.
This document was produced under the chairmanship of Blaine Cook, This document was produced under the chairmanship of Blaine Cook,
Peter Saint-Andre, Hannes Tschofenig, Barry Leiba, and Derek Atkins. Peter Saint-Andre, Hannes Tschofenig, Barry Leiba, and Derek Atkins.
The area directors included Lisa Dusseault, Peter Saint-Andre, and The area directors included Lisa Dusseault, Peter Saint-Andre, and
Stephen Farrell. Stephen Farrell.
Appendix C. Editor's Notes Appendix D. Document History
While many people contributed to this specification throughout its [[ to be removed by the RFC editor before publication as an RFC ]]
long journey, the editor would like to acknowledge and thank a few
individuals for their outstanding and invaluable efforts leading up
to the publication of this specification.
David Recordon for continuously being one of OAuth's most valuable -29
assets, bringing pragmatism and urgency to the work, and helping o Added "MUST" to "A public client that was not issued a client
shape it from its very beginning, as well as being one of the best password MUST use the "client_id" request parameter to identify
collaborators I had the pleasure of working with. itself when sending requests to the token endpoint" and added text
explaining why this must be so.
o Added that the authorization server MUST "ensure the authorization
code was issued to the authenticated confidential client or to the
public client identified by the "client_id" in the request".
o Added Security Considerations section "Misuse of Access Token to
Impersonate Resource Owner in Implicit Flow".
o Added references in the "Implicit" and "Implicit Grant" sections
to particularly pertinent security considerations.
o Added appendix "Use of application/x-www-form-urlencoded Media
Type" and referenced it in places that this encoding is used.
o Deleted ";charset=UTF-8" from examples formerly using "Content-
Type: application/x-www-form-urlencoded;charset=UTF-8".
o Added the phrase "with a character encoding of UTF-8" when
describing how to send requests using the HTTP request entity-
body.
o For symmetry when using HTTP Basic authentication, also apply the
"application/x-www-form-urlencoded" encoding to the client
password, just as was already done for the client identifier.
o Added "The ABNF below is defined in terms of Unicode code points
[W3C.REC-xml-20081126]; these characters are typically encoded in
UTF-8".
o Replaced UNICODENOCTRLCHAR in ABNF with UNICODECHARNOCRLF = %x09 /
%x20-7E / %x80-D7FF / %xE000-FFFD / %x10000-10FFFF.
o Corrected incorrect uses of "which".
o Reduced multiple blank lines around artwork elements to single
blank lines.
o Removed Eran Hammer's name from the author list, at his request.
Dick Hardt is now listed as the editor.
James Manger for his creative ideas and always insightful feedback. -28
Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, o Updated the ABNF in the manner discussed by the working group,
Marius Scurtescu, and Luke Shepard for their continued participation allowing "username" and "password" to be Unicode and restricting
and valuable feedback. "client_id" and "client_secret" to ASCII.
o Specified the use of the application/x-www-form-urlencoded
content-type encoding method to encode the "client_id" when used
as the password for HTTP Basic.
Special thanks goes to Mike Curtis and Yahoo! for their unconditional -27
support of this work for over three years. o Added character set restrictions for error, error_description, and
error_uri parameters consistent with the OAuth Bearer spec.
o Added "resource access error response" as an error usage location
in the OAuth Extensions Error Registry.
o Added an ABNF for all message elements.
o Corrected editorial issues identified during review.
Authors' Addresses Authors' Addresses
Eran Hammer (editor) Dick Hardt (editor)
Microsoft
Email: eran@hueniverse.com Email: dick.hardt@gmail.com
URI: http://hueniverse.com URI: http://dickhardt.org/
David Recordon David Recordon
Facebook Facebook
Email: dr@fb.com Email: dr@fb.com
URI: http://www.davidrecordon.com/ URI: http://www.davidrecordon.com/
Dick Hardt
Microsoft
Email: dick.hardt@gmail.com
URI: http://dickhardt.org/
 End of changes. 133 change blocks. 
213 lines changed or deleted 355 lines changed or added

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