HTTP Authentication: Token Access Authentication
Yahoo!
eran@hueniverse.comhttp://hueniverse.com
This document specifies the HTTP Token Access Authentication scheme.
[[ This draft is submitted for the consideration of the OAuth Working Group to be adopted as
an official working group item per its current charter. It is presented in its raw form to
assist in facilitating a more effective working group conversation and should not be
considered a complete proposal. Please discuss this draft on the
oauth@ietf.org mailing
list. ]]
With the growing use of distributed web services and cloud computing, clients need to allow
other parties access to the resources they control. When granting access, clients should
not be required to share their credentials (typically a username and password), and should
have the ability to restrict access to a limited subset of the resources they control or
the access methods supported by these resources. These goals require new classes of
authentication credentials.
The HTTP Basic and Digest Access authentication schemes defined by ,
enable clients to make authenticated HTTP requests by using a username (or userid) and
a password. In most cases, the client uses a single set of credentials to access all the
resources it controls which are hosted by the server.
While the Basic and Digest schemes can be used to send credentials other than a username
and password, their wide deployment and well-established behavior in user-agents preclude
them from being used with other classes of credentials. Extending these schemes to support
new classes would require impractical changes to their existing deployment.
The Token Access Authentication scheme provides a method for making authenticated HTTP
requests using a token - an identifier used to denote an access grant with specific scope,
duration, cryptographic properties, and other attributes. Tokens can issued by the server,
self-issued by the client, or issued by a third party.
The token scheme support an extensible set of credential classes, by enabling the server to
declare the classes it supports. Token classes determine how tokens are obtained and the
context in which they can be used. It also supports an extensible set of authentication
methods and authentication coverage (the elements of the HTTP request such as the request
URI or entity-body included in the authentication process).
This specification defines four token authentication methods to support the most common use
cases and describes their security properties. The methods through which clients obtain
tokens supporting these methods are beyond the scope of this specification. The OAuth
protocol defines one such set of methods
for obtaining oauth-class token credentials.
An HTTP client (per ) capable of making
Token-authenticated requests.
An HTTP server (per ) capable of accepting
Token-authenticated requests.
An access-restricted resource (per ) hosted by the server
and accessible by making a Token-authenticated request.
A set of a unique identifier (token) and an authentication method with an OPTIONAL
shared secret (symmetric or asymmetric), as well as other attributes (e.g. class,
duration, scope), used by the client to make authenticated
requests.
A string representing various elements of the HTTP request, normalized and
concatenated together. The elements included in the normalize request string are
determined by the authentication coverage supported by the server.
This means the server is expecting an oauth class token using
either the hmac-sha-1 or hmac-sha-256
authentication methods. It also provides its current time to assist the client in
synchronizing its clock with the server's clock for the purpose of producing a unique
nonce value.
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
.
This document uses the Augmented Backus-Naur Form (ABNF) notation of
. Additionally, the following rules are
included from : realm, auth-param.
The client makes authenticated requests by calculating the values of a set of attributes
and adding them to the HTTP request using the Authorization header field.
Authenticated request can be sent either directly (without first receiving a challenge), or
in response to an authentication challenge.
To make an authenticated request, the client obtains information about the attributes
supported by the server. This information is provided by the server via the
WWW-Authenticate header field. The client SHOULD only send an
authenticated request to the server (without first receiving a challenge) if it has prior
knowledge of the attributes supported by server.
The client chooses an available token with the supported class and authentication method.
It also chooses a supported authentication coverage. The methods through which the client
obtains a valid token, or the criteria used to choose a token if more than one is available
are beyond the scope of this specification.
Once the client selects the appropriate token credentials it proceeds to:
Assign values based on its selection to the following attributes:
tokenclassmethodcoverage
If the client uses a coverage method other than none it
MUST assign values to the following attributes:
noncetimestamp
Assigns value to any additional class-specific, method-specific, or coverage-specific
attributes as defined by protocol extensions.
If the client uses a coverage method other than none it
constructs the normalized request string based on the selected coverage as described in
.
Calculates the value of the auth attribute as defined by
the selected authentication method.
Adds the assigned attributes to the request via the
Authorization header field.
Sends the authenticated HTTP request to the server.
A servers receiving an authenticated request validates it by performing the following
REQUIRED steps:
Verify that the token used by the client as well as the coverage method matches the
server's requirements.
If the client used a coverage method other than none,
construct the normalized request string based on the selected coverage as described in
.
If the client used an authentication method other than none,
recalculate the value of the auth attribute as described in
and compare it to the value received from the client via
the auth attribute.
If the client used a coverage method other than none,
ensure that the combination of nonce, timestamp, and token received from the client has
not been used before in a previous request (the server MAY reject requests with stale
timestamps; the determination of staleness is left up to the server to define).
Verify the scope and status of the client credentials as represented by the token.
If the request fails verification, the server SHOULD respond with an HTTP 401 (unauthorized)
status code, and SHOULD include a token scheme authentication challenge using the
WWW-Authenticate header field. The server MAY include
further details about why the request was rejected using the
Authorization-Error header field.
A server receiving a request for a protected resource without a valid
Authorization header field MUST respond with a 401
status code (Unauthorized), and includes at least one
WWW-Authenticate header field including a token scheme
challenge.
The WWW-Authenticate header field uses the framework defined by
as follows:
The name of the token class supported by the server. Servers MAY support multiple classes
per protected resource by providing multiple challenges, each with a different class.
The list of authentication method names supported by the server, provided as a
space-delimited list. Authentication methods are described in .
The list of authentication coverage names supported by the server, provided as a
space-delimited list. If omitted, the attribute defaults to base.
Authentication coverage is described in .
Signature-based and hash-based authentication methods use timestamps in combination with
unique nonce values to protect against replay attacks when used over an unsecure channel.
The timestamp attribute is used by the server to publish its current time, enabling
clients to synchronize their close with the server. 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.
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. Servers applying such a restriction SHOULD provide their current time to the
client either in every challenge or when a request fails due to a timestamp outside the
allowed window.
A client making a request for a protected resource either directly, or in retrying a
request after receiving a 401 status code (Unauthorized) with a token challenge, MUST
include at least one Authorization header field including
token scheme credentials.
The Authorization header field uses the framework defined by
as follows:
The value used to identify the set of token credentials used by the client to
authenticate. The token identifier can be an opaque string or use a well-defined internal
structure, which is determined by the token class.
The name of the token class used by the client to make the request.
The name of the authentication method used by the client to make the request.
The name of the authentication coverage method used by the client to make the request.
If the attribute is omitted, its value defaults to base.
A random string, uniquely generated by the client to allow 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 and token combinations.
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.
The output of the authentication method function after applying it to the selected
coverage as described in .
A server receiving a request for a protected resource with an invalid
Authorization header field MAY includes the
Authentication-Error header field providing the client with
information to help it successfully authenticate with the server.
The Authentication-Error header field is defined as follows:
In order for the server to verify the authenticity of the request and prevent unauthorized
access, the client must prove it is the rightful owner of the credentials. This is
accomplished using the authentication method associated with the token.
This specification provides three methods for the client to prove its rightful ownership of
the credentials: hmac-sha-1, hmac-sha-256,
and rsassa-pkcs1-v1.5-sha-256. In addition, the
none method is defined to allow the use of bearer token which
does not utilizes any cryptographic means.
The authentication process does not change the request or its parameters, with the exception
of the auth attribute.
The none method does not employ a cryptographic algorithm
and does not provide any security on its own. Servers utilizing this method use the token
identifier as a bearer token, relying solely on the value of the token identifier to
authenticate the client.
The nonce, timestamp, and
auth attributes are not used, and SHOULD NOT be included in
authenticated requests. The coverage attribute MUST be set to
none but MAY be omitted from the request. Nevertheless, these
attributes MUST be included in the normalized request string together with any other
authentication attributes.
The hmac-sha-1 authentication method uses the HMAC-SHA1
algorithm as defined in :
The HMAC-SHA1 function variables are used in following way:
is set to the value of the normalize request string as described in
.
is set to the shared-secret associated with the token.
is used to set the value of the auth
attribute, after the result octet string is base64-encoded per
section 6.8.
The hmac-sha-256 authentication method uses the HMAC
algorithm as defined in together with the SHA-256 hash
function defined in :
The HMAC-SHA256 function variables are used in following way:
is set to the value of the normalize request string as described in
.
is set to the shared-secret associated with the token.
is used to set the value of the auth
attribute, after the result octet string is base64-encoded per
section 6.8.
The rsassa-pkcs1-v1.5-sha-256 signature method uses the
RSASSA-PKCS1-v1_5 signature algorithm as defined in section 8.2
(also known as PKCS#1), using SHA-256 as the hash function as defined in
for EMSA-PKCS1-v1_5.
The normalized request string is signed using the RSA private key associated with the
token as defined in section 8.2.1:
Where:
is set to the RSA private key associated with the token,
is set to the value of the normalized request string described
in , and
is the result signature used to set the value of the auth
attribute, after the result octet string is base64-encoded per
section 6.8.
The server verifies the signature per section 8.2.2:
Where:
is set to the RSA public key associated with the token,
is set to the value of the normalized request string described
in , and
is set to the octet string value of the auth attribute
received from the client.
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 authentication methods with the exception of none.
When using the base method, the normalized request string
includes the following components of the HTTP request:
The HTTP request method (e.g. GET,
POST, etc.).
The authority as declared by the HTTP Host request
header.
The request resource URI.
The Authorization header field attributes, with the
exception of the auth attribute.
The base 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 server cannot verify the authenticity
of the excluded request elements without using additional protections such as SSL/TLS or
other methods.
The normalized request string is constructed by concatenating together, in order, the
following HTTP request elements:
The HTTP request method in uppercase. For example: HEAD,
GET, POST, etc.
A , character (ASCII code 44).
The hostname, colon-separated (ASCII code 58) from the TCP port used to make the
request as included in the HTTP request Host header
field. The port MUST be included even if it is not included in the
Host header field (i.e. the default port for the
scheme).
A , character (ASCII code 44).
Any authentication attribute, with the exception of the auth,
which is assigned a value (including default values), are added to the normalized
request string as follows:
The name of each parameter is concatenated to its corresponding value using an
= character (ASCII code 61) as separator, even if the
value is empty.
The name/value pairs are sorted using ascending byte value ordering.
The sorted name/value pairs are concatenated together into a single string by
using a , character (ASCII code 44) as separator.
A , character (ASCII code 44).
The request resource URI.
The base+body-hmac-sha-256 method added the request entity-body
to the elements included in the normalized request string. It does not include the
entity-body directly in the normalized string. Instead, it calculates the hash value of
the entity-body using the SHA-256 hash function defined in .
The normalized request string is constructed following the same process defined in
, with the following addition:
Before constructing the string, the entity-body hash is calculated by applying the
SHA-256 hash function on the raw entity-body content.
The hash value is added to the list of authentication attributes by assigning its
value to the body-hash attribute name. This is done
prior to the attributes being sorted and added to the string.
The body-hash attribute is only included in the
normalized request string and is not added to the
Authorization header field.
As stated in , 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.
This specification does not describe any mechanism for obtaining or transmitting raw
tokens credentials. Methods used to obtain tokens should ensure that these transmissions
are protected using transport-layer mechanisms such as TLS or SSL.
While this protocol 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.
This protocol 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 using this protocol, and should require transport-layer
security for any requests where the authenticity of the server or of request responses is
an issue.
When used with a symmetric shared-secret authentication method, the token shared-secret
function the same way passwords do in traditional authentication systems. In order to
compute the signatures used in methods, 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.
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.
By itself, this protocol does not provide any method for scoping the access rights
granted to a client. However, most applications do require greater granularity of access
rights. For example, servers may wish to make it possible to grant access to some
protected resources but not others, or to grant only limited access (such as read-only
access) to those protected resources.
When implementing this protocol, servers should consider the types of access resource
owners may wish to grant clients, and should provide mechanisms to do so. Servers should
also take care to ensure that resource owners understand the access they are granting, as
well as any risks that may be involved.
Unless a transport-layer security protocol is used, eavesdroppers will have full access
to authenticated requests and signatures, and will thus be able to mount offline brute-force
attacks to recover the credentials used. Servers should be careful to assign
shared-secrets which are long enough, and random enough, to resist such attacks for at
least the length of time that the shared-secrets are valid.
For example, if shared-secrets are valid for two weeks, servers should ensure that it is
not possible to mount a brute force attack that recovers the shared-secret in less than
two weeks. Of course, servers are urged to err on the side of caution, and use the longest
secrets reasonable.
It is equally important that the pseudo-random number generator (PRNG) used to generate
these secrets be of sufficiently high quality. Many PRNG implementations generate number
sequences that may appear to be random, but which nevertheless exhibit patterns or other
weaknesses which make cryptanalysis or brute force attacks easier. Implementers should be
careful to use cryptographically secure PRNGs to avoid these problems.
This specification includes a number of features which may make resource exhaustion
attacks against servers possible. For example, this protocol requires servers to track
used nonces. If an attacker is able to use many nonces quickly, the resources required to
track them may exhaust available capacity. And again, this protocol can require servers
to perform potentially expensive computations in order to verify the signature on
incoming requests. An attacker may exploit this to perform a denial of service attack by
sending a large number of invalid requests to the server.
Resource Exhaustion attacks are by no means specific to this specification. However,
implementers should be careful to consider the additional avenues of attack that this
protocol exposes, and design their implementations accordingly. For example, entropy
starvation typically results in either a complete denial of service while the system
waits for new entropy or else in weak (easily guessable) secrets. When implementing this
protocol, servers should consider which of these presents a more serious risk for their
application and design accordingly.
The normalized request string has been designed to support the authentication methods
defined in this specification. Those designing additional methods, should evaluated the
compatibility of the normalized request string with their security requirements.
Since the normalized request string does not cover the entire HTTP request, servers
should employ additional mechanisms to protect such elements.
The author would like to thank Richard Barnes, Breno de Medeiros, Brian Eaton, Ben Laurie,
Mark Nottingham, John Panzer, and Peter Saint-Andre for their suggestions, feedback, and
continued support.
[[ To be removed by the RFC editor before publication as an RFC. ]]
-00
Initial (incomplete) draft.
Secure Hash Standard (SHS). FIPS PUB 180-3, October 2008National Institute of Standards and Technology