identity 1.0 documentation

HTTP Authentication: MAC Access Authentication

«  OAuth 2.0 Multiple Response Type Encoding Practices   ::   Contents   ::   OAuth Dynamic Client Registration Protocol  »

HTTP Authentication: MAC Access Authentication

Based on http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01 ( February 8, 2012 )

Abstract

This document specifies the HTTP MAC access authentication scheme, an HTTP authentication method using a message authentication code (MAC) algorithm to provide cryptographic verification of portions of HTTP requests. The document also defines an OAuth 2.0 binding for use as an access-token type.

(Draft 01, http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01)

1. Introduction

This specification defines the HTTP MAC access authentication scheme, providing a method for making authenticated HTTP requests with partial cryptographic verification of the request, covering the HTTP method, request URI, and host.

Similar to the HTTP Basic access authentication scheme [RFC2617], the MAC scheme utilizes a set of client credentials which include an identifier and key. However, in contrast with the Basic scheme, the key is never included in authenticated requests but is used to calculate the request MAC value which is included instead.

The MAC scheme requires the establishment of a shared symmetric key between the client and the server. This specification offers one such method for issuing a set of MAC credentials to the client using OAuth 2.0 in the form of a MAC-type access token.

The primary design goal of this mechanism is to simplify and improve HTTP authentication for services that are unwilling or unable to employ TLS for every request. In particular, this mechanism leverage an initial TLS setup phase to establish a shared secret between the client and the server. The shared secret is then used over an insecure channel to provide protection against a passive network attacker.

In particular, when a server uses this mechanism, a passive network attacker will be unable to “steal” the user’s session token, as is possible today with cookies and other bearer tokens. In addition, this mechanism helps secure the session token against leakage when sent over a secure channel to the wrong server. For example, when the client uses some form of dynamic configuration to determine where to send an authenticated request, or when the client fails to properly validate the server’s identity as part of its TLS handshake.

Unlike the HTTP Digest authentication scheme, this mechanism does not require interacting with the server to prevent replay attacks. Instead, the client provides both a nonce and a timestamp, which the server can use to prevent replay attacks using a bounded amount of storage. Also unlike Digest, this mechanism is not intended to protect the user’s password itself because the client and server both have access to the key material in the clear. Instead, servers should issue a short-lived derivative credential for this mechanism during the initial TLS setup phase.

http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01#section-1

Note

  • TLS/SSL is required only when “token” is exchanged.
  • nonce and timestamp prevent replay attacks

1.1. Example

The client attempts to access a protected resource without authentication, making the following HTTP request to the resource server:

GET /resource/1?b=1&a=2 HTTP/1.1
Host: example.com

The resource server returns the following authentication challenge:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: MAC

The client has previously obtained a set of MAC credentials for accessing resources on the “http://example.com/” server. The MAC credentials issued to the client include the following attributes:

MAC key identifier:  h480djs93hd8
MAC key:  489dks293j39
MAC algorithm:  hmac-sha-1

The client constructs the authentication header by calculating a timestamp (e.g. the number of seconds since January 1, 1970 00:00:00 GMT) and generating a random string used as a nonce:

Timestamp:  1336363200
Nonce:  dj83hs9s

The client constructs the normalized request string (the new line separator character is represented by “n” for display purposes only; the trailing new line separator signify that no extension value is included with the request, explained below):

1336363200\n
dj83hs9s\n
GET\n
/resource/1?b=1&a=2\n
example.com\n
80\n
\n

The request MAC is calculated using the specified MAC algorithm “hmac-sha-1” and the MAC key over the normalized request string. The result is base64-encoded to produce the request MAC:

bhCQXTVyfj5cmA9uKkPFx1zeOXM=

The client includes the MAC key identifier, nonce, and request MAC with the request using the “Authorization” request header field:

GET /resource/1?b=1&a=2 HTTP/1.1
Host: example.com
Authorization: MAC id="h480djs93hd8",
                   ts="1336363200",
                   nonce="dj83hs9s",
                   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="

The server validates the request by calculating the request MAC again based on the request received and verifies the validity and scope of the MAC credentials. If valid, the server responds with the requested resource representation.

(Draft 01 , http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01#section-1.1)

1.2. Notational Conventions

The key words ‘MUST’, ‘MUST NOT’, ‘REQUIRED’, ‘SHALL’, ‘SHALL NOT’, ‘SHOULD’, ‘SHOULD NOT’, ‘RECOMMENDED’, ‘MAY’, and ‘OPTIONAL’ in this specification are to be interpreted as described in [RFC2119].

This specification uses the Augmented Backus-Naur Form (ABNF) notation of [I-D.ietf-httpbis-p1-messaging]. Additionally, the following rules are included from [RFC2617]: auth-param.

(draft 01)

5. Use with OAuth 2.0

OAuth 2.0 ([I-D.ietf-oauth-v2]) defines an extensible token-based authentication framework. The MAC authentication scheme can be used to make OAuth-based requests by issuing MAC-type access tokens.

This specification does not define methods for the client to specifically request a MAC-type token from the authorization server. Additionally, it does not include any discovery facilities for identifying which HMAC algorithms are supported by a resource server, or how the client may go about obtaining MAC access tokens for any given protected resource.

(Draft 01, http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01#section-5 )

5.1. Issuing MAC-Type Access Tokens

Authorization servers issuing MAC-type access tokens MUST include the following parameters whenever a response includes the “access_token” parameter:

access_token
REQUIRED. The MAC key identifier.
mac_key
REQUIRED. The MAC key.
mac_algorithm

REQUIRED.

The MAC algorithm used to calculate the request MAC. Value MUST be one of “hmac-sha-1”, “hmac-sha-256”, or a registered extension algorithm name as described in Section 7.1.

For example:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token":"SlAV32hkKG",
  "token_type":"mac",
  "expires_in":3600,
  "refresh_token":"8xLOxBtZp8",
  "mac_key":"adijq39jdlaska9asud",
  "mac_algorithm":"hmac-sha-256"
}

(Draft 01, http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01#section-5.1 )

«  OAuth 2.0 Multiple Response Type Encoding Practices   ::   Contents   ::   OAuth Dynamic Client Registration Protocol  »