| < draft-ietf-oauth-v2-17.txt | draft-ietf-oauth-v2-18.txt > | |||
|---|---|---|---|---|
| Network Working Group E. Hammer-Lahav, Ed. | Network Working Group E. Hammer-Lahav, Ed. | |||
| Internet-Draft Yahoo! | Internet-Draft Yahoo! | |||
| Obsoletes: 5849 (if approved) D. Recordon | Obsoletes: 5849 (if approved) D. Recordon | |||
| Intended status: Standards Track Facebook | Intended status: Standards Track Facebook | |||
| Expires: January 9, 2012 D. Hardt | Expires: January 9, 2012 D. Hardt | |||
| Microsoft | Microsoft | |||
| July 8, 2011 | July 8, 2011 | |||
| The OAuth 2.0 Authorization Protocol | The OAuth 2.0 Authorization Protocol | |||
| draft-ietf-oauth-v2-17 | draft-ietf-oauth-v2-18 | |||
| Abstract | Abstract | |||
| The OAuth 2.0 authorization protocol enables a third-party | The OAuth 2.0 authorization protocol enables a third-party | |||
| application to obtain limited access to an HTTP service, either on | application to obtain limited access to an HTTP service, either on | |||
| behalf of a resource owner by orchestrating an approval interaction | behalf of a resource owner by orchestrating an approval interaction | |||
| between the resource owner and the HTTP service, or by allowing the | between the resource owner and the HTTP service, or by allowing the | |||
| third-party application to obtain access on its own behalf. | third-party application to obtain access on its own behalf. | |||
| Status of this Memo | Status of this Memo | |||
| skipping to change at page 2, line 10 ¶ | skipping to change at page 2, line 10 ¶ | |||
| (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 | |||
| carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
| to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
| include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
| the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
| described in the Simplified BSD License. | described in the Simplified BSD License. | |||
| Table of Contents | Table of Contents | |||
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
| 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 | 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
| 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6 | 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 5 | |||
| 1.3. Access Token . . . . . . . . . . . . . . . . . . . . . . 7 | 1.3. Access Token . . . . . . . . . . . . . . . . . . . . . . 6 | |||
| 1.4. Authorization Grant . . . . . . . . . . . . . . . . . . . 8 | 1.4. Authorization Grant . . . . . . . . . . . . . . . . . . . 7 | |||
| 1.4.1. Authorization Code . . . . . . . . . . . . . . . . . . 8 | 1.4.1. Authorization Code . . . . . . . . . . . . . . . . . . 7 | |||
| 1.4.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8 | 1.4.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
| 1.4.3. Resource Owner Password Credentials . . . . . . . . . 9 | 1.4.3. Resource Owner Password Credentials . . . . . . . . . 8 | |||
| 1.4.4. Client Credentials . . . . . . . . . . . . . . . . . . 9 | 1.4.4. Client Credentials . . . . . . . . . . . . . . . . . . 8 | |||
| 1.4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . 9 | 1.4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . 8 | |||
| 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9 | 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 8 | |||
| 1.6. Notational Conventions . . . . . . . . . . . . . . . . . 11 | 1.6. Notational Conventions . . . . . . . . . . . . . . . . . 10 | |||
| 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 11 | 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 10 | |||
| 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 12 | 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 11 | |||
| 2.2. Registration Requirements . . . . . . . . . . . . . . . . 12 | 2.2. Registration Requirements . . . . . . . . . . . . . . . . 11 | |||
| 2.3. Client Identifier . . . . . . . . . . . . . . . . . . . . 12 | 2.3. Client Identifier . . . . . . . . . . . . . . . . . . . . 11 | |||
| 2.4. Client Authentication . . . . . . . . . . . . . . . . . . 12 | 2.4. Client Authentication . . . . . . . . . . . . . . . . . . 11 | |||
| 2.4.1. Client Password . . . . . . . . . . . . . . . . . . . 13 | 2.4.1. Client Password . . . . . . . . . . . . . . . . . . . 12 | |||
| 2.4.2. Other Authentication Methods . . . . . . . . . . . . . 14 | 2.4.2. Other Authentication Methods . . . . . . . . . . . . . 13 | |||
| 2.5. Unregistered Clients . . . . . . . . . . . . . . . . . . 14 | 2.5. Unregistered Clients . . . . . . . . . . . . . . . . . . 13 | |||
| 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 14 | 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 13 | |||
| 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 14 | 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 13 | |||
| 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 15 | 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 14 | |||
| 3.1.2. Redirection URI . . . . . . . . . . . . . . . . . . . 16 | 3.1.2. Redirection URI . . . . . . . . . . . . . . . . . . . 15 | |||
| 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 18 | 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 17 | |||
| 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 18 | 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 17 | |||
| 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 19 | 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 18 | |||
| 4.1. Authorization Code . . . . . . . . . . . . . . . . . . . 19 | 4.1. Authorization Code . . . . . . . . . . . . . . . . . . . 18 | |||
| 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 21 | 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 20 | |||
| 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 22 | 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 21 | |||
| 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 24 | 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 23 | |||
| 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 25 | 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 24 | |||
| 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 25 | 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 24 | |||
| 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 28 | 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 27 | |||
| 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 29 | 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 28 | |||
| 4.3. Resource Owner Password Credentials . . . . . . . . . . . 32 | 4.3. Resource Owner Password Credentials . . . . . . . . . . . 30 | |||
| 4.3.1. Authorization Request and Response . . . . . . . . . . 33 | 4.3.1. Authorization Request and Response . . . . . . . . . . 31 | |||
| 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 33 | 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 32 | |||
| 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 34 | 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 33 | |||
| 4.4. Client Credentials . . . . . . . . . . . . . . . . . . . 34 | 4.4. Client Credentials . . . . . . . . . . . . . . . . . . . 33 | |||
| 4.4.1. Authorization Request and Response . . . . . . . . . . 35 | 4.4.1. Authorization Request and Response . . . . . . . . . . 34 | |||
| 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 35 | 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 34 | |||
| 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 36 | 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 35 | |||
| 4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . 36 | 4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . 35 | |||
| 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 37 | 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 36 | |||
| 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 37 | 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 36 | |||
| 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 39 | 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 38 | |||
| 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 40 | 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 39 | |||
| 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 41 | 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 40 | |||
| 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 42 | 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 41 | |||
| 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 43 | 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 42 | |||
| 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 43 | 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 42 | |||
| 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 43 | 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 42 | |||
| 8.3. Defining New Authorization Grant Types . . . . . . . . . 44 | 8.3. Defining New Authorization Grant Types . . . . . . . . . 43 | |||
| 8.4. Defining New Authorization Endpoint Response Types . . . 44 | 8.4. Defining New Authorization Endpoint Response Types . . . 43 | |||
| 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 44 | 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 43 | |||
| 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 45 | 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 44 | |||
| 10. Security Considerations . . . . . . . . . . . . . . . . . . . 46 | 10. Security Considerations . . . . . . . . . . . . . . . . . . . 45 | |||
| 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 47 | 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 46 | |||
| 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 47 | 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 46 | |||
| 10.3. Access Token Credentials . . . . . . . . . . . . . . . . 48 | 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 47 | |||
| 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 48 | 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 47 | |||
| 10.5. Request Confidentiality . . . . . . . . . . . . . . . . . 49 | 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 48 | |||
| 10.6. Endpoints Authenticity . . . . . . . . . . . . . . . . . 49 | 10.6. Authorization Code Leakage . . . . . . . . . . . . . . . 48 | |||
| 10.7. Credentials Guessing Attacks . . . . . . . . . . . . . . 49 | 10.7. Resource Owner Password Credentials . . . . . . . . . . . 49 | |||
| 10.8. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 49 | 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 49 | |||
| 10.9. Authorization Codes . . . . . . . . . . . . . . . . . . . 50 | 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 49 | |||
| 10.10. Authorization Code Leakage . . . . . . . . . . . . . . . 50 | 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 49 | |||
| 10.11. Redirection URI Validation . . . . . . . . . . . . . . . 51 | 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 50 | |||
| 10.12. Resource Owner Password Credentials . . . . . . . . . . . 51 | 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 50 | |||
| 10.13. Cross-Site Request Forgery . . . . . . . . . . . . . . . 51 | 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 51 | |||
| 10.14. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 52 | 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 | |||
| 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 | 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 51 | |||
| 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 52 | 11.1.1. Registration Template . . . . . . . . . . . . . . . . 52 | |||
| 11.1.1. Registration Template . . . . . . . . . . . . . . . . 53 | 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 52 | |||
| 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 53 | 11.2.1. Registration Template . . . . . . . . . . . . . . . . 53 | |||
| 11.2.1. Registration Template . . . . . . . . . . . . . . . . 54 | 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 53 | |||
| 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 54 | ||||
| 11.3. The OAuth Authorization Endpoint Response Type | 11.3. The OAuth Authorization Endpoint Response Type | |||
| Registry . . . . . . . . . . . . . . . . . . . . . . . . 56 | Registry . . . . . . . . . . . . . . . . . . . . . . . . 55 | |||
| 11.3.1. Registration Template . . . . . . . . . . . . . . . . 57 | 11.3.1. Registration Template . . . . . . . . . . . . . . . . 56 | |||
| 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 57 | 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 56 | |||
| 11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 57 | 11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 57 | |||
| 11.4.1. Registration Template . . . . . . . . . . . . . . . . 58 | 11.4.1. Registration Template . . . . . . . . . . . . . . . . 57 | |||
| 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 59 | 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 58 | |||
| Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 59 | Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 59 | |||
| 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 60 | 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59 | |||
| 13.1. Normative References . . . . . . . . . . . . . . . . . . 60 | 13.1. Normative References . . . . . . . . . . . . . . . . . . 59 | |||
| 13.2. Informative References . . . . . . . . . . . . . . . . . 61 | 13.2. Informative References . . . . . . . . . . . . . . . . . 60 | |||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 61 | ||||
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 62 | ||||
| 1. Introduction | 1. Introduction | |||
| In the traditional client-server authentication model, the client | In the traditional client-server authentication model, the client | |||
| accesses a protected resource on the server by authenticating with | accesses a protected resource on the server by authenticating with | |||
| the server using the resource owner's credentials. In order to | the server using the resource owner's credentials. In order to | |||
| provide third-party applications access to protected resources, the | provide third-party applications access to protected resources, the | |||
| resource owner shares its credentials with the third-party. This | resource owner shares its credentials with the third-party. This | |||
| creates several problems and limitations: | creates several problems and limitations: | |||
| skipping to change at page 5, line 39 ¶ | skipping to change at page 4, line 39 ¶ | |||
| OAuth addresses these issues by introducing an authorization layer | OAuth addresses these issues by introducing an authorization layer | |||
| and separating the role of the client from that of the resource | and separating the role of the client from that of the resource | |||
| owner. In OAuth, the client requests access to resources controlled | owner. In OAuth, the client requests access to resources controlled | |||
| by the resource owner and hosted by the resource server, and is | by the resource owner and hosted by the resource server, and is | |||
| issued a different set of credentials than those of the resource | issued a different set of credentials than those of the resource | |||
| owner. | owner. | |||
| Instead of using the resource owner's credentials to access protected | Instead of using the resource owner's credentials to access protected | |||
| resources, the client obtains an access token - a string denoting a | resources, the client obtains an access token - a string denoting a | |||
| specific scope, duration, 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- | |||
| skipping to change at page 9, line 18 ¶ | skipping to change at page 8, line 18 ¶ | |||
| access token. However, this convenience should be weighted against | access token. However, this convenience should be weighted against | |||
| the security implications of using implicit grants, especially when | the security implications of using implicit grants, especially when | |||
| the authorization code grant type is available. | the authorization code grant type is available. | |||
| 1.4.3. Resource Owner Password Credentials | 1.4.3. Resource Owner Password Credentials | |||
| The resource owner password credentials (e.g. a username and | The resource owner password credentials (e.g. a username and | |||
| password) can be used directly as an authorization grant to obtain an | password) can be used directly as an authorization grant to obtain an | |||
| access token. The credentials should only be used when there is a | access token. The credentials should only be used when there is a | |||
| high degree of trust between the resource owner and the client (e.g. | high degree of trust between the resource owner and the client (e.g. | |||
| its computer operating system or a highly privileged application), | its device operating system or a highly privileged application), and | |||
| and when other authorization grant types are not available (such as | when other authorization grant types are not available (such as an | |||
| an authorization code). | authorization code). | |||
| Even though this grant type requires direct client access to the | Even though this grant type requires direct client access to the | |||
| resource owner credentials, the resource owner credentials are used | resource owner credentials, the resource owner credentials are used | |||
| for a single request and are exchanged for an access token. Unlike | for a single request and are exchanged for an access token. Unlike | |||
| the HTTP Basic authentication scheme defined in [RFC2617], this grant | the HTTP Basic authentication scheme defined in [RFC2617], this grant | |||
| type (when combined with a refresh token) eliminates the need for the | type (when combined with a refresh token) eliminates the need for the | |||
| client to store the resource owner credentials for future use. | client to store the resource owner credentials for future use. | |||
| 1.4.4. Client Credentials | 1.4.4. Client Credentials | |||
| skipping to change at page 11, line 41 ¶ | skipping to change at page 10, line 41 ¶ | |||
| Unless otherwise noted, all the protocol parameter names and values | Unless otherwise noted, all the protocol parameter names and values | |||
| are case sensitive. | are case sensitive. | |||
| 2. Client Registration | 2. Client Registration | |||
| [[ Pending Consensus ]] | [[ Pending Consensus ]] | |||
| Before initiating the protocol, the client registers with the | Before initiating the protocol, the client registers with the | |||
| authorization server. The means through which the client registers | authorization server. The means through which the client registers | |||
| with the authorization server are beyond the scope of this | with the authorization server are beyond the scope of this | |||
| specification, but typically involve human interaction with an HTML | specification, but typically involve end-user interaction with an | |||
| registration form. | HTML registration form. | |||
| Client registration does not require a direct interaction between the | Client registration does not require a direct interaction between the | |||
| client and the authorization server. When supported by the | client and the authorization server. When supported by the | |||
| authorization server, registration can rely on other means for | authorization server, registration can rely on other means for | |||
| establishing trust and obtaining the required client properties (e.g. | establishing trust and obtaining the required client properties (e.g. | |||
| redirection URI, client type). For example, registration can be | redirection URI, client type). For example, registration can be | |||
| accomplished using a self-issued or third-party-issued assertion, or | accomplished using a self-issued or third-party-issued assertion, or | |||
| by the authorization server performing client discovery using a | by the authorization server performing client discovery using a | |||
| trusted channel. | trusted channel. | |||
| skipping to change at page 26, line 19 ¶ | skipping to change at page 25, line 19 ¶ | |||
| from the authorization server. | from the authorization server. | |||
| Unlike the authorization code grant type in which the client makes | Unlike the authorization code grant type in which the client makes | |||
| separate requests for authorization and access token, the client | separate requests for authorization and access token, the client | |||
| receives the access token as the result of the authorization request. | receives the access token as the result of the authorization request. | |||
| The implicit grant type does not include client authentication, and | The implicit grant type does not include client authentication, and | |||
| relies on the presence of the resource owner and the registration of | relies on the presence of the resource owner and the registration of | |||
| the redirection URI. Because the access token is encoded into the | the redirection URI. Because the access token is encoded into the | |||
| redirection URI, it may be exposed to the resource owner and other | redirection URI, it may be exposed to the resource owner and other | |||
| applications residing on its computer or device. | applications residing on its device. | |||
| +----------+ | +----------+ | |||
| | Resource | | | Resource | | |||
| | Owner | | | Owner | | |||
| | | | | | | |||
| +----------+ | +----------+ | |||
| ^ | ^ | |||
| | | | | |||
| (B) | (B) | |||
| +----|-----+ Client Identifier +---------------+ | +----|-----+ Client Identifier +---------------+ | |||
| skipping to change at page 29, line 41 ¶ | skipping to change at page 28, line 41 ¶ | |||
| 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: | |||
| access_token | access_token | |||
| REQUIRED. The access token issued by the authorization server. | REQUIRED. The access token issued by the authorization server. | |||
| token_type | token_type | |||
| REQUIRED. The type of the token issued as described in | REQUIRED. The type of the token issued as described in | |||
| Section 7.1. Value is case insensitive. | Section 7.1. Value is case insensitive. | |||
| expires_in | expires_in | |||
| OPTIONAL. The duration in seconds of the access token | OPTIONAL. The lifetime in seconds of the access token. For | |||
| lifetime. For example, the value "3600" denotes that the | example, the value "3600" denotes that the access token will | |||
| access token will expire in one hour from the time the response | expire in one hour from the time the response was generated. | |||
| was generated. | ||||
| scope | scope | |||
| OPTIONAL. The scope of the access token expressed as a list of | OPTIONAL. The scope of the access token expressed as a list of | |||
| space-delimited, case sensitive strings. The value is defined | space-delimited, case sensitive strings. The value is defined | |||
| by the authorization server. If the value contains multiple | by the authorization server. If the value contains multiple | |||
| space-delimited strings, their order does not matter, and each | space-delimited strings, their order does not matter, and each | |||
| string adds an additional access range to the requested scope. | string adds an additional access range to the requested scope. | |||
| The authorization server SHOULD include the parameter if the | The authorization server SHOULD include the parameter if the | |||
| access token scope is different from the one requested by the | access token scope is different from the one requested by the | |||
| client. | client. | |||
| state | state | |||
| REQUIRED if the "state" parameter was present in the client | REQUIRED if the "state" parameter was present in the client | |||
| authorization request. Set to the exact value received from | authorization request. Set to the exact value received from | |||
| the client. | the client. | |||
| For example, the authorization server redirects the user-agent by | For example, the authorization server redirects the user-agent by | |||
| sending the following HTTP response (URI extra line breaks are for | sending the following HTTP response (URI extra line breaks are for | |||
| skipping to change at page 32, line 9 ¶ | skipping to change at page 30, line 50 ¶ | |||
| 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.3. Resource Owner Password Credentials | 4.3. Resource Owner Password Credentials | |||
| The resource owner password credentials grant type is suitable in | The resource owner password credentials grant type is suitable in | |||
| cases where the resource owner has a trust relationship with the | cases where the resource owner has a trust relationship with the | |||
| client, such as its computer operating system or a highly privileged | client, such as its device operating system or a highly privileged | |||
| application. The authorization server should take special care when | application. The authorization server should take special care when | |||
| enabling the grant type, and only when other flows are not viable. | enabling the grant type, and only when other flows are not viable. | |||
| The grant type is suitable for clients capable of obtaining the | The grant type is suitable for clients capable of obtaining the | |||
| resource owner credentials (username and password, typically using an | resource owner credentials (username and password, typically using an | |||
| interactive form). It is also used to migrate existing clients using | interactive form). It is also used to migrate existing clients using | |||
| direct authentication schemes such as HTTP Basic or Digest | direct authentication schemes such as HTTP Basic or Digest | |||
| authentication to OAuth by converting the stored credentials to an | authentication to OAuth by converting the stored credentials to an | |||
| access token. | access token. | |||
| skipping to change at page 37, line 44 ¶ | skipping to change at page 36, line 44 ¶ | |||
| The authorization server issues an access token and optional refresh | The authorization server issues an access token and optional refresh | |||
| token, and constructs the response by adding the following parameters | token, and constructs the response by adding the following parameters | |||
| to the entity body of the HTTP response with a 200 (OK) status code: | to the entity body of the HTTP response with a 200 (OK) status code: | |||
| access_token | access_token | |||
| REQUIRED. The access token issued by the authorization server. | REQUIRED. The access token issued by the authorization server. | |||
| token_type | token_type | |||
| REQUIRED. The type of the token issued as described in | REQUIRED. The type of the token issued as described in | |||
| Section 7.1. Value is case insensitive. | Section 7.1. Value is case insensitive. | |||
| expires_in | expires_in | |||
| OPTIONAL. The duration in seconds of the access token | OPTIONAL. The lifetime in seconds of the access token. For | |||
| lifetime. For example, the value "3600" denotes that the | example, the value "3600" denotes that the access token will | |||
| access token will expire in one hour from the time the response | expire in one hour from the time the response was generated. | |||
| was generated. | ||||
| refresh_token | refresh_token | |||
| OPTIONAL. The refresh token which can be used to obtain new | OPTIONAL. The refresh token which can be used to obtain new | |||
| access tokens using the same authorization grant as described | access tokens using the same authorization grant as described | |||
| in Section 6. | in Section 6. | |||
| scope | scope | |||
| OPTIONAL. The scope of the access token expressed as a list of | OPTIONAL. The scope of the access token expressed as a list of | |||
| space-delimited, case sensitive strings. The value is defined | space-delimited, case sensitive strings. The value is defined | |||
| by the authorization server. If the value contains multiple | by the authorization server. If the value contains multiple | |||
| space-delimited strings, their order does not matter, and each | space-delimited strings, their order does not matter, and each | |||
| skipping to change at page 38, line 28 ¶ | skipping to change at page 37, line 28 ¶ | |||
| The parameters are included in the entity body of the HTTP response | The parameters are included in the entity body of the HTTP response | |||
| using the "application/json" media type as defined by [RFC4627]. The | using the "application/json" media type as defined by [RFC4627]. The | |||
| parameters are serialized into a JSON structure by adding each | parameters are serialized into a JSON structure by adding each | |||
| parameter at the highest structure level. Parameter names and string | parameter at the highest structure level. Parameter names and string | |||
| values are included as JSON strings. Numerical values are included | values are included as JSON strings. Numerical values are included | |||
| as JSON numbers. | as JSON numbers. | |||
| The authorization server MUST include the HTTP "Cache-Control" | The authorization server MUST include the HTTP "Cache-Control" | |||
| response header field [RFC2616] with a value of "no-store" in any | response header field [RFC2616] with a value of "no-store" in any | |||
| response containing tokens, secrets, or other sensitive information, | response containing tokens, credentials, or other sensitive | |||
| as well as the "Pragma" response header field [RFC2616] with a value | information, as well as the "Pragma" response header field [RFC2616] | |||
| of "no-cache". | with a value of "no-cache". | |||
| For example: | For example: | |||
| HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
| Content-Type: application/json;charset=UTF-8 | Content-Type: application/json;charset=UTF-8 | |||
| Cache-Control: no-store | Cache-Control: no-store | |||
| Pragma: no-cache | Pragma: no-cache | |||
| { | { | |||
| "access_token":"2YotnFZFEjr1zCsicMWpAA", | "access_token":"2YotnFZFEjr1zCsicMWpAA", | |||
| skipping to change at page 45, line 32 ¶ | skipping to change at page 44, line 32 ¶ | |||
| The authorization endpoint requires interaction between the client | The authorization endpoint requires interaction between the client | |||
| and the resource owner's user-agent. Native applications can invoke | and the resource owner's user-agent. Native applications can invoke | |||
| an external user-agent or embed a user-agent within the application. | an external user-agent or embed a user-agent within the application. | |||
| For example: | For example: | |||
| o External user-agent - the native application can capture the | o External user-agent - the native application can capture the | |||
| response from the authorization server using a redirection URI | response from the authorization server using a redirection URI | |||
| with an scheme registered with the operating system to invoke the | with an scheme registered with the operating system to invoke the | |||
| client as the handler, manual copy-and-paste of the credentials, | client as the handler, manual copy-and-paste of the credentials, | |||
| running a local web server, installing a user-agent plug-in, or by | running a local web server, installing a user-agent extension, or | |||
| providing a redirection URI identifying a server-hosted resource | by providing a redirection URI identifying a server-hosted | |||
| under the client's control, which in turn makes the response | resource under the client's control, which in turn makes the | |||
| available to the native application. | response available to the native application. | |||
| o Embedded user-agent - the native application obtains the response | o Embedded user-agent - the native application obtains the response | |||
| by directly communicating with the embedded user-agent by | by directly communicating with the embedded user-agent by | |||
| monitoring state changes emitted during the resource load, | monitoring state changes emitted during the resource load, or | |||
| monitoring HTTP headers, or accessing the user-agent's cookies | accessing the user-agent's cookies storage. | |||
| storage. | ||||
| When choosing between an external or embedded user-agent, developers | When choosing between an external or embedded user-agent, developers | |||
| should consider: | should consider: | |||
| o External user-agents may improve completion rate as the resource | o External user-agents may improve completion rate as the resource | |||
| owner may already have an active session with the authorization | owner may already have an active session with the authorization | |||
| server removing the need to re-authenticate, and provide a | server removing the need to re-authenticate. It provides a | |||
| familiar user-agent user experience and functionality. The | familiar end-user experience and functionality. The resource | |||
| resource owner may also rely on extensions or add-ons to assist | owner may also rely on user-agent features or extensions to assist | |||
| with authentication (e.g. password managers or 2-factor device | with authentication (e.g. password manager, 2-factor device | |||
| reader). | reader). | |||
| o Embedded user-agents may offer an improved usability, as they | o Embedded user-agents may offer an improved usability, as they | |||
| remove the need to switch context and open new windows. | remove the need to switch context and open new windows. | |||
| o Embedded user-agents pose a security challenge because resource | o Embedded user-agents pose a security challenge because resource | |||
| owners are authenticating in an unidentified window without access | owners are authenticating in an unidentified window without access | |||
| to the visual protections found on by many of the external user- | to the visual protections found in most external user-agents. | |||
| agents. Embedded user-agents educate end-user to trust | Embedded user-agents educate end-user to trust unidentified | |||
| unidentified requests for authentication (making phishing attacks | requests for authentication (making phishing attacks easier to | |||
| easier to execute). | execute). | |||
| When choosing between implicit and authorization code grant types, | When choosing between the implicit grant type and the authorization | |||
| 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 | |||
| flow SHOULD do so without using client password credentials, due | SHOULD do so without using client credentials, due to the native | |||
| to the native application's inability to keep those credentials | application's inability to keep credentials confidential. | |||
| secure. | ||||
| o When using the implicit grant type flow a refresh token is not | o When using the implicit grant type flow a refresh token is not | |||
| returned. | returned. | |||
| 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 three common | provide implementers with security guidelines focused on three common | |||
| client types: | client types: | |||
| Web Application | Web Application | |||
| A web application is a client running on a web server. Resource | A web application is a client running on a web server. Resource | |||
| owners access the client via an HTML user interface rendered in a | owners access the client via an HTML user interface rendered in a | |||
| user-agent on the resource-owner's device. The client credentials | user-agent on the resource-owner's device. The client credentials | |||
| as well as any access token issued to the client are stored on the | as well as any access token issued to the client are stored on the | |||
| web server and are not exposed to or accessible by the resource | web server and are not exposed to or accessible by the resource | |||
| owner. | owner. | |||
| User-Agent-based Application | User-Agent-based Application | |||
| A user-agent-based application is a client in which the client | A user-agent-based application is a client in which the client | |||
| code is downloaded from a web server and executes within a user- | code is downloaded from a web server and executes within a user- | |||
| agent on the resource owner's device. The OAuth protocol data and | agent on the resource owner's device. Protocol data and | |||
| credentials are accessible to the resource owner. Since such | credentials are easily accessible (and often visible) to the | |||
| applications directly reside within the user-agent, they can make | resource owner. Since such applications reside within the user- | |||
| seamless use of the user-agent capabilities in the resource owner | agent, they can make seamless use of the user-agent capabilities | |||
| authorization process. | when requesting authorization. | |||
| Native Application | Native Application | |||
| A native application is a client which is installed and executes | A native application is a client installed and executed on the | |||
| on the resource owner's device. The OAuth protocol data and | resource owner's device. Protocol data and credentials are | |||
| credentials are accessible to the resource owner. It is assumed | accessible to the resource owner. It is assumed that any client | |||
| that any client authentication credentials included in the | authentication credentials included in the application can be | |||
| application can be extracted, and furthermore that rotation of the | extracted, and furthermore that rotation of the client | |||
| client authentication credentials is not practical. Dynamically | authentication credentials is impractical. On the other hand, | |||
| issued credentials such as access tokens or refresh tokens, on the | dynamically issued credentials such access tokens or refresh | |||
| other hand, can receive an acceptable level of protection. At a | tokens, can receive an acceptable level of protection. At a | |||
| minimum these credentials are protected from hostile servers which | minimum, these credentials are protected from hostile servers | |||
| the application may contact. On some platform those credentials | which the application may interact with. On some platform these | |||
| might be protected from other applications residing on the same | credentials might be protected from other applications residing on | |||
| device. | the same device. | |||
| A comprehensive OAuth security model and analysis, as well as | A comprehensive OAuth security model and analysis, as well as | |||
| background for the protocol design is provided in | background for the protocol design is provided by | |||
| [I-D.lodderstedt-oauth-security]. | [I-D.lodderstedt-oauth-security]. | |||
| 10.1. Client Authentication | 10.1. Client Authentication | |||
| The authorization server issues client credentials to web | The authorization server establishes client credentials with web | |||
| applications for the purpose of authenticating them. The | application clients for the purpose of client authentication. The | |||
| authorization server is encouraged to consider using stronger client | authorization server is encouraged to consider stronger client | |||
| authentication means than a client password. Application developers | authentication means than a client password. Web application clients | |||
| MUST ensure confidentiality of client passwords and other | MUST ensure confidentiality of client passwords and other client | |||
| credentials. | credentials. | |||
| The authorization server MUST NOT issue client passwords or other | The authorization server MUST NOT issue client passwords or other | |||
| credentials to native or user-agent-based applications for the | client credentials to native application or user-agent-based | |||
| purpose of client authentication. The authorization server MAY issue | application clients for the purpose of client authentication. The | |||
| a client password or other credentials for a specific installation of | authorization server MAY issue a client password or other credentials | |||
| a native application on a specific device. | for a specific installation of a native application client on a | |||
| specific device. | ||||
| 10.2. Client Impersonation | 10.2. Client Impersonation | |||
| Given the inability of some clients to keep their client credentials | A malicious client can impersonate another client and obtain access | |||
| confidential, a malicious client can impersonate another client and | to protected resources, if the impersonated client fails to, or is | |||
| obtain access to protected resources. The authorization server MUST | unable to, keep is client credentials confidential. | |||
| authenticate the client whenever possible. If the authorization | ||||
| server cannot authenticate the a client due to the client's | The authorization server MUST authenticate the client whenever | |||
| limitations, the authorization server should utilize other means to | possible. If the authorization server cannot authenticate the client | |||
| protect resource owners from such malicious clients, including but | due to the client nature, the authorization server MUST require the | |||
| not limited to engaging the resource owner to assist in identifying | registration of any redirection URI used for receiving authorization, | |||
| the client and its source. | and SHOULD utilize other means to protect resource owners from such | |||
| malicious clients. For example, engage the resource owner to assist | ||||
| in identifying the client and its origin. | ||||
| The authorization server SHOULD enforce explicit resource owner | The authorization server SHOULD enforce explicit resource owner | |||
| authentication, or prompt the resource owner to authorize access | authentication and provide the resource owner with information about | |||
| again, providing the resource owner with information about the | the client and the requested authorization scope and lifetime. It is | |||
| client, scope, and duration of the authorization. It is up to the | up to the resource owner to review the information in the context of | |||
| resource owner to review the information in the context of the | the current client, and authorize the request. | |||
| current client, and authorize the request. | ||||
| The authorization server SHOULD NOT automatically, without active | The authorization server SHOULD NOT process repeated authorization | |||
| resource owner interaction, process repeated authorization requests | requests automatically (without active resource owner interaction) | |||
| without authenticating the client or relying on other measures to | without authenticating the client or relying on other measures to | |||
| ensure the repeated request comes from a valid client and not an | ensure the repeated request comes from an authentic client and not an | |||
| impersonator. | impersonator. | |||
| The authorization server SHOULD require the client to register its | 10.3. Access Tokens | |||
| redirection URI and validate the value of the "redirect_uri" against | ||||
| the registered value. The client MUST NOT serve an open redirector | ||||
| resource which can be used by an attacker to construct an URI that | ||||
| will pass the authorization server's redirection URI matching rules, | ||||
| and will redirect the resource owner's user-agent to the attacker's | ||||
| server. | ||||
| 10.3. Access Token Credentials | ||||
| Access token credentials MUST be kept confidential in transit and | Access token (as well as any type-specific attributes) MUST be kept | |||
| storage, and shared only among the authorization server, the resource | confidential in transit and storage, and only shared among the | |||
| servers the credentials are valid for, and the client to whom the | authorization server, the resource servers the access token is valid | |||
| credentials were issued. | for, and the client to whom the access token is issued. | |||
| When using the implicit grant type, the access token credentials are | When using the implicit grant type, the access token is transmitted | |||
| transmitted in the URI fragment, which can expose the credentials to | in the URI fragment, which can expose it to unauthorized parties. | |||
| unauthorized parties. | ||||
| The authorization server MUST ensure that access token credentials | The authorization server MUST ensure that access tokens cannot be | |||
| cannot be generated, modified, or guessed to produce valid access | generated, modified, or guessed to produce valid access tokens. | |||
| token credentials. | ||||
| The client SHOULD request access token credentials with the minimal | The client SHOULD request access tokens with the minimal scope and | |||
| scope and duration necessary. The authorization server SHOULD take | lifetime necessary. The authorization server SHOULD take the client | |||
| the client identity into account when choosing to honor the requested | identity into account when choosing how to honor the requested scope | |||
| scope, and MAY issue credentials with a lesser scope than requested. | and lifetime, and MAY issue an access token with a less rights than | |||
| requested. | ||||
| 10.4. Refresh Tokens | 10.4. Refresh Tokens | |||
| Authorization servers MAY issue refresh tokens to web and native | Authorization servers MAY issue refresh tokens to web application | |||
| applications. | clients and native application clients. | |||
| Refresh tokens MUST be kept confidential in transit and storage, and | Refresh tokens MUST be kept confidential in transit and storage, and | |||
| shared only among the authorization server and the client to whom the | shared only among the authorization server and the client to whom the | |||
| refresh tokens were issued. The authorization server MUST maintain | refresh tokens were issued. The authorization server MUST maintain | |||
| the link between a refresh token and the client to whom it was | the binding between a refresh token and the client to whom it was | |||
| issued. | issued. | |||
| The authorization server MUST verify the link between the refresh | The authorization server MUST verify the binding between the refresh | |||
| token and client identity whenever the client's identity can be | token and client identity whenever the client identity can be | |||
| authenticated. When client authentication is not possible, the | authenticated. When client authentication is not possible, the | |||
| authorization server SHOULD deploy other means to detect refresh | authorization server SHOULD deploy other means to detect refresh | |||
| token abuse. | token abuse [[ add example ]]. | |||
| The authorization server MUST ensure that refresh tokens cannot be | The authorization server MUST ensure that refresh tokens cannot be | |||
| generated, modified, or guessed to produce valid refresh tokens. | generated, modified, or guessed to produce valid refresh tokens. | |||
| 10.5. Request Confidentiality | 10.5. Authorization Codes | |||
| Access token credentials, refresh tokens, resource owner passwords, | ||||
| and client secrets MUST NOT be transmitted in the clear. | ||||
| Authorization codes SHOULD NOT be transmitted in the clear. | ||||
| 10.6. Endpoints Authenticity | ||||
| In order to prevent man-in-the-middle and phishing attacks, the | ||||
| authorization server MUST implement and require TLS with server | ||||
| authentication in all exchanges as described by [RFC2818]. The | ||||
| client MUST validate the authorization server's TLS certificate in | ||||
| accordance with its requirements for authentication of the server's | ||||
| identity. | ||||
| 10.7. Credentials Guessing Attacks | ||||
| The authorization server MUST prevent attackers from guessing access | ||||
| tokens, authorization codes, refresh tokens, resource owner | ||||
| passwords, and client secrets. | ||||
| When generating tokens and other secrets not intended for direct | ||||
| human utilization, the authorization server MUST use a reasonable | ||||
| level of entropy in order to mitigate the risk of guessing attacks. | ||||
| When creating secrets intended for human usage, the authorization | ||||
| server MUST utilize other means to protect those secrets. | ||||
| 10.8. Phishing Attacks | ||||
| Native applications SHOULD use external browsers instead of embedding | ||||
| browsers within the application when requesting resource owner | ||||
| authorization. External browsers offer a familiar user experience | ||||
| and a trusted environment in which resource owners can confirm the | ||||
| authenticity of the authorization server. | ||||
| To reduce the risk of phishing attacks, the authorization servers | ||||
| MUST utilize TLS to allow user-agents to validate the authorization | ||||
| server's identity. Service providers should educate their end-users | ||||
| about the risks of phishing attacks and how they can verify the | ||||
| authorization server's identity. | ||||
| 10.9. Authorization Codes | ||||
| The transmission of authorization codes SHOULD be made over a secure | The transmission of authorization codes SHOULD be made over a secure | |||
| channel, and the client SHOULD implement TLS for use with its | channel, and the client SHOULD implement TLS for use with its | |||
| redirection URI if the URI identifies a network resource. | redirection URI if the URI identifies a network resource. Effort | |||
| Authorization codes MUST be kept confidential. Since authorization | should be made to keep authorization codes confidential. Since | |||
| codes are transmitted via user-agent redirections, they could | authorization codes are transmitted via user-agent redirections, they | |||
| potentially be disclosed through user-agent history and HTTP referrer | could potentially be disclosed through user-agent history and HTTP | |||
| headers. | referrer headers. | |||
| Authorization codes operate as plaintext bearer credentials, used to | Authorization codes operate as plaintext bearer credentials, used to | |||
| verify that the resource owner who granted authorization at the | verify that the resource owner who granted authorization at the | |||
| authorization server, is the same resource owner returning to the | authorization server, is the same resource owner returning to the | |||
| client to complete the process. Therefore, if the client relies on | client to complete the process. Therefore, if the client relies on | |||
| the authorization code for its own resource owner authentication, the | the authorization code for its own resource owner authentication, the | |||
| client redirection endpoint MUST require TLS. | client redirection endpoint MUST require TLS. | |||
| Authorization codes MUST be short lived and single use. If the | Authorization codes MUST be short lived and single use. If the | |||
| authorization server observes multiple attempts to exchange an | authorization server observes multiple attempts to exchange an | |||
| authorization code for an access token, the authorization server | authorization code for an access token, the authorization server | |||
| SHOULD attempt to revoke all access tokens already granted based on | SHOULD attempt to revoke all access tokens already granted based on | |||
| the compromised authorization code. | the compromised authorization code. | |||
| If the client can be authenticated, the authorization servers MUST | If the client can be authenticated, the authorization servers MUST | |||
| authenticate the client and ensure that the authorization code was | authenticate the client and ensure that the authorization code was | |||
| issued to the same client. | issued to the same client. | |||
| 10.10. Authorization Code Leakage | 10.6. Authorization Code Leakage | |||
| Session fixation attacks leverage the authorization code grant type, | Session fixation attacks leverage the authorization code grant type, | |||
| by tricking a resource owner to authorize access to a legitimate | by tricking a resource owner to authorize access to a legitimate | |||
| client, but to a client account under the control of the attacker. | client, but using a client account under the control of the attacker. | |||
| The only difference between a valid flow and the attack flow is in | The only difference between a valid request and the attack request is | |||
| how the victim reached the authorization server to grant access. | in how the victim reached the authorization server to grant access. | |||
| Once at the authorization server, the victim is prompted with a | Once at the authorization server, the victim is prompted with a | |||
| normal, valid request on behalf of a legitimate and familiar client. | normal, valid request on behalf of a legitimate and familiar client. | |||
| The attacker then uses the victim's authorization to gain access to | The attacker then uses the victim's authorization to gain access to | |||
| the information authorized by the victim. | the information authorized by the victim (via the client). | |||
| In order to prevent such an attack, authorization servers MUST ensure | In order to prevent such an attack, authorization servers MUST ensure | |||
| that the redirection URI used to obtain the authorization code, is | that the redirection URI used to obtain the authorization code, is | |||
| the same as the redirection URI provided when exchanging the | the same as the redirection URI provided when exchanging the | |||
| authorization code for an access token. The authorization server | authorization code for an access token. The authorization server | |||
| SHOULD require the client to register their redirection URI and if | SHOULD require the client to register their redirection URI and if | |||
| provided, MUST validate the redirection URI received in the | provided, MUST validate the redirection URI received in the | |||
| authorization request against the registered value. | authorization request against the registered value. | |||
| 10.11. Redirection URI Validation | 10.7. Resource Owner Password Credentials | |||
| [[ Add specific recommendations about redirection validation and | ||||
| matching ]] | ||||
| 10.12. Resource Owner Password Credentials | ||||
| The resource owner password credentials grant type is often used for | The resource owner password credentials grant type is often used for | |||
| legacy or migration reasons. It reduces the overall risk of storing | legacy or migration reasons. It reduces the overall risk of storing | |||
| username and password in the client, but does not eliminate the need | username and password by the client, but does not eliminate the need | |||
| to expose highly privileged credentials to the client. | to expose highly privileged credentials to the client. | |||
| This grant type carries a higher risk than the other grant types | This grant type carries a higher risk than other grant types because | |||
| because it maintains the password anti-pattern OAuth seeks to avoid. | it maintains the password anti-pattern this protocol seeks to avoid. | |||
| The client could abuse the password or the password could | The client could abuse the password or the password could | |||
| unintentionally be disclosed to an attacker (e.g. via log files or | unintentionally be disclosed to an attacker (e.g. via log files or | |||
| other records kept by the client). | other records kept by the client). | |||
| Additionally, because the resource owner does not have control over | Additionally, because the resource owner does not have control over | |||
| the authorization process (the resource owner involvement ends when | the authorization process (the resource owner involvement ends when | |||
| it hands over its credentials to the client), the client can obtain | it hands over its credentials to the client), the client can obtain | |||
| access tokens with a broader scope and longer duration than desired | access tokens with a broader scope and longer lifetime than desired | |||
| by the resource owner. The authorization server SHOULD restrict the | by the resource owner. The authorization server SHOULD restrict the | |||
| scope and duration of access tokens issued via this grant type. | scope and lifetime of access tokens issued via this grant type. | |||
| The authorization server and client SHOULD minimize use of this grant | The authorization server and client SHOULD minimize use of this grant | |||
| type and utilize other grant types whenever possible. | type and utilize other grant types whenever possible. | |||
| 10.13. Cross-Site Request Forgery | 10.8. Request Confidentiality | |||
| Access tokens, refresh tokens, resource owner passwords, and client | ||||
| credentials MUST NOT be transmitted in the clear. Authorization | ||||
| codes SHOULD NOT be transmitted in the clear. | ||||
| 10.9. Endpoints Authenticity | ||||
| In order to prevent man-in-the-middle and phishing attacks, the | ||||
| authorization server MUST implement and require TLS with server | ||||
| authentication as defined by [RFC2818] for any request sent to the | ||||
| authorization and token endpoints. The client MUST validate the | ||||
| authorization server's TLS certificate in accordance with its | ||||
| requirements for server identity authentication. | ||||
| 10.10. Credentials Guessing Attacks | ||||
| The authorization server MUST prevent attackers from guessing access | ||||
| tokens, authorization codes, refresh tokens, resource owner | ||||
| passwords, and client credentials. | ||||
| When generating tokens and other credentials not intended for | ||||
| handling by end-users, the authorization server MUST use a reasonable | ||||
| level of entropy in order to mitigate the risk of guessing attacks. | ||||
| The authorization server MUST utilize other means to protect | ||||
| credentials intended for end-user usage. | ||||
| 10.11. Phishing Attacks | ||||
| Wide deployment of this and similar protocols may cause end-users to | ||||
| become inured to the practice of being redirected to websites where | ||||
| they are asked to enter their passwords. If end-users are not | ||||
| careful to verify the authenticity of these websites before entering | ||||
| their credentials, it will be possible for attackers to exploit this | ||||
| practice to steal resource owners' passwords. | ||||
| Service providers should attempt to educate end-users about the risks | ||||
| phishing attacks pose, and should provide mechanisms that make it | ||||
| easy for end-users to confirm the authenticity of their sites. | ||||
| Client developers should consider the security implications of how | ||||
| they interact with the user-agent (e.g., external, embedded), and the | ||||
| ability of the end-user to verify the authenticity of the | ||||
| authorization server. | ||||
| To reduce the risk of phishing attacks, the authorization servers | ||||
| MUST utilize TLS on every endpoint used for end-user interaction. | ||||
| 10.12. Cross-Site Request Forgery | ||||
| Cross-site request forgery (CSRF) is a web-based attack whereby HTTP | Cross-site request forgery (CSRF) is a web-based attack whereby HTTP | |||
| requests are transmitted from the user-agent of an end-user the | requests are transmitted from the user-agent of an end-user the | |||
| server trusts or has authenticated. CSRF attacks on the | server trusts or has authenticated. CSRF attacks on the | |||
| authorization endpoint can allow an attacker to obtain authorization | authorization endpoint can allow an attacker to obtain authorization | |||
| without the consent of the resource owner. | without the consent of the resource owner. | |||
| The "state" request parameter SHOULD be used to mitigate against CSRF | The "state" request parameter SHOULD be used to mitigate against CSRF | |||
| attacks, particularly for login CSRF attacks. CSRF attacks against | attacks, particularly for login CSRF attacks. CSRF attacks against | |||
| the client's redirection URI allow an attacker to inject their own | the client's redirection URI allow an attacker to inject their own | |||
| skipping to change at page 52, line 7 ¶ | skipping to change at page 50, line 49 ¶ | |||
| than the victim's. Depending on the nature of the client and the | than the victim's. Depending on the nature of the client and the | |||
| protected resources, this can have undesirable and damaging effects. | protected resources, this can have undesirable and damaging effects. | |||
| It is strongly RECOMMENDED that the client includes the "state" | It is strongly RECOMMENDED that the client includes the "state" | |||
| request parameter with authorization requests to the authorization | request parameter with authorization requests to the authorization | |||
| server. The "state" request parameter MUST contain a non-guessable | server. The "state" request parameter MUST contain a non-guessable | |||
| value, and the client MUST keep it in a location accessible only by | value, and the client MUST keep it in a location accessible only by | |||
| the client or the user-agent (i.e., protected by same-origin policy). | the client or the user-agent (i.e., protected by same-origin policy). | |||
| For example, using a DOM variable (protected by JavaScript or other | For example, using a DOM variable (protected by JavaScript or other | |||
| DOM-binding language's enforcement of SOP), HTTP cookie, or HTML5 | DOM-binding language's enforcement of SOP [[ add reference ]]), HTTP | |||
| client-side storage. The authorization server includes the value of | cookie, or HTML5 client-side storage. The authorization server | |||
| the "state" parameter when redirecting the user-agent back to the | includes the value of the "state" parameter when redirecting the | |||
| client which MUST then ensure the received value matches the stored | user-agent back to the client which MUST then ensure the received | |||
| value. | value matches the stored value. | |||
| 10.14. Clickjacking | 10.13. Clickjacking | |||
| [[ Rework to use specification terminology ]] | ||||
| Clickjacking is the process of tricking end-users into revealing | ||||
| confidential information or taking control of their device while | ||||
| clicking on seemingly innocuous web pages. In more detail, a | ||||
| malicious site loads the target site in a transparent iframe overlaid | ||||
| on top of a set of dummy buttons which are carefully constructed to | ||||
| be placed directly under important buttons on the target site. When | ||||
| a user clicks a visible button, they are actually clicking a button | ||||
| (such as an "Authorize" button) on the hidden page. | ||||
| To prevent clickjacking (and phishing attacks), native applications | ||||
| SHOULD use external browsers instead of embedding browsers in an | ||||
| iframe when requesting end-user authorization. For newer browsers, | ||||
| avoidance of iframes can be enforced by the authorization server | ||||
| using the "x-frame-options" header [[ Add reference ]]. This header | ||||
| can have two values, "deny" and "sameorigin", which will block any | ||||
| framing or framing by sites with a different origin, respectively. | ||||
| For older browsers, javascript framebusting techniques can be used | ||||
| but may not be effective in all browsers. | ||||
| 11. IANA Considerations | 11. IANA Considerations | |||
| 11.1. The OAuth Access Token Type Registry | 11.1. The OAuth Access Token Type Registry | |||
| This specification establishes the OAuth access token type registry. | This specification establishes the OAuth access token type registry. | |||
| Access token types are registered on the advice of one or more | Access token types are registered on the advice of one or more | |||
| Designated Experts (appointed by the IESG or their delegate), with a | Designated Experts (appointed by the IESG or their delegate), with a | |||
| Specification Required (using terminology from [RFC5226]). However, | Specification Required (using terminology from [RFC5226]). However, | |||
| End of changes. 51 change blocks. | ||||
| 273 lines changed or deleted | 281 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ | ||||