< draft-ietf-oauth-v2-04.txt   draft-ietf-oauth-v2-05.txt >
Network Working Group E. Hammer-Lahav, Ed. Network Working Group E. Hammer-Lahav, Ed.
Internet-Draft Yahoo! Internet-Draft Yahoo!
Intended status: Standards Track D. Recordon Intended status: Standards Track D. Recordon
Expires: November 10, 2010 Facebook Expires: November 14, 2010 Facebook
D. Hardt D. Hardt
May 9, 2010 May 13, 2010
The OAuth 2.0 Protocol The OAuth 2.0 Protocol
draft-ietf-oauth-v2-04 draft-ietf-oauth-v2-05
Abstract Abstract
This specification describes the OAuth 2.0 protocol. OAuth provides This specification describes the OAuth 2.0 protocol. OAuth provides
a method for making authenticated HTTP requests using a token - an a method for making authenticated HTTP requests using a token - an
identifier used to denote an access grant with specific scope, identifier used to denote an access grant with specific scope,
duration, and other attributes. Tokens are issued to third-party duration, and other attributes. Tokens are issued to third-party
clients by an authorization server with the approval of the resource clients by an authorization server with the approval of the resource
owner. OAuth defines multiple flows for obtaining a token to support owner. OAuth defines multiple flows for obtaining a token to support
a wide range of client types and user experience. a wide range of client types and user experience.
skipping to change at page 1, line 38 skipping to change at page 1, line 38
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 November 10, 2010. This Internet-Draft will expire on November 14, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 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 19 skipping to change at page 2, line 19
Table of Contents Table of Contents
1. Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
2.2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4. Notational Conventions . . . . . . . . . . . . . . . . . . 8 2.4. Notational Conventions . . . . . . . . . . . . . . . . . . 8
2.5. Conformance . . . . . . . . . . . . . . . . . . . . . . . 8 2.5. Conformance . . . . . . . . . . . . . . . . . . . . . . . 8
3. Obtaining an Access Token . . . . . . . . . . . . . . . . . . 9 3. Obtaining an Access Token . . . . . . . . . . . . . . . . . . 9
3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . . 9 3.1. Client Credentials . . . . . . . . . . . . . . . . . . . . 9
3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . . 10 3.2. End-User Endpoint . . . . . . . . . . . . . . . . . . . . 9
3.2.1. Response Format . . . . . . . . . . . . . . . . . . . 10 3.3. Token Endpoint . . . . . . . . . . . . . . . . . . . . . . 10
3.3. Flow Parameters . . . . . . . . . . . . . . . . . . . . . 12 3.3.1. Client Authentication . . . . . . . . . . . . . . . . 11
3.4. Client Credentials . . . . . . . . . . . . . . . . . . . . 12 3.3.2. Response Format . . . . . . . . . . . . . . . . . . . 12
3.5. User-Agent Flow . . . . . . . . . . . . . . . . . . . . . 12 3.4. Flow Parameters . . . . . . . . . . . . . . . . . . . . . 14
3.5.1. Client Requests Authorization . . . . . . . . . . . . 14 3.5. User-Agent Flow . . . . . . . . . . . . . . . . . . . . . 15
3.5.2. Client Extracts Access Token . . . . . . . . . . . . . 17 3.5.1. Client Requests Authorization . . . . . . . . . . . . 16
3.6. Web Server Flow . . . . . . . . . . . . . . . . . . . . . 17 3.5.2. Client Extracts Access Token . . . . . . . . . . . . . 19
3.6.1. Client Requests Authorization . . . . . . . . . . . . 19 3.6. Web Server Flow . . . . . . . . . . . . . . . . . . . . . 20
3.6.2. Client Requests Access Token . . . . . . . . . . . . . 21 3.6.1. Client Requests Authorization . . . . . . . . . . . . 21
3.7. Device Flow . . . . . . . . . . . . . . . . . . . . . . . 23 3.6.2. Client Requests Access Token . . . . . . . . . . . . . 24
3.7.1. Client Requests Authorization . . . . . . . . . . . . 25 3.7. Device Flow . . . . . . . . . . . . . . . . . . . . . . . 25
3.7.2. Client Requests Access Token . . . . . . . . . . . . . 27 3.7.1. Client Requests Authorization . . . . . . . . . . . . 27
3.8. Username and Password Flow . . . . . . . . . . . . . . . . 29 3.7.2. Client Requests Access Token . . . . . . . . . . . . . 29
3.8.1. Client Requests Access Token . . . . . . . . . . . . . 30 3.8. Username and Password Flow . . . . . . . . . . . . . . . . 31
3.9. Client Credentials Flow . . . . . . . . . . . . . . . . . 32 3.8.1. Client Requests Access Token . . . . . . . . . . . . . 33
3.9.1. Client Requests Access Token . . . . . . . . . . . . . 32 3.9. Client Credentials Flow . . . . . . . . . . . . . . . . . 35
3.10. Assertion Flow . . . . . . . . . . . . . . . . . . . . . . 34 3.9.1. Client Requests Access Token . . . . . . . . . . . . . 35
3.10.1. Client Requests Access Token . . . . . . . . . . . . . 35 3.10. Assertion Flow . . . . . . . . . . . . . . . . . . . . . . 37
4. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 36 3.10.1. Client Requests Access Token . . . . . . . . . . . . . 38
5. Accessing a Protected Resource . . . . . . . . . . . . . . . . 38 4. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 40
5.1. The Authorization Request Header . . . . . . . . . . . . . 39 5. Accessing a Protected Resource . . . . . . . . . . . . . . . . 42
5.2. Bearer Token Requests . . . . . . . . . . . . . . . . . . 40 5.1. The Authorization Request Header . . . . . . . . . . . . . 43
5.2.1. URI Query Parameter . . . . . . . . . . . . . . . . . 41 5.2. Bearer Token Requests . . . . . . . . . . . . . . . . . . 44
5.2.2. Form-Encoded Body Parameter . . . . . . . . . . . . . 41 5.2.1. URI Query Parameter . . . . . . . . . . . . . . . . . 45
5.3. Cryptographic Tokens Requests . . . . . . . . . . . . . . 42 5.2.2. Form-Encoded Body Parameter . . . . . . . . . . . . . 45
5.3.1. The 'hmac-sha256' Algorithm . . . . . . . . . . . . . 43 5.3. Cryptographic Tokens Requests . . . . . . . . . . . . . . 46
6. Identifying a Protected Resource . . . . . . . . . . . . . . . 46 5.3.1. The 'hmac-sha256' Algorithm . . . . . . . . . . . . . 47
6.1. The WWW-Authenticate Response Header . . . . . . . . . . . 46 6. Identifying a Protected Resource . . . . . . . . . . . . . . . 50
6.1.1. The 'realm' Attribute . . . . . . . . . . . . . . . . 47 6.1. The WWW-Authenticate Response Header . . . . . . . . . . . 50
6.1.2. The 'authorization-uri' Attribute . . . . . . . . . . 47 7. Security Considerations . . . . . . . . . . . . . . . . . . . 51
6.1.3. The 'algorithms' Attribute . . . . . . . . . . . . . . 47 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51
6.1.4. The 'error' Attribute . . . . . . . . . . . . . . . . 47 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 52
7. Security Considerations . . . . . . . . . . . . . . . . . . . 47 Appendix A. Differences from OAuth 1.0a . . . . . . . . . . . . . 52
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47 Appendix B. Document History . . . . . . . . . . . . . . . . . . 52
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 47 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Appendix A. Differences from OAuth 1.0a . . . . . . . . . . . . . 47 10.1. Normative References . . . . . . . . . . . . . . . . . . . 53
Appendix B. Document History . . . . . . . . . . . . . . . . . . 48 10.2. Informative References . . . . . . . . . . . . . . . . . . 55
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 55
10.1. Normative References . . . . . . . . . . . . . . . . . . . 49
10.2. Informative References . . . . . . . . . . . . . . . . . . 50
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 50
1. Authors 1. Authors
This specification was authored with the participation and based on This specification was authored with the participation and based on
the work of Allen Tom (Yahoo!), Brian Eaton (Google), Brent Goldman the work of Allen Tom (Yahoo!), Brian Eaton (Google), Brent Goldman
(Facebook), Luke Shepard (Facebook), Raffi Krikorian (Twitter), and (Facebook), Luke Shepard (Facebook), Raffi Krikorian (Twitter), and
Yaron Goland (Microsoft). Yaron Goland (Microsoft).
2. Introduction 2. Introduction
skipping to change at page 5, line 40 skipping to change at page 5, line 40
bearer token An access token without a matching secret, used to bearer token An access token without a matching secret, used to
obtain access to a protected resource by simply presenting the obtain access to a protected resource by simply presenting the
access token as-is to the resource server. access token as-is to the resource server.
authorization server authorization server
An HTTP server capable of issuing tokens after successfully An HTTP server capable of issuing tokens after successfully
authenticating the resource owner and obtaining authorization. authenticating the resource owner and obtaining authorization.
The authorization server may be the same server as the resource The authorization server may be the same server as the resource
server, or a separate entity. server, or a separate entity.
authorization endpoint end-user endpoint
The authorization server's HTTP endpoint capable of The authorization server's HTTP endpoint capable of
authenticating the resource owner and obtaining authorization. authenticating the end-user and obtaining authorization.
token endpoint token endpoint
The authorization server's HTTP endpoint capable of issuing The authorization server's HTTP endpoint capable of issuing
tokens and refreshing expired tokens. tokens and refreshing expired tokens.
client identifier client identifier
An unique identifier issued to the client to identify itself to An unique identifier issued to the client to identify itself to
the authorization server. Client identifiers may have a the authorization server. Client identifiers may have a
matching secret. matching secret.
skipping to change at page 9, line 26 skipping to change at page 9, line 26
In many cases it is desirable to issue access tokens with a shorter In many cases it is desirable to issue access tokens with a shorter
lifetime than the duration of the authorization grant. However, it lifetime than the duration of the authorization grant. However, it
may be undesirable to require the resource owner to authorize the may be undesirable to require the resource owner to authorize the
request again. Instead, the authorization server issues a refresh request again. Instead, the authorization server issues a refresh
token in addition to the access token. When the access token token in addition to the access token. When the access token
expires, the client can request a new access token without involving expires, the client can request a new access token without involving
the resource owner as long as the authorization grant is still valid. the resource owner as long as the authorization grant is still valid.
The token refresh method is described in Section 4. The token refresh method is described in Section 4.
3.1. Authorization Endpoint 3.1. Client Credentials
Clients direct the resource owner to the authorization endpoint to When requesting access from the authorization server, the client
approve their access request. Before granting access, the resource identifies itself using a set of client credentials. The client
owner first authenticates with the authorization server. The way in credentials include a client identifier and an OPTIONAL symmetric
which the authorization server authenticates the end-user (e.g. shared secret. The means through which the client obtains these
username and password login, OpenID, session cookies) and in which credentials are beyond the scope of this specification, but usually
the authorization server obtains the end-user's authorization, involve registration with the authorization server.
The client identifier is used by the authorization server to
establish the identity of the client for the purpose of presenting
information to the resource owner prior to granting access, as well
as for providing different service levels to different clients. They
can also be used to block unauthorized clients from requesting
access.
Due to the nature of some clients, authorization servers SHOULD NOT
make assumptions about the confidentiality of client credentials
without establishing trust with the client operator. Authorization
servers SHOULD NOT issue client secrets to clients incapable of
keeping their secrets confidential.
3.2. End-User Endpoint
In flows that involved an end-user, clients direct the end-user to
the end-user endpoint to approve their access request. When
accessing the end-user endpoint, the end-user first authenticates
with the authorization server, and then approves or denies the access
request.
The way in which the authorization server authenticates the end-user
(e.g. username and password login, OpenID, session cookies) and in
which the authorization server obtains the end-user's authorization,
including whether it uses a secure channel such as TLS/SSL, is beyond including whether it uses a secure channel such as TLS/SSL, is beyond
the scope of this specification. However, the authorization server the scope of this specification. However, the authorization server
MUST first verify the identity of the end-user. MUST first verify the identity of the end-user.
The URI of the authorization endpoint can be found in the service The URI of the end-user endpoint can be found in the service
documentation, or can be obtained by the client by making an documentation, or can be obtained by the client by making an
unauthorized protected resource request (from the "WWW-Authenticate" unauthorized protected resource request (from the "WWW-Authenticate"
response header auth-uri (Section 6.1.2) attribute). response header "user-uri" attribute as described by Section 5.1).
The authorization endpoint advertised by the resource server MAY The end-user endpoint advertised by the resource server MAY include a
include a query component as defined by [RFC3986] section 3. query component as defined by [RFC3986] section 3, which must be
retained when adding additional query parameters.
Since requests to the authorization endpoint result in user Since requests to the end-user endpoint result in user authentication
authentication and the transmission of sensitive values, the and the transmission of sensitive values, the authorization server
authorization server SHOULD require the use of a transport-layer SHOULD require the use of a transport-layer mechanism such as TLS/SSL
mechanism such as TLS/SSL (or a secure channel with equivalent (or a secure channel with equivalent protections) when sending
protections) when sending requests to the authorization endpoints. requests to the end-user endpoint.
3.2. Token Endpoint 3.3. Token Endpoint
After obtaining authorization from the resource owner, clients After obtaining authorization from the resource owner, clients
request an access token from the authorization server's token request an access token from the authorization server's token
endpoint. endpoint.
The URI of the token endpoint can be found in the service The URI of the token endpoint can be found in the service
documentation, or can be obtained by the client by making an documentation, or can be obtained by the client by making an
unauthorized protected resource request (from the "WWW-Authenticate" unauthorized protected resource request (from the "WWW-Authenticate"
response header token-uri (Section 6.1.2) attribute). response header "token-uri" attribute as described by Section 5.1).
The token endpoint advertised by the resource server MAY include a The token endpoint advertised by the resource server MAY include a
query component as defined by [RFC3986] section 3. query component as defined by [RFC3986] section 3.
Since requests to the token endpoint result in the transmission of Since requests to the token endpoint result in the transmission of
plain text credentials in the HTTP request and response, the plain text credentials in the HTTP request and response, the
authorization server MUST require the use of a transport-layer authorization server MUST require the use of a transport-layer
mechanism such as TLS/SSL (or a secure channel with equivalent mechanism such as TLS/SSL (or a secure channel with equivalent
protections) when sending requests to the token endpoints. protections) when sending requests to the token endpoints.
3.2.1. Response Format 3.3.1. Client Authentication
The token endpoint requires the client to authenticate itself to the
authorization server. This is done by including the client
identifier (and optional secret) in the request. The client
identifier and secret are included in the request using two request
parameters: "client_id" and "client_secret".
For example (line breaks are for display purposes only):
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
type=web_server&client_id=s6BhdRkqt3&
client_secret=gX1fBat3bV&code=i1WsRn1uB1&
redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
The client MAY include the client credentials using an HTTP
authentication scheme instead of using the "client_id" and
"client_secret" request parameters. Including the client credentials
using an HTTP authentication scheme fullfills the requirements of
including the parameters as defined by the various flows. The client
MUST NOT include the client credentials using more than one
mechanism.
The authorization server MUST accept the client credentials using
both the request parameters, and the HTTP Basic authentication scheme
as defined in [RFC2617]. The authorization server MAY support
additional HTTP authentication schemes.
For example (line breaks are for display purposes only):
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
type=web_server&code=i1WsRn1uB1&
redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
3.3.2. Response Format
Authorization servers respond to client requests by including a set Authorization servers respond to client requests by including a set
of response parameters in the entity body of the HTTP response. The of response parameters in the entity body of the HTTP response. The
response uses the "application/json" media type as defined by response uses one of three formats based on the format requested by
[RFC4627]. the client (using the "format" request parameter):
The parameters are serialized into a JSON structure by adding each o The "application/json" media type as defined by [RFC4627]. The
parameter at the highest structure level. Parameter names and string parameters are serialized into a JSON structure by adding each
values are included as JSON strings. Numerical number are included parameter at the highest structure level. Parameter names and
as JSON numbers. string values are included as JSON strings. Numerical values are
included as JSON numbers.
For example:
{
"access_token":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8"
}
o The "application/xml" media type as defined by [RFC3023]. The
parameters are serialized into an XML structure by adding each
parameter as a child element of the root "<OAuth>" element. [[ Add
namespace ]]
For example:
<?xml version='1.0' encoding="utf-8"?>
<OAuth>
<access_token>SlAV32hkKG</access_token>
<expires_in>3600</expires_in>
<refresh_token>8xLOxBtZp8</refresh_token>
</OAuth>
o The "application/x-www-form-urlencoded" media type as defined by
[W3C.REC-html40-19980424].
For example (line breaks are for display purposes only):
access_token=SlAV32hkKG&expires_in=3600&
refresh_token=8xLOxBtZp8
The authorization server MUST include the HTTP "Cache-Control" The authorization server MUST include the HTTP "Cache-Control"
response header field with a value of "no-store" in any response response header field with a value of "no-store" in any response
containing tokens, secrets, or other sensitive information. containing tokens, secrets, or other sensitive information.
3.2.1.1. Access Token Response 3.3.2.1. Access Token Response
After receiving and verifying a valid and authorized access token After receiving and verifying a valid and authorized access token
request from the client (as described in each of the flows below), request from the client (as described in each of the flows below),
the authorization server constructs a JSON-formatted response which the authorization server constructs the response using the format
includes the common parameters set as well as additional flow- requested by the client, which includes the common parameters set as
specific parameters. The formatted parameters are sent to the client well as additional flow-specific parameters. The formatted
in the entity body of the HTTP response with a 200 status code (OK). parameters are sent to the client in the entity body of the HTTP
response with a 200 status code (OK).
The token response contains the following common parameters: The token response contains the following common parameters:
access_token access_token
REQUIRED. The access token issued by the authorization server. REQUIRED. The access token issued by the authorization server.
expires_in expires_in
OPTIONAL. The duration in seconds of the access token OPTIONAL. The duration in seconds of the access token
lifetime. lifetime.
skipping to change at page 11, line 28 skipping to change at page 14, line 5
token secret as requested by the client. token secret as requested by the client.
scope scope
OPTIONAL. The scope of the access token as a list of space- OPTIONAL. The scope of the access token as a list of space-
delimited strings. The value of the "scope" parameter is delimited strings. The value of the "scope" parameter is
defined by the authorization server. If the value contains defined by the authorization server. If the value contains
multiple space-delimited strings, their order does not matter, multiple space-delimited strings, their order does not matter,
and each string adds an additional access range to the and each string adds an additional access range to the
requested scope. requested scope.
For example (line breaks are for display purposes only): For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"access_token":"SlAV32hkKG","expires_in":3600, {
"refresh_token":"8xLOxBtZp8"} "access_token":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8"
}
3.2.1.2. Error Response 3.3.2.2. Error Response
If the token request is invalid or unauthorized, the authorization If the token request is invalid or unauthorized, the authorization
server constructs a JSON-formatted response which includes the common server constructs a JSON-formatted response which includes the common
parameters set as well as additional flow-specific parameters. The parameters set as well as additional flow-specific parameters. The
formatted parameters are sent to the client in the entity body of the formatted parameters are sent to the client in the entity body of the
HTTP response with a 400 status code (Bad Request). HTTP response with a 400 status code (Bad Request).
The response contains the following common parameter: The response contains the following common parameter:
error error
REQUIRED. The parameter value MUST be set to one of the values REQUIRED. The parameter value MUST be set to one of the values
specified by each flow. specified by each flow.
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"error":"incorrect_client_credentials"} {
"error":"incorrect_client_credentials"
}
3.3. Flow Parameters 3.4. Flow Parameters
The sizes of tokens and other values received from the authorization The sizes of tokens and other values received from the authorization
server, are left undefined by this specification. Clients should server, are left undefined by this specification. Clients should
avoid making assumptions about value sizes. Servers should document avoid making assumptions about value sizes. Servers should document
the expected size of any value they issue. the expected size of any value they issue.
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.
3.4. Client Credentials
When requesting access from the authorization server, the client
identifies itself using a set of client credentials. The client
credentials include a client identifier and an OPTIONAL symmetric
shared secret. The means through which the client obtains these
credentials are beyond the scope of this specification, but usually
involve registration with the authorization server.
The client identifier is used by the authorization server to
establish the identity of the client for the purpose of presenting
information to the resource owner prior to granting access, as well
as for providing different service levels to different clients. They
can also be used to block unauthorized clients from requesting
access.
Due to the nature of some clients, authorization servers SHOULD NOT
make assumptions about the confidentiality of client credentials
without establishing trust with the client operator. Authorization
servers SHOULD NOT issue client secrets to clients incapable of
keeping their secrets confidential.
3.5. User-Agent Flow 3.5. User-Agent Flow
The user-agent flow is a user delegation flow suitable for client The user-agent flow is a user delegation flow suitable for client
applications residing in a user-agent, typically implemented in a applications residing in a user-agent, typically implemented in a
browser using a scripting language such as JavaScript. These clients browser using a scripting language such as JavaScript. These clients
cannot keep client secrets confidential and the authentication of the cannot keep client secrets confidential and the authentication of the
client is based on the user-agent's same-origin policy. client is based on the user-agent's same-origin policy.
Unlike other flows in which the client makes separate authorization Unlike other flows in which the client makes separate authorization
and access token requests, the client received the access token as a and access token requests, the client received the access token as a
skipping to change at page 14, line 30 skipping to change at page 16, line 35
the user-agent. the user-agent.
(F) The user-agent executes the script provided by the web server (F) The user-agent executes the script provided by the web server
which extracts the access token and passes it to the client. which extracts the access token and passes it to the client.
3.5.1. Client Requests Authorization 3.5.1. Client Requests Authorization
In order for the end-user to grant the client access, the client In order for the end-user to grant the client access, the client
sends the end-user to the authorization server. The client sends the end-user to the authorization server. The client
constructs the request URI by adding the following URI query constructs the request URI by adding the following URI query
parameters to the user authorization endpoint URI: parameters to the end-user endpoint URI:
type type
REQUIRED. The parameter value MUST be set to "user_agent". REQUIRED. The parameter value MUST be set to "user_agent".
client_id client_id
REQUIRED. The client identifier as described in Section 3.4. REQUIRED. The client identifier as described in Section 3.1.
redirect_uri redirect_uri
REQUIRED unless a redirection URI has been established between REQUIRED unless a redirection URI has been established between
the client and authorization server via other means. An the client and authorization server via other means. An
absolute URI to which the authorization server will redirect absolute URI to which the authorization server will redirect
the user-agent to when the end-user authorization step is the user-agent to when the end-user authorization step is
completed. The authorization server SHOULD require the client completed. The authorization server SHOULD require the client
to pre-register their redirection URI. Authorization servers to pre-register their redirection URI. Authorization servers
MAY restrict the redirection URI to not include a query MAY restrict the redirection URI to not include a query
component as defined by [RFC3986] section 3. component as defined by [RFC3986] section 3.
skipping to change at page 18, line 30 skipping to change at page 20, line 37
| | | | | |
| |<---(E)------- Access Token -----------------' | |<---(E)------- Access Token -----------------'
+---------+ (w/ Optional Refresh Token) +---------+ (w/ Optional Refresh Token)
Figure 4 Figure 4
The web server flow illustrated in Figure 4 includes the following The web server flow illustrated in Figure 4 includes the following
steps: steps:
(A) The web client initiates the flow by redirecting the end-user's (A) The web client initiates the flow by redirecting the end-user's
user-agent to the authorization endpoint with its client user-agent to the end-user endpoint with its client identifier
identifier and a redirect URI to which the authorization server and a redirect URI to which the authorization server will send
will send the end-user back once authorization is received (or the end-user back once authorization is received (or denied).
denied).
(B) The authorization server authenticates the end-user (via the (B) The authorization server authenticates the end-user (via the
user-agent) and establishes whether the end-user grants or user-agent) and establishes whether the end-user grants or
denies the client's access request. denies the client's access request.
(C) Assuming the end-user granted access, the authorization server (C) Assuming the end-user granted access, the authorization server
redirects the user-agent back to the client to the redirection redirects the user-agent back to the client to the redirection
URI provided earlier. The authorization includes a verification URI provided earlier. The authorization includes a verification
code for the client to use to obtain an access token. code for the client to use to obtain an access token.
skipping to change at page 19, line 13 skipping to change at page 21, line 18
previous step. previous step.
(E) The authorization server validates the client credentials and (E) The authorization server validates the client credentials and
the verification code and responds back with the access token. the verification code and responds back with the access token.
3.6.1. Client Requests Authorization 3.6.1. Client Requests Authorization
In order for the end-user to grant the client access, the client In order for the end-user to grant the client access, the client
sends the end-user to the authorization server. The client sends the end-user to the authorization server. The client
constructs the request URI by adding the following URI query constructs the request URI by adding the following URI query
parameters to the user authorization endpoint URI: parameters to the end-user endpoint URI:
type type
REQUIRED. The parameter value MUST be set to "web_server". REQUIRED. The parameter value MUST be set to "web_server".
client_id client_id
REQUIRED. The client identifier as described in Section 3.4. REQUIRED. The client identifier as described in Section 3.1.
redirect_uri redirect_uri
REQUIRED unless a redirection URI has been established between REQUIRED unless a redirection URI has been established between
the client and authorization server via other means. An the client and authorization server via other means. An
absolute URI to which the authorization server will redirect absolute URI to which the authorization server will redirect
the user-agent to when the end-user authorization step is the user-agent to when the end-user authorization step is
completed. The authorization server MAY require the client to completed. The authorization server MAY require the client to
pre-register their redirection URI. Authorization servers MAY pre-register their redirection URI. Authorization servers MAY
restrict the redirection URI to not include a query component restrict the redirection URI to not include a query component
as defined by [RFC3986] section 3. as defined by [RFC3986] section 3.
skipping to change at page 22, line 9 skipping to change at page 24, line 18
The client obtains an access token from the authorization server by The client obtains an access token from the authorization server by
making an HTTP "POST" request to the token endpoint. The client making an HTTP "POST" request to the token endpoint. The client
constructs a request URI by adding the following parameters to the constructs a request URI by adding the following parameters to the
request: request:
type type
REQUIRED. The parameter value MUST be set to "web_server". REQUIRED. The parameter value MUST be set to "web_server".
client_id client_id
REQUIRED. The client identifier as described in Section 3.4. REQUIRED. The client identifier as described in Section 3.1.
client_secret client_secret
REQUIRED if the client identifier has a matching secret. The REQUIRED if the client identifier has a matching secret. The
client secret as described in Section 3.4. client secret as described in Section 3.1.
code code
REQUIRED. The verification code received from the REQUIRED. The verification code received from the
authorization server. authorization server.
redirect_uri redirect_uri
REQUIRED. The redirection URI used in the initial request. REQUIRED. The redirection URI used in the initial request.
secret_type secret_type
OPTIONAL. The access token secret type as described by OPTIONAL. The access token secret type as described by
Section 5.3. If omitted, the authorization server will issue a Section 5.3. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as bearer token (an access token without a matching secret) as
described by Section 5.2. described by Section 5.2.
format
OPTIONAL. The response format requested by the client. Value
MUST be one of "json", "xml", or "form". Defaults to "json" if
no omitted.
For example, the client makes the following HTTPS request (line For example, the client makes the following HTTPS request (line
breaks are for display purposes only): breaks are 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 Content-Type: application/x-www-form-urlencoded
type=web_server&client_id=s6BhdRkqt3& type=web_server&client_id=s6BhdRkqt3&
client_secret=gX1fBat3bV&code=i1WsRn1uB1& client_secret=gX1fBat3bV&code=i1WsRn1uB1&
redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
The authorization server MUST verify that the verification code, The authorization server MUST verify that the verification code,
client identity, client secret, and redirection URI are all valid and client identity, client secret, and redirection URI are all valid and
match its stored association. If the request is valid, the match its stored association. If the request is valid, the
authorization server issues a successful response as described in authorization server issues a successful response as described in
Section 3.2.1.1. Section 3.3.2.1.
For example (line breaks are for display purposes only): For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"access_token":"SlAV32hkKG","expires_in":3600, {
"refresh_token":"8xLOxBtZp8"} "access_token":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8"
}
If the request is invalid, the authorization server returns an error If the request is invalid, the authorization server returns an error
response as described in Section 3.2.1.2 with one of the following response as described in Section 3.3.2.2 with one of the following
error codes: error codes:
o "redirect_uri_mismatch" o "redirect_uri_mismatch"
o "bad_verification_code" o "bad_verification_code"
o "incorrect_client_credentials" o "incorrect_client_credentials"
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"error":"incorrect_client_credentials"} {
"error":"incorrect_client_credentials"
}
3.7. Device Flow 3.7. Device Flow
The device flow is a user delegation flow suitable for clients The device flow is a user delegation flow suitable for clients
executing on devices which do not have an easy data-entry method executing on devices which do not have an easy data-entry method
(e.g. game consoles or media hub), but where the end-user has (e.g. game consoles or media hub), but where the end-user has
separate access to a user-agent on another computer or device (e.g. separate access to a user-agent on another computer or device (e.g.
home computer, a laptop, or a smart phone). The client is incapable home computer, a laptop, or a smart phone). The client is incapable
of receiving incoming requests from the authorization server of receiving incoming requests from the authorization server
(incapable of acting as an HTTP server). (incapable of acting as an HTTP server).
Instead of interacting with the end-user's user-agent, the client Instead of interacting with the end-user's user-agent, the client
instructs the end-user to use another computer or device and connect instructs the end-user to use another computer or device and connect
to the authorization server to approve the access request. Since the to the authorization server to approve the access request. Since the
client cannot receive incoming requests, it polls the authorization client cannot receive incoming requests, it polls the authorization
server repeatedly until the end-user completes the approval process. server repeatedly until the end-user completes the approval process.
skipping to change at page 24, line 39 skipping to change at page 27, line 8
| Browser | | | | Browser | | |
+----------+ +----------------+ +----------+ +----------------+
Figure 5 Figure 5
The device flow illustrated in Figure 5 includes the following steps: The device flow illustrated in Figure 5 includes the following steps:
(A) The client requests access from the authorization server and (A) The client requests access from the authorization server and
includes its client identifier in the request. includes its client identifier in the request.
(B) The authorization server issues a verification code, a user (B) The authorization server issues a verification code, an end-user
code, and provides the end-user authorization URI. code, and provides the end-user verification URI.
(C) The client instructs the end-user to use its user-agent (C) The client instructs the end-user to use its user-agent
(elsewhere) and visit the provided authorization URI. The (elsewhere) and visit the provided end-user verification URI.
client provides the user with the user code to enter in order to The client provides the end-user with the end-user code to enter
grant access. in order to grant access.
(D) The authorization server authenticates the end-user (via the (D) The authorization server authenticates the end-user (via the
user-agent) and prompts the end-user to grant the client's user-agent) and prompts the end-user to grant the client's
access request. If the end-user agrees to the client's access access request. If the end-user agrees to the client's access
request, the end-user enters the user code provided by the request, the end-user enters the end-user code provided by the
client. client. The authorization server validates the end-user code
provided by the end-user.
(E) While the end-user authorizes (or denies) the client's request (E) While the end-user authorizes (or denies) the client's request
(D), the client repeatedly polls the authorization server to (D), the client repeatedly polls the authorization server to
find out if the end-user completed the user authorization step. find out if the end-user completed the end-user authorization
The client includes the verification code and its client step. The client includes the verification code and its client
identifier. identifier.
(F) Assuming the end-user granted access, the authorization server (F) Assuming the end-user granted access, the authorization server
validates the verification code provided by the client and validates the verification code provided by the client and
responds back with the access token. responds back with the access token.
3.7.1. Client Requests Authorization 3.7.1. Client Requests Authorization
The client initiates the flow by requesting a set of verification The client initiates the flow by requesting a set of verification
codes from the authorization server by making an HTTP "POST" request codes from the authorization server by making an HTTP "POST" request
to the token endpoint. The client constructs a request URI by adding to the token endpoint. The client constructs a request URI by adding
the following parameters to the request: the following parameters to the request:
type type
REQUIRED. The parameter value MUST be set to "device_code". REQUIRED. The parameter value MUST be set to "device_code".
client_id client_id
REQUIRED. The client identifier as described in Section 3.4. REQUIRED. The client identifier as described in Section 3.1.
scope scope
OPTIONAL. The scope of the access request expressed as a list OPTIONAL. The scope of the access request expressed as a list
of space-delimited strings. The value of the "scope" parameter of space-delimited strings. The value of the "scope" parameter
is defined by the authorization server. If the value contains is defined by the authorization server. If the value contains
multiple space-delimited strings, their order does not matter, multiple space-delimited strings, their order does not matter,
and each string adds an additional access range to the and each string adds an additional access range to the
requested scope. requested scope.
format
OPTIONAL. The response format requested by the client. Value
MUST be one of "json", "xml", or "form". Defaults to "json" if
no omitted.
For example, the client makes the following HTTPS request (line For example, the client makes the following HTTPS request (line
breaks are for display purposes only): breaks are for display purposes only):
POST /token?type=device_code&client_id=s6BhdRkqt3 POST /token?type=device_code&client_id=s6BhdRkqt3
HTTP/1.1 HTTP/1.1
Host: server.example.com Host: server.example.com
In response, the authorization server generates a verification code In response, the authorization server generates a verification code
and a user code and includes them in the HTTP response body using the and an end-user code and includes them in the HTTP response body
"application/json" format as described by Section 3.2.1 with a 200 using the "application/json" format as described by Section 3.3.2
status code (OK). The response contains the following parameters: with a 200 status code (OK). The response contains the following
parameters:
code code
REQUIRED. The verification code. REQUIRED. The verification code.
user_code user_code
REQUIRED. The user code. REQUIRED. The end-user code.
user_uri verification_uri
REQUIRED. The user authorization URI on the authorization REQUIRED. The end-user verification URI on the authorization
server. The URI should be short and easy to remember as end- server. The URI should be short and easy to remember as end-
users will be asked to manually type it into their user-agent. users will be asked to manually type it into their user-agent.
expires_in expires_in
OPTIONAL. The duration in seconds of the verification code OPTIONAL. The duration in seconds of the verification code
lifetime. lifetime.
interval interval
OPTIONAL. The minimum amount of time in seconds that the OPTIONAL. The minimum amount of time in seconds that the
client SHOULD wait between polling requests to the token client SHOULD wait between polling requests to the token
endpoint. endpoint.
For example (line breaks are for display purposes only): For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"code":"74tq5miHKB","user_code":"94248","user_uri":"http%3A%2F%2 {
Fwww%2Eexample%2Ecom%2Fdevice","interval"=5} "code":"74tq5miHKB",
"user_code":"94248",
"verification_uri":"http://www.example.com/device",
"interval"=5
}
The client displays the user code and the user authorization URI to The client displays the end-user code and the end-user verification
the end-user, and instructs the end-user to visit the URI using a URI to the end-user, and instructs the end-user to visit the URI
user-agent and enter the user code. using a user-agent and enter the end-user code.
The end-user manually types the provided URI and authenticates with The end-user manually types the provided verification URI and
the authorization server. The authorization server prompts the end- authenticates with the authorization server. The authorization
user to authorize the client's request by entering the user code server prompts the end-user to authorize the client's request by
provided by the client. Once the end-user approves or denies the entering the end-user code provided by the client. Once the end-user
request, the authorization server informs the end-user to return to approves or denies the request, the authorization server informs the
the device for further instructions. end-user to return to the device for further instructions.
3.7.2. Client Requests Access Token 3.7.2. Client Requests Access Token
Since the client is unable to receive incoming requests from the Since the client is unable to receive incoming requests from the
authorization server, it polls the authorization server repeatedly authorization server, it polls the authorization server repeatedly
until the end-user grants or denies the request, or the verification until the end-user grants or denies the request, or the verification
code expires. code expires.
The client makes the following request at an arbitrary but reasonable The client makes the following request at an arbitrary but reasonable
interval which MUST NOT exceed the minimum interval rate provided by interval which MUST NOT exceed the minimum interval rate provided by
skipping to change at page 27, line 26 skipping to change at page 30, line 6
user to manually inform it when authorization was granted. user to manually inform it when authorization was granted.
The client requests an access token by making an HTTP "POST" request The client requests an access token by making an HTTP "POST" request
to the token endpoint. The client constructs a request URI by adding to the token endpoint. The client constructs a request URI by adding
the following parameters to the request: the following parameters to the request:
type type
REQUIRED. The parameter value MUST be set to "device_token". REQUIRED. The parameter value MUST be set to "device_token".
client_id client_id
REQUIRED. The client identifier as described in Section 3.4. REQUIRED. The client identifier as described in Section 3.1.
code code
The verification code received from the authorization server. The verification code received from the authorization server.
secret_type secret_type
OPTIONAL. The access token secret type as described by OPTIONAL. The access token secret type as described by
Section 5.3. If omitted, the authorization server will issue a Section 5.3. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as bearer token (an access token without a matching secret) as
described by Section 5.2. described by Section 5.2.
format
OPTIONAL. The response format requested by the client. Value
MUST be one of "json", "xml", or "form". Defaults to "json" if
no omitted.
For example, the client makes the following HTTPS request (line For example, the client makes the following HTTPS request (line
breaks are for display purposes only): breaks are for display purposes only):
POST /token?type=device_token&client_id=s6BhdRkqt3 POST /token?type=device_token&client_id=s6BhdRkqt3
&code=J2vC42OifV HTTP/1.1 &code=74tq5miHKB HTTP/1.1
Host: server.example.com Host: server.example.com
If the end-user authorized the request, the authorization server If the end-user authorized the request, the authorization server
issues an access token response as described in Section 3.2.1.1. issues an access token response as described in Section 3.3.2.1.
For example (line breaks are for display purposes only): For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"access_token":"SlAV32hkKG","expires_in":3600, {
"refresh_token":"8xLOxBtZp8"} "access_token":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8"
}
If the request is invalid, the authorization server returns an error If the request is invalid, the authorization server returns an error
response as described in Section 3.2.1.2 with one of the following response as described in Section 3.3.2.2 with one of the following
error codes: error codes:
o "authorization_declined" o "authorization_declined"
o "bad_verification_code" o "bad_verification_code"
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"error":"authorization_declined"} {
"error":"authorization_declined"
}
If the end-user authorization is pending or expired without receiving If the end-user authorization is pending or expired without receiving
any response from the end-user, or the client is exceeding the any response from the end-user, or the client is exceeding the
allowed polling interval, the authorization server returns an error allowed polling interval, the authorization server returns an error
response as described in Section 3.2.1.2 with one of the following response as described in Section 3.3.2.2 with one of the following
error codes: error codes:
o "'authorization_pending" o "'authorization_pending"
o "slow_down" o "slow_down"
o "code_expired" o "code_expired"
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"error":"authorization_pending"} {
"error":"authorization_pending"
}
3.8. Username and Password Flow 3.8. Username and Password Flow
The username and password flow is suitable for clients capable of The username and password flow is suitable for clients capable of
asking end-users for their usernames and passwords. It is also used asking end-users for their usernames and passwords. It is also used
to migrate existing clients using direct authentication schemes such to migrate existing clients using direct authentication schemes such
as HTTP Basic or Digest authentication to OAuth by converting the as HTTP Basic or Digest authentication to OAuth by converting the
end-user credentials stored with tokens. end-user credentials stored with tokens.
However, unlike the HTTP Basic authentication scheme defined in However, unlike the HTTP Basic authentication scheme defined in
skipping to change at page 30, line 28 skipping to change at page 33, line 15
3.8.1. Client Requests Access Token 3.8.1. Client Requests Access Token
The client requests an access token by making an HTTP "POST" request The client requests an access token by making an HTTP "POST" request
to the token endpoint. The client constructs a request URI by adding to the token endpoint. The client constructs a request URI by adding
the following parameters to the request: the following parameters to the request:
type type
REQUIRED. The parameter value MUST be set to "username". REQUIRED. The parameter value MUST be set to "username".
client_id client_id
REQUIRED. The client identifier as described in Section 3.4. REQUIRED. The client identifier as described in Section 3.1.
client_secret client_secret
REQUIRED. The client secret as described in Section 3.4. REQUIRED. The client secret as described in Section 3.1.
OPTIONAL if no client secret was issued. OPTIONAL if no client secret was issued.
username username
REQUIRED. The end-user's username. REQUIRED. The end-user's username.
password password
REQUIRED. The end-user's password. REQUIRED. The end-user's password.
scope scope
OPTIONAL. The scope of the access request expressed as a list OPTIONAL. The scope of the access request expressed as a list
skipping to change at page 31, line 6 skipping to change at page 33, line 41
multiple space-delimited strings, their order does not matter, multiple space-delimited strings, their order does not matter,
and each string adds an additional access range to the and each string adds an additional access range to the
requested scope. requested scope.
secret_type secret_type
OPTIONAL. The access token secret type as described by OPTIONAL. The access token secret type as described by
Section 5.3. If omitted, the authorization server will issue a Section 5.3. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as bearer token (an access token without a matching secret) as
described by Section 5.2. described by Section 5.2.
format
OPTIONAL. The response format requested by the client. Value
MUST be one of "json", "xml", or "form". Defaults to "json" if
no omitted.
For example, the client makes the following HTTPS request (line For example, the client makes the following HTTPS request (line
breaks are for display purposes only): breaks are for display purposes only):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
type=username&client_id=s6BhdRkqt3&client_secret= type=username&client_id=s6BhdRkqt3&client_secret=
47HDu8s&username=johndoe&password=A3ddj3w 47HDu8s&username=johndoe&password=A3ddj3w
The authorization server MUST validate the client credentials and The authorization server MUST validate the client credentials and
end-user credentials and if valid issues an access token response as end-user credentials and if valid issues an access token response as
described in Section 3.2.1.1. described in Section 3.3.2.1.
For example (line breaks are for display purposes only): For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"access_token":"SlAV32hkKG","expires_in":3600, {
"refresh_token":"8xLOxBtZp8"} "access_token":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8"
}
If the request is invalid, the authorization server returns an error If the request is invalid, the authorization server returns an error
response as described in Section 3.2.1.2 with one of the following response as described in Section 3.3.2.2 with one of the following
error codes: error codes:
o "incorrect_client_credentials" o "incorrect_client_credentials"
o "unauthorized_client'" - The client is not permitted to use this o "unauthorized_client'" - The client is not permitted to use this
flow. flow.
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"error":"incorrect_client_credentials"} {
"error":"incorrect_client_credentials"
}
3.9. Client Credentials Flow 3.9. Client Credentials Flow
The client credentials flow is used when the client acts on behalf of The client credentials flow is used when the client acts on behalf of
itself (the client is the resource owner), or when the client itself (the client is the resource owner), or when the client
credentials are used to obtain an access token representing a credentials are used to obtain an access token representing a
previously established access authorization. The client secret is previously established access authorization. The client secret is
assumed to be high-entropy since it is not designed to be memorized assumed to be high-entropy since it is not designed to be memorized
by an end-user. by an end-user.
skipping to change at page 32, line 44 skipping to change at page 35, line 44
The client requests an access token by making an HTTP "POST" request The client requests an access token by making an HTTP "POST" request
to the token endpoint. The client constructs a request URI by adding to the token endpoint. The client constructs a request URI by adding
the following parameters to the request: the following parameters to the request:
type type
REQUIRED. The parameter value MUST be set to REQUIRED. The parameter value MUST be set to
"client_credentials". "client_credentials".
client_id client_id
REQUIRED. The client identifier as described in Section 3.4. REQUIRED. The client identifier as described in Section 3.1.
client_secret client_secret
REQUIRED. The client secret as described in Section 3.4. REQUIRED. The client secret as described in Section 3.1.
scope scope
OPTIONAL. The scope of the access request expressed as a list OPTIONAL. The scope of the access request expressed as a list
of space-delimited strings. The value of the "scope" parameter of space-delimited strings. The value of the "scope" parameter
is defined by the authorization server. If the value contains is defined by the authorization server. If the value contains
multiple space-delimited strings, their order does not matter, multiple space-delimited strings, their order does not matter,
and each string adds an additional access range to the and each string adds an additional access range to the
requested scope. requested scope.
secret_type secret_type
OPTIONAL. The access token secret type as described by OPTIONAL. The access token secret type as described by
Section 5.3. If omitted, the authorization server will issue a Section 5.3. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as bearer token (an access token without a matching secret) as
described by Section 5.2. described by Section 5.2.
For example, the client makes the following HTTPS request (line format
breaks are for display purposes only): OPTIONAL. The response format requested by the client. Value
MUST be one of "json", "xml", or "form". Defaults to "json" if
no omitted.
For example, the client makes the following HTTPS request:
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
type=client_credentials&client_id=s6BhdRkqt3&client_secret=47HDu8s type=client_credentials&client_id=s6BhdRkqt3&client_secret=47HDu8s
The authorization server MUST validate the client credentials and if The authorization server MUST validate the client credentials and if
valid issues an access token response as described in valid issues an access token response as described in
Section 3.2.1.1. Section 3.3.2.1.
For example (line breaks are for display purposes only): For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"access_token":"SlAV32hkKG","expires_in":3600, {
"refresh_token":"8xLOxBtZp8"} "access_token":"SlAV32hkKG",
"expires_in":3600,
"refresh_token":"8xLOxBtZp8"
}
If the request is invalid, the authorization server returns an error If the request is invalid, the authorization server returns an error
response as described in Section 3.2.1.2 with one of the following response as described in Section 3.3.2.2 with one of the following
error codes: error codes:
o "incorrect_client_credentials" o "incorrect_client_credentials"
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"error":"incorrect_client_credentials"} {
"error":"incorrect_client_credentials"
}
3.10. Assertion Flow 3.10. Assertion Flow
The assertion flow is used when a client wishes to exchange an The assertion flow is used when a client wishes to exchange an
existing security token or assertion for an access token. This flow existing security token or assertion for an access token. This flow
is suitable when the client is the resource owner or is acting on is suitable when the client is the resource owner or is acting on
behalf of the resource owner (based on the content of the assertion behalf of the resource owner (based on the content of the assertion
used). used).
The assertion flow requires the client to obtain a assertion (such as The assertion flow requires the client to obtain a assertion (such as
skipping to change at page 35, line 21 skipping to change at page 38, line 27
type type
REQUIRED. The parameter value MUST be set to "assertion". REQUIRED. The parameter value MUST be set to "assertion".
format format
REQUIRED. The format of the assertion as defined by the REQUIRED. The format of the assertion as defined by the
authorization server. The value MUST be an absolute URI. authorization server. The value MUST be an absolute URI.
assertion assertion
REQUIRED. The assertion. REQUIRED. The assertion.
client_id
OPTIONAL. The client identifier as described in Section 3.1.
The authorization server MAY require including the client
credentials with the request based on the assertion properties.
client_secret
OPTIONAL. The client secret as described in Section 3.1. MUST
NOT be included if the "client_id" parameter is omitted.
scope scope
OPTIONAL. The scope of the access request expressed as a list OPTIONAL. The scope of the access request expressed as a list
of space-delimited strings. The value of the "scope" parameter of space-delimited strings. The value of the "scope" parameter
is defined by the authorization server. If the value contains is defined by the authorization server. If the value contains
multiple space-delimited strings, their order does not matter, multiple space-delimited strings, their order does not matter,
and each string adds an additional access range to the and each string adds an additional access range to the
requested scope. requested scope.
secret_type secret_type
OPTIONAL. The access token secret type as described by OPTIONAL. The access token secret type as described by
Section 5.3. If omitted, the authorization server will issue a Section 5.3. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as bearer token (an access token without a matching secret) as
described by Section 5.2. described by Section 5.2.
format
OPTIONAL. The response format requested by the client. Value
MUST be one of "json", "xml", or "form". Defaults to "json" if
no omitted.
For example, the client makes the following HTTPS request (line For example, the client makes the following HTTPS request (line
breaks are for display purposes only): breaks are for display purposes only):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
type=assertion&format=_______&assertion=_______ type=assertion&format=_______&assertion=_______
The authorization server MUST validate the assertion and if valid The authorization server MUST validate the assertion and if valid
issues an access token response as described in Section 3.2.1.1. The issues an access token response as described in Section 3.3.2.1. The
authorization server SHOULD NOT issue a refresh token. authorization server SHOULD NOT issue a refresh token.
For example (line breaks are for display purposes only): For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"access_token":"SlAV32hkKG","expires_in":3600} {
"access_token":"SlAV32hkKG",
"expires_in":3600
}
If the request is invalid, the authorization server returns an error If the request is invalid, the authorization server returns an error
response as described in Section 3.2.1.2 with one of the following response as described in Section 3.3.2.2 with one of the following
error codes: error codes:
o "invalid_assertion" o "invalid_assertion"
o "unknown_format" o "unknown_format"
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"error":"invalid_assertion"} {
"error":"invalid_assertion"
}
Authorization servers SHOULD issue access tokens with a limited Authorization servers SHOULD issue access tokens with a limited
lifetime and require clients to refresh them by requesting a new lifetime and require clients to refresh them by requesting a new
access token using the same assertion if it is still valid. access token using the same assertion if it is still valid.
Otherwise the client MUST obtain a new valid assertion. Otherwise the client MUST obtain a new valid assertion.
4. Refreshing an Access Token 4. Refreshing an Access Token
Token refresh is used when the lifetime of an access token is shorter Token refresh is used when the lifetime of an access token is shorter
than the lifetime of the authorization grant. It allows clients to than the lifetime of the authorization grant. It allows clients to
skipping to change at page 37, line 24 skipping to change at page 41, line 6
To refresh a token, the client constructs an HTTP "POST" request to To refresh a token, the client constructs an HTTP "POST" request to
the token endpoint and includes the following parameters in the HTTP the token endpoint and includes the following parameters in the HTTP
request body using the "application/x-www-form-urlencoded" content request body using the "application/x-www-form-urlencoded" content
type as defined by [W3C.REC-html40-19980424]: type as defined by [W3C.REC-html40-19980424]:
type type
REQUIRED. The parameter value MUST be set to "refresh". REQUIRED. The parameter value MUST be set to "refresh".
client_id client_id
REQUIRED. The client identifier as described in Section 3.4. REQUIRED. The client identifier as described in Section 3.1.
client_secret client_secret
REQUIRED if the client was issued a secret. The client secret. REQUIRED if the client was issued a secret. The client secret.
refresh_token refresh_token
REQUIRED. The refresh token associated with the access token REQUIRED. The refresh token associated with the access token
to be refreshed. to be refreshed.
secret_type secret_type
OPTIONAL. The access token secret type as described by OPTIONAL. The access token secret type as described by
Section 5.3. If omitted, the authorization server will issue a Section 5.3. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as bearer token (an access token without a matching secret) as
described by Section 5.2. described by Section 5.2.
format
OPTIONAL. The response format requested by the client. Value
MUST be one of "json", "xml", or "form". Defaults to "json" if
no omitted.
For example, the client makes the following HTTPS request (line break For example, the client makes the following HTTPS request (line break
are for display purposes only): are 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 Content-Type: application/x-www-form-urlencoded
type=refresh_token&client_id=s6BhdRkqt3&client_secret=8eSEIpnqmM type=refresh_token&client_id=s6BhdRkqt3&client_secret=8eSEIpnqmM
&refresh_token=n4E9O119d&secret_type=hmac-sha256 &refresh_token=n4E9O119d&secret_type=hmac-sha256
verify the client credential, the validity of the refresh token, and verify the client credential, the validity of the refresh token, and
that the resource owner's authorization is still valid. If the that the resource owner's authorization is still valid. If the
request is valid, the authorization server issues an access token request is valid, the authorization server issues an access token
response as described in Section 3.2.1.1. The authorization server response as described in Section 3.3.2.1. The authorization server
MAY issue a new refresh token in which case the client MUST NOT use MAY issue a new refresh token in which case the client MUST NOT use
the previous refresh token and replace it with the newly issued the previous refresh token and replace it with the newly issued
refresh token. refresh token.
For example (line breaks are for display purposes only): For example:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"access_token":"SlAV32hkKG","expires_in":3600} {
"access_token":"SlAV32hkKG",
"expires_in":3600
}
If the request is invalid, the authorization server returns an error If the request is invalid, the authorization server returns an error
response as described in Section 3.2.1.2 with one of the following response as described in Section 3.3.2.2 with one of the following
error codes: error codes:
o "incorrect_client_credentials" o "incorrect_client_credentials"
o "authorization_expired" o "authorization_expired"
o "unsupported_secret_type" o "unsupported_secret_type"
For example: For example:
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{"error":"incorrect_client_credentials"} {
"error":"incorrect_client_credentials"
}
5. Accessing a Protected Resource 5. Accessing a Protected Resource
Clients access protected resources by presenting an access token to Clients access protected resources by presenting an access token to
the resource server. The methods used by the resource server to the resource server. The methods used by the resource server to
validate the access token are beyond the scope of this specification, validate the access token are beyond the scope of this specification,
but generally involve an interaction or coordination between the but generally involve an interaction or coordination between the
resource server and authorization server. resource server and authorization server.
The method in which a client uses an access token depends on the The method in which a client uses an access token depends on the
skipping to change at page 46, line 15 skipping to change at page 50, line 15
key key
is set to the access token secret. is set to the access token secret.
The request signature is the calculated value of the "digest" The request signature is the calculated value of the "digest"
variable after the result octet string is base64-encoded per variable after the result octet string is base64-encoded per
[RFC2045] section 6.8. [RFC2045] section 6.8.
6. Identifying a Protected Resource 6. Identifying a Protected Resource
Clients access protected resources after locating the appropriate Clients access protected resources after locating the appropriate
authorization and token endpoints and obtaining an access token. In end-user and token endpoints and obtaining an access token. In many
many cases, interacting with a protected resource requires prior cases, interacting with a protected resource requires prior knowledge
knowledge of the protected resource properties and methods, as well of the protected resource properties and methods, as well as its
as its authentication requirements (i.e. establishing client authentication requirements (i.e. establishing client identity,
identity, locating the authorization and token endpoints). locating the end-user and token endpoints).
However, there are cases in which clients are unfamiliar with the However, there are cases in which clients are unfamiliar with the
protected resource, including whether the resource requires protected resource, including whether the resource requires
authentication. When clients attempt to access an unfamiliar authentication. When clients attempt to access an unfamiliar
protected resource without an access token, the resource server protected resource without an access token, the resource server
denies the request and informs the client of the required credentials denies the request and informs the client of the required credentials
using an HTTP authentication challenge. using an HTTP authentication challenge.
In addition, when receiving an invalid authenticated request, the In addition, when receiving an invalid authenticated request, the
resource server issues an authentication challenge including the resource server issues an authentication challenge including the
error type and message. error type and message.
6.1. The WWW-Authenticate Response Header 6.1. The WWW-Authenticate Response Header
A resource server receiving a request for a protected resource A resource server receiving a request for a protected resource
without a valid access token MUST respond with a 401 HTTP status code without a valid access token MUST respond with a 401 (Unauthorized)
(Unauthorized), and includes at least one "Token" "WWW-Authenticate" or 403 (Forbidden) HTTP status code, and include at least one "Token"
response header field challenge. "WWW-Authenticate" response header field challenge.
The "WWW-Authenticate" header field uses the framework defined by The "WWW-Authenticate" header field uses the framework defined by
[RFC2617] as follows: [RFC2617] as follows:
challenge = "Token" RWS token-challenge challenge = "Token" RWS token-challenge
token-challenge = realm token-challenge = realm
[ CS authz-uri ] [ CS user-uri ]
[ CS token-uri ] [ CS token-uri ]
[ CS algorithms ] [ CS algorithms ]
[ CS scope ]
[ CS error ] [ CS error ]
authz-uri = "auth-uri" "=" URI-Reference user-uri = "user-uri" "=" URI-Reference
token-uri = "token-uri" "=" URI-Reference token-uri = "token-uri" "=" URI-Reference
algorithms = "algorithms" "=" <"> 1#algorithm-name <"> algorithms = "algorithms" "=" <"> 1#algorithm-name <">
scope = "scope" "=" <"> 1#URI-Reference <">
error = "error" "=" <"> token <"> error = "error" "=" <"> token <">
CS = OWS "," OWS CS = OWS "," OWS
6.1.1. The 'realm' Attribute
The "realm" attribute is used to provide the protected resources The "realm" attribute is used to provide the protected resources
partition as defined by [RFC2617]. partition as defined by [RFC2617].
6.1.2. The 'authorization-uri' Attribute The "user-uri" and "token-uri" attributes provide a way for the
resource server to advertise the URIs of the end-user and token
endpoints capable of issuing an access token suitable for accessing
the requested resource.
6.1.3. The 'algorithms' Attribute The "algorithms" attribute is a space-delimited list of the
cryptographic algorithms supported by the resource server. The
client MAY request an access token with a suitable matching secret by
using the "secret_type" request parameter as described in
Section 5.3.
6.1.4. The 'error' Attribute The "scope" attribute is a space-delimited list of URIs (relative or
absolute) indicating the required scope of the access token for
accessing the requested resource.
The "error" attribute is used to inform the client the reason why an
access request was declined. [[ Add list of error codes ]]
7. Security Considerations 7. Security Considerations
[[ Todo ]] [[ Todo ]]
8. IANA Considerations 8. IANA Considerations
[[ Not Yet ]] [[ Not Yet ]]
9. Acknowledgements 9. Acknowledgements
skipping to change at page 48, line 9 skipping to change at page 52, line 17
[[ Add OAuth 1.0a authors + WG contributors ]] [[ Add OAuth 1.0a authors + WG contributors ]]
Appendix A. Differences from OAuth 1.0a Appendix A. Differences from OAuth 1.0a
[[ Todo ]] [[ Todo ]]
Appendix B. Document History Appendix B. Document History
[[ to be removed by RFC editor before publication as an RFC ]] [[ to be removed by RFC editor before publication as an RFC ]]
-05
o Corrected device example.
o Added client credentials parameters to the assertion flow as
OPTIONAL.
o Added the ability to send client credentials using an HTTP
authentication scheme.
o Initial text for the "WWW-Authenticate" header (also added scope
support).
o Change authorization endpoint to end-user endpoint.
o In the device flow, change the "user_uri" parameter to
"verification_uri" to avoid confusion with the end-user endpoint.
o Add "format" request parameter and support for XML and form-
encoded responses.
-04 -04
o Changed all token endpoints to use "POST" o Changed all token endpoints to use "POST"
o Clarified the authorization server's ability to issue a new o Clarified the authorization server's ability to issue a new
refresh token when refreshing a token. refresh token when refreshing a token.
o Changed the flow categories to clarify the autonomous group. o Changed the flow categories to clarify the autonomous group.
o Changed client credentials language not to always be server- o Changed client credentials language not to always be server-
skipping to change at page 49, line 43 skipping to change at page 54, line 28
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.
[RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
Types", RFC 3023, January 2001.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
Standards (PKCS) #1: RSA Cryptography Specifications Standards (PKCS) #1: RSA Cryptography Specifications
Version 2.1", RFC 3447, February 2003. Version 2.1", RFC 3447, February 2003.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003. 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.
 End of changes. 108 change blocks. 
206 lines changed or deleted 403 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/