Grant types and client authentication
The grant types the token endpoint accepts, how each kind of client proves itself, and the algorithms involved.
On this page
This page is the summary of what an application can do at the token endpoint. The generated OIDC endpoints page is the machine-checked list; this page explains the combinations.
Grant types#
Discovery lists four values in grant_types_supported.
| Grant | Use it for | Notes |
|---|---|---|
authorization_code | Signing a person in. | Needs a pushed authorization request, PKCE with S256, and an exact registered redirect address. The code lives 60 seconds (an operator can shorten that) and is single use. |
refresh_token | Getting a new access token without another sign-in. | Rotates on every use. A client only receives one when it asked for offline_access and is allowed refresh tokens. |
client_credentials | A service acting as itself. | Access token with the client's lifetime (600 seconds by default, at most 900) and no refresh token. The client must be linked to a service principal. |
urn:ietf:params:oauth:grant-type:token-exchange | A service calling another service, on behalf of a caller or as itself. | See Service to service. |
A client can only use the grants it was registered with. Asking for another one fails with unauthorized_client. A value outside this list fails with unsupported_grant_type.
Authorization request rules#
| Rule | Detail |
|---|---|
| Response type | code only. Anything else is unsupported_response_type. |
| Pushed authorization requests | Required. The authorization endpoint accepts only client_id and the request_uri returned by the pushed request endpoint. |
| PKCE | S256 only. A code_verifier that is not valid for RFC 7636 is refused. |
| Response modes | query and form_post. |
state | Required, at least a minimum length, printable ASCII. |
nonce | Printable ASCII, within a length limit. It is echoed in the ID token. |
| Scope | openid must be present. A scope outside the client's allowed scopes is invalid_scope. |
| Resource | resource is an absolute http or https address without a fragment, registered for a product. Every access token has one audience, so several resources mean several token requests. A resource that is not available to the client is invalid_target. See Scopes and consent. |
| Issuer in the response | The authorization response carries iss. Check it. |
| Subject type | A client has the public or the pairwise subject type (pairwise only for a third-party client), listed in subject_types_supported. It is fixed at registration and decides the sub in the ID token and userinfo: see Token claims. |
client_id | A registered identifier. When the oauth_cimd flag is on (it defaults OFF), an https URL naming a client metadata document is also accepted, and such a client may authenticate only with private_key_jwt or none. |
How a client authenticates#
Discovery lists the methods in token_endpoint_auth_methods_supported, and the same list applies to introspection and revocation.
| Method | Who uses it | How |
|---|---|---|
private_key_jwt | Service clients and any client with a key | A signed client assertion sent with client_assertion_type set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer. The assertion carries exp, a unique jti, and an aud equal to the issuer as a single string. Its exp is at most 5 minutes ahead (an operator can lower that), it names a registered key by kid, and each assertion can be used once. |
tls_client_auth | Clients registered for it, where a deployment supports it | A verified client certificate that is registered for the client. A request with no verified certificate is invalid_client. |
none | Public clients such as browser and native applications | No secret. The client is bound by PKCE and by DPoP. |
Assertion algorithms are EdDSA and ES256. The same two are accepted for DPoP proofs and used for ID tokens.
Sender constraint#
An access token is bound to a key unless it was issued to a first-party web client.
- DPoP. The client proves possession of a key with a
DPoPproof on each request. See DPoP. - Mutual TLS. Where a deployment supports it, discovery sets
tls_client_certificate_bound_access_tokensto true and the token is bound to the certificate thumbprint.
A client that does not prove a key, and is not a first-party web client, is refused with invalid_client.
Other endpoints#
Introspection and revocation use the same client authentication methods. Back-channel logout is supported, with the session id in the logout token; see Back-channel logout.