oauth2.dev

Bearer

IETF

Registry Context

Bearer is an OAuth access token type usable by any party possessing the token, without proof of possession of cryptographic key material.

Technical Summary

RFC 6750 registers the Bearer access token type and Bearer HTTP authentication scheme, with no additional token endpoint response parameters. It defines header, form-body, and URI-query transmission methods.

When Used

Used when presenting an OAuth bearer access token to a protected resource. The Authorization header method is preferred; form-body and URI-query transmission are restricted or discouraged.

Normative Requirements

Clients

MUST NOT
3
  1. RFC 6750 - Section 2

    use more than one method to transmit the token in one request.

    Condition: when sending bearer access tokens in resource requests

    Clients MUST NOT use more than one method to transmit the token in each request.

  2. RFC 6750 - Section 2.2

    use form-body token transmission unless the content type is application/x-www-form-urlencoded, its encoding rules are followed, the body is single-part and ASCII-only, and the method has defined request-body semantics.

    Condition: when placing an access token in the HTTP request entity-body

    The client MUST NOT use this method unless all of the following conditions are met:

  3. RFC 6750 - Section 2.2

    use the GET method.

    Condition: when using form-body token transmission

    the "GET" method MUST NOT be used.

MUST
6
  1. RFC 6750 - Section 2.2

    ensure content encoded in the entity-body consists entirely of ASCII characters.

    Condition: when using form-body token transmission

    The content to be encoded in the entity-body MUST consist entirely of ASCII characters.

  2. RFC 6750 - Section 2.2

    separate the access_token parameter from other request-specific body parameters using ampersand characters.

    Condition: when the entity-body includes other request-specific parameters

    the "access_token" parameter MUST be properly separated from the request-specific parameters using "&" character(s)

  3. RFC 6750 - Section 2.3

    separate the access_token parameter from other request-specific query parameters using ampersand characters.

    Condition: when the URI query includes other request-specific parameters

    the "access_token" parameter MUST be properly separated from the request-specific parameters using "&" character(s)

  4. RFC 6750 - Section 5.2

    validate the TLS certificate chain, including checking the certificate revocation list.

    Condition: when requesting protected resources

    the client MUST validate the TLS certificate chain when making requests to protected resources, including checking the Certificate Revocation List

  5. RFC 6750 - Section 5.2

    verify the identity of the resource server.

    Condition: when presenting a bearer token

    the client MUST verify the identity of that resource server

  6. RFC 6750 - Section 5.3

    prevent bearer tokens from leaking to unintended parties.

    Client implementations MUST ensure that bearer tokens are not leaked to unintended parties

SHOULD NOT
2
  1. RFC 6750 - Section 2.2

    use form-body token transmission except where participating browsers cannot access the Authorization request header field.

    The "application/x-www-form-urlencoded" method SHOULD NOT be used except in application contexts where participating browsers do not have access to the "Authorization" request header field.

  2. RFC 6750 - Section 2.3

    use URI-query token transmission unless header and entity-body transmission are impossible.

    it SHOULD NOT be used unless it is impossible to transport the access token in the "Authorization" request header field or the HTTP request entity-body.

SHOULD
2
  1. RFC 6750 - Section 2.1

    use the Authorization request header field with the Bearer HTTP authorization scheme.

    Condition: when making authenticated requests with a bearer token

    Clients SHOULD make authenticated requests with a bearer token using the "Authorization" request header field

  2. RFC 6750 - Section 2.3

    send a Cache-Control header containing the no-store option.

    Condition: when using URI-query token transmission

    Clients using the URI Query Parameter method SHOULD also send a Cache-Control header containing the "no-store" option.

MAY
1
  1. RFC 6750 - Section 3.1

    request a new access token and retry the protected-resource request.

    Condition: after an invalid_token error

    The client MAY request a new access token and retry the protected resource request.

Authorization servers

MUST
1
  1. RFC 6750 - Section 5.2

    implement TLS.

    The authorization server MUST implement TLS.

RECOMMENDED
1
  1. RFC 6750 - Section 5.2

    restrict token use to a specific scope.

    Condition: to mitigate token redirect

    Restricting the use of the token to a specific scope is also RECOMMENDED.

Resource servers

