About OAuth 2.0 Grants

There are several OAuth 2.0 grant types you can use in Oracle Integration. Review the following information to identify the grant type to use for your use case.

Grant Type About the Grant Type Use Cases and Risks

Grant Type	About the Grant Type	Use Cases and Risks
JWT user assertion (recommended)	A user assertion is a user token that contains identity information about the user. The user can either represent a human or a service integration account created for identifying a specific calling application. The user assertion is used directly as an authorization grant to obtain an access token. The client details are provided either as an authentication header in the request or as a client assertion. The user assertion grant is more secure than the resource owner password credentials grant because the user’s credentials are never exposed. The user assertion workflow: Is used with confidential clients. The OAuth clients are trusted to assert a user/service integration account identity on behalf of the user/service integration account. The resource owner's credentials (Oracle Integration user) are never accessible to the client application. It just uses the assertion of the resource owner. It isn’t redirection-based. It takes a request only from the client application to the authorization server. The user is not redirected between interfaces to authorize the request. This user assertion grant works as follows: The client requests an access token by providing a user assertion. The client details are provided either as an authentication header in the request or as a client assertion. The OAuth service authenticates the client and, if valid, supplies an access token. The JWT user assertion characteristics are as follows: Does not require the client to have knowledge of user credentials. There is no browser-based end user interaction. A refresh token is allowed. An access token is in the context of the end user. In this OAuth flow: A user attempts to access a client application by sending a generated user assertion. The client application requests an access token, and often a refresh token, by providing a user assertion or a third-party user assertion. The Oracle Identity Cloud Service authorization server returns the access token to the client application. The client application uses the access token in an API call to invoke the integration.	This grant is used by applications that want to programmatically invoke integrations without any user intervention. The client application impersonates the user by sending the user assertion to Oracle Identity Cloud Service while requesting token access. An access token is returned in the user context. The user can either represent a human or a service integration account created for identifying a specific calling application. Oracle Integration recommends the use of this grant for acquiring an OAuth access token by the applications that must programmatically start the integration without any user intervention. Risks Carefully use this grant (only with first party/trusted clients) because it allows for trivial impersonation to more highly privileged accounts on services. Usage See Prerequisites for JWT User Assertions.
Authorization code	The authorization code grant type is used by web and mobile applications. It differs from most of the other grant types by first requiring the application to launch a browser to begin the integration. At a high level, the integration consists of the following steps: The application opens a browser to send the user to the OAuth server. The user sees the authorization prompt and approves the application request. The user is redirected back to the application with authorization code in the query string. The application exchanges the authorization code for an access token. The authorization code has the following characteristics: Does not require the client to have knowledge of user credentials. Is a browser-based end user interaction. A refresh token is allowed. An access token is in the context of the end user. In this OAuth flow: A user clicks a link in a web server client application to request access to protected resources. The client application redirects the browser to the Oracle Identity Cloud Service authorization endpoint with a request for an authorization code: `oauth2/v1/authorize` The Oracle Identity Cloud Service authorization server returns an authorization code to the client application through a browser redirect after the resource owner gives consent. The client application subsequently exchanges the authorization code for an access token, and often a refresh token. The Oracle Identity Cloud Service authorization server returns the access token to the client application. The client application uses the access token in an API call to invoke the integration.	This grant is used by the applications such as web portals and mobile applications involving user interactions that may end up invoking the integrations. In this type of use case, the user signing in to the web portal/mobile application explicitly provides the consent by authenticating against Oracle Integration to let their application start the integration. Usage See Prerequisites for Authorization Code.
Resource owner password credential (ROPC)	The resource owner’s password credentials (that is, the user name and password) can be used by the OAuth client directly as an authorization grant to obtain an access token. The resource owner password credentials grant type is suitable for cases where the resource owner has a trust relationship with the OAuth client. When using the resource owner password credentials grant, the user provides the credentials (user name and password) directly to the application. The application then uses the credentials to obtain an access token from the OAuth token service. The resource owner password credentials grant is a grant workflow where the client application, together with its client identifier and secret, sends the user name and password in exchange for an access token. Instead of the user having to log in and approve the authorization request in a web interface, the user can enter the user name and password in the client application user interface directly. This workflow has different security properties than other OAuth workflows. The primary difference is that the user’s password is accessible to the application. This requires a strong trust of the application by the user. The resource owner password credentials grant has the following characteristics: The client is required to have knowledge of user credentials. Is not a browser-based end user interaction. A refresh token is allowed. An access token is in the context of the end user. In this OAuth flow: The user clicks a link in the client application requesting access to protected resources. The client application requests the resource owner's user name and password. The user logs in with their user name and password. The client application exchanges those credentials for an access token, and often a refresh token, from the Oracle Identity Cloud Service authorization server. The Oracle Identity Cloud Service authorization server returns the access token to the client application. The client application uses the access token in an API call to invoke the integration.	This grant can be used by applications that want to programmatically invoke the integration without any user intervention. Use this grant only with trusted first-party clients that securely handle user credentials. Even though this grant type can be used by client applications to acquire an OAuth access token to use for sending the request to invoke an integration in a programmatic manner, Oracle Integration does not recommend the resource owner password credential grant because of the following risks: Risks This grant type carries a higher risk than other grant types because it maintains the password anti-pattern this protocol seeks to avoid. The client can abuse the password or the password can unintentionally be disclosed to an attacker (for example, through log files or other records kept by the client). The application can request a scope with complete access to user resources once it possesses the password credential. Passwords expire. This grant is currently in a deprecated state. Usage See Prerequisites for Resource Owner Password Credentials.
Client credentials	The client uses its client credentials (or other supported means of authentication) to request an access token when requesting access to protected resources: Under its control Those of another resource owner that have been previously arranged with the authorization server Only confidential clients must use this grant type. In this OAuth flow: The client authenticates with the authorization server and requests an access token from the token endpoint. Because client authentication is used as the authorization grant, no additional authorization request is required. The authorization server authenticates the client and, if valid, issues an access token. If the request fails client authentication or is invalid, the authorization server returns an error response.	This grant is typically used by clients to obtain an access token outside of the context of a user (for example, to access resources about themselves rather than to access a user's resources). Usage See Prerequisites for Client Credentials.

JWT user assertion

(recommended)

A user assertion is a user token that contains identity information about the user. The user can either represent a human or a service integration account created for identifying a specific calling application.

The user assertion is used directly as an authorization grant to obtain an access token. The client details are provided either as an authentication header in the request or as a client assertion.

The user assertion grant is more secure than the resource owner password credentials grant because the user’s credentials are never exposed.

The user assertion workflow:

Is used with confidential clients. The OAuth clients are trusted to assert a user/service integration account identity on behalf of the user/service integration account.
The resource owner's credentials (Oracle Integration user) are never accessible to the client application. It just uses the assertion of the resource owner.
It isn’t redirection-based. It takes a request only from the client application to the authorization server. The user is not redirected between interfaces to authorize the request.

This user assertion grant works as follows:

The client requests an access token by providing a user assertion. The client details are provided either as an authentication header in the request or as a client assertion.
The OAuth service authenticates the client and, if valid, supplies an access token.

The JWT user assertion characteristics are as follows:

Does not require the client to have knowledge of user credentials.
There is no browser-based end user interaction.
A refresh token is allowed.
An access token is in the context of the end user.

In this OAuth flow:

A user attempts to access a client application by sending a generated user assertion.
The client application requests an access token, and often a refresh token, by providing a user assertion or a third-party user assertion.
The Oracle Identity Cloud Service authorization server returns the access token to the client application.
The client application uses the access token in an API call to invoke the integration.

This grant is used by applications that want to programmatically invoke integrations without any user intervention.

The client application impersonates the user by sending the user assertion to Oracle Identity Cloud Service while requesting token access. An access token is returned in the user context.

The user can either represent a human or a service integration account created for identifying a specific calling application.

Oracle Integration recommends the use of this grant for acquiring an OAuth access token by the applications that must programmatically start the integration without any user intervention.

Risks

Carefully use this grant (only with first party/trusted clients) because it allows for trivial impersonation to more highly privileged accounts on services.

Usage

See Prerequisites for JWT User Assertions.

Authorization code

The authorization code grant type is used by web and mobile applications. It differs from most of the other grant types by first requiring the application to launch a browser to begin the integration. At a high level, the integration consists of the following steps:

The application opens a browser to send the user to the OAuth server.
The user sees the authorization prompt and approves the application request.
The user is redirected back to the application with authorization code in the query string.
The application exchanges the authorization code for an access token.

The authorization code has the following characteristics:

Does not require the client to have knowledge of user credentials.
Is a browser-based end user interaction.
A refresh token is allowed.
An access token is in the context of the end user.

In this OAuth flow:

A user clicks a link in a web server client application to request access to protected resources.
The client application redirects the browser to the Oracle Identity Cloud Service authorization endpoint with a request for an authorization code:
```
oauth2/v1/authorize
```
The
Oracle Identity Cloud Service authorization server returns an authorization code to the client application through a browser redirect after the resource owner gives consent.
The client application subsequently exchanges the authorization code for an access token, and often a refresh token.
The
Oracle Identity Cloud Service authorization server returns the access token to the client application.
The client application uses the access token in an API call to invoke the integration.

This grant is used by the applications such as web portals and mobile applications involving user interactions that may end up invoking the integrations. In this type of use case, the user signing in to the web portal/mobile application explicitly provides the consent by authenticating against Oracle Integration to let their application start the integration.

Usage

See Prerequisites for Authorization Code.

Resource owner password credential (ROPC)

The resource owner’s password credentials (that is, the user name and password) can be used by the OAuth client directly as an authorization grant to obtain an access token.

The resource owner password credentials grant type is suitable for cases where the resource owner has a trust relationship with the OAuth client.

When using the resource owner password credentials grant, the user provides the credentials (user name and password) directly to the application. The application then uses the credentials to obtain an access token from the OAuth token service.

The resource owner password credentials grant is a grant workflow where the client application, together with its client identifier and secret, sends the user name and password in exchange for an access token. Instead of the user having to log in and approve the authorization request in a web interface, the user can enter the user name and password in the client application user interface directly. This workflow has different security properties than other OAuth workflows. The primary difference is that the user’s password is accessible to the application. This requires a strong trust of the application by the user.

The resource owner password credentials grant has the following characteristics:

The client is required to have knowledge of user credentials.
Is not a browser-based end user interaction.
A refresh token is allowed.
An access token is in the context of the end user.

In this OAuth flow:

The user clicks a link in the client application requesting access to protected resources.
The client application requests the resource owner's user name and password.
The user logs in with their user name and password.
The client application exchanges those credentials for an access token, and often a refresh token, from the Oracle Identity Cloud Service authorization server.
The Oracle Identity Cloud Service authorization server returns the access token to the client application.
The client application uses the access token in an API call to invoke the integration.

This grant can be used by applications that want to programmatically invoke the integration without any user intervention.

Use this grant only with trusted first-party clients that securely handle user credentials.

Even though this grant type can be used by client applications to acquire an OAuth access token to use for sending the request to invoke an integration in a programmatic manner, Oracle Integration does not recommend the resource owner password credential grant because of the following risks:

Risks

This grant type carries a higher risk than other grant types because it maintains the password anti-pattern this protocol seeks to avoid. The client can abuse the password or the password can unintentionally be disclosed to an attacker (for example, through log files or other records kept by the client).
The application can request a scope with complete access to user resources once it possesses the password credential.
Passwords expire.
This grant is currently in a deprecated state.

Usage

See Prerequisites for Resource Owner Password Credentials.

Client credentials

The client uses its client credentials (or other supported means of authentication) to request an access token when requesting access to protected resources:

Under its control
Those of another resource owner that have been previously arranged with the authorization server

Only confidential clients must use this grant type.

In this OAuth flow:

The client authenticates with the authorization server and requests an access token from the token endpoint.
Because client authentication is used as the authorization grant, no additional authorization request is required.
The authorization server authenticates the client and, if valid, issues an access token.
If the request fails client authentication or is invalid, the authorization server returns an error response.

This grant is typically used by clients to obtain an access token outside of the context of a user (for example, to access resources about themselves rather than to access a user's resources).

Usage

See Prerequisites for Client Credentials.