To obtain an access token, a client interacts with an OAuth authorization server (AS),
sending a request for an access token that includes an access grant. An access grant is also
used when a resource server (RS) requests validation of an access token from the AS.
Primary grant types
OAuth defines several different access grant types. Each grant type reflects different
authorization mechanisms.
- Authorization code
-
authorization_code
- An authorization code is returned to the client through a browser redirect after
the resource owner gives consent to the AS. The client subsequently exchanges the
authorization code for an access token (and often a refresh token). Resource owner
credentials are never exposed to the client.
- Resource owner password credentials
-
password
- The client collects the resource owner's password and exchanges it at the AS for
an access token, and often a refresh token. This grant type is suitable in cases
where the RO has a trust relationship with the client, such as its computer
operation system or a highly privileged application because the client must
discard the password after using it to obtain the access token.
- Refresh token
-
refresh_token
- A refresh token is often returned with an access token. Once the original access
token expires, the corresponding refresh token can be sent to the AS to obtain a
fresh access token without requiring the resource owner to reauthenticate. This
allows short-lived access tokens to exist between the client and the resource
server, and long-lived tokens between the client and the AS.
- The Refresh Token grant type can only be used in conjunction with either the
Authorization Code or Resource Owner Password Credentials grant type.
- Implicit
-
implicit
- An access token is returned to the client through a browser redirect in response
to the resource owner authorization request (rather than an intermediate
authorization code). This grant type is suitable for clients incapable of keeping
client credentials confidential (for use in authenticating with the AS) such as
client applications implemented in a browser using a scripting language like
JavaScript.
- Client credentials
-
client_credentials
- The client presents its own credentials to the AS in order to obtain an access
token. This access token is either associated with the client's own resources, and
not a particular resource owner, or is associated with a resource owner for whom
the client is otherwise authorized to act.
Extension grant types
OAuth provides an extension mechanism for defining new extension grant types to support
additional clients or to provide a bridge between OAuth and other trust frameworks. An OAuth
client uses an extension grant type by specifying an absolute URI as the value of the
grant_type parameter and by adding any additional parameters
necessary when contacting the token endpoint at /as/token.oauth2.
PingFederate supports the following extension grant types:
- Assertion grants
-
- JWT Bearer
-
urn:ietf:params:oauth:grant-type:jwt-bearer
- The client obtains a JSON Web Token (JWT) and uses it to request an
access token from the AS. This grant type allows a client to use an
existing trust relationship, expressed through a JWT, without a direct
user approval step at the AS.
- SAML 2.0 Bearer
-
urn:ietf:params:oauth:grant-type:saml2-bearer
- The client obtains a SAML 2.0 bearer assertion and uses it to request
an access token from the AS. Similar to the JWT Bearer grant type,
this grant type allows a client to use an existing trust relationship,
expressed through a SAML assertion, without a direct user approval
step at the AS.
Note: The SAML assertion used for this grant type
generally cannot be a browser-based SSO assertion. To ensure its
validity, the assertion must be associated with WS-Trust STS
processing.
- Client-initiated backchannel authentication (CIBA) grant
-
urn:openid:params:grant-type:ciba
- The client presents an identity hint (and optionally a user code) to the AS. The
AS identifies the resource owner based on the hint provided and then authenticates
and obtains authorization from the resource owner via an out-of-band flow.
Depending on the setup, the client can either poll the AS for the authorization
result or wait for a signal from the AS to return to the AS for the authorization
result. If the resource owner approves the authorization request, the AS returns a
access token to the client; otherwise, the AS returns an error message per the
specification.
- Device authorization grant
-
urn:ietf:params:oauth:grant-type:device_code
- The client presents a device code and user code to the AS in order to identify
the device-authorization session and obtain an access token. This access token is
associated with a resource owner for whom the client is otherwise authorized to
act.
- Token exchange grant
urn:ietf:params:oauth:grant-type:token-exchange
- The client presents a security token to the AS. In exchange, the AS returns
another kind of security token to the client. The new token might be an access
token that is more narrowly scoped for a downstream service or it could be an
entirely different kind of token. This grant type supports subject and actor
tokens employing impersonation and delegation.
- Validation grant
-
urn:pingidentity.com:oauth2:grant_type:validate_bearer
- This proprietary PingFederate OAuth extension enables an RS to act as a client in
the request/response exchange with PingFederate (the AS in this scenario). The
grant type allows an RS to check with PingFederate on the validity of a bearer
access token received from a client making a protected-resources call.