+--------+                               +---------------+
     |        |--(A)- Authorization Request ->|   Resource    |
     |        |                               |     Owner     |
     |        |<-(B)-- Authorization Grant ---|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(C)-- Authorization Grant -->| Authorization |
     | Client |                               |     Server    |
     |        |<-(D)----- Access Token -------|               |
     |        |                               +---------------+
     |        |
     |        |                               +---------------+
     |        |--(E)----- Access Token ------>|    Resource   |
     |        |                               |     Server    |
     |        |<-(F)--- Protected Resource ---|               |
     +--------+                               +---------------+		  

Figure 1: Abstract OAuth 2.0 Protocol Flow

3.1. Binding a Key to an Access Token

OAuth 2.0 offers different ways to obtain an access token, namely using authorization grants and using a refresh token. The core OAuth specification defines four authorization grants, see Section 1.3 of [I-D.ietf-oauth-v2], and [I-D.ietf-oauth-assertions] adds an assertion-based authorization grant to that list.

This document extends the communication with the token endpoint. The token endpoint, which is described in Section 3.2 of [I-D.ietf-oauth-v2], is used with every authorization grant except for the implicit grant type. In the implicit grant type the access token is issued directly.

Two types of keying material can be bound to an access token, namely symmetric keys and asymmetric keys, and we explain them in separate sub-sections.

3.1.1. Symmetric Keys

In case a symmetric key shall be bound to an access token then the following procedure is applicable. In the request message from the OAuth client to the authorization server the following parameters MUST be included:

token_type:

REQUIRED. For the symmetric holder-of-the-key variant the value MUST be set to "hotk-sk".

profile:

REQUIRED. The profile parameter provides information about what mechanisms the client supports to provide proof of possession of the key towards a resource server. The value MUST be taken from the algorithm registry created in Section 5.4. Algorithm names are case-sensitive. If the client supports more than one profile then each individual value MUST be separated by a comma.

              
     POST /token HTTP/1.1
     Host: server.example.com
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
     Content-Type: application/x-www-form-urlencoded;charset=UTF-8

     grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
     &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
     &token_type=hotk-sk
     &profile=jws,mac

          

Example Request to the Authorization Server

For example, the client makes the following HTTP request using TLS (extra line breaks are for display purposes only):

If the access token request is valid and authorized, the authorization server issues an access token and optionally a refresh token. If the request client authentication failed or is invalid, the authorization server returns an error response as described in Section 5.2 of [I-D.ietf-oauth-v2].

The authorization server MUST include the following parameters in a successful response, if it supports any of the profiles listed by the client.

id:

REQUIRED. An ephemeral and unique key identifier. The authorization server MUST NOT select the same key identifier twice within the lifetime of the access token, which is indicated by the 'expires_in' parameter.

key:

REQUIRED. A fresh and unique shared symmetric secret with sufficient entrophy.

profile:

REQUIRED. The profile parameter provides further information about how the client has to provide proof of possession of the key with the resource server. The authorization server chooses a value from the list of supported mechanisms supported by the client.

For example:

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

  {
    "access_token":"SlAV.....32hkKG",
    "token_type":"hotk-sk",
    "expires_in":3600,
    "refresh_token":"8xLOxBtZp8",
    "id":"client12345@example.com", 
    "key":"adijq39jdlaska9asud",
    "profile":"jws"
  }
  
  The content of the 'access_token' MUST contain 
  the key identifier value in the 'hotk' element, 
  as shown in the example below. 
   
    {"typ":"JWT",
     "alg":"HS256"
    }
    .
    {"iss":"authorization-server-id",
     "exp":1300819380, 
     "hotk":"client12345@example.com"     
    }
    .
    bbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZC  

          

DISCUSSION: Should we put the encrypted key into the access token? This would make the mechanism more similar to a Kerberos-based scheme.

The key identifier, the key, and the profile name MUST NOT include characters other than:

          
  %x20-21 / %x23-5B / %x5D-7E
  ; Any printable ASCII character except for <"> and <\>

        

3.1.2. Asymmetric Keys

