The OAuth 2.0 Authorization Framework: Bearer Token Usage
updated by
Extracted elements (28)
Bearer tokens can either encode authorization information directly or contain a reference to it; references MUST be infeasible to guess and may require an extra server-to-issuer interaction to resolve. This document intentionally does not specify token encoding or contents.
The Bearer authentication scheme is designed primarily for server authentication using WWW-Authenticate and Authorization headers but does not preclude use for proxy authentication. It defines a general HTTP authorization method usable with bearer tokens from any source, not only OAuth.
The URI query parameter method is included solely to document current use; its use is not recommended due to security deficiencies (likely URL logging) and because it uses a reserved query parameter name contrary to URI namespace best practices per W3C Web Architecture.
The Bearer Authorization header syntax follows the Basic scheme usage from RFC 2617 Section 2 and does not conform to the generic syntax in RFC 2617 Section 1.2, though it is compatible with the HTTP/1.1 authentication framework being developed. This reflects existing deployments.
Bearer tokens MUST NOT be stored in cookies that can be sent in the clear. Implementations that do store bearer tokens in cookies MUST take precautions against cross-site request forgery.
Bearer tokens SHOULD NOT be passed in page URLs (e.g., as query string parameters). They SHOULD be passed in HTTP message headers or message bodies for which confidentiality measures are taken, to prevent leakage via browser history or server logs.
Clients MUST always use TLS (https) or equivalent transport security when making requests with bearer tokens. Client implementations MUST ensure that bearer tokens are not leaked to unintended parties.
Clients MUST NOT use more than one method to transmit the bearer token in each request. The three permitted methods are the Authorization header, form-encoded body parameter, and URI query parameter.
Clients SHOULD make authenticated requests using the Authorization request header field with the Bearer HTTP authorization scheme. Resource servers MUST support this method.
If the protected resource request does not include authentication credentials or contains an invalid access token, the resource server MUST include the HTTP WWW-Authenticate response header field using the auth-scheme value "Bearer".
If the request lacks any authentication information, the resource server SHOULD NOT include an error code or other error information in the WWW-Authenticate response.
In deployments where TLS terminates before the actual resource server (e.g., load balancers), sufficient measures MUST be employed to ensure confidentiality of the token between the front-end and back-end servers.
The authorization server MUST implement TLS. Token integrity protection MUST be sufficient to prevent modification. Confidentiality protection MUST be applied using TLS with a ciphersuite providing both confidentiality and integrity.
The client MUST NOT use the form-encoded body parameter method unless the Content-Type is application/x-www-form-urlencoded, the body is single-part ASCII, and the HTTP method is not GET.
The client MUST validate the TLS certificate chain when making requests to protected resources, including checking the CRL. The client MUST also verify the identity of the resource server per RFC 2818 Section 3.1.
The form-encoded body method SHOULD NOT be used except where participating browsers do not have access to the Authorization request header field. Resource servers MAY support this method.
The lifetime of the token MUST be limited to mitigate token capture and replay; a validity time field inside the protected part of the token is one means of achieving this. Confidentiality protection of all exchanges MUST be applied.
The URI query parameter method SHOULD NOT be used unless it is impossible to transport the token in the Authorization header or request body, due to security deficiencies including likely URL logging. Resource servers MAY support this method.
Token servers SHOULD issue bearer tokens that contain an audience restriction, scoping their use to the intended relying party or set of relying parties, to mitigate token redirect attacks.
Token servers SHOULD issue short-lived (one hour or less) bearer tokens, particularly for clients running in web browsers or other environments where information leakage may occur.
The form-encoded body parameter method transmits the access token as the "access_token" parameter in the request entity-body, with Content-Type application/x-www-form-urlencoded. Multiple parameters MUST be separated using "&" (ASCII 38).
The URI query parameter method appends the access token as the "access_token" query parameter per RFC 3986. Clients using this method SHOULD also send Cache-Control: no-store, and servers SHOULD respond with Cache-Control: private.
The WWW-Authenticate header for Bearer supports auth-param attributes: "realm" (optional, MUST NOT appear more than once), "scope" (space-delimited case-sensitive scope values, OPTIONAL), "error", "error_description", and "error_uri" (each MUST NOT appear more than once).
Three error codes are defined for resource access failures: invalid_request (HTTP 400), invalid_token (HTTP 401, client MAY retry with new token), and insufficient_scope (HTTP 403, MAY include scope attribute indicating required scope).
Registers the "Bearer" OAuth Access Token Type in the OAuth Access Token Types registry (defined in RFC 6749), with HTTP Authentication Scheme "Bearer" and no additional token endpoint response parameters.
Registers three error values in the OAuth Extensions Error registry (defined in RFC 6749) for use in resource access error responses with the Bearer access token type: invalid_request, invalid_token, and insufficient_scope.
Four principal threats are identified: token manufacture/modification (attacker forges or alters token content), token disclosure (token contains sensitive information exposed in transit or storage), token redirect (token issued for one resource server reused at another), and token replay (previously used token replayed at same server).
The Bearer credentials syntax is: b64token = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) *"="; credentials = "Bearer" 1*SP b64token. Transmitted in the Authorization request header field.