OAuth2 Signed Tokens

This document describes how to cryptographically bind an OAuth token and (parts of an) HTTP request with JSON tokens.

Summary: We include an OAuth2 Signed Token in the Authorization header of an HTTP request to ensure integrity of the transmitted request.

Token Structure

HTTP Signature tokens are JSON Tokens with the following additional fields in the payload:

Name	Value Type	Value Semantics
method	string	the HTTP method used to execute the HTTP request
nonce	string	Used to prevent replay attacks. Receivers of OAuth2 Signed Token may verify that nonces have not been previously used within a reasonable interval.
body_hash	string	(optional) The websafe-base64-encoded hash of the request body. Which hash algorithm is used depends on the signature algorithm specified in the payload.
token	string	The OAuth token.

OAuth Clients generate OAuth2 Signed Tokens. The Client must use its client id as the issuer value in the token payload. They must use the URL of the Protected Resource as the audience value in the payload.

Senders should set the token_lifetime in the token payload to a short lifetime, e.g., 1 minute.

Clients include a OAuth2 signed token into the authorization header as follows:

Authorization: Token signed_token="<the OAuth2 signed token>"

Validation of OAuth2 Signed Tokens

Receivers of OAuth2 Signed Tokens proceed as follows to validate an incoming HTTP request:

They validate the JSON Tokens as explained in the JSON Token spec.
They verify that the method in the token payload equals the method used to access the HTTP resource
They verify that the audience in the token payload matches the URI used to access the HTTP resource.
They may verify that the token nonce has not been used within the lifetime of the token.
If the body_hash field is present, they should verify that the received request body hashes to the specified value.

If all these steps succeed, then the token in the payload can be used to determine access control decisions for the protected resource.