In case an asymmetric key shall be bound to an access token then the following procedure is applicable. In the request message from the OAuth client to the authorization server the following parameters MUST be included:

token_type:

REQUIRED. For the asymmetric holder-of-the-key variant the value MUST be set to "hotk-pk".

pk_info:

REQUIRED. This field contains information about the public key the client would like to bind to the access token in the JSON Web Key format. The public key is "application/x-www-form-urlencoded" encoded.

              
     POST /token HTTP/1.1
     Host: server.example.com
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
     Content-Type: application/x-www-form-urlencoded;charset=UTF-8

     grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
     &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
     &token_type=hotk-pk
     &pk_info=eZQQYbYS6WxS...lxlOB

   whereby the content of the pk_info field represents the following
   structure:

  {"keys":
     [
       {"alg":"RSA",
        "mod": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
   4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
   tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
   QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
   SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
   w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
        "exp":"AQAB",
        "kid":"2011-04-29"}
     ]
   }
   

Example Request to the Authorization Server

For example, the client makes the following HTTP request using TLS (extra line breaks are for display purposes only):

If the access token request is valid and authorized, the authorization server issues an access token and optionally a refresh token. If the request client authentication failed or is invalid, the authorization server returns an error response as described in Section 5.2 of [I-D.ietf-oauth-v2].

The authorization server also places information about the public key used by the client into the access token to create the binding between the two. The new token type, called 'hotk-pk', is placed into the 'token_type' parameter.

              
     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFE....jr1zCsicMWpAA",
       "token_type":"hotk-pk",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
     }   

    whereby the content of the 'access_token' field, for example, 
    contains an encoded JWT with the following raw structure:
   
    {"typ":"JWT",
     "alg":"HS256"}
    .
    {"iss":"authorization-server-id",
     "exp":1300819380, 
     "hotk": {"keys":
     [
       {"alg":"RSA",
        "mod": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
    4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
    tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
    QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
    SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
    w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
        "exp":"AQAB",
        "kid":"2011-04-29"}
     ]
    }
    }
    .
    bbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZC   
    

Example Response from the Authorization Server

An example of a successful response is shown below:

3.2. Accessing a Protected Resource

Accessing a protected resource depends on the chosen credential type.

3.2.1. Symmetric Keys

When a symmetric key was used as a holder-of-the-key then the client has to demonstrate possession of the key that corresponds to the key identifier found in the access token.

              

1) HTTP Request

     POST /request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=2+q HTTP/1.1
     Host: example.com
              
2) JWS Document
              
   {"typ":"HOTK-SK",
    "alg":"HS256",
    "kid":"client12345@example.com",
    "timestamp":"2012-07-15T10:20:00.000-05:00" }
   .
   {"request":"POST/request?b5=%3D%253D&a3=a&c%40=&a2=r%20b&c2&a3=
    2+qexample.com80"}
   . 
   dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
      

JWS Example

This specification defines three ways for providing this proof of possession, which are indicated as profiles in Section 3.1.1:

jws:

When the 'jws' profile is chosen then the client MUST compute the following string by concatenating together, in order, the following HTTP request elements:

1. The HTTP request method in upper case. For example: "HEAD", "GET", "POST", etc.
2. The HTTP request-URI as defined by Section 5.1.2 of [RFC2616].
3. The hostname included in the HTTP request using the "Host" request header field in lower case.
4. The port as included in the HTTP request using the "Host" request header field. If the header field does not include a port, the default value for the scheme MUST be used (e.g., 80 for HTTP and 443 for HTTPS).
5. The value of the "ext" "Authorization" request header field attribute if one was included in the request, otherwise, an empty string.

Each element is followed by a new line character (%x0A) including the last element and even when an element value is an empty string. The resulting value MUST be put into the "request" element of a JSON document that is then subject to JWS processing

[I-D.ietf-jose-json-web-signature]. The resulting JWS structure is put into the body of the HTTP request. A receiving authorization server MUST use the value in the 'kid' structure to identify the shared key and then use that key to verify the keyed message digest. Additionally, the content of the 'request' field needs to be verified against the HTTP header information. If any of these verification steps fail then the request to the protected resource MUST fail with a "401 Unauthorized" error message back to the OAuth client.

The following example shows and the corresponding encoding in a JWS structure:

mac:

When the 'mac' profile is chosen then the client MUST follow the description in [I-D.ietf-oauth-v2-http-mac].

3.2.2. Asymmetric Keys

The client accesses protected resources by presenting the access token to the resource server. It does so via a Transport Layer Security (TLS) secured channel. Since the client had previously bound a public key to an access token it selects this key for usage with TLS as described in [I-D.ietf-tls-oob-pubkey].

The resource server validates the access token and ensure it has not expired and that its scope covers the requested resource. Additionally, the resource server verifies that the public key presented during the TLS handshake corresponds to the public key that is contained in the access token.

Note that this step confirms that the client is in possession of the private key corresponding to the public key previously bound to the access token. Information about the client authentication may be contained in the token in case the authorization server added this information when it authenticated the client.

4. Security Considerations

4.1. Security Threats

The following list presents several common threats against protocols utilizing some form of tokens. This list of threats is based on NIST Special Publication 800-63 [NIST800-63]. We exclude a discussion of threats related to any form of registration and authentication.

Token manufacture/modification:

An attacker may craft a fake token or modify the token content (such as the authentication or attribute statements), causing a resource server to grant inappropriate access to the attacker. For example, an attacker may modify the token to extend the validity period or the scope to have extended access to information.

Token disclosure:

Tokens may contain authentication and attribute statements that include sensitive information.

Token redirect:

An attacker uses a token generated for consumption by one resource server to gain access to a different resource server that mistakenly believes the token to be for it.

Token reuse:

An attacker attempts to use a token that has already been used with that resource server in the past.

4.2. Threat Mitigation

A large range of threats can be mitigated by protecting the contents of the access token by using a digital signature or a Message Authentication Code (MAC). Consequently, the token integrity protection MUST be sufficient to prevent the token from being modified.

To deal with token redirect, it is important for the authorization server to include the identity of the intended recipients (the audience), typically a single resource server (or a list of resource servers), in the token. Restricting the use of the token to a specific scope is also RECOMMENDED.

The authorization server MUST implement and use TLS. Which version(s) ought to be implemented will vary over time, and depend on the widespread deployment and known security vulnerabilities at the time of implementation. At the time of this writing, TLS version 1.2 [RFC5246] is the most recent version. The client MUST validate the TLS certificate chain when making requests to protected resources, including checking the Certificate Revocation List (CRL) [RFC5280].

For the interaction between the client and the resource server this specification requires a TLS extension for usage with out-of-band validation [I-D.ietf-tls-oob-pubkey] to be used that allows clients to present raw public keys for asymmetric holder-of-the-key usage.

With the usage of the holder-of-the-key concept it is not possible for any party other than the legitimate client to use an access token and to re-use it without knowing the corresponding asymmetric key pair. This mechanism prevents against token disclosure.

With the usage of the asymmetric holder-of-the-key concept the following deployment consideration needs to be taken into consideration. In some deployments, including those utilizing load balancers, the TLS connection to the resource server terminates prior to the actual server that provides the resource. This could leave the token unprotected between the front end server where the TLS connection terminates and the back end server that provides the resource.

Client implementations must be carefully implemented to avoid leaking the ephemeral credentials (either the private key from the asymmetric credential or the shared secret).

Token replay is also not possible since an eavesdropper will also have to obtain the corresponding private key or shared secret that is bound to the access token. Nevertheless, it is good practice to limit the lifetime of the access token and therefore the lifetime of associated key.

4.3. Summary of Recommendations

The following three items represent the main recommendations:

Safeguard the private key/shared secret:

Client implementations MUST ensure that the ephemeral private key / shared secret is not leaked to third parties, since those will be able to use the access token together with the keying material to gain access to protected resources.

Switch keying material regularly:

Clients can at any time create a new ephemeral credential and associate it with an access token. For example, a client presents a new public key when requesting an access token with the help of a refresh token. Nevertheless, the lifetime of these access token may be longer than the lifetime of bearer tokens.

Issue scoped bearer tokens:

Token servers SHOULD issue bearer tokens that contain an audience restriction, scoping their use to the intended relying party or set of relying parties.

5. IANA Considerations

This document requires IANA to take the following actions.

5.1. OAuth Parameters Registration

This specification registers the following parameters in the OAuth Parameters Registry established by [I-D.ietf-oauth-v2].

Parameter name:

pk_info

Parameter usage location:

token request

Change controller:

IETF

Specification document(s):

[[ this document ]]

Related information:

None

Parameter name:

token_type

Parameter usage location:

token request, token response, authorization response

Change controller:

IETF

Specification document(s):

[[ this document ]]

Related information:

None

Parameter name:

profile

Parameter usage location:

token request, token response, authorization response

Change controller:

IETF

Specification document(s):

[[ this document ]]

Related information:

None

Parameter name:

id

Parameter usage location:

token response, authorization response

Change controller:

IETF

Specification document(s):

[[ this document ]]

Related information:

None

Parameter name:

key

Parameter usage location:

token response, authorization response

Change controller:

IETF

Specification document(s):

[[ this document ]]

Related information:

None

5.2. The 'hotk' JSON Web Token Claims

[I-D.ietf-oauth-json-web-token] established the IANA JSON Web Token Claims registry for reserved JWT Claim Names and this document adds the 'hotk' name to that registry.

5.3. The 'hotk' OAuth Access Token Type

Section 11.1 of [I-D.ietf-oauth-v2] defines the OAuth Access Token Type Registry and this document adds another token type to this registry.

Type name:

hotk

Additional Token Endpoint Response Parameters:

(none)

HTTP Authentication Scheme(s):

Holder of the key confirmation using TLS

Change controller:

IETF

Specification document(s):

[[ this document ]]

5.4. Profile Registry

This document asks IANA to create a registry for profiles of symmetric key-based holder-of-the-key mechanisms. The policy for adding new entries to the registry is "Specification Required". IANA is asked to populate the registry with the following values:

• Profile name: jws
• Change controller: IETF
• Specification document(s): [[ this document ]]

• Profile name: mac
• Change controller: IETF
• Specification document(s): [[ this document ]]

6. Acknowledgements

The author would like to thank the OAuth working group and participants of the Internet Identity Workshop for their discussion input that lead to this document.

7. References

7.1. Normative References

[1]	Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[2]	Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[3]	Hardt, D., "The OAuth 2.0 Authorization Framework", Internet-Draft draft-ietf-oauth-v2-31, August 2012.
[4]	Jones, M., "JSON Web Key (JWK)", Internet-Draft draft-ietf-jose-json-web-key-19, December 2013.
[5]	Wouters, P., Tschofenig, H., Gilmore, J., Weiler, S. and T. Kivinen, "Using Raw Public Keys in Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", Internet-Draft draft-ietf-tls-oob-pubkey-10, October 2013.
[6]	Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", Internet-Draft draft-ietf-oauth-json-web-token-14, December 2013.
[7]	Jones, M., Bradley, J. and N. Sakimura, "JSON Web Signature (JWS)", Internet-Draft draft-ietf-jose-json-web-signature-19, December 2013.
[8]	Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[9]	Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R. and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, May 2008.
[10]	Richer, J., Mills, W., Tschofenig, H. and P. Hunt, "OAuth 2.0 Message Authentication Code (MAC) Tokens", Internet-Draft draft-ietf-oauth-v2-http-mac-04, July 2013.

7.2. Informative References

[1]	Campbell, B., Mortimore, C., Jones, M. and Y. Goland, "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", Internet-Draft draft-ietf-oauth-assertions-13, December 2013.
[2]	Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", Internet-Draft draft-ietf-oauth-v2-bearer-23, August 2012.
[3]	Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, April 2010.
[4]	Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S. and E. Nabbus, "NIST Special Publication 800-63-1, INFORMATION SECURITY", December 2008.

Authors' Addresses