MUST NOT
5
  1. RFC 6750 - Section 3

    include the realm attribute more than once.

    Condition: in a Bearer challenge

    The "realm" attribute MUST NOT appear more than once.

  2. RFC 6750 - Section 3

    include the scope attribute more than once.

    Condition: in a Bearer challenge

    The "scope" attribute MUST NOT appear more than once.

  3. RFC 6750 - Section 3

    include error, error_description, or error_uri more than once each.

    Condition: in a Bearer challenge

    The "error", "error_description", and "error_uri" attributes MUST NOT appear more than once.

  4. RFC 6750 - Section 3

    use characters outside the permitted scope-value and delimiter character sets.

    Condition: in a Bearer challenge scope attribute

    Values for the "scope" attribute MUST NOT include characters outside the set %x21 / %x23-5B / %x5D-7E for representing scope values and %x20 for delimiters

  5. RFC 6750 - Section 3

    use characters outside %x20-21, %x23-5B, and %x5D-7E.

    Condition: in error and error_description attributes

    Values for the "error" and "error_description" attributes MUST NOT include characters outside the set %x20-21 / %x23-5B / %x5D-7E.

MUST
3
  1. RFC 6750 - Section 2.1

    support bearer-token transmission through the Authorization request header field.

    Resource servers MUST support this method.

  2. RFC 6750 - Section 3

    include the WWW-Authenticate response header field.

    Condition: when a protected-resource request lacks authentication credentials or an access token enabling access

    the resource server MUST include the HTTP "WWW-Authenticate" response header field

  3. RFC 6750 - Section 3

    make error_uri values conform to URI-reference syntax.

    Condition: when including error_uri in a Bearer challenge

    Values for the "error_uri" attribute MUST conform to the URI-reference syntax

SHOULD NOT
1
  1. RFC 6750 - Section 3.1

    include an error code or other error information.

    Condition: when the request lacks all authentication information

    the resource server SHOULD NOT include an error code or other error information.

SHOULD
6
  1. RFC 6750 - Section 2.3

    include a Cache-Control header containing the private option in successful responses.

    Condition: when responding successfully to URI-query token requests

    Server success (2XX status) responses to these requests SHOULD contain a Cache-Control header with the "private" option.

  2. RFC 6750 - Section 3

    include the error attribute explaining why access was declined.

    Condition: when a request included an access token but authentication failed

    the resource server SHOULD include the "error" attribute

  3. RFC 6750 - Section 3.1

    respond with HTTP 400 Bad Request.

    Condition: for an invalid_request error

    The resource server SHOULD respond with the HTTP 400 (Bad Request) status code.

  4. RFC 6750 - Section 3.1

    respond with HTTP 401 Unauthorized.

    Condition: for an invalid_token error

    The resource SHOULD respond with the HTTP 401 (Unauthorized) status code.

  5. RFC 6750 - Section 3.1

    respond with HTTP 403 Forbidden.

    Condition: for an insufficient_scope error

    The resource server SHOULD respond with the HTTP 403 (Forbidden) status code

  6. RFC 9700 - Section 2.2.1

    use mechanisms for sender-constraining access tokens.

    Condition: to prevent misuse of stolen or leaked access tokens

    Authorization and resource servers SHOULD use mechanisms for sender-constraining access tokens

MAY
4
  1. RFC 6750 - Section 2.2

    support form-body bearer-token transmission.

    Resource servers MAY support this method.

  2. RFC 6750 - Section 2.3

    support URI-query bearer-token transmission.

    Resource servers MAY support this method.

  3. RFC 6750 - Section 3

    include the WWW-Authenticate response header field.

    Condition: in response to other conditions

    it MAY include it in response to other conditions as well.

  4. RFC 6750 - Section 3.1

    include the scope attribute identifying the scope needed for access.

    Condition: for an insufficient_scope error

    MAY include the "scope" attribute with the scope necessary to access the protected resource.

Token servers

SHOULD
2
  1. RFC 6750 - Section 5.3

    issue bearer tokens with lifetimes of one hour or less.

    Condition: particularly for browser clients or environments where information leakage may occur

    Token servers SHOULD issue short-lived (one hour or less) bearer tokens

  2. RFC 6750 - Section 5.3

    issue bearer tokens containing an audience restriction.

    Condition: to restrict use to the intended relying party or parties

    Token servers SHOULD issue bearer tokens that contain an audience restriction

Challenges

MUST
2
  1. RFC 6750 - Section 3

    use the Bearer auth-scheme value.

    All challenges defined by this specification MUST use the auth-scheme value "Bearer".

  2. RFC 6750 - Section 3

    be followed by one or more auth-param values.

    This scheme MUST be followed by one or more auth-param values.

