One document matched: draft-ietf-oauth-authentication-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-authentication-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 Authentication">The OAuth Protocol: Authentication</title>
<author initials="E" surname="Hammer-Lahav" fullname="Eran Hammer-Lahav" role="editor">
<organization>
Yahoo!
</organization>
<address>
<email>eran@hueniverse.com</email>
<uri>http://hueniverse.com</uri>
</address>
</author>
<date year="2009"/>
<abstract>
<t>
This document specifies the OAuth protocol authentication method. OAuth allows clients
to access server resources on behalf of another party (such a different client or an end
user). This document defines an HTTP authentication method which supports the ability to
include two sets of credential with each request, one identifying the client and another
identifying the resource owner on whose behalf the request is made.
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
The OAuth protocol provides a method for servers to allow third-party access to protected
resources, without forcing their end users to share their credentials. This pattern is
common among services that allow third-party developers to extend the service functionality,
by building applications using an open API.
</t>
<t>
For example, a web user (resource owner) can grant a printing service (client) access to
its private photos stored at a photo sharing service (server), without sharing its
credentials with the printing service. Instead, the user authenticates directly with
the photo sharing service and issue the printing service delegation-specific credentials.
</t>
<t>
OAuth introduces a third role to the traditional client-server authentication model: the
resource owner. In the OAuth model, the client requests access to resources hosted by the
server but not controlled by the client, but by the resource owner. In addition, OAuth
allows the server to verify not only the resource owner's credentials, but also those of
the client making the request.
</t>
<t>
In order for the client to access resources, it first has to obtain permission from the
resource owner. This permission is expressed in the form of a token and matching
shared-secret. The purpose of the token is to substitute the need for the resource owner to
share its server credentials (usually a username and password pair) with the client. Unlike
server credentials, tokens can be issued with a restricted scope and limited lifetime.
</t>
<t>
This specification consists of two parts. This document defines a method for making
authenticated HTTP requests using two sets of credentials, one identifying the client
making the request, and a second identifying the resource owner on whose behalf the
request is being made.
</t>
<t>
<xref target="draft-ietf-oauth-web-delegation" /> defines a redirection-based user agent
process for end users to authorize client access to their resources, by authenticating
directly with the server and provisioning tokens to the client for use with the
authentication method.
</t>
<section title="Terminology">
<t>
<list style="hanging" hangIndent="6">
<t hangText="client">
<vspace />
An HTTP client (per <xref target="RFC2616" />) capable of making
OAuth-authenticated requests.
</t>
<t hangText="server">
<vspace />
An HTTP server (per <xref target="RFC2616" />) capable of accepting
OAuth-authenticated requests.
</t>
<t hangText="protected resource">
<vspace />
An access-restricted resource (per <xref target="RFC2616" />) which can be obtained
from the server using an OAuth-authenticated request.
</t>
<t hangText="resource owner">
<vspace />
An entity capable of accessing and controlling protected resources by using credentials
to authenticate with the server.
</t>
<t hangText="token">
<vspace />
An unique identifier issued by the server and used by the client to associate
authenticated requests with the resource owner whose authorization is requested or
has been obtained by the client. Tokens have a matching shared-secret that is used
by the client to establish its ownership of the token, and its authority to represent
the resource owner.
</t>
</list>
</t>
</section>
</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>
</section>
<section title="Authenticated Requests">
<t>
The HTTP authentication methods defined by <xref target="RFC2617" />, enable clients
to make authenticated HTTP requests. Clients using these methods gain access to protected
resource by using their server credentials (typically a username and password pair), which
allows the server to verify their authenticity. Using these methods for delegation requires
the client to pretend it was the resource owner.
</t>
<t>
OAuth provides a method designed to include two sets of credentials with each request, one
to identify the client, and another to identify the resource owner. Before a client can
make authenticated requests on behalf of the resource owner, it must obtain a token
authorized by the resource owner. <xref target="draft-ietf-oauth-web-delegation" /> provides one such
method in which the client can obtain a token authorized by the resource owner.
</t>
<t>
The client credentials take the form of a unique identifier, and an associated share-secret
or RSA key pair. Prior to making authenticated requests, the client establishes a set of
credentials with the server. The process and requirements for provisioning these are
outside the scope of this specification. Implementers are urged to consider the security
ramification of using client credentials, some of which are described in
<xref target="client_cred_sec" />.
</t>
<t>
Making authenticated requests requires prior knowledge of the server's configuration.
OAuth provides multiple methods for including protocol parameters in requests
(<xref target="param_include" />), as well as multiple methods for the client to
prove its rightful ownership of the credentials used (<xref target="signature" />).
The way in which clients discovery the required configuration is outside the scope of
this specification.
</t>
</section>
<section title="Protocol Parameters">
<t>
An OAuth-authenticated request includes several protocol parameters. Each parameter name
begins with the <spanx style="verb">oauth_</spanx> prefix, and the parameter names
and values are case sensitive. Protocol parameters MUST NOT appear more than once per
request. The parameters are:
<list style="hanging" hangIndent="6">
<t hangText="oauth_consumer_key">
<vspace />
The identifier portion of the client credentials (equivalent to a username). The
parameter name reflects a deprecated term (Consumer Key) used in previous revisions
of the specification, and has been retained to maintain backward compatibility.
</t>
<t hangText="oauth_token">
<vspace />
The token value used to associate the request with the resource owner. If the request
is not associated with a resource owner (no token), clients MAY omit the parameter.
</t>
<t hangText="oauth_signature_method">
<vspace />
The name of the signature method used by the client to sign the request,
as defined in <xref target="signature" />.
</t>
<t hangText="oauth_signature">
<vspace />
The signature value as defined in <xref target="signature" />.
</t>
<t hangText="oauth_timestamp">
<vspace />
The timestamp value as defined in <xref target="nonce" />.
</t>
<t hangText="oauth_nonce">
<vspace />
The nonce value as defined in <xref target="nonce" />.
</t>
<t hangText="oauth_version">
<vspace />
The protocol version. If omitted, the protocol version defaults to
<spanx style="verb">1.0</spanx>.
</t>
</list>
</t>
<t>
Server-specific request parameters MUST NOT begin with the
<spanx style="verb">oauth_</spanx> prefix.
</t>
</section>
<section title="Nonce and Timestamp" anchor="nonce">
<t>
Unless otherwise specified by the server, the timestamp is expressed in the number of
seconds since January 1, 1970 00:00:00 GMT. The timestamp value MUST be a positive
integer and MUST be equal or greater than the timestamp used in previous requests with
the same client credentials and token credentials combination.
</t>
<t>
A nonce is a random string, uniquely generated to allows the 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, client credentials, and token combinations.
</t>
<t>
To avoid the need to retain an infinite number of nonce values for future checks, servers
MAY choose to restrict the time period after which a request with an old timestamp is
rejected. Server applying such restriction SHOULD provide a way for the client to sync
its clock with the server's clock.
</t>
</section>
<section title="Signature" anchor="signature">
<t>
OAuth-authenticated requests can have two sets of credentials included via the
<spanx style="verb">oauth_consumer_key</spanx> parameter and the
<spanx style="verb">oauth_token</spanx> parameter. In order for the server to
verify the authenticity of the request and prevent unauthorized access, the client needs
to prove it is the rightful owner of the credentials. This is accomplished using the
shared-secret (or RSA key) part of each set of credentials.
</t>
<t>
OAuth provides three methods for the client to prove its rightful ownership of the
credentials: <spanx style="verb">HMAC-SHA1</spanx>, <spanx style="verb">RSA-SHA1</spanx>,
and <spanx style="verb">PLAINTEXT</spanx>. These methods are generally referred to as
signature methods, even though <spanx style="verb">PLAINTEXT</spanx> does not involve a
signature. In addition, <spanx style="verb">RSA-SHA1</spanx> utilizes an RSA key instead
of the shared-secrets associated with the client credentials.
</t>
<t>
OAuth does not mandate a particular signature method, as each implementation can have its
own unique requirements. Servers are free to implement and document their own custom
methods. Recommending any particular method is beyond the scope of this specification.
</t>
<t>
The client declares which signature method is used via the
<spanx style="verb">oauth_signature_method</spanx> parameter. It then generates a signature
(or a sting of an equivalent value), and includes it in the
<spanx style="verb">oauth_signature</spanx> parameter. The server verifies the signature
as specified for each method.
</t>
<t>
The signature process does not change the request or its parameter, with the exception of
the <spanx style="verb">oauth_signature</spanx> parameter.
</t>
<section title="Signature Base String">
<t>
The signature base string is a consistent, reproducible concatenation of several
request elements into a single string. The string is used as an input to the
<spanx style="verb">HMAC-SHA1</spanx> and <spanx style="verb">RSA-SHA1</spanx>
signature methods, or potential future extension.
</t>
<t>
The signature base string does not cover the entire HTTP request. Most notably, it
does not include the entity-body in most requests, nor does it include most HTTP
entity-headers. The importance of the signature base string scope is that the
authenticity of the excluded components cannot be verified using the signature.
</t>
<section title="Collect Request Parameters" anchor="collect_param">
<t>
The signature base string includes a specific set of request parameters. In order for
the parameter to be included in the signature base string, they MUST be used in their
unencoded form.
<figure>
<preamble>
For example, the URI:
</preamble>
<artwork>
http://example.com/request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2q
</artwork>
<postamble>
contains the following raw-form parameters:
</postamble>
</figure>
</t>
<texttable>
<ttcol align='center'>Name</ttcol>
<ttcol align='center'>Value</ttcol>
<c>b5</c>
<c>=%3D</c>
<c>a3</c>
<c>a</c>
<c>c@</c>
<c></c>
<c>a2</c>
<c>r b</c>
<c>c2</c>
<c></c>
<c>a3</c>
<c>2q</c>
</texttable>
<t>
Note that the value of <spanx style="verb">b5</spanx> is <spanx style="verb">=%3D</spanx>
and not <spanx style="verb">==</spanx>. Both <spanx style="verb">c@</spanx> and
<spanx style="verb">c2</spanx> have empty values.
</t>
<t>
The request parameters, which include both protocol parameters and request-specific
parameters, are extracted and restored to their original unencoded form, from
the following sources:
<list style="symbols">
<t>
The <xref target="auth_header">OAuth HTTP Authorization header</xref>. The
<spanx style="verb">realm</spanx> parameter MUST be excluded if present.
</t>
<t>
The HTTP request entity-body, but only if:
<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 set to <spanx style="verb">application/x-www-form-urlencoded</spanx>.
</t>
</list>
</t>
<t>
The query component of the HTTP request URI as defined by
<xref target="RFC3986" /> section 3.
</t>
</list>
</t>
<t>
The <spanx style="verb">oauth_signature</spanx> parameter MUST be
excluded if present.
</t>
<t>
In many cases, clients have direct access to the parameters in their original,
unencoded form. In such cases, clients SHOULD use the unencoded values instead of
extracting them. This option is not available for servers when validating incoming
requests. Even though the parameters are encoded again in the process, they are
decoded because each of the three sources uses a different encoding algorithm.
</t>
<t>
The output of this step is a list of unencoded parameter name / value pairs.
</t>
</section>
<section title="Normalize Request Parameters" anchor="sig_norm_param">
<t>
The parameter collected in <xref target="collect_param" /> are normalized into a
single string as follows:
<list style="numbers">
<t>
First, the name and value of each parameter are <xref target="encoding">encoded</xref>.
</t>
<t>
The parameters are sorted by name, using lexicographical byte value ordering. If
two or more parameters share the same name, they are sorted by their value.
</t>
<t>
The name of each parameter is concatenated to its corresponding value using an
<spanx style="verb">=</spanx> character (ASCII code 61) as separator, even if the
value is empty.
</t>
<t>
The sorted name / value pairs are concatenated together into a single string by
using an <spanx style="verb">&</spanx> character (ASCII code 38) as separator.
</t>
</list>
</t>
<t>
For example, the list of parameters from the previous section would be normalized as
follows:
</t>
<texttable>
<preamble>
Encoded:
</preamble>
<ttcol align='center'>Name</ttcol>
<ttcol align='center'>Value</ttcol>
<c>b5</c>
<c>%3D%253D</c>
<c>a3</c>
<c>a</c>
<c>c%40</c>
<c></c>
<c>a2</c>
<c>r%20b</c>
<c>c2</c>
<c></c>
<c>a3</c>
<c>2q</c>
</texttable>
<texttable>
<preamble>
Sorted:
</preamble>
<ttcol align='center'>Name</ttcol>
<ttcol align='center'>Value</ttcol>
<c>a2</c>
<c>r%20b</c>
<c>a3</c>
<c>2q</c>
<c>a3</c>
<c>a</c>
<c>b5</c>
<c>%3D%253D</c>
<c>c%40</c>
<c></c>
<c>c2</c>
<c></c>
</texttable>
<texttable>
<preamble>
Concatenated Pairs:
</preamble>
<ttcol align='center'>Name=Value</ttcol>
<c>a2=r%20b</c>
<c>a3=2q</c>
<c>a3=a</c>
<c>b5=%3D%253D</c>
<c>c%40=</c>
<c>c2=</c>
</texttable>
<figure>
<preamble>
And concatenated together into a single string:
</preamble>
<artwork>
a2=r%20b&a3=2q&a3=a&b5=%3D%253D&c%40=&c2=
</artwork>
</figure>
</section>
<section title="Construct Base String URI" anchor="sig_uri">
<t>
The signature base string incorporates the scheme, authority, and path of the request
URI as defined by <xref target="RFC3986" /> section 3. The request URI query component
is included through the <xref target="sig_norm_param">normalized parameters string</xref>,
and the fragment component is excluded.
</t>
<t>
This is done by constructing a base string URI representing the request without the query
or fragment components. The base string URI is constructed as follows:
<list style="numbers">
<t>
The scheme and host MUST be in lowercase.
</t>
<t>
The host and port values MUST match the content of the HTTP request
<spanx style="verb">Host</spanx> header, if present. If the
<spanx style="verb">Host</spanx> header is not present, the client MUST use the
hostname and port used to make the request. Servers SHOULD remove potential
ambiguity in such cases by specifying the expected host value.
</t>
<t>
The port MUST be included if it is not the default port for the scheme, and MUST
be excluded if it is the default. Specifically, the port MUST be excluded when an
<spanx style="verb">http</spanx> request uses port 80 or when an
<spanx style="verb">https</spanx> request uses port 443. All other non-default
port numbers MUST be included.
</t>
<t>
If the URI includes an empty path, it MUST be included as <spanx style="verb">/</spanx>.
</t>
</list>
</t>
<t>
For example:
</t>
<texttable>
<ttcol align='left'>The request URI</ttcol>
<ttcol align='left'>Is included in base string as</ttcol>
<c>HTTP://EXAMPLE.com:80/r/x?id=123</c>
<c>http://example.com/r/x</c>
<c>https://example.net:8080?q=1#top</c>
<c>https://example.net:8080/</c>
</texttable>
</section>
<section title="Concatenate Base String Elements" anchor="base_string">
<t>
Finally, the signature base string is put together by concatenating its elements
together. The elements MUST be concatenated in the following order:
<list style="numbers">
<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. If the
request uses a custom HTTP method, it MUST be <xref target="encoding">encoded</xref>.
</t>
<t>
An <spanx style="verb">&</spanx> character (ASCII code 38).
</t>
<t>
The base string URI from <xref target="sig_uri" />, after being
<xref target="encoding">encoded</xref>.
</t>
<t>
An <spanx style="verb">&</spanx> character (ASCII code 38).
</t>
<t>
The normalized request parameters string from <xref target="sig_norm_param" />,
after being <xref target="encoding">encoded</xref>.
</t>
</list>
</t>
</section>
</section>
<section title="HMAC-SHA1">
<t>
The <spanx style="verb">HMAC-SHA1</spanx> signature method uses the HMAC-SHA1 signature
algorithm as defined in <xref target="RFC2104" />:
<figure>
<artwork>
digest = HMAC-SHA1 (key, text)
</artwork>
</figure>
</t>
<t>
The HMAC-SHA1 function variables are used in following way:
<list style="hanging" hangIndent="6">
<t hangText="text">
<vspace />
is set to the value of the signature base string from <xref target="base_string" />.
</t>
<t hangText="key">
<vspace />
is set to the concatenated values of:
<list style="numbers">
<t>
The client shared-secret, after being <xref target="encoding">encoded</xref>.
</t>
<t>
An <spanx style="verb">&</spanx> character (ASCII code 38), which MUST be
included even when either secret is empty.
</t>
<t>
The token shared-secret, after being <xref target="encoding">encoded</xref>.
</t>
</list>
</t>
<t hangText="digest">
<vspace />
is used to set the value of the <spanx style="verb">oauth_signature</spanx>
protocol parameter, after the result octet string is base64-encoded per
<xref target="RFC2045" /> section 6.8.
</t>
</list>
</t>
</section>
<section title="RSA-SHA1">
<t>
The <spanx style="verb">RSA-SHA1</spanx> signature method uses the RSASSA-PKCS1-v1_5
signature algorithm as defined in <xref target="RFC3447" /> section 8.2 (also known as
PKCS#1), using SHA-1 as the hash function for EMSA-PKCS1-v1_5. To use this method, the
client MUST have established client credentials with the server which included its RSA
public key (in a manner which is beyond the scope of this specification).
</t>
<t>
The signature base string is signed using the client's RSA private key per
<xref target="RFC3447" /> section 8.2.1:
<figure>
<artwork>
S = RSASSA-PKCS1-V1_5-SIGN (K, M)
</artwork>
</figure>
Where:
<list style="hanging" hangIndent="6">
<t hangText="K">
<vspace />
is set to the client's RSA private key,
</t>
<t hangText="M">
<vspace />
is set to the value of the signature base string from <xref target="base_string" />, and
</t>
<t hangText="S">
<vspace />
is the result signature used to set the value of the <spanx style="verb">oauth_signature</spanx>
protocol parameter, after the result octet string is base64-encoded per <xref target="RFC2045" />
section 6.8.
</t>
</list>
</t>
<t>
The server verifies the signature per <xref target="RFC3447" /> section 8.2.2:
<figure>
<artwork>
RSASSA-PKCS1-V1_5-VERIFY ((n, e), M, S)
</artwork>
</figure>
Where:
<list style="hanging" hangIndent="6">
<t hangText="(n, e)">
<vspace />
is set to the client's RSA public key,
</t>
<t hangText="M">
<vspace />
is set to the value of the signature base string from <xref target="base_string" />, and
</t>
<t hangText="S">
<vspace />
is set to the octet string value of the <spanx style="verb">oauth_signature</spanx>
protocol parameter received from the client.
</t>
</list>
</t>
</section>
<section title="PLAINTEXT">
<t>
The <spanx style="verb">PLAINTEXT</spanx> method does not employ a signature algorithm
and does not provide any security as it transmits secrets in the clear. It SHOULD only
be used with a transport-layer mechanisms such as TLS or SSL. It does not use the
signature base string.
</t>
<t>
The <spanx style="verb">oauth_signature</spanx> protocol parameter is set to the
concatenated value of:
<list style="numbers">
<t>
The client shared-secret, after being <xref target="encoding">encoded</xref>.
</t>
<t>
An <spanx style="verb">&</spanx> character (ASCII code 38), which MUST be
included even when either secret is empty.
</t>
<t>
The token shared-secret, after being <xref target="encoding">encoded</xref>.
</t>
</list>
</t>
</section>
</section>
<section title="Parameter Transmission" anchor="param_include">
<t>
When making an OAuth-authenticated request, protocol parameters SHALL be included in
the request using one and only one of the following locations, listed in order of
decreasing preference:
<list style="numbers">
<t>
The HTTP <spanx style="verb">Authorization</spanx> header as described in
<xref target="auth_header" />.
</t>
<t>
The HTTP request entity-body as described in <xref target="auth_body" />.
</t>
<t>
The HTTP request URI query as described in <xref target="auth_query" />.
</t>
</list>
</t>
<t>
In addition to these three methods, future extensions may provide other methods for
including protocol parameters in the request.
</t>
<section title="Authorization Header" anchor="auth_header">
<t>
Protocol parameters can be transmitted using the HTTP
<spanx style="verb">Authorization</spanx> header as defined by <xref target="RFC2617" />
with the auth-scheme name set to <spanx style="verb">OAuth</spanx> (case-insensitive).
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork>
Authorization: OAuth realm="http://server.example.com/",
oauth_consumer_key="0685bd9184jfhq22",
oauth_token="ad180jjd733klru7",
oauth_signature_method="HMAC-SHA1",
oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
oauth_timestamp="137131200",
oauth_nonce="4572616e48616d6d65724c61686176",
oauth_version="1.0"
</artwork>
</figure>
<t>
Protocol parameters SHALL be included in the <spanx style="verb">Authorization</spanx>
header as follows:
<list style="numbers">
<t>
Parameter names and values are encoded per
<xref target="encoding">Parameter Encoding</xref>.
</t>
<t>
Each parameter's name is immediately followed by an <spanx style="verb">=</spanx>
character (ASCII code 61), a <spanx style="verb">"</spanx> character (ASCII code 34),
the parameter value (MAY be empty), and another <spanx style="verb">"</spanx> character
(ASCII code 34).
</t>
<t>
Parameters are separated by a <spanx style="verb">,</spanx> character (ASCII code 44)
and OPTIONAL linear whitespace per <xref target="RFC2617" />.
</t>
<t>
The OPTIONAL <spanx style="verb">realm</spanx> parameter MAY be added and
interpreted per <xref target="RFC2617" />, section 1.2.
</t>
</list>
</t>
<t>
Servers MAY indicate their support for the <spanx style="verb">OAuth</spanx>
auth-scheme by returning the HTTP <spanx style="verb">WWW-Authenticate</spanx>
response header upon client requests for protected resources. As per
<xref target="RFC2617" /> such a response MAY include additional HTTP
<spanx style="verb">WWW-Authenticate</spanx> headers:
</t>
<figure>
<preamble>
For example:
</preamble>
<artwork>
WWW-Authenticate: OAuth realm="http://server.example.com/"
</artwork>
</figure>
<t>
The realm parameter defines a protection realm per <xref target="RFC2617" />,
section 1.2.
</t>
</section>
<section title="Form-Encoded Body" anchor="auth_body">
<t>
Protocol parameters can be transmitted in the HTTP request entity-body, but 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 set to <spanx style="verb">application/x-www-form-urlencoded</spanx>.
</t>
</list>
<figure>
<preamble>
For example (line breaks are for display purposes only):
</preamble>
<artwork>
oauth_consumer_key=0685bd9184jfhq22&oauth_token=ad180jjd733klr
u7&oauth_signature_method=HMAC-SHA1&oauth_signature=wOJIO9A2W5
mFwDgiDvZbTSMK%2FPY%3D&oauth_timestamp=137131200&oauth_nonce=4
572616e48616d6d65724c61686176&oauth_version=1.0
</artwork>
</figure>
The entity-body MAY include other request-specific parameters, in which case, the
protocol parameters SHOULD be appended following the request-specific parameters,
properly separated by an <spanx style="verb">&</spanx> character (ASCII code 38).
</t>
</section>
<section title="Request URI Query" anchor="auth_query">
<t>
Protocol parameters can be transmitted by being added to the HTTP request URI as a
query parameter as defined by <xref target="RFC3986" /> section 3.
<figure>
<preamble>
For example (line breaks are for display purposes only):
</preamble>
<artwork>
GET /example/path?oauth_consumer_key=0685bd9184jfhq22&
oauth_token=ad180jjd733klru7&oauth_signature_method=HM
AC-SHA1&oauth_signature=wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%
3D&oauth_timestamp=137131200&oauth_nonce=4572616e48616
d6d65724c61686176&oauth_version=1.0 HTTP/1.1
</artwork>
</figure>
The request URI MAY include other request-specific query parameters, in which case,
the protocol parameters SHOULD be appended following the request-specific parameters,
properly separated by an <spanx style="verb">&</spanx> character (ASCII code 38).
</t>
</section>
</section>
<section title="Server Response" anchor="auth_response">
<t>
Servers receiving an authenticated request MUST:
<list style="symbols">
<t>
Recalculate the request signature independently and compare it to the value
received from the client.
</t>
<t>
Ensure that the nonce / timestamp / token combination has not been used before, and
MAY reject requests with stale timestamps.
</t>
<t>
If a token is present, verify the scope and status of the client authorization by
using the token, and MAY choose to restrict token usage to the client to which it
was issued.
</t>
<t>
Ensure that the protocol version used is <spanx style="verb">1.0</spanx>.
</t>
</list>
If the request fails verification, the server SHOULD respond with the appropriate HTTP
response status code. The server MAY include further details about why the request was
rejected in the response body. The following status codes SHOULD be used:
<list style="symbols">
<t>
400 (Bad Request)
<list style="symbols">
<t>
Unsupported parameters
</t>
<t>
Unsupported signature method
</t>
<t>
Missing parameters
</t>
<t>
Duplicated protocol parameters
</t>
</list>
</t>
<t>
401 (Unauthorized)
<list style="symbols">
<t>
Invalid client credentials
</t>
<t>
Invalid or expired token
</t>
<t>
Invalid signature
</t>
<t>
Invalid or used nonce
</t>
</list>
</t>
</list>
</t>
</section>
<section title="Percent Encoding" anchor="encoding">
<t>
OAuth uses the following percent-encoding rules:
<list style="numbers">
<t>
Text values are first encoded as UTF-8 octets per <xref target="RFC3629" /> if they are
not already. This does not include binary values which are not intended for human
consumption.
</t>
<t>
The values are then escaped using the <xref target="RFC3986" /> percent-encoding
(%XX) mechanism as follows:
<list style="symbols">
<t>
Characters in the unreserved character set as defined by <xref target="RFC3986" />
section 2.3 (ALPHA, DIGIT, "-", ".", "_", "~") MUST NOT be encoded.
</t>
<t>
All other characters MUST be encoded.
</t>
<t>
The two hexadecimal characters use to represent encoded characters MUST be
upper case.
</t>
</list>
</t>
</list>
</t>
</section>
<section title="IANA Considerations" anchor="IANA">
<t>
This memo includes no request to IANA.
</t>
</section>
<section title="Security Considerations" anchor="Security">
<t>
As stated in <xref target="RFC2617" />, the greatest sources of risks are usually found not
in the core protocol itself but in policies and procedures surrounding its use. Implementers
are strongly encouraged to assess how this protocol addresses their security requirements.
</t>
<section title="RSA-SHA1 Signature Method">
<t>
When used with <spanx style="verb">RSA-SHA1</spanx> signatures, the
OAuth protocol does not use the token shared-secret, or any provisioned client
shared-secret. This means the protocol relies completely on the secrecy of the private
key used by the client to sign requests.
</t>
</section>
<section title="PLAINTEXT Signature Method">
<t>
When used with the <spanx style="verb">PLAINTEXT</spanx> method, the protocol makes no
attempts to protect credentials from eavesdroppers or man-in-the-middle attacks. The
<spanx style="verb">PLAINTEXT</spanx> method is only intended to be used in conjunction
with a transport-layer security mechanism such as TLS or SSL which does provide such
protection.
</t>
</section>
<section title="Confidentiality of Requests">
<t>
While OAuth provides a mechanism for verifying the integrity of requests, it provides no
guarantee of request confidentiality. Unless further precautions are taken, eavesdroppers
will have full access to request content. Servers should carefully consider the kinds of
data likely to be sent as part of such requests, and should employ transport-layer
security mechanisms to protect sensitive resources.
</t>
</section>
<section title="Spoofing by Counterfeit Servers">
<t>
OAuth makes no attempt to verify the authenticity of the server. A hostile party could
take advantage of this by intercepting the client's requests and returning misleading or
otherwise incorrect responses. Service providers should consider such attacks when
developing services based on OAuth, and should require transport-layer security for any
requests where the authenticity of the server or of request responses is an issue.
</t>
</section>
<section title="Proxying and Caching of Authenticated Content">
<t>
The <xref target="auth_header">HTTP Authorization scheme</xref> is optional. However,
<xref target="RFC2616" /> relies on the <spanx style="verb">Authorization</spanx> and
<spanx style="verb">WWW-Authenticate</spanx> headers to distinguish authenticated content
so that it can be protected. Proxies and caches, in particular, may fail to adequately
protect requests not using these headers.
</t>
<t>
For example, private authenticated content may be stored in (and thus retrievable from)
publicly-accessible caches. Servers not using the
<xref target="auth_header">HTTP Authorization header</xref> should take care to use other
mechanisms, such as the <spanx style="verb">Cache-Control</spanx> header, to ensure that
authenticated content is protected.
</t>
</section>
<section title="Plaintext Storage of Credentials">
<t>
The client shared-secret and token shared-secret function the same way passwords do in
traditional authentication systems. In order to compute the signatures used in methods
other than <spanx style="verb">RSA-SHA1</spanx>, the server must have access to these
secrets in plaintext form. This is in contrast, for example, to modern operating systems,
which store only a one-way hash of user credentials.
</t>
<t>
If an attacker were to gain access to these secrets - or worse, to the server's database
of all such secrets - he or she would be able to perform any action on behalf of any
resource owner. Accordingly, it is critical that servers protect these secrets from
unauthorized access.
</t>
</section>
<section title="Secrecy of the Client Credentials" anchor="client_cred_sec">
<t>
In many cases, the client application will be under the control of potentially untrusted
parties. For example, if the client is a freely available desktop application, an
attacker may be able to download a copy for analysis. In such cases, attackers will be
able to recover the client credentials.
</t>
<t>
Accordingly, servers should not use the client credentials alone to verify the identity
of the client. Where possible, other factors such as IP address should be used as well.
</t>
</section>
<section title="Cryptographic Attacks">
<t>
SHA-1, the hash algorithm used in <spanx style="verb">HMAC-SHA1</spanx> signatures, has
been <xref target="SHA1-CHARACTERISTICS">shown</xref> to have a number of cryptographic
weaknesses that significantly reduce its resistance to collision attacks. Practically
speaking, these weaknesses are difficult to exploit, and by themselves do not pose a
significant risk to users of OAuth. They may, however, make more efficient attacks
possible, and NIST has <xref target="SHA-COMMENTS">announced</xref> that it will phase
out use of SHA-1 by 2010. Servers should take this into account when considering whether
SHA-1 provides an adequate level of security for their applications.
</t>
</section>
<section title="Signature Base String Limitations">
<t>
The signature base string has been designed to support the signature methods defined in
this specification. When designing additional signature methods, the signature base
string should be evaluated to ensure compatibility with the algorithms used.
</t>
<t>
Since the signature base string does not cover the entire HTTP request, such as most
request entity-body, most entity-headers, and the order in which parameters are sent,
servers should employ additional mechanisms to protect such elements.
</t>
</section>
</section>
<appendix title="Examples">
<t>
[[ TODO ]]
</t>
</appendix>
<appendix title="Acknowledgments">
<t>
This specification is directly based on the <xref target="OAuth Core 1.0 Revision A" /> community
specification which was the product of the OAuth community. OAuth was modeled after
existing proprietary protocols and best practices that have been independently implemented
by various web sites. This specification was orignially authored by: Mark Atwood,
Dirk Balfanz, Darren Bounds, Richard M. Conlan, Blaine Cook, Leah Culver, Breno de Medeiros,
Brian Eaton, Kellan Elliott-McCrea, Larry Halff, Eran Hammer-Lahav, Ben Laurie, Chris Messina,
John Panzer, Sam Quigley, David Recordon, Eran Sandler, Jonathan Sergent, Todd Sieling,
Brian Slesinsky, and Andy Smith.
</t>
</appendix>
<appendix title="Document History">
<t>
[[ To be removed by the RFC editor before publication as an RFC. ]]
</t>
<t>
-01
<list style="symbols">
<t>
Moved all subsection from section 3 to the document root.
</t>
<t>
Synced acknoledgments section with web-delegation draft.
</t>
</list>
</t>
<t>
-00
<list style="symbols">
<t>
Transitioned from the individual submission draft-hammer-oauth-02 to working group draft.
</t>
<t>
Split draft-hammer-oauth-02 into two drafts, one dealing with authentication (this draft)
and another dealing with web delegation draft-ietf-oauth-web-delegation.
</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.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"?>
<reference anchor="draft-ietf-oauth-web-delegation">
<front>
<title>The OAuth Protocol: Web Delegation</title>
<author initials="E" surname="Hammer-Lahav" fullname="Eran Hammer-Lahav" role="editor">
<organization>
Yahoo!
</organization>
<address>
<email>eran@hueniverse.com</email>
<uri>http://hueniverse.com</uri>
</address>
</author>
</front>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-oauth-web-delegation-01.txt" />
</reference>
</references>
<references title="Informative References">
<reference anchor="OAuth Core 1.0 Revision A">
<front>
<title>OAuth Core 1.0</title>
<author initials="OCW" surname="OAuth" fullname="OAuth Core Workgroup">
<organization />
</author>
</front>
<format type="HTML" target="http://oauth.net/core/1.0a" />
</reference>
<reference anchor="SHA1-CHARACTERISTICS">
<front>
<title>Finding SHA-1 Characteristics: General Results and Applications</title>
<author initials="C.DC" surname="De Canniere" fullname="Christophe De Canniere">
<organization />
</author>
<author initials="C.R" surname="Rechberger" fullname="Christian Rechberger">
<organization />
</author>
</front>
<format type="HTML" target="http://dx.doi.org/10.1007/11935230_1" />
</reference>
<reference anchor="SHA-COMMENTS">
<front>
<title>NIST Brief Comments on Recent Cryptanalytic Attacks on Secure Hashing Functions and the Continued Security Provided by SHA-1, August, 2004.</title>
<author initials="NIST" surname="National Institute of Standards and Technology" fullname="National Institute of Standards and Technolog">
<organization />
</author>
</front>
<format type="PDF" target="http://csrc.nist.gov/hash_standards_comments.pdf" />
</reference>
</references>
</back>
</rfc>| PAFTECH AB 2003-2026 | 2026-04-22 22:43:40 |