Grant types

A grant type indicates the authorization mechanism that the client uses to retrieve the ID token and access token from Verify. You can choose from authorization code, implicit, authorization code and implicit, device flow, resource owner credentials, JWT, Context-based authorization, refresh token, and token exchange.

See the following tables for a comparison of the supported grant types and to determine which grant type to set for the application.
Table 1. Grant types
Characteristics Authorization code Implicit Authorization code and Implicit
Description

The authorization endpoint /authorize returns an authorization code. The authorization code can then be exchanged for an ID token, access token, or refresh token.

Client authentication is required by using a client ID and secret to retrieve the ID token or access token from the token endpoint /token.

It is the most commonly used flow.

The authorization endpoint /authorize directly returns an ID token or access token.

It does not use an authorization code or a token endpoint /token.

It allows the client front-end and back-end to receive tokens independently of each other.

The client obtains an authorization code and tokens from the authorization endpoint /authorize. Some tokens are requested from the token endpoint /token.
Use case

Use for clients that can securely maintain a client secret such as web applications, and native mobile applications.

It is intended to authenticate the user, and the client.

Use for clients that cannot keep a client secret such as the browser or JavaScript based applications.

It is intended to authenticate the user.
Use for clients that:
  • Can securely maintain a client secret such as web applications, and native mobile applications.
  • Requires immediate access to the ID token for identity information.
  • Requires longer-lived tokens by using refresh tokens.
Response type value 
code
 
id_token
token
id_token token
 
code id_token
code token
code id_token token
All tokens are returned from the authorization endpoint. No Yes No
All tokens are returned from the token endpoint. Yes No No
Tokens are not revealed to the user agent. Yes No No
Client application can be authenticated. Yes No Yes
Generate refresh tokens. Yes No Yes
Communication in one round trip No Yes No
Most communication server-to-server Yes No varies
Login hint (login_hint) Yes
This value could be the user name as a string, for example, john@ibm.com, or a JSON , for example, 
{"realm":"securityVerifyRealm",
"username":"john@ibm.com"}
. When using a JSON value, the realm represents the identity source realm.
 Yes
This value could be the user name as a string, for example, john@ibm.com, or a JSON , for example, 
{"realm":"securityVerifyRealm",
"username":"john@ibm.com"}
. When using a JSON value, the realm represents the identity source realm.
 Yes
This value could be the user name as a string, for example, john@ibm.com, or a JSON , for example, 
{"realm":"securityVerifyRealm",
"username":"john@ibm.com"}
. When using a JSON value, the realm represents the identity source realm.
Maximum authentication age (max_age) This value is the allowable elapsed time in seconds since the last time the user was actively authenticated. This attribute applies to Cloud Directory login sessions only. This value is the allowable elapsed time in seconds since the last time the user was actively authenticated. This attribute applies to Cloud Directory login sessions only. This value is the allowable elapsed time in seconds since the last time the user was actively authenticated. This attribute applies to Cloud Directory login sessions only.
Workflow
  1. Client prepares an authentication request that contains the required request parameters.
  2. Client sends the request to the Verify authorization server.
  3. The Verify authorization server authenticates the user.
  4. The Verify authorization server obtains the user consent or authorization.
  5. The Verify authorization server sends the user back to the client with an authorization code.
  6. Client requests an authentication response by using the authorization code at the token endpoint.
  7. Client receives a response that contains an ID token and access token in the response body.
  8. Client validates the ID token and retrieves the subject identifier of the user.
  1. Client prepares an authentication request that contains the required request parameters.
  2. Client sends the request to the Verify authorization server.
  3. The Verify authorization server authenticates the user.
  4. The Verify authorization server obtains the user consent or authorization.
  5. The Verify authorization server sends the user back to the client with an ID token and, if requested, an access token.
  6. Client validates the ID token and retrieves the subject identifier of the user.
  1. Client prepares an authentication request that contains the required request parameters.
  2. Client sends the request to the Verify authorization server.
  3. The Verify authorization server authenticates the user.
  4. The Verify authorization server obtains the user consent or authorization.
  5. The Verify authorization server sends the user back to the client with an authorization code and depending on the response type, one or more parameters.
  6. Client requests a response by using the Authorization Code at the Token Endpoint.
  7. Client receives a response that contains an ID token and access token in the response body.
  8. Client validates the ID token and retrieves the subject identifier of the user.
Table 2. Grant types continued
Characteristics Device Flow Resource Owner Password Credentials JWT
Description It allows the client to be authorized by using a QR code or a user code that is sent to a URL. Client and user authentication is required by using a client ID, a client secret, a user name, and a password to retrieve the access token and ID token from the token endpoint /token. The username and password is validated against Cloud Directory. Defined in RFC7523. Allows a client to present a signed, or encrypted, or a signed and encrypted JWT in exchange for a grant. The JWT is validated by the authorization server and the identity within the JWT is used as the subject of the grant.
Use case
Use for clients that:
  • Lack a browser to perform a user-agent based OAuth flow.
  • Are input-constrained to the extent that requiring the user to input a lot of text is impractical.