Implementations

MUST NOT
1
  1. RFC 6750 - Section 5.2

    store bearer tokens in cookies that can be sent in the clear.

    bearer tokens MUST NOT be stored in cookies that can be sent in the clear.

MUST
4
  1. RFC 6750 - Section 5.2

    apply TLS confidentiality and integrity protection to client-to-authorization-server and client-to-resource-server communication.

    Condition: to protect against token disclosure

    confidentiality protection MUST be applied using TLS with a ciphersuite that provides confidentiality and integrity protection.

  2. RFC 6750 - Section 5.2

    encrypt the token in addition to using TLS.

    Condition: when the client is prevented from observing the token contents

    token encryption MUST be applied in addition to the usage of TLS protection.

  3. RFC 6750 - Section 5.2

    apply confidentiality protection to exchanges between clients and authorization servers and between clients and resource servers.

    Condition: to mitigate token capture and replay

    confidentiality protection of the exchanges between the client and the authorization server and between the client and the resource server MUST be applied.

  4. RFC 6750 - Section 5.3

    take precautions against cross-site request forgery.

    Condition: when storing bearer tokens in cookies

    Implementations that do store bearer tokens in cookies MUST take precautions against cross-site request forgery.

Bearer-token implementations

MUST
1
  1. RFC 6750 - Section 5.2

    provide integrity protection sufficient to prevent token modification.

    The token integrity protection MUST be sufficient to prevent the token from being modified.

Bearer-token issuers

MUST
1
  1. RFC 6750 - Section 5.2

    make reference token values infeasible for attackers to guess.

    Condition: when a bearer token contains a reference to authorization information

    Such references MUST be infeasible for an attacker to guess

Bearer-token users

SHOULD NOT
1
  1. RFC 6750 - Section 5.3

    pass bearer tokens in page URLs.

    Bearer tokens SHOULD NOT be passed in page URLs

SHOULD
1
  1. RFC 6750 - Section 5.3

    pass bearer tokens in HTTP message headers or confidentiality-protected message bodies.

    Condition: instead of page URLs

    bearer tokens SHOULD be passed in HTTP message headers or message bodies for which confidentiality measures are taken.

Deployments

MUST
1
  1. RFC 6750 - Section 5.2

    protect token confidentiality between front-end and back-end servers.

    Condition: when TLS terminates before the server providing the resource

    sufficient measures MUST be employed to ensure confidentiality of the token between the front-end and back-end servers

Token issuers

MUST
1
  1. RFC 6750 - Section 5.2

    limit token lifetime.

    Condition: to mitigate token capture and replay

    the lifetime of the token MUST be limited

Validation Guidance

error

Reject requests that transmit a bearer token using more than one method.

error

Support and validate Bearer credentials in the Authorization header; prefer this method for clients.

error

For form-body transmission, require application/x-www-form-urlencoded encoding, a single-part ASCII body, a method with defined body semantics, and proper parameter separation.

warning

Warn when form-body transmission is used outside the stated browser compatibility exception.

warning

For URI-query transmission, validate parameter separation, client no-store caching, server private caching, and that header and body transport were impossible.

error

Require applicable WWW-Authenticate challenges to use Bearer with auth parameters and reject duplicate or syntactically invalid attributes.

warning

Validate bearer error responses and their corresponding HTTP status codes.

error

Require token integrity, unguessable reference tokens, limited lifetimes, and audience or scope restrictions as applicable.

error

Require confidentiality and integrity protection across token-transport paths, including internal hops after TLS termination.

error

Flag bearer tokens stored in cleartext-capable cookies or included in page URLs.

warning

Check whether authorization and resource servers support sender-constrained access tokens to reduce replay of stolen tokens.

Security Notes

RFC 6750 - Section 1.2

Possession of a bearer token is sufficient to use it; implementations therefore need to prevent disclosure and replay.

RFC 6750 - Section 2.3

URI-query transmission is discouraged because token-bearing URLs are likely to be logged and retained in browser history or other data structures.

RFC 9700 - Section 2.2.1

Current OAuth security best practice recommends sender-constrained access tokens, such as mutual TLS or DPoP, to reduce misuse of stolen or leaked tokens.

Reference

Details

Entry Id
Bearer
Name
Bearer
Http Authentication Scheme
Bearer
Change Controller
IETF
Reference
RFC6750