OAuth 2.0 Message Authentication Code (MAC) Tokens


OAuth 2.0 Message Authentication Code (MAC) Tokens is defined (As far as we know) only in OAuth 2.0 Message Authentication Code (MAC) Tokens draft-ietf-oauth-v2-http-mac-05.txt.

OAuth 2.0 Message Authentication Code (MAC) Tokens describes how to use MAC Tokens in HTTP requests and responses to access Protected Resources via the OAuth 2.0 protocol (RFC 6749). An OAuth Client willing to access a Protected Resource needs to demonstrate possession of a Symmetric Key by using it with a keyed message digest function to the request. The keyed message digest function is computed over a flexible set of parameters from the HTTP message.

The MAC Token mechanism requires the establishment of a shared Symmetric Key between the OAuth Client and the Resource Server. The OAuth 2.0 Message Authentication Code (MAC) Tokens specification defines a three party key distribution protocol to dynamically distribute this session key from the Authorization Server to the OAuth Client and the Resource Server.

The design goal for this mechanism is to support the requirements outlined in Appendix A. In particular, when a server uses this mechanism, a passive attacker will be unable to use an eavesdropped access token exchanged between the OAuth Client and the Resource Server. In addition, this mechanism helps secure the access token against leakage when sent over a secure channel to the wrong Resource Server if the OAuth Client provided information about the Resource Server it wants to interact with in the request to the Authorization Server.

Since a keyed message digest only provides integrity protection and data-origin authentication confidentiality protection can only be added by the usage of Transport Layer Security (TLS). This specification provides a mechanism for channel binding is included to ensure that a TLS channel is not terminated prematurely and indeed covers the entire end-to-end communication.

client Key-Exchange#

Authorization Servers issue MAC Tokens based on requests from clients. The request MUST include the audience parameter defined in OAuth 2.0 Audience Information, which indicates the Resource Server the client wants to interact with. This specification assumes use of the Authorization Code Grant. If the request is processed successfully by the Authorization Servers it MUST return at least the following parameters to the client:
  • kid - The name of the key (key id), which is an identifier generated by the Resource Server. It is RECOMMENDED that the Authorization Servers generates this key id by computing a hash over the Access Token, for example using SHA-1, and to encode it in a base64 format.
  • access_token - The OAuth 2.0 Access Token.
  • mac_key - The Session Key generated by the Authorization Servers. Note that the lifetime of the Session Key is equal to the lifetime of the Access Token.
  • mac_algorithm - The MAC algorithm used to calculate the request MAC. The value MUST be one of "hmac-sha-1", "hmac-sha-256", or a registered extension algorithm name as described in Section 9.2 which uses the OAuth Parameters Registry. The authorization server is assumed to know the set of algorithms supported by the client and the Resource Server. It selects an algorithm that meets the security policies and is supported by both nodes.

Resource Server and Authorization Server Key-Exchange#

The transport of the mac_key from the Authorization Servers to the Resource Server is accomplished by conveying the encrypting mac_key inside the Access Token. At the time of writing only one standardized format for carrying the Access Token is defined: the JSON Web Token (JWT). Note that the header of the JSON Web Encryption (JWE) structure, which is a JWT with encrypted content, MUST contain a key id (kid) in the header to allow the Resource Server to select the appropriate keying material for decryption. The keying material is a Symmetric Key or an Asymmetric Key long-term key established between the Resource Server and the Authorization Servers. The establishment of this long-term key is outside the scope of this specification.

This document defines two new claims to be carried in the JWT:

These two parameters match the content of the mac_key and the kid conveyed to the client.

More Information#

There might be more information for this subject on one of the following: