One document matched: draft-ietf-oauth-v2-01.xml
<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<rfc category='std' ipr='trust200902' docName='draft-ietf-oauth-v2-01'>
<?rfc strict='yes' ?>
<?rfc toc='yes' ?>
<?rfc tocdepth='3' ?>
<?rfc symrefs='yes' ?>
<?rfc sortrefs='yes' ?>
<?rfc compact='yes' ?>
<?rfc subcompact='no' ?>
<front>
<title abbrev='OAuth 2.0'>The OAuth 2.0 Protocol</title>
<author fullname='Eran Hammer-Lahav' surname='Hammer-Lahav' initials='E' role='editor'>
<organization>Yahoo!</organization>
<address>
<email>eran@hueniverse.com</email>
</address>
</author>
<author fullname='David Recordon' surname='Recordon' initials='D'>
<organization>Facebook</organization>
<address>
<email>davidrecordon@facebook.com</email>
<uri>http://www.davidrecordon.com/</uri>
</address>
</author>
<author fullname='Dick Hardt' surname='Hardt' initials='D'>
<organization/>
<address>
<email>dick.hardt@gmail.com</email>
<uri>http://dickhardt.org/</uri>
</address>
</author>
<date year='2010' />
<abstract>
<t>
This specification describes the OAuth 2.0 protocol. OAuth provides a method for making
authenticated HTTP requests using a token - an identifier used to denote an access grant
with specific scope, duration, and other attributes. Tokens are issued to third-party
clients by an authorization server with the approval of the resource owner. OAuth defines
multiple flows for obtaining a token to support a wide range of client types and user
experience.
</t>
</abstract>
</front>
<middle>
<section title='Authors'>
<t>
This specification was authored with the participation and based on the work of
Allen Tom (Yahoo!), Brian Eaton (Google), Brent Goldman (Facebook), Luke Shepard
(Facebook), Raffi Krikorian (Twitter), and Yaron Goland (Microsoft).
</t>
</section>
<section title='Introduction'>
<t>
With the increasing use of distributed web services and cloud computing, third-party
applications require access to server-hosted resources. These resources are usually
protected and require authentication using the resource owner's credentials (typically a
username and password). In the traditional client-server authentication model, a client
accessing a protected resource on a server presents the resource owner's credentials in
order to authenticate and gain access.
</t>
<t>
Resource owners should not be required to share their credentials when granting third-party
applications access to their protected resources. They should also have the ability to
restrict access to a limited subset of the resources they control, to limit access
duration, or to limit access to the HTTP methods supported by these resources.
</t>
<t>
OAuth provides a method for making authenticated HTTP requests using a token - an
identifier used to denote an access grant with specific scope, duration, and other
attributes. Tokens are issued to third-party clients by an authorization server with the
approval of the resource owner. Instead of sharing their credentials with the client,
resource owners grant access by authenticating directly with the authorization server which
in turn issues a token to the client. The client uses the token (and optional secret) to
authenticate with the resource server and gain access.
</t>
<t>
For example, a web user (resource owner) can grant a printing service (client) access to
her protected photos stored at a photo sharing service (resource server), without sharing
her username and password with the printing service. Instead, she authenticates directly
with the photo sharing service (authorization server) which issues the printing service
delegation-specific credentials (token).
</t>
<t>
This specification defines the use of OAuth over <xref target='RFC2616'>HTTP</xref>
(or HTTP over TLS 1.0 as defined by <xref target='RFC2818' />. Other specifications may
extend it for use with other tranport protocols.
</t>
<section title='Terminology'>
<t>
<list style='hanging' hangIndent='6'>
<t hangText='resource server'>
<vspace />
An <xref target='RFC2616'>HTTP</xref> server capable of accepting authenticated
resource requests using the OAuth protocol.
</t>
<t hangText='protected resource'>
<vspace />
An access-restricted resource which can be obtained from a resource server using
an OAuth-authenticated request.
</t>
<t hangText='client'>
<vspace />
An HTTP client capable of making authenticated requests for protected resources using
the OAuth protocol.
</t>
<t hangText='resource owner'>
<vspace />
An entity capable of granting access to a protected resource.
</t>
<t hangText='end-user'>
<vspace />
A human resource owner.
</t>
<t hangText='access token'>
<vspace />
A unique identifier used by the client to make authenticated requests on behalf of
the resource owner. Access tokens may have a matching secret.
</t>
<t hangText='bearer token'>
An access token without a matching secret, used to obtain access to a protected
resource by simply presenting the access token as-is to the resource server.
</t>
<t hangText='authorization server'>
<vspace />
An HTTP server capable of issuing tokens after successfully authenticating the
resource owner and obtaining authorization. The authorization server may be the same
server as the resource server, or a separate entity.
</t>
<t hangText='authorization endpoint'>
<vspace />
The authorization server's HTTP endpoint capable of authenticating the resource
owner and obtaining authorization.
</t>
<t hangText='token endpoint'>
<vspace />
The authorization server's HTTP endpoint capable of issuing tokens and refreshing
expired tokens.
</t>
<t hangText='client identifier'>
<vspace />
An unique identifier issued to the client to identify itself to the authorization
server. Client identifiers may have a matching secret.
</t>
<t hangText='refresh token'>
<vspace />
A unique identifier used by the client to replace an expired access token with a new
access token without having to involve the resource owner. A refresh token is used
when the access token is valid for a shorter time period than the duration of the
access grant approved by the resource owner.
</t>
</list>
</t>
</section>
<section title='Overview'>
<t>
Clients interact with a protected resource, first by requesting access (which is granted
in the form of an access token) from the authorization server, and then by authenticating
with the resource server by presenting the access token. <xref target='Figure 1' />
demonstrates the flow between the client and authorization server (A, B), and the flow
between the client and resource server (C, D), when the client is acting autonomously
(the client is also the resource owner).
</t>
<figure anchor='Figure 1'>
<artwork><![CDATA[
+--------+ +---------------+
| |--(A)------ Credentials --------->| Authorization |
| | | Server |
| |<-(B)------ Access Token ---------| |
| | (w/ Optional Refresh Token) +---------------+
| Client |
| | HTTP Request +---------------+
| |--(C)--- with Access Token ------>| Resource |
| | | Server |
| |<-(D)------ HTTP Response --------| |
+--------+ +---------------+
]]>
</artwork>
</figure>
<t>
Access token strings can use any internal structure agreed upon between the authorization
server and the resource server, but their structure is opaque to the client. Since the
access token provides the client access to the protected resource for the life of the
access token (or until revoked), the authorization server should issue access tokens
which expire within an appropriate time, usually much shorter than the duration of the
access grant.
</t>
<t>
When an access token expires, the client can request a new access token from the
authorization server by presenting its credentials again (<xref target='Figure 1' />), or
by using the refresh token (if issued with the access token) as shown in
<xref target='Figure 2' />. Once an expired access token has been replaced with a new
access token (A, B), the client uses the new access token as before (C, D).
</t>
<figure anchor='Figure 2'>
<artwork><![CDATA[
+--------+ +---------------+
| |--(A)------ Refresh Token ------->| Authorization |
| | | Server |
| |<-(B)------ Access Token ---------| |
| | (with Optional Secret) +---------------+
| Client |
| | HTTP Request +---------------+
| |--(C)--- with Access Token ------>| Resource |
| | | Server |
| |<-(D)----- HTTP Response ---------| |
+--------+ +---------------+
]]>
</artwork>
</figure>
<t>
This specification defines a number of authorization flows to support different client
types and scenarios. These authorization flows can be separated into three groups:
user delegation flows, end-user credentials flows, and autonomous flows.
</t>
<t>
Additional authorization flows may be defined by other specifications to cover different
scenarios and client types.
</t>
<t>
User delegation authorization enable clients to act on behalf of an end-user after
obtaining authorization from the end-user. The user delegation flows defined by this
specifications are:
<list style='symbols'>
<t>
User-Agent Flow - This flow is designed for clients running inside a user-agent
(typically a web browser). This flow is described in
<xref target='user_agent_flow' />.
</t>
<t>
Web Server Flow - This flow is optimized for clients that are part of a web server
application, accessible via HTTP requests. This flow is described in
<xref target='web_server_flow' />.
</t>
<t>
Device Flow - This flow is suitable for clients executing on limited devices, but
where the end-user has separate access to a user-agent on another computer or device.
This flow is described in <xref target='device_flow' />.
</t>
</list>
</t>
<t>
End-user credentials flow enable clients with direct access to the end-user's credentials
to exchange them for an access token without seeking additional authorization. These
flows are only suitable when there is a high degree of trust between the end-user and the
client. The end-user credentials flow defined by this specification is:
<list style='symbols'>
<t>
Username and Password Flow - This flow is used in cases where the end-user trusts
the client to handle its credentials but it is still undesirable for the client to
store the end-user's username and password. This flow is described in
<xref target='username_password_flow' />.
</t>
</list>
</t>
<t>
Autonomous flows enable clients to act for their own behalf (the client is also the
resource owner). The autonomous authorization flows defined by this specifications are:
<list style='symbols'>
<t>
Client Credentials Flow - The client uses its credentials to obtain an access token.
This flow is described in <xref target='client_credentials_flow' />.
</t>
<t>
Assertion Flow - The client presents an assertion such as a
<xref target='OASIS.saml-core-2.0-os'>SAML</xref> assertion to the authorization
server in exchange for an access token. This flow is described in
<xref target='assertion_flow' />.
</t>
</list>
</t>
</section>
<section title='Example'>
<t>
[[ Todo ]]
</t>
</section>
<section title='Notational Conventions'>
<t>
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD
NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as
described in <xref target='RFC2119' />.
</t>
<t>
This document uses the Augmented Backus-Naur Form (ABNF) notation of
<xref target='I-D.ietf-httpbis-p1-messaging' />. Additionally, the realm and auth-param
rules are included from <xref target='RFC2617' />, and the URI-Reference rule from
<xref target='RFC3986' />.
</t>
</section>
<section title='Conformance'>
<t>
An implementation is not compliant if it fails to satisfy one or more of the MUST or
REQUIRED level requirements for the flows it implements. An implementation that
satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its
flows is said to be "unconditionally compliant"; one that satisfies all the MUST
level requirements but not all the SHOULD level requirements for its flows is said to
be "conditionally compliant."
</t>
</section>
</section>
<section title='Obtaining an Access Token' anchor='get_token'>
<t>
The client obtains an access token by using one of the authorization flows supported by the
authorization server. The authorization flows all use the same authorization and token
endpoints, each with a different set of request parameters and values.
</t>
<t>
Access tokens have a scope, duration, and other access attributes granted by the resource
owner. These attributes MUST be enforced by the resource server when receiving a protected
resource request, and by the authorization server when receiving a token refresh request.
</t>
<t>
In many cases it is desirable to issue access tokens with a shorter lifetime than the
duration of the authorization grant. However, it may be undesirable to require the resource
owner to authorize the request again. Instead, the authorization server issues a refresh
token in addition to the access token. When the access token expires, the client can
request a new access token without involving the resource owner as long as the
authorization grant is still valid. The token refresh method is described in
<xref target='token_refresh' />.
</t>
<section title='Authorization Endpoint'>
<t>
Clients direct the resource owner to the authorization endpoint to approve their access
request. Before granting access, the resource owner first authenticates with the
authorization server. 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 the scope of this specification. However, the
authorization server MUST first verify the identity of the end-user.
</t>
<t>
The URI of the authorization endpoint can be found in the service documentation, or can
be obtained by the client by making an unauthorized protected resource request (from the
<spanx style='verb'>WWW-Authenticate</spanx> response header
<xref target='authz_uri_attribute'>auth-uri</xref> attribute).
</t>
<t>
The authorization endpoint advertised by the resource server MAY include a query
component as defined by <xref target='RFC3986' /> section 3.
</t>
<t>
Since requests to the authorization endpoint result in user authentication and the
transmission of sensitive values, the authorization server SHOULD require the
use of a transport-layer mechanism such as TLS/SSL (or a secure channel with
equivalent protections) when sending requests to the authorization endpoints.
</t>
</section>
<section title='Token Endpoint'>
<t>
After obtaining authorization from the resource owner, clients request an access token
from the authorization server's token endpoint.
</t>
<t>
The URI of the token endpoint can be found in the service documentation, or can be
obtained by the client by making an unauthorized protected resource request (from the
<spanx style='verb'>WWW-Authenticate</spanx> response header
<xref target='authz_uri_attribute'>token-uri</xref> attribute).
</t>
<t>
The token endpoint advertised by the resource server MAY include a query component as
defined by <xref target='RFC3986' /> section 3.
</t>
<t>
Since requests to the token endpoint result in the transmission of plain text
credentials in the HTTP request and response, the authorization server MUST require the
use of a transport-layer mechanism such as TLS/SSL (or a secure channel with
equivalent protections) when sending requests to the token endpoints.
</t>
<t>
The authorization server MUST include the HTTP <spanx style='verb'>Cache-Control</spanx>
response header field with a value of <spanx style='verb'>no-store</spanx> in any
response containing tokens, secrets, or other sensitive information.
</t>
</section>
<section title='Flow Parameters'>
<t>
The sizes of tokens and other values received from the authorization server, are left
undefined by this specification. Clients should avoid making assumptions about value
sizes. Servers should document the expected size of any value they issue.
</t>
<t>
Unless otherwise noted, all the protocol parameter names and values are case sensitive.
</t>
</section>
<section title='Client Credentials' anchor='client_id'>
<t>
When requesting access from the authorization server, the client identifies itself using
its authorization-server-issued 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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title='User Delegation Flows'>
<t>
User delegation flows are used to grant client access to protected resources by the
end-user without sharing the end-user credentials (e.g. a username and password) with the
client. Instead, the end-user authenticates directly with the authorization server, and
grants client access to its protected resources.
</t>
<section title='User-Agent Flow' anchor='user_agent_flow'>
<t>
The user-agent flow is a user delegation flow suitable for client applications residing
in a user-agent, typically implemented in a browser using a scripting language such as
JavaScript. These clients cannot keep client secrets confidential and the authentication
of the client is based on the user-agent's same-origin policy.
</t>
<t>
Unlike other flows in which the client makes separate authorization and access token
requests, the client received the access token as a result of the authorization
request in the form of an HTTP redirection. The client requests the authorization
server to redirect the user-agent to another web server or local resource accessible to
the browser which is capable of extracting the access token from the response and
passing it to the client.
</t>
<t>
This user-agent flow does not utilize the client secret since the client executables
reside on the end-user's computer or device which makes the client secret accessible
and exploitable. Because the access token is encoded into the redirection URI, it may
be exposed to the end-user and other applications residing on the computer or device.
</t>
<figure anchor='Figure 5'>
<artwork><![CDATA[
+----------+ Client Identifier +----------------+
| |>---(A)-- & Redirection URI --->| |
| | | |
End <--+ - - - +----(B)-- User authenticates -->| Authorization |
User | | | Server |
| |<---(C)-- Redirect URI --------<| |
| Client | with Access Token | |
| in | (w/ Optional Refresh Token) +----------------+
| Browser | in Fragment
| | +----------------+
| |>---(D)-- Redirect URI -------->| |
| | without Fragment | Web Server |
| | | with Client |
| (F) |<---(E)-- Web Page with -------<| Resource |
| Access | Script | |
| Token | +----------------+
+----------+
]]>
</artwork>
</figure>
<t>
The user-agent flow illustrated in <xref target='Figure 5' /> includes the following
steps:
<list style='format (%C)'>
<t>
The client sends the user-agent to the authorization server and includes its client
identifier and redirection URI in the request.
</t>
<t>
The authorization server authenticates the end-user (via the user-agent) and
establishes whether the end-user grants or denies the client's access request.
</t>
<t>
Assuming the end-user granted access, the authorization server redirects the
user-agent to the redirection URI provided earlier. The redirection URI includes
the access token in the URI fragment.
</t>
<t>
The user-agent follows the redirection instructions by making a request to the web
server which does not include the fragment. The user-agent retains the fragment
information locally.
</t>
<t>
The web server returns a web page containing a script capable of extracting the
access token from the URI fragment retained by the user-agent.
</t>
<t>
The user-agent executes the script provided by the web server which extracts the
access token and passes it to the client.
</t>
</list>
</t>
<section title='Client Requests Authorization'>
<t>
In order for the end-user to grant the client access, the client sends the end-user
to the authorization server. The client constructs the request URI by adding the
following URI query parameters to the user authorization endpoint URI:
<list style='hanging' hangIndent='6'>
<t hangText='type'>
<vspace />
REQUIRED. The parameter value MUST be set to <spanx style='verb'>user_agent</spanx>.
</t>
<t hangText='client_id'>
<vspace />
REQUIRED. The client identifier as described in <xref target='client_id' />.
</t>
<t hangText='redirect_uri'>
<vspace />
REQUIRED unless a redirection URI has been established between the client and
authorization server via other means. An absolute URI to which the authorization
server will redirect the user-agent to when the end-user authorization step is
completed. The authorization server SHOULD require the client to pre-register
their redirection URI. The redirection URI MUST NOT include a query component
as defined by <xref target='RFC3986' /> section 3 if the
<spanx style='verb'>state</spanx> parameter is present.
</t>
<t hangText='state'>
<vspace />
OPTIONAL. An opaque value used by the client to maintain state between the request
and callback. The authorization server includes this value when redirecting the
user-agent back to the client.
</t>
<t hangText='immediate'>
<vspace />
OPTIONAL. The parameter value must be set to <spanx style='verb'>true</spanx> or
<spanx style='verb'>false</spanx>. If set to
<spanx style='verb'>true</spanx>, the authorization server MUST NOT prompt the
end-user to authenticate or approve access. Instead, the authorization server
attempts to establish the end-user's identity via other means (e.g. browser
cookies) and checks if the end-user has previously approved an identical access
request by the same client and if that access grant is still active. If the
authorization server does not support an immediate check or if it is unable to
establish the end-user's identity or approval status, it MUST deny the request
without prompting the end-user. Defaults to <spanx style='verb'>false</spanx> if
omitted.
</t>
<t hangText='secret_type'>
<vspace />
OPTIONAL. The access token secret type as described by
<xref target='crypto_token' />. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as described by
<xref target='bearer_token' />.
</t>
</list>
</t>
<t>
The client directs the end-user to the constructed URI using an HTTP redirection
response, or by other means available to it via the end-user's user-agent. The
request MUST use the HTTP <spanx style='verb'>GET</spanx> method.
</t>
<figure>
<preamble>
For example, the client directs the end-user's user-agent to make the following
HTTPS request (line breaks are for display purposes only):
</preamble>
<artwork><![CDATA[
GET /authorize?type=user_agent&client_id=s6BhdRkqt3&
redirect_uri=https%3A%2F%2FEexample%2Ecom%2Frd HTTP/1.1
Host: server.example.com
]]>
</artwork>
</figure>
<t>
If the client has previously registered a redirection URI with the authorization server,
the authorization server MUST verify that the redirection URI received matches the
registered URI associated with the client identifier.
</t>
<t>
The authorization server authenticates the end-user and obtains an authorization
decision (by asking the end-user or establishing approval via other means). The
authorization server sends the end-user's user-agent to the provided client
redirection URI using an HTTP redirection response.
</t>
<section title='End-user Grants Authorization'>
<t>
If the end-user authorizes the access request, the authorization server issues an
access token and delivers it to the client by adding the following parameters, using
the <spanx style='verb'>application/x-www-form-urlencoded</spanx> format as defined
by <xref target='W3C.REC-html40-19980424' />, to the redirection URI fragment:
<list style='hanging' hangIndent='6'>
<t hangText='access_token'>
<vspace />
REQUIRED. The access token.
</t>
<t hangText='expires_in'>
<vspace />
OPTIONAL. The duration in seconds of the access token lifetime.
</t>
<t hangText='refresh_token'>
<vspace />
OPTIONAL. The refresh token.
</t>
<t hangText='state'>
<vspace />
REQUIRED if the <spanx style='verb'>state</spanx> parameter was present in the
client authorization request. Set to the exact value received from the client.
</t>
<t hangText='access_token_secret'>
<vspace />
REQUIRED if requested by the client. The corresponding access token secret as
requested by the client.
</t>
</list>
</t>
<figure>
<preamble>
For example, the authorization server redirects the end-user's user-agent by
sending the following HTTP response:
</preamble>
<artwork><![CDATA[
HTTP/1.1 302 Found
Location: http://example.com/rd#access_token=FJQbwq9&expires_in=3600
]]>
</artwork>
</figure>
</section>
<section title='End-user Denies Authorization'>
<t>
If the end-user denied the access request, the authorization server responds to the
client by adding the following parameters, using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> format as defined by
<xref target='W3C.REC-html40-19980424' />, to the redirection URI fragment:
<list style='hanging' hangIndent='6'>
<t hangText='error'>
<vspace />
REQUIRED. The parameter value MUST be set to
<spanx style='verb'>user_denied</spanx>.
</t>
<t hangText='state'>
<vspace />
REQUIRED if the <spanx style='verb'>state</spanx> parameter was present in the
client authorization request. Set to the exact value received from the client.
</t>
</list>
</t>
<figure>
<preamble>
For example, the authorization server responds with the following:
</preamble>
<artwork><![CDATA[
HTTP/1.1 302 Found
Location: http://example.com/rd#error=user_denied
]]>
</artwork>
</figure>
<t>
The authorization flow concludes unsuccessfully. To extract the error message, the
client follows the steps described in <xref target='user_agent_extract' />.
</t>
</section>
</section>
<section title='Client Extracts Access Token' anchor='user_agent_extract'>
<t>
The user-agent follows the authorization server redirection response by making an
HTTP <spanx style='verb'>GET</spanx> request to the URI received in the
<spanx style='verb'>Location</spanx> HTTP response header. The user-agent SHALL NOT
include the fragment component with the request.
</t>
<figure>
<preamble>
For example, the user-agent makes the following HTTP
<spanx style='verb'>GET</spanx> request in response to the redirection directive
received from the authorization server:
</preamble>
<artwork><![CDATA[
GET /rd HTTP/1.1
Host: example.com
]]>
</artwork>
</figure>
<t>
The HTTP response to the redirection request returns a web page (typically an HTML
page with an embedded script) capable of accessing the full redirection URI including
the fragment retained by the user-agent, and extracting the access token (and other
parameters) contained in the fragment.
</t>
</section>
</section>
<section title='Web Server Flow' anchor='web_server_flow'>
<t>
The web server flow is a user delegation flow suitable for clients capable of
interacting with the end-user's user-agent (typically a web browser) and capable of
receiving incoming requests from the authorization server (capable of acting as an HTTP
server).
</t>
<figure anchor='Figure 3'>
<artwork><![CDATA[
+----------+ Client Identifier +---------------+
| -+----(A)-- & Redirect URI ------->| |
| End-user | | Authorization |
| at |<---(B)-- User authenticates --->| Server |
| Browser | | |
| -+----(C)-- Verification Code ----<| |
+-|----|---+ +---------------+
| | ^ v
(A) (C) | |
| | | |
^ v | |
+---------+ | |
| |>---(D)-- Client Credentials, --------' |
| Web | Verification Code, |
| Client | & Redirect URI |
| | |
| |<---(E)------- Access Token -----------------'
+---------+ (w/ Optional Refresh Token)
]]>
</artwork>
</figure>
<t>
The web server flow illustrated in <xref target='Figure 3' /> includes the following
steps:
<list style='format (%C)'>
<t>
The web client initiates the flow by redirecting the end-user's user-agent to the
authorization endpoint with its client identifier and a redirect URI to which the
authorization server will send the end-user back once authorization is received (or
denied).
</t>
<t>
The authorization server authenticates the end-user (via the user-agent) and
establishes whether the end-user grants or denies the client's access request.
</t>
<t>
Assuming the end-user granted access, the authorization server redirects the
user-agent back to the client to the redirection URI provided earlier. The
authorization includes a verification code for the client to use to obtain an
access token.
</t>
<t>
The client requests an access token from the authorization server by including its
client credentials (identifier and secret), as well as the verification code
received in the previous step.
</t>
<t>
The authorization server validates the client credentials and the verification
code and responds back with the access token.
</t>
</list>
</t>
<section title='Client Requests Authorization'>
<t>
In order for the end-user to grant the client access, the client sends the end-user
to the authorization server. The client constructs the request URI by adding the
following URI query parameters to the user authorization endpoint URI:
<list style='hanging' hangIndent='6'>
<t hangText='type'>
<vspace />
REQUIRED. The parameter value MUST be set to <spanx style='verb'>web_server</spanx>.
</t>
<t hangText='client_id'>
<vspace />
REQUIRED. The client identifier as described in <xref target='client_id' />.
</t>
<t hangText='redirect_uri'>
<vspace />
REQUIRED unless a redirection URI has been established between the client and
authorization server via other means. An absolute URI to which the authorization
server will redirect the user-agent to when the end-user authorization step is
completed. The authorization server MAY require the client to pre-register
their redirection URI. The redirection URI MUST NOT include a query component
as defined by <xref target='RFC3986' /> section 3 if the
<spanx style='verb'>state</spanx> parameter is present.
</t>
<t hangText='state'>
<vspace />
OPTIONAL. An opaque value used by the client to maintain state between the request
and callback. The authorization server includes this value when redirecting the
user-agent back to the client.
</t>
<t hangText='immediate'>
<vspace />
OPTIONAL. The parameter value must be set to <spanx style='verb'>true</spanx> or
<spanx style='verb'>false</spanx>. If set to
<spanx style='verb'>true</spanx>, the authorization server MUST NOT prompt the
end-user to authenticate or approve access. Instead, the authorization server
attempts to establish the end-user's identity via other means (e.g. browser
cookies) and checks if the end-user has previously approved an identical access
request by the same client and if that access grant is still active. If the
authorization server does not support an immediate check or if it is unable to
establish the end-user's identity or approval status, it MUST deny the request
without prompting the end-user. Defaults to <spanx style='verb'>false</spanx> if
omitted.
</t>
</list>
</t>
<t>
The client directs the end-user to the constructed URI using an HTTP redirection
response, or by other means available to it via the end-user's user-agent. The
request MUST use the HTTP <spanx style='verb'>GET</spanx> method.
</t>
<figure>
<preamble>
For example, the client directs the end-user's user-agent to make the
following HTTPS requests (line breaks are for display purposes only):
</preamble>
<artwork><![CDATA[
GET /authorize?type=web_server&client_id=s6BhdRkqt3&redirect_uri=
https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
Host: server.example.com
]]>
</artwork>
</figure>
<t>
If the client has previously registered a redirection URI with the authorization server,
the authorization server MUST verify that the redirection URI received matches the
registered URI associated with the client identifier.
</t>
<t>
The authorization server authenticates the end-user and obtains an authorization
decision (by asking the end-user or establishing approval via other means). The
authorization server sends the end-user's user-agent to the provided client
redirection URI using an HTTP redirection response, or by other means available to it
via the end-user's user-agent.
</t>
<section title='End-user Grants Authorization'>
<t>
If the end-user authorizes the access request, the authorization server generates a
verification code and associates it with the client identifier and redirection URI. The
authorization server constructs the request URI by adding the following parameters to
the query component of redirection URI provided by the client:
<list style='hanging' hangIndent='6'>
<t hangText='code'>
<vspace />
REQUIRED. The verification code generated by the authorization server.
</t>
<t hangText='state'>
<vspace />
REQUIRED if the <spanx style='verb'>state</spanx> parameter was present in the
client authorization request. Set to the exact value received from the client.
</t>
</list>
</t>
<t>
The verification code should expire shortly after it is issued and allowed for a
single use.
</t>
<figure>
<preamble>
For example, the authorization server redirects the end-user's user-agent by
sending the following HTTP response:
</preamble>
<artwork><![CDATA[
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=i1WsRn1uB1
]]>
</artwork>
</figure>
<figure>
<preamble>
In turn, the end-user's user-agent makes the following HTTPS
<spanx style='verb'>GET</spanx> request:
</preamble>
<artwork><![CDATA[
GET /cb?code=i1WsRn1uB1 HTTP/1.1
Host: client.example.com
]]>
</artwork>
</figure>
</section>
<section title='End-user Denies Authorization'>
<t>
If the end-user denied the access request, the authorization server constructs the
request URI by adding the following parameters to the query component of the
redirection URI provided by the client:
<list style='hanging' hangIndent='6'>
<t hangText='error'>
<vspace />
REQUIRED. The parameter value MUST be set to
<spanx style='verb'>user_denied</spanx>.
</t>
<t hangText='state'>
<vspace />
REQUIRED if the <spanx style='verb'>state</spanx> parameter was present in the
client authorization request. Set to the exact value received from the client.
</t>
</list>
</t>
<figure>
<preamble>
For example, the authorization server directs the client to make the following HTTP
request:
</preamble>
<artwork><![CDATA[
GET /cb?error=user_denied HTTP/1.1
Host: client.example.com
]]>
</artwork>
</figure>
<t>
The authorization flow concludes unsuccessfully.
</t>
</section>
</section>
<section title='Client Requests Access Token'>
<t>
The client obtains an access token from the authorization server by making an HTTP
<spanx style='verb'>POST</spanx> request to the token endpoint. The client
constructs a request URI by adding the following parameters to the request:
<list style='hanging' hangIndent='6'>
<t hangText='type'>
<vspace />
REQUIRED. The parameter value MUST be set to <spanx style='verb'>web_server</spanx>.
</t>
<t hangText='client_id'>
<vspace />
REQUIRED. The client identifier as described in <xref target='client_id' />.
</t>
<t hangText='client_secret'>
<vspace />
REQUIRED if the client identifier has a matching secret. The client secret as
described in <xref target='client_id' />.
</t>
<t hangText='code'>
<vspace />
REQUIRED. The verification code received from the authorization server.
</t>
<t hangText='redirect_uri'>
<vspace />
REQUIRED. The redirection URI used in the initial request.
</t>
<t hangText='secret_type'>
<vspace />
OPTIONAL. The access token secret type as described by
<xref target='crypto_token' />. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as described by
<xref target='bearer_token' />.
</t>
</list>
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request (line breaks are for display
purposes only):
</preamble>
<artwork><![CDATA[
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
]]>
</artwork>
</figure>
<t>
The authorization server MUST verify that the verification code, client identity,
client secret, and redirection URI are all valid and match its stored association. If
the request is valid, the authorization server issues an access token and delivers it
to the client in the HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as defined
by <xref target='W3C.REC-html40-19980424' /> with a 200 status code (OK).
</t>
<t>
The response contains the following parameters:
<list style='hanging' hangIndent='6'>
<t hangText='access_token'>
<vspace />
REQUIRED. The access token issued by the authorization server.
</t>
<t hangText='expires_in'>
<vspace />
OPTIONAL. The duration in seconds of the access token lifetime.
</t>
<t hangText='refresh_token'>
<vspace />
OPTIONAL. The refresh token used to obtain new access tokens using the same
end-user access grant as described in <xref target='token_refresh' />.
</t>
<t hangText='access_token_secret'>
<vspace />
REQUIRED if requested by the client. The corresponding access token secret as
requested by the client.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
access_token=SlAV32hkKG&expires_in=3600&refresh_token=8xLOxBtZp8
]]>
</artwork>
</figure>
<t>
If the request is invalid, the authorization server returns an error message in the
HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as defined
by <xref target='W3C.REC-html40-19980424' /> with a 400 status code (Bad Request).
</t>
<t>
The response contains the following parameter:
<list style='hanging' hangIndent='6'>
<t hangText='error'>
<vspace />
OPTIONAL. The parameter value MUST be set to either
<spanx style='verb'>redirect_uri_mismatch</spanx>,
<spanx style='verb'>bad_verification_code</spanx>,
<spanx style='verb'>incorrect_client_credentials</spanx>.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 400 Bad Request
Content-Type: application/x-www-form-urlencoded
error=bad_verification_code
]]>
</artwork>
</figure>
</section>
</section>
<section title='Device Flow' anchor='device_flow'>
<t>
The device flow is a user delegation flow suitable for clients 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 separate access to a user-agent on another computer or device
(e.g. home computer, a laptop, or a smartphone). The client is incapable of receiving
incoming requests from the authorization server (incapable of acting as an HTTP
server).
</t>
<t>
Instead of interacting with the end-user's user-agent, the client instructs the end-user
to use another computer or device and connect to the authorization server to approve the
access request. Since the client cannot receive incoming requests, it polls the
authorization server repeatedly until the end-user completes the approval process.
</t>
<t>
This device flow does not utilize the client secret since the client executables
reside on a local device which makes the client secret accessible and exploitable.
</t>
<figure anchor='Figure 6'>
<artwork><![CDATA[
+----------+ +----------------+
| |>---(A)-- Client Identifier --->| |
| | | |
| |<---(B)-- Verification Code, --<| |
| | User Code, | |
| | & Verification URI | |
| Device | | |
| Client | Client Identifier & | |
| |>---(E)-- Verification Code --->| |
| | ... | |
| |>---(E)---> | |
| | | Authorization |
| |<---(F)-- Access Token --------<| Server |
+----------+ (w/ Optional Refresh Token) | |
v | |
: | |
(C) User Code & Verification URI | |
: | |
v | |
+----------+ | |
| End-user | | |
| at |<---(D)-- User authenticates -->| |
| Browser | | |
+----------+ +----------------+
]]>
</artwork>
</figure>
<t>
The device flow illustrated in <xref target='Figure 6' /> includes the following
steps:
<list style='format (%C)'>
<t>
The client requests access from the authorization server and includes its client
identifier in the request.
</t>
<t>
The authorization server issues a verification code, a user code, and provides the
end-user authorization URI.
</t>
<t>
The client instructs the end-user to use its user-agent (elsewhere) and visit the
provided authorization URI. The client provides the user with the user code to
enter in order to grant access.
</t>
<t>
The authorization server authenticates the end-user (via the user-agent) and
prompts the end-user to grant the client's access request by entering the user
code provided by the client.
</t>
<t>
While the end-user authorizes (or denies) the client's request (D), the client
repeatedly polls the authorization server to find out if the end-user completed the
user authorization step. The client includes the verification code and its client
identifier.
</t>
<t>
Assuming the end-user granted access, the authorization server validates the
verification code provided by the client and responds back with the access token.
</t>
</list>
</t>
<section title='Client Requests Authorization'>
<t>
The client initiates the flow by requesting a set of verification codes from the
authorization server by making an HTTP <spanx style='verb'>GET</spanx> request to the
token endpoint. The client constructs a request URI by adding the following
parameters to the request:
<list style='hanging' hangIndent='6'>
<t hangText='type'>
<vspace />
REQUIRED. The parameter value MUST be set to
<spanx style='verb'>device_code</spanx>.
</t>
<t hangText='client_id'>
<vspace />
REQUIRED. The client identifier as described in <xref target='client_id' />.
</t>
</list>
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request (line breaks are for
display purposes only):
</preamble>
<artwork><![CDATA[
GET /token?type=device_code&client_id=s6BhdRkqt3
HTTP/1.1
Host: server.example.com
]]>
</artwork>
</figure>
<t>
In response, the authorization server generates a verification code and a user code
and includes them in the HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> format as defined by
<xref target='W3C.REC-html40-19980424' /> with a 200 status code (OK). The
response contains the following parameters:
<list style='hanging' hangIndent='6'>
<t hangText='code'>
<vspace />
REQUIRED. The verification code.
</t>
<t hangText='user_code'>
<vspace />
REQUIRED. The user code.
</t>
<t hangText='user_uri'>
<vspace />
REQUIRED. The user authorization URI on the authorization server.
</t>
<t hangText='expires_in'>
<vspace />
OPTIONAL. The duration in seconds of the verification code lifetime.
</t>
<t hangText='interval'>
<vspace />
OPTIONAL. The minimum amount of time in seconds that the client SHOULD wait
between polling requests to the token endpoint.
</t>
</list>
</t>
<figure>
<preamble>
For example (line breaks are for display purposes only):
</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
code=74tq5miHKB&user_code=94248&user_uri=http%3A%2F%2
Fwww%2Eexample%2Ecom%2Fdevice&interval=5
]]>
</artwork>
</figure>
<t>
The client displays the user code and the user authorization URI to the end-user, and
instructs the end-user to visit the URI using a user-agent and enter the user code.
</t>
<t>
The end-user manually types the provided URI and authenticates with the authorization
server. The authorization server prompts the end-user to authorize the client's
request by entering the user code provided by the client. Once the end-user approves
or denies the request, the authorization server informs the end-user to return to the
device for further instructions.
</t>
</section>
<section title='Client Requests Access Token'>
<t>
Since the client is unable to receive incoming requests from the authorization
server, it polls the authorization server repeatedly until the end-user grants or
denies the request, or the verification code expires.
</t>
<t>
The client makes the following request at an arbitrary but reasonable interval which
MUST NOT exceed the minimum interval rate provided by the authorization server (if
present via the <spanx style='verb'>interval</spanx> parameter). Alternatively, the
client MAY provide a user interface for the end-user to manually inform it when
authorization was granted.
</t>
<t>
The client requests an access token by making an HTTP <spanx style='verb'>GET</spanx>
request to the token endpoint. The client constructs a request URI by adding
the following parameters to the request:
<list style='hanging' hangIndent='6'>
<t hangText='type'>
<vspace />
REQUIRED. The parameter value MUST be set to
<spanx style='verb'>device_token</spanx>.
</t>
<t hangText='client_id'>
<vspace />
REQUIRED. The client identifier as described in <xref target='client_id' />.
</t>
<t hangText='code'>
<vspace />
The verification code received from the authorization server.
</t>
<t hangText='secret_type'>
<vspace />
OPTIONAL. The access token secret type as described by
<xref target='crypto_token' />. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as described by
<xref target='bearer_token' />.
</t>
</list>
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request (line breaks are for display
purposes only):
</preamble>
<artwork><![CDATA[
GET /token?type=device_token&client_id=s6BhdRkqt3
&code=J2vC42OifV HTTP/1.1
Host: server.example.com
]]>
</artwork>
</figure>
<section title='End-user Grants Authorization'>
<t>
If the end-user authorized the request, the authorization server issues an access
token and delivers it to the client by including it in the HTTP response
body using the <spanx style='verb'>application/x-www-form-urlencoded</spanx>
content type as defined by <xref target='W3C.REC-html40-19980424' /> with a 200
status code (OK). The response contains the following parameters:
<list style='hanging' hangIndent='6'>
<t hangText='access_token'>
<vspace />
REQUIRED. The access token.
</t>
<t hangText='expires_in'>
<vspace />
OPTIONAL. The duration in seconds of the access token lifetime.
</t>
<t hangText='refresh_token'>
<vspace />
OPTIONAL. The refresh token.
</t>
<t hangText='access_token_secret'>
<vspace />
REQUIRED if requested by the client. The corresponding access token secret as
requested by the client.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
access_token=FJQbwq9OD8&expires_in=3600
]]>
</artwork>
</figure>
</section>
<section title='End-user Denies Authorization'>
<t>
If the end-user denied the request, the authorization server provides the client
with the error message in the HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as
defined by <xref target='W3C.REC-html40-19980424' /> with a 400 status code
(Bad Request). The response contains the following parameters:
<list style='hanging' hangIndent='6'>
<t hangText='error'>
<vspace />
REQUIRED. Value must be set to
<spanx style='verb'>authorization_declined</spanx>.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 400 Bad Request
Content-Type: application/x-www-form-urlencoded
error=authorization_declined
]]>
</artwork>
</figure>
</section>
<section title='End-user Authorization Pending or Expired'>
<t>
If the end-user authorization is pending or expired without receiving any response
from the end-user, or the client is exceeding the allowed polling interval, the
authorization server provides the client with the error message in the HTTP
response body using the <spanx style='verb'>application/x-www-form-urlencoded</spanx>
content type as defined by <xref target='W3C.REC-html40-19980424' /> with a 400
status code (Bad Request). The response contains the following parameters:
<list style='hanging' hangIndent='6'>
<t hangText='error'>
<vspace />
REQUIRED. Value MUST be set to
<spanx style='verb'>authorization_pending</spanx>,
<spanx style='verb'>slow_down</spanx>, or
<spanx style='verb'>code_expired</spanx>.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 400 Bad Request
Content-Type: application/x-www-form-urlencoded
error=authorization_pending
]]>
</artwork>
</figure>
</section>
</section>
</section>
</section>
<section title='End-user Credentials Flows'>
<t>
End-user credential flows are used to grant client access to protected resources by the
end-user directly sharing the end-user's username and password with the client. Unlike user
delegation flows, end-user credentials flows require a much higher degree of trust between
the client and end-user.
</t>
<t>
These flows are suitable in cases where the end-user already has a trust relationship
with the client, such as its computer operating system or highly privileged applications.
Authorization servers SHOULD take special care when enabling user credentials flows, and
SHOULD only do so when other delegation flows are not viable.
</t>
<t>
However, unlike the HTTP Basic authentication scheme defined in
<xref target='RFC2617' />, the end-user's credentials are used in a single request and
are exchanged for an access token and refresh token which eliminates the client need to
store them for future use.
</t>
<section title='Username and Password Flow' anchor='username_password_flow'>
<t>
The username and password flow is an end-user credentials flow suitable for clients
capable of asking end users for their usernames and passwords. It is also used to
migrate existing clients using direct authentication schemes such as HTTP Basic or
Digest authentication to OAuth by converting the end-user credentials stored with
tokens.
</t>
<t>
The methods through which the client prompts end users for their usernames and
passwords is beyond the scope of this specification. The client MUST discard the
usernames and passwords once an access token has been obtained.
</t>
<figure anchor='Figure 7'>
<artwork><![CDATA[
End-user
v
:
(A)
:
v
+--------+ +---------------+
| | Client Credentials | |
| |>--(B)--- & User Credentials ---->| Authorization |
| Client | | Server |
| |<--(C)---- Access Token ---------<| |
| | (w/ Optional Refresh Token) | |
+--------+ +---------------+
]]>
</artwork>
</figure>
<t>
The username and password flow illustrated in <xref target='Figure 7' /> includes the
following steps:
<list style='format (%C)'>
<t>
The end-user provides the client with its username and password.
</t>
<t>
The client sends an access token request to the authorization server and includes
its client identifier and client secret, and the end-user's username and password.
</t>
<t>
The authorization server validates the end-user credentials and the client
credentials and issues an access token.
</t>
</list>
</t>
<section title='Client Requests Access Token'>
<t>
The client requests an access token by making an HTTP <spanx style='verb'>POST</spanx>
request to the token endpoint. The client constructs a request URI by adding
the following parameters to the request:
<list style='hanging' hangIndent='6'>
<t hangText='type'>
<vspace />
REQUIRED. The parameter value MUST be set to
<spanx style='verb'>username</spanx>.
</t>
<t hangText='client_id'>
<vspace />
REQUIRED. The client identifier as described in <xref target='client_id' />.
</t>
<t hangText='client_secret'>
<vspace />
REQUIRED. The client secret as described in <xref target='client_id' />. OPTIONAL
if no client secret was issued.
</t>
<t hangText='username'>
<vspace />
REQUIRED. The end-user's username.
</t>
<t hangText='password'>
<vspace />
REQUIRED. The end-user's password.
</t>
<t hangText='secret_type'>
<vspace />
OPTIONAL. The access token secret type as described by
<xref target='crypto_token' />. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as described by
<xref target='bearer_token' />.
</t>
</list>
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request (line breaks are for
display purposes only):
</preamble>
<artwork><![CDATA[
POST /token HTTP/1.1
Host: server.example.com
type=username&client_id=s6BhdRkqt3&client_secret=
47HDu8s&username=johndoe&password=A3ddj3w
]]>
</artwork>
</figure>
<t>
The authorization server MUST validate the client credentials and end-user credentials
and if valid issue an access token and deliver to the client in the HTTP response body
using the <spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as
defined by <xref target='W3C.REC-html40-19980424' /> with a 200 status code (OK).
</t>
<t>
The response contains the following parameters:
<list style='hanging' hangIndent='6'>
<t hangText='access_token'>
<vspace />
REQUIRED. The access token.
</t>
<t hangText='expires_in'>
<vspace />
OPTIONAL. The duration in seconds of the access token lifetime.
</t>
<t hangText='refresh_token'>
<vspace />
OPTIONAL. The refresh token.
</t>
<t hangText='access_token_secret'>
<vspace />
REQUIRED if requested by the client. The corresponding access token secret as
requested by the client.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
access_token=FJQbwq9OD8&refresh_token=gO3CHNqpH8
]]>
</artwork>
</figure>
<t>
If the request is invalid, the authorization server returns an error message in the
HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as defined
by <xref target='W3C.REC-html40-19980424' /> with a 400 status code (Bad Request).
</t>
<t>
The response contains the following parameter:
<list style='hanging' hangIndent='6'>
<t hangText='error'>
<vspace />
OPTIONAL. The parameter value MUST be set to either
<spanx style='verb'>incorrect_client_credentials</spanx> or
<spanx style='verb'>unauthorized_client</spanx> (the client is not permitted to
use this flow).
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 400 Bad Request
Content-Type: application/x-www-form-urlencoded
error=incorrect_client_credentials
]]>
</artwork>
</figure>
</section>
</section>
</section>
<section title='Autonomous Client Flows'>
<t>
Autonomous client flows are used to grant client access to protected resources controlled
by the client (i.e. the client is the resource owner). For example, these flows are
useful when a service provides both client-specific resources in addition to end-user
resources.
</t>
<section title='Client Credentials Flow' anchor='client_credentials_flow'>
<t>
The client credentials flow is used when the client acts autonomously without acting on
behalf of a separate resource owner. The client secret is assumed to be high-entropy
since it is not designed to be memorized by an end-user.
</t>
<figure anchor='Figure 8'>
<artwork>
<![CDATA[
+--------+ +---------------+
| | | |
| |>--(A)--- Client Credentials ---->| Authorization |
| Client | | Server |
| |<--(B)---- Access Token ---------<| |
| | (w/ Optional Refresh Token) | |
+--------+ +---------------+
]]>
</artwork>
</figure>
<t>
The client credential flow illustrated in <xref target='Figure 8' /> includes the
following steps:
<list style='format (%C)'>
<t>
The client sends an access token request to the authorization server and includes
its client identifier and client secret.
</t>
<t>
The authorization server validates the client credentials and issues an access
token.
</t>
</list>
</t>
<section title='Client Requests Access Token'>
<t>
The client requests an access token by making an HTTP <spanx style='verb'>POST</spanx>
request to the token endpoint. The client constructs a request URI by adding
the following parameters to the request:
<list style='hanging' hangIndent='6'>
<t hangText='type'>
<vspace />
REQUIRED. The parameter value MUST be set to
<spanx style='verb'>client_credentials</spanx>.
</t>
<t hangText='client_id'>
<vspace />
REQUIRED. The client identifier as described in <xref target='client_id' />.
</t>
<t hangText='client_secret'>
<vspace />
REQUIRED. The client secret as described in <xref target='client_id' />.
</t>
<t hangText='secret_type'>
<vspace />
OPTIONAL. The access token secret type as described by
<xref target='crypto_token' />. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as described by
<xref target='bearer_token' />.
</t>
</list>
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request (line breaks are for
display purposes only):
</preamble>
<artwork><![CDATA[
POST /token HTTP/1.1
Host: server.example.com
type=client_credentials&client_id=s6BhdRkqt3&client_secret=47HDu8s
]]>
</artwork>
</figure>
<t>
The authorization server MUST validate the client credentials and if valid issue an
access token and deliver to the client in the HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as defined
by <xref target='W3C.REC-html40-19980424' /> with a 200 status code (OK).
</t>
<t>
The response contains the following parameters:
<list style='hanging' hangIndent='6'>
<t hangText='access_token'>
<vspace />
REQUIRED. The access token.
</t>
<t hangText='expires_in'>
<vspace />
OPTIONAL. The duration in seconds of the access token lifetime.
</t>
<t hangText='refresh_token'>
<vspace />
OPTIONAL. The refresh token.
</t>
<t hangText='access_token_secret'>
<vspace />
REQUIRED if requested by the client. The corresponding access token secret as
requested by the client.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
access_token=FJQbwq9OD8
]]>
</artwork>
</figure>
<t>
If the request is invalid, the authorization server returns an error message in the
HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as defined
by <xref target='W3C.REC-html40-19980424' /> with a 400 status code (Bad Request).
</t>
<t>
The response contains the following parameter:
<list style='hanging' hangIndent='6'>
<t hangText='error'>
<vspace />
OPTIONAL. The parameter value MUST be set to
<spanx style='verb'>incorrect_client_credentials</spanx>.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 400 Bad Request
Content-Type: application/x-www-form-urlencoded
error=incorrect_client_credentials
]]>
</artwork>
</figure>
</section>
</section>
<section title='Assertion Flow' anchor='assertion_flow'>
<t>
The assertion flow is used when a client wishes to exchange an existing security token
or assertion for an access token. This flow is suitable when the client is acting
autonomously or on behalf of the end-user (based on the content of the assertion used).
</t>
<t>
The assertion flow requires the client to obtain a assertion (such as a
<xref target='OASIS.saml-core-2.0-os'>SAML</xref> assertion) from an assertion issuer
or to self-issue an assertion prior to initiating the flow. The assertion format, the
process by which the assertion is obtained, and the method of validating the assertion
are defined by the assertion issuer and the authorization server, and are beyond the
scope of this specification.
</t>
<t>
The client credentials flow is used when the client acts autonomously without acting on
behalf of a separate resource owner.
</t>
<figure anchor='Figure 9'>
<artwork>
<![CDATA[
+--------+ +---------------+
| | | |
| |>--(A)------ Assertion ---------->| Authorization |
| Client | | Server |
| |<--(B)---- Access Token ---------<| |
| | | |
+--------+ +---------------+
]]>
</artwork>
</figure>
<t>
The client credential flow illustrated in <xref target='Figure 9' /> includes the
following steps:
<list style='format (%C)'>
<t>
The client sends an access token request to the authorization server and includes
an assertion.
</t>
<t>
The authorization server validates the assertion and issues an access token.
</t>
</list>
</t>
<section title='Client Requests Access Token'>
<t>
The client requests an access token by making an HTTP <spanx style='verb'>POST</spanx>
request to the token endpoint. The client constructs a request URI by adding
the following parameters to the request:
<list style='hanging' hangIndent='6'>
<t hangText='type'>
<vspace />
REQUIRED. The parameter value MUST be set to
<spanx style='verb'>assertion</spanx>.
</t>
<t hangText='format'>
<vspace />
REQUIRED. The format of the assertion as defined by the authorization server. The
value MUST be an absolute URI.
</t>
<t hangText='assertion'>
<vspace />
REQUIRED. The assertion.
</t>
<t hangText='secret_type'>
<vspace />
OPTIONAL. The access token secret type as described by
<xref target='crypto_token' />. If omitted, the authorization server will issue a
bearer token (an access token without a matching secret) as described by
<xref target='bearer_token' />.
</t>
</list>
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request (line breaks are for
display purposes only):
</preamble>
<artwork><![CDATA[
POST /token HTTP/1.1
Host: server.example.com
type=assertion&format=_______&assertion=_______
]]>
</artwork>
</figure>
<t>
The authorization server MUST validate the assertion and if valid issue an access
token and deliver to the client in the HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as defined
by <xref target='W3C.REC-html40-19980424' /> with a 200 status code (OK).
</t>
<t>
The response contains the following parameters:
<list style='hanging' hangIndent='6'>
<t hangText='access_token'>
<vspace />
REQUIRED. The access token.
</t>
<t hangText='expires_in'>
<vspace />
OPTIONAL. The duration in seconds of the access token lifetime.
</t>
<t hangText='access_token_secret'>
<vspace />
REQUIRED if requested by the client. The corresponding access token secret as
requested by the client.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
access_token=FJQbwq9OD8
]]>
</artwork>
</figure>
<t>
If the assertion is invalid, the authorization server returns an error message in the
HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as defined
by <xref target='W3C.REC-html40-19980424' /> with a 400 status code (Bad Request).
</t>
<t>
The response contains the following parameter:
<list style='hanging' hangIndent='6'>
<t hangText='error'>
<vspace />
OPTIONAL. The parameter value MUST be set to either
<spanx style='verb'>invalid_assertion</spanx> or
<spanx style='verb'>unknown_format</spanx>.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 400 Bad Request
Content-Type: application/x-www-form-urlencoded
error=incorrect_credentials
]]>
</artwork>
</figure>
<t>
Authorization servers SHOULD issue access tokens with a limited lifetime and require
clients to refresh them by requesting a new access token using the same assertion if it
is still valid. Otherwise the client MUST obtain a new valid assertion.
</t>
</section>
</section>
</section>
</section>
<section title='Refreshing an Access Token' anchor='token_refresh'>
<t>
Token refresh is used when the lifetime of an access token is shorter than the lifetime of
the authorization grant. It allows clients to obtain a new access token without having to
go through the authorization flow again or involve the resource owner. It is also used to
obtain a new token with different security properties (e.g. bearer token, token with
shared symmetric secret).
</t>
<figure anchor='Figure 10'>
<artwork><![CDATA[
+--------+ Client Credentials, +---------------+
| | Refresh Token, | |
| |>--(A)----- & Secret Type ------->| Authorization |
| Client | | Server |
| |<--(B)----- Access Token --------<| |
| | & Optional Secret | |
+--------+ +---------------+
]]>
</artwork>
</figure>
<t>
To refresh a token, the client constructs an HTTP <spanx style='verb'>POST</spanx> request
to the token endpoint and includes the following parameters in the HTTP request
body using the <spanx style='verb'>application/x-www-form-urlencoded</spanx> content type
as defined by <xref target='W3C.REC-html40-19980424' />:
<list style='hanging' hangIndent='6'>
<t hangText='type'>
<vspace />
REQUIRED. The parameter value MUST be set to <spanx style='verb'>refresh</spanx>.
</t>
<t hangText='client_id'>
<vspace />
REQUIRED. The client identifier as described in <xref target='client_id' />.
</t>
<t hangText='client_secret'>
<vspace />
REQUIRED if the client was issued a secret. The client secret.
</t>
<t hangText='refresh_token'>
<vspace />
REQUIRED. The refresh token associated with the access token to be refreshed.
</t>
<t hangText='secret_type'>
<vspace />
OPTIONAL. The access token secret type as described by <xref target='crypto_token' />.
If omitted, the authorization server will issue a bearer token (an access token without
a matching secret) as described by <xref target='bearer_token' />.
</t>
</list>
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request (line break are for display
purposes only):
</preamble>
<artwork>
<![CDATA[
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
type=refresh_token&client_id=s6BhdRkqt3&client_secret=8eSEIpnqmM
&refresh_token=n4E9O119d&secret_type=hmac-sha256
]]>
</artwork>
</figure>
<t>
The authorization server MUST verify the client credential, the validity of the refresh
token, and that the resource owner's authorization is still valid. If the request is valid,
the authorization server issues a new access token and includes the following parameters in
the HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as defined by
<xref target='W3C.REC-html40-19980424' /> with a 200 status code (OK):
<list style='hanging' hangIndent='6'>
<t hangText='access_token'>
<vspace />
REQUIRED. The access token.
</t>
<t hangText='expires_in'>
<vspace />
OPTIONAL. The duration in seconds of the access token lifetime.
</t>
<t hangText='access_token_secret'>
<vspace />
REQUIRED if requested by the client. The corresponding access token secret as requested
by the client.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork>
<![CDATA[
HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
access_token=8F44J2HGMl&access_token_secret=hfd83hjd&expires_in=3600
]]>
</artwork>
</figure>
<t>
If the request fails verification, the authorization server returns an error message in the
HTTP response body using the
<spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as defined
by <xref target='W3C.REC-html40-19980424' /> with a 400 status code (Bad Request).
</t>
<t>
The response contains the following parameter:
<list style='hanging' hangIndent='6'>
<t hangText='error'>
<vspace />
OPTIONAL. The parameter value MUST be set to either
<spanx style='verb'>incorrect_credentials</spanx>,
<spanx style='verb'>authorization_expired</spanx>, or
<spanx style='verb'>unsupported_secret_type</spanx>.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 400 Bad Request
Content-Type: application/x-www-form-urlencoded
error=incorrect_credentials
]]>
</artwork>
</figure>
</section>
<section title='Accessing a Protected Resource' anchor='access_resource'>
<t>
Clients access protected resources by presenting an access token to the resource server.
The methods used by the resource server to validate the access token are beyond the scope
of this specification, but generally involve an interaction or coordination between the
resource server and authorization server.
</t>
<t>
The method in which a client uses an access token depends on the security properties of the
access tokens. By default, access tokens are issued without a matching secret. Clients MAY
request an access token with a matching secret by specifying the desired secret type using
the <spanx style='verb'>secret_type</spanx> token request parameter.
</t>
<t>
When an access token does not include a matching secret, the access token acts as a bearer
token, where the token string is a shared symmetric secret. This requires treating the
access token with the same care as other secrets (e.g. user passwords). Access tokens
SHOULD NOT be sent in the clear over an insecure channel.
</t>
<t>
However, when it is necessary to transmit bearer tokens in the clear without a secure
channel, authorization servers SHOULD issue access tokens with limited scope and lifetime
to reduce the potential risk from a compromised access token. Clients SHOULD request and
utilize an access token with a matching secret when making protected resource requests over
an insecure channel (e.g. an HTTP request without using TLS/SSL).
</t>
<t>
When an access token includes a matching secret, the secret is not included directly in the
request but is used instead to generate a cryptographic signature of the request. The
signature can only be generated and verified by entities with access to the secret.
</t>
<t>
Clients SHOULD NOT make authenticated requests with an access token to unfamiliar resource
servers, especially when using bearer tokens, regardless of the presence of a secure
channel.
</t>
<section title='The Authorization Request Header' anchor='authz_header'>
<t>
The <spanx style='verb'>Authorization</spanx> request header field is used by clients to
make both bearer token and cryptographic token requests. When making bearer token
requests, the client uses the <spanx style='verb'>token</spanx> attribute to include the
access token in the request without any of the other attributes. Additional methods for
making bearer token requests are described in <xref target='bearer_token' />.
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
GET /resource HTTP/1.1
Host: server.example.com
Authorization: Token token="vF9dft4qmT"
]]>
</artwork>
</figure>
<t>
When making a cryptographic token request (using an access token with a matching secret)
the client uses the <spanx style='verb'>token</spanx> attribute to include the access
token in the request, and uses the <spanx style='verb'>nonce</spanx>,
<spanx style='verb'>timestamp</spanx>, <spanx style='verb'>algorithm</spanx>, and
<spanx style='verb'>signature</spanx> attributes to apply the matching secret.
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
GET /resource HTTP/1.1
Host: server.example.com
Authorization: Token token="vF9dft4qmT",
nonce="s8djwd",
timestamp="137131200",
algorithm="hmac-sha256",
signature="wOJIO9A2W5mFwDgiDvZbTSMK/PY="
]]>
</artwork>
</figure>
<t>
The <spanx style='verb'>Authorization</spanx> header field uses the framework defined by
<xref target='RFC2617' /> as follows:
</t>
<figure>
<artwork xml:space='preserve'><![CDATA[
credentials = "Token" RWS token-response
token-response = token-id
[ CS nonce ]
[ CS timestamp ]
[ CS algorithm ]
[ CS signature ]
token-id = "token" "=" <"> token <">
timestamp = "timestamp" "=" <"> 1*DIGIT <">
nonce = "nonce" "=" <"> token <">
algorithm = "algorithm" "=" algorithm-name
algorithm-name = "hmac-sha256" /
token
signature = "signature" "=" <"> token <">
]]>
</artwork>
</figure>
</section>
<section title='Bearer Token Requests' anchor='bearer_token'>
<t>
Clients make bearer token requests by including the access token using the HTTP
<spanx style='verb'>Authorization</spanx> request header with the
<spanx style='verb'>Token</spanx> authentication scheme as described in
<xref target='authz_header' />. The access token is included using the
<spanx style='verb'>token</spanx> parameter.
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request:
</preamble>
<artwork><![CDATA[
GET /resource HTTP/1.1
Host: server.example.com
Authorization: Token token="vF9dft4qmT"
]]>
</artwork>
</figure>
<t>
The resource server MUST validate the access token and ensure it has not expired and
that its scope covers the requested resource. If the token expired or is invalid, the
resource server MUST reply with an HTTP 401 status code (Unauthorized) and include
the HTTP <spanx style='verb'>WWW-Authenticate</spanx> response header as described in
<xref target='authn_header' />.
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Token realm='Service', error='token_expired'
]]>
</artwork>
</figure>
<t>
Alternatively, the client MAY include the access token using the HTTP request URI in the
query component as described in <xref target='query_param' />, or in the HTTP body when
using the <spanx style='verb'>application/x-www-form-urlencoded</spanx> content type as
described in <xref target='body_param' />. Clients SHOULD only use the request URI or
body when the <spanx style='verb'>Authorization</spanx> request header is not available,
and MUST NOT use more than one method in each request.
</t>
<section title='URI Query Parameter' anchor='query_param'>
<t>
When including the access token in the HTTP request URI, the client adds the access
token to the request URI query component as defined by <xref target='RFC3986' /> using
the <spanx style='verb'>oauth_token</spanx> parameter.
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request:
</preamble>
<artwork>
<![CDATA[
GET /resource?oauth_token=vF9dft4qmT HTTP/1.1
Host: server.example.com
]]>
</artwork>
</figure>
<t>
The HTTP request URI query can include other request-specific parameters, in which
case, the <spanx style='verb'>oauth_token</spanx> parameters SHOULD be appended
following the request-specific parameters, properly separated by an
<spanx style="verb">&</spanx> character (ASCII code 38).
</t>
<t>
The resource server MUST validate the access token and ensure it has not expired and
its scope includes the requested resource. If the resource expired or is not valid, the
resource server MUST reply with an HTTP 401 status code (Unauthorized) and include the
HTTP <spanx style='verb'>WWW-Authenticate</spanx> response header as described in
<xref target='authn_header' />.
</t>
</section>
<section title='Form-Encoded Body Parameter' anchor='body_param'>
<t>
When including the access token in the HTTP request entity-body, the client adds the
access token to the request body using the <spanx style='verb'>oauth_token</spanx>
parameter. The client can use this method only if the following REQUIRED conditions are
met:
<list style="symbols">
<t>
The entity-body is single-part.
</t>
<t>
The entity-body follows the encoding requirements of the
<spanx style="verb">application/x-www-form-urlencoded</spanx> content-type as
defined by <xref target="W3C.REC-html40-19980424" />.
</t>
<t>
The HTTP request entity-header includes the <spanx style="verb">Content-Type</spanx>
header field set to <spanx style="verb">application/x-www-form-urlencoded</spanx>.
</t>
<t>
The HTTP request method is <spanx style='verb'>POST</spanx>,
<spanx style='verb'>PUT</spanx>, or <spanx style='verb'>DELETE</spanx>.
</t>
</list>
</t>
<t>
The entity-body can include other request-specific parameters, in which case, the
<spanx style='verb'>oauth_token</spanx> parameters SHOULD be appended following the
request-specific parameters, properly separated by an <spanx style="verb">&</spanx>
character (ASCII code 38).
</t>
<figure>
<preamble>
For example, the client makes the following HTTPS request:
</preamble>
<artwork>
<![CDATA[
POST /resource HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
oauth_token=vF9dft4qmT
]]>
</artwork>
</figure>
<t>
The resource server MUST validate the access token and ensure it has not expired and
its scope includes the requested resource. If the resource expired or is not valid, the
resource server MUST reply with an HTTP 401 status code (Unauthorized) and include the
HTTP <spanx style='verb'>WWW-Authenticate</spanx> response header as described in
<xref target='authn_header' />.
</t>
</section>
</section>
<section title='Cryptographic Tokens Requests' anchor='crypto_token'>
<t>
Clients make authenticated protected resource requests using an access token with a
matching secret by calculating a set of values and including them in the request using
the <spanx style='verb'>Authorization</spanx> header field. The way clients calculate
these values depends on the access token secret type as issued by the authorization
server.
</t>
<t>
This specification defines the <spanx style='verb'>hmac-sha256</spanx> algorithm, and
establishes a registry for providing additional algorithms. Clients obtain an access
token with a matching <spanx style='verb'>hmac-sha256</spanx> secret by using the
<spanx style='verb'>token_type</spanx> parameter when requesting an access token.
</t>
<section title="The 'hmac-sha256' Algorithm" anchor='hmac-sha256'>
<t>
The <spanx style='verb'>hmac-sha256</spanx> algorithm uses the HMAC method as defined
in <xref target='RFC2104' /> together with the SHA-256 hash function defined in
<xref target='NIST FIPS-180-3' /> to apply the access token secret to the request and
generate a signature value that is included in the request instead of transmitting
the secret in the clear.
</t>
<t>
To use the <spanx style='verb'>hmac-sha256</spanx> algorithm, clients:
<list style='numbers'>
<t>
Calculate the request timestamp and generate a request nonce as described in
<xref target='nonce_ts' />.
</t>
<t>
Construct the normalized request string as described in
<xref target='base_string' />.
</t>
<t>
Calculate the request signature as described in
<xref target='hmac_sha256_function' />.
</t>
<t>
Include the timestamp, nonce, algorithm name, and calculated signature in the
request using the <spanx style='verb'>Authorization</spanx> header field.
</t>
</list>
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
GET /resource HTTP/1.1
Host: server.example.com
Authorization: Token token="vF9dft4qmT",
nonce="s8djwd",
timestamp="137131200",
algorithm="hmac-sha256",
signature="wOJIO9A2W5mFwDgiDvZbTSMK/PY="
]]>
</artwork>
</figure>
<t>
The resource server MUST validate the access token and ensure it has not expired and
that its scope covers the requested resource. The resource server MUST also recalculate
the request signature using the attributes provided by the client and compare it to the
signature provided. If the token expired or is invalid, or if the signature is
incorrect, the resource server MUST reply with an HTTP 401 status code (Unauthorized)
and include the HTTP <spanx style='verb'>WWW-Authenticate</spanx> response header as
described in <xref target='authn_header' />.
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork><![CDATA[
HTTP/1.1 401 Unauthorized
Date: Tue, 15 Nov 2010 08:12:31 GMT
WWW-Authenticate: Token realm='Service',
algorithms='hmac-sha256',
error='invalid_signature'
]]>
</artwork>
</figure>
<t>
[[ Errors list ]]
</t>
<section title='Nonce and Timestamp' anchor='nonce_ts'>
<t>
A timestamp in combination with unique nonce values is used to protect against
replay attacks when transmitted over an insecure channel.
</t>
<t>
The nonce is a random string, uniquely generated by the client to allow the resource
server to verify that a request has never been made before and helps prevent replay
attacks when requests are made over a non-secure channel. The nonce value MUST be
unique across all requests with the same timestamp and token combinations.
</t>
<t>
The timestamp value is the current time expressed in the number of seconds since
January 1, 1970 00:00:00 GMT, and MUST be a positive integer.
</t>
<t>
To avoid the need to retain an infinite number of nonce values for future checks,
resource servers MAY choose to restrict the time period after which a request with an
old timestamp is rejected. When resource servers apply such a restriction, clients
SHOULD synchronize their clocks by using the resource server's time as indicated by
the HTTP <spanx style='verb'>Date</spanx> response header field as defined in
<xref target='RFC2616' />.
</t>
</section>
<section title='Normalized String Construction' anchor='base_string'>
<t>
The normalized request string is a consistent, reproducible concatenation of
several of the HTTP request elements into a single string. The string is used as an
input to the selected cryptographic method and includes the HTTP request method
(e.g. <spanx style='verb'>GET</spanx>, <spanx style='verb'>POST</spanx>, etc.), the
authority as declared by the HTTP <spanx style='verb'>Host</spanx> request header,
and the request resource URI.
</t>
<t>
The normalized request string does not cover the entire HTTP request. Most notably,
it does not include the entity-body or most HTTP entity-headers. It is important to
note that the resource server cannot verify the authenticity of the excluded request
elements without using additional protections such as TLS/SSL.
</t>
<t>
The normalized request string is constructed by concatenating together, in order,
the following HTTP request elements, separated by the <spanx style='verb'>,</spanx>
character (ASCII code 44):
<list style='numbers'>
<t>
The request timestamp as described in <xref target='nonce_ts' />.
</t>
<t>
The request nonce as described in <xref target='nonce_ts' />.
</t>
<t>
The cryptographic algorithm used.
</t>
<t>
The HTTP request method in uppercase. For example:
<spanx style='verb'>HEAD</spanx>, <spanx style='verb'>GET</spanx>,
<spanx style='verb'>POST</spanx>, etc.
</t>
<t>
The hostname, colon-separated (ASCII code 58) from the TCP port used to make
the request as included in the HTTP request <spanx style='verb'>Host</spanx>
header field. The port MUST be included even if it is not included in the
<spanx style='verb'>Host</spanx> header field (i.e. the default port for the
scheme).
</t>
<t>
The request resource URI.
</t>
</list>
</t>
<figure>
<preamble>
For example, the normalized request string for the
<spanx style='verb'>GET</spanx> request URI
<spanx style='verb'>http://example.com/resource</spanx>, request timestamp
<spanx style='verb'>137131200</spanx>, request nonce
<spanx style='verb'>s8djwd</spanx>, and <spanx style='verb'>hmac-sha256</spanx>
algorithm (line breaks are for display purposes only):
</preamble>
<artwork><![CDATA[
137131200,s8djwd,hmac-sha256,GET,example.com:80,
http://example.com/resource
]]>
</artwork>
</figure>
</section>
<section title='Signature Calculation' anchor='hmac_sha256_function'>
<t>
Clients calculate the request signature using the HMAC-SHA256 function:
</t>
<figure>
<artwork><![CDATA[
digest = HMAC-SHA256 (key, text)
]]>
</artwork>
</figure>
<t>
by setting the function variables are follows:
<list style='hanging' hangIndent='6'>
<t hangText='text'>
<vspace />
is set to the value of the normalize request string as described in
<xref target='base_string' />.
</t>
<t hangText='key'>
<vspace />
is set to the access token secret.
</t>
</list>
</t>
<t>
The request signature is the calculated value of the
<spanx style='verb'>digest</spanx> variable after the result octet string is
base64-encoded per <xref target='RFC2045' /> section 6.8.
</t>
</section>
</section>
</section>
</section>
<section title='Identifying a Protected Resource'>
<t>
Clients access protected resources after locating the appropriate authorization and token endpoints
and obtaining an access token. In many cases, interacting with a protected resource requires
prior knowledge of the protected resource properties and methods, as well as its
authentication requirements (i.e. establishing client identity, locating the authorization
and token endpoints).
</t>
<t>
However, there are cases in which clients are unfamiliar with the protected resource,
including whether the resource requires authentication. When clients attempt to access an
unfamiliar protected resource without an access token, the resource server denies the
request and informs the client of the required credentials using an HTTP authentication
challenge.
</t>
<t>
In addition, when receiving an invalid authenticated request, the resource server issues an
authentication challenge including the error type and message.
</t>
<section title='The WWW-Authenticate Response Header' anchor='authn_header'>
<t>
A resource server receiving a request for a protected resource without a valid access
token MUST respond with a 401 HTTP status code (Unauthorized), and includes at least one
<spanx style='verb'>Token</spanx> <spanx style='verb'>WWW-Authenticate</spanx> response
header field challenge.
</t>
<t>
The <spanx style='verb'>WWW-Authenticate</spanx> header field uses the framework defined by
<xref target='RFC2617' /> as follows:
</t>
<figure>
<artwork><![CDATA[
challenge = "Token" RWS token-challenge
token-challenge = realm
[ CS authz-uri ]
[ CS token-uri ]
[ CS algorithms ]
[ CS error ]
authz-uri = "auth-uri" "=" URI-Reference
token-uri = "token-uri" "=" URI-Reference
algorithms = "algorithms" "=" <"> 1#algorithm-name <">
error = "error" "=" <"> token <">
CS = OWS "," OWS
]]>
</artwork>
</figure>
<section title="The 'realm' Attribute">
<t>
The <spanx style='verb'>realm</spanx> attribute is used to provide the protected
resources partition as defined by <xref target='RFC2617' />.
</t>
</section>
<section title="The 'authorization-uri' Attribute" anchor='authz_uri_attribute'>
<t>
</t>
</section>
<section title="The 'algorithms' Attribute">
<t>
</t>
</section>
<section title="The 'error' Attribute">
<t>
</t>
</section>
</section>
</section>
<section title='Security Considerations'>
<t>
[[ Todo ]]
</t>
</section>
<section title='IANA Considerations'>
<t>
[[ Not Yet ]]
</t>
</section>
<section title='Acknowledgements'>
<t>
[[ Add OAuth 1.0a authors + WG contributors ]]
</t>
</section>
<appendix title='Differences from OAuth 1.0a'>
<t>
[[ Todo ]]
</t>
</appendix>
<appendix title='Document History'>
<t>
[[ to be removed by RFC editor before publication as an RFC ]]
</t>
<t>
-01
<list style='symbols'>
<t>
Editorial changes based on feedback from Brian Eaton, Bill Keenan, and Chuck Mortimore.
</t>
<t>
Changed devide flow <spanx style='verb'>type</spanx> parameter values and switch to use
only the token endpoint.
</t>
</list>
</t>
<t>
-00
<list style='symbols'>
<t>
Initial draft based on a combination of WRAP and OAuth 1.0a.
</t>
</list>
</t>
</appendix>
</middle>
<back>
<references title='Normative References'>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2045.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2104.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2617.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.2818.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3447.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-html40-19980424.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-httpbis-p1-messaging-09.xml'?>
<reference anchor="NIST FIPS-180-3">
<front>
<title>Secure Hash Standard (SHS). FIPS PUB 180-3, October 2008</title>
<author>
<organization>National Institute of Standards and Technology</organization>
</author>
</front>
<format type="pdf" target="http://csrc.nist.gov/publications/fips/fips180-3/fips180-3_final.pdf" />
</reference>
</references>
<references title='Informative References'>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hammer-oauth-10.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-hardt-oauth-01.xml' ?>
<?rfc include='http://xml.resource.org/public/rfc/bibxml2/reference.OASIS.saml-core-2.0-os.xml' ?>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 03:35:03 |