# Behaviour: Token Requests

_(c) AMWA 2019, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_

## Grants

The implicit grant MUST NOT be used as it has been deprecated in Section 3.1.2. of the
[OAuth 2.0 Best Common Practice][oauth-security-topics] guidelines.

The password grant SHOULD NOT be used as it has been deprecated in Section 3.4. of the
[OAuth 2.0 Best Common Practice][oauth-security-topics] guidelines.

The Authorization Code grant MUST be supported by the Authorization Server, and SHOULD act as the primary grant flow.
When used with Public Clients, this grant MUST be used alongside PKCE as outlined in [RFC 7636][RFC-7636], in-keeping
with the recommendations given in 3.1.1. of the [OAuth 2.0 Best Common Practice][oauth-security-topics].

The Client Credentials grant MUST be supported by the Authorization Server. This grant type MUST only be used by
confidential clients in machine to machine use cases. Authorization Servers SHOULD provide the means to restrict which
scopes can be used with this grant type either during dynamic client registration or during token requests.

The Refresh Token grant MUST be supported in order to ease the refreshing of Access Tokens where the Authorization Code
grant is used, and reduce the number of user authorization requests.

It is RECOMMENDED that Section 5 of [RFC 6819][RFC-6819], OAuth 2.0 Threat Model and Security Considerations, be
followed as closely as possible to minimise chance of a security breach, such as the leaking or hijacking of client
credentials, Authorization Codes or Refresh Tokens.

## Authorization Request and Response
_Found at the [RFC 8414][RFC-8414] `authorization_endpoint`, for example at **/authorize**_

Successful authorization requests for the Authorization Code grant SHALL be provided by registered clients as
defined in [RFC 6749][RFC-6749] Section 4.1.1.

The means by which the Authorization Server validates the end-user is beyond the scope of this specification, but may
include the use of a login prompt and session cookies, or integration with a corporate Single-Sign-On (SSO) System.

A successful authorization response SHALL be serviced by the Authorization Server as defined in [RFC 6749][RFC-6749]
Section 4.1.2. The `state` parameter SHOULD be used and is capable of providing per-request customization.
Support for the PKCE `code_challenge` parameter MUST be implemented as outlined in [RFC 7636][RFC-7636] for public
clients. A `code_challenge_method` parameter MUST be used alongside the `code_challenge` parameter and SHOULD be equal
to "S256" unless the client is unable to perform a SHA256 hash, in which case a value of "plain" MAY be used.
Authorization Servers MUST support both the "S256" and "plain" `code_challenge_method`s.

## Access Token Request and Response
_Found at the [RFC 8414][RFC-8414] `token_endpoint`, for example at **/token**_

Access Token requests SHALL be provided by clients as defined in [RFC 6749][RFC-6749] Section 4 based on the OAuth
2.0 grant being used.

For Public Clients, the additional parameter of `code_verifier` is added to the request, as outlined in Section 4.5 of
[RFC 7636][RFC-7636] to prevent authorization code hijacking.

Clients MUST include the `scope` parameter in their token requests, noting any scopes which they will require within the
returned token.

Successful Access Token responses SHALL be serviced by the Authorization Server as defined in [RFC 6749][RFC-6749]
Section 5.1. Additionally the `expires_in` and `refresh_token` fields MUST be included in the response, unless using the
Client Credentials grant where the `refresh_token` SHOULD be omitted. The `token_type` field value MUST be treated as
case-insensitive, in order to accommodate values such as "Bearer" and "bearer".

## Refresh Tokens

A Refresh Token is a string representing the authorization granted to the client by the resource owner. Refresh Tokens
are issued to the client by the Authorization Server and are used to obtain a new Access Token when the current Access
Token becomes invalid or expires, in accordance with Section 1.5 of [RFC 6749][RFC-6749]. A Refresh Token MUST be at
least 40 characters in length. The process of refreshing an Access Token is outlined in Section 6 of
[RFC 6749][RFC-6749].

Authorization Servers MUST issue Refresh Tokens in the Bearer Token returned after the completion of an authorization
flow. Each Refresh Token SHOULD be time-limited.

Refresh Tokens MUST be bound to a specific client, and this binding MUST be checked during token refresh.

Refresh Tokens SHOULD be rotated by the Authorization Server when clients make new token requests, as recommended by
[RFC 6819][RFC-6819]. Authorization Servers MAY continue to issue Refresh Tokens indefinitely without requiring users
to re-authenticate, provided the Refresh Token is not explicitly revoked or has expired.

In the case of Browser-Based Clients, when issuing a rotated Refresh Token, the Refresh Token MUST be time-limited and
the Authorization Server MUST NOT extend the lifetime of the new Refresh Token beyond the lifetime of the initial
Refresh Token, as stated in Section 8 of [OAuth 2.0 for Browser-Based Apps][oauth-browser-based-apps].

## Token Revocation
_Found at the [RFC 8414][RFC-8414] `revocation_endpoint`, for example at **/revoke**_

Access Tokens and Refresh Tokens SHOULD be revoked by the Authorization Server as defined by [RFC 7009][RFC-7009].

OAuth 2.0 clients SHOULD check for the presence of a valid `revocation_endpoint` in the OAuth 2.0 Authorization
Server Metadata and, if present, SHOULD revoke any valid refresh tokens using the revocation endpoint upon a user
ceasing to require authorization. This may be, for example, due to logging out of an application, a change of user
identity or uninstalling a given application.

[RFC-6749]: https://tools.ietf.org/html/rfc6749 "The OAuth 2.0 Authorization Framework"

[RFC-6819]: https://tools.ietf.org/html/rfc6819 "OAuth 2.0 Threat Model and Security Considerations"

[RFC-7009]: https://tools.ietf.org/html/rfc7009 "OAuth 2.0 Token Revocation"

[RFC-7636]: https://tools.ietf.org/html/rfc7636 "Proof Key for Code Exchange by OAuth Public Clients"

[RFC-8414]: https://tools.ietf.org/html/rfc8414 "OAuth 2.0 Authorization Server Metadata"

[oauth-security-topics]: https://datatracker.ietf.org/doc/draft-ietf-oauth-security-topics/ "OAuth 2.0 Security Best Current Practice 13"

[oauth-browser-based-apps]: https://datatracker.ietf.org/doc/draft-ietf-oauth-browser-based-apps