Some examples are, smart TVs, media consoles, digital picture frames, and printers.
 This grant type can be enabled, but use it only if no other flows are available. It can be used for:
  • Resource owners that have a trust relationship with the client, for example the device operating system or a highly privileged application.
  • Clients that can obtain the resource owner's credentials (username and password) by using an interactive form.
  • Migrating existing clients that use direct authentication schemes such as HTTP Basic or Digest authentication to OAuth by converting the stored credentials to an access token.
 There is an established trust relationship between the authorization server (Verify) and an entity, which issues JWTs. The client obtains a JWT from the JWT issuing entity and presents it to the authorization server in exchange for a grant. The JWT issuing entity might have its own requirements, which must be fulfilled before a JWT is issued (such as alternative authentication and authorization checks).
Response type value Not applicable Not applicable Not applicable
All tokens are returned from the authorization endpoint. No No No
All tokens are returned from the token endpoint. Yes Yes Yes
Tokens are not revealed to the user agent. Yes Yes Yes
Client application can be authenticated. Yes Yes Yes
Generate refresh tokens. Yes Yes Yes
Communication in one round trip      
Most communication server-to-server      
Login hint (login_hint) No No No
Maximum authentication age (max_age)     Not applicable
Workflow
  1. The users starts the flow by sending the client ID from the device to request a user code and device code.
  2. If the client ID is valid, the verification URI, user code , and device code are returned.
  3. The device displays the verification URI and user code for the user to type into a browser or it displays a QR code for the user to scan.
  4. The device continuously tries to exchange the device code for a token.
  5. The user scans or keys in the verification URI and user code manually to send the user code to the OIDC service.
  6. If the user code is valid, a success message is sent and the device code is exchanged for an access token.
  1. The user enters their user name and password on a form at the relying party.
  2. The client sends the user name, password, client ID, and client secret to the token endpoint.
  3. The user name and password is validated against Cloud Directory.
  4. The Client receives a response that contains an ID token and access token in the response body.
  1. The client obtains a JWT (by any external means) and presents it to the endpoint.
  2. The JWT is validated and the subject and additional attributes are extracted.
  3. The client receives a response that contains an ID token and an access token in the response body.
Table 3. Grant types continued
Characteristics Context-based authorization Refresh Token Token Exchange
Description An API driven flow where additional authentication and authorization checks are performed. Before a grant is issued to the client, multi-factor authentication might be required. Client and user authentication is required by using a client ID, a client secret, and a refresh token to retrieve a new set of access token, ID token, and refresh token from the token endpoint /token. The refresh token must belong to the same client ID. Attribute values associated with the token are not refreshed during this flow. Defined in RFC8693. Allows a client to present a token to be exchanged for another token.
Use case

  • The client must be instrumented to handle a challenge type response from the authorization server.

  • The client uses the authentication factors APIs available within Verify to receive a JWT, which is then presented to continue the flow.
  • The client must include additional context information in the request via the `context` parameter.
 Use this grant type to get a fresh set of access token, with renewed token lifetime. This allows the access token lifetime to be kept short but will not require the user to login again to get a new access token.

  • Impersonation: For a client to gain access to a resource as a different entity.

  • Delegation: For a client to act on behalf of an authorized entity.
Response type value Not applicable Not applicable Not applicable
All tokens are returned from the authorization endpoint. No No No
All tokens are returned from the token endpoint. Yes Yes Yes
Tokens are not revealed to the user agent. Yes Yes Yes
Client application can be authenticated. Yes Yes Yes
Generate refresh tokens. Yes Yes Yes
Communication in one round trip     Yes
Most communication server-to-server     Yes
Login hint (login_hint) No No No
Maximum authentication age (max_age) Not applicable   No
Workflow
  1. The client initiates the flow by presenting some `context` with a request using grant_type=Context-based authorization
  2. The client recieves either a DENY (if access should not be allowed in this context), or a CHALLENGE (identified via the scope that is returned).
  3. The client uses the access token that is returned with the challenge response to access the available authentication factors APIs including the flag to request a JWT as the result of completing a factor .
  4. The JWT that is returned from the completed factor is presented back to /token as a JWT Bearer grant request (context must also be included) and tokens are issued.
Note:
  • Depending on the policy that is configured, after the first factor is performed, additional factors might be required. Those factors might require that a second CHALLENGE and a second authentication factor be performed .
  • This grant type requires a custom access policy be authored and attached to the application. This access policy must contain rules for first factor authentication, and optionally, any 2FA requirements.
  1. The client determines that the access token is expiring or has expired, and wants to get access tokens.
  2. The client sends the client credentials and refresh token to the token endpoint.
  3. The refresh token and client credentials are validated.
  4. The client receives a response that contains an ID token, refresh token, and access token in the response body.

  1. The client generates or retrieves a token to be used as the subject token. Optionally, it will also have an actor token.

  2. Send a request to the authorization server’s token endpoint with the subject token, and optionally the actor token.

  3. Authorization server returns the requested token.