About OAuth 2.0 Grants

The following sections describe Oracle Utilities Adapter authentication capabilities in detail.

This authentication scheme enables external clients to acquire a token that is also sent as part of the request sent to invoke Oracle Utilities application APIs.

The most important step for an application in the OAuth flow is how the application receives an access token (and optionally a refresh token). A grant type is the mechanism used to retrieve the token. OAuth defines several different access grant types that represent different authorization mechanisms.

Applications can request an access token to access protected endpoints in different ways, depending on the type of grant type specified in the Oracle Identity Cloud Service application. A grant is a credential representing the resource owner's authorization to access a protected resource.

The following sections discuss the various grant types and their pros/cons, along with instructions on how to configure the specific grant type.

There are several OAuth 2.0 grant types you can use in Oracle Integration with the Oracle Utilities Adapter. 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
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. 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 Utilities Application services.	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 Creating a Connection.
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 requests the protected resource. 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. Usage See Prerequisites for Resource Owner Password Credentials.
Client credentials	The client credentials grant is used when the OAuth client itself owns the data and doesn’t need delegated access from a resource owner. The client credentials grant provides a specific grant flow in which the resource owner (that is, the user) is not involved. When using this grant, the client application requests an access token only with its own credentials (the identifier and secret) or an assertion from the token endpoint and uses the access token on behalf of the client application itself. The token endpoint does not issue a refresh token. This is because refresh tokens are not supported by the client credentials grant. When the access token expires, the client application must request a new access token. Client credentials have the following characteristics: Are used by confidential OAuth clients. The OAuth client application communicates with the service provider directly and not on behalf of a resource owner. The flow is not redirection-based. An access token is outside of the context of the end user. In this OAuth flow: The user requests the protected resource. The client application exchanges its credentials for an access token from the Oracle Identity Cloud Service authorization server. The Oracle Identity Cloud Service authorization server validates the client credentials and returns the access token to the client application. The client application uses the access token in an API call to invoke the integration.	A OAuth client that uses the client credentials grant must have credentials on the authorization server, which means the client must be a confidential client. With the client credentials grant, the integration server does not know the owner because the client does not need resource owner approval. This grant flow is best-suited for when a service provider wants to provide some API methods for use by the client application in general, instead of methods that apply to a certain resource owner. Usage See Prerequisites for OAuth Client Credentials

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.
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 Utilities Application services.

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 Creating a Connection.

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 requests the protected resource.
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.

Usage

See Prerequisites for Resource Owner Password Credentials.

Client credentials

The client credentials grant is used when the OAuth client itself owns the data and doesn’t need delegated access from a resource owner. The client credentials grant provides a specific grant flow in which the resource owner (that is, the user) is not involved. When using this grant, the client application requests an access token only with its own credentials (the identifier and secret) or an assertion from the token endpoint and uses the access token on behalf of the client application itself. The token endpoint does not issue a refresh token. This is because refresh tokens are not supported by the client credentials grant. When the access token expires, the client application must request a new access token.

Client credentials have the following characteristics:

Are used by confidential OAuth clients.
The OAuth client application communicates with the service provider directly and not on behalf of a resource owner.
The flow is not redirection-based.
An access token is outside of the context of the end user.

In this OAuth flow:

The user requests the protected resource.
The client application exchanges its credentials for an access token from the Oracle Identity Cloud Service authorization server.
The Oracle Identity Cloud Service authorization server validates the client credentials and returns the access token to the client application.
The client application uses the access token in an API call to invoke the integration.

A OAuth client that uses the client credentials grant must have credentials on the authorization server, which means the client must be a confidential client.

With the client credentials grant, the integration server does not know the owner because the client does not need resource owner approval.

This grant flow is best-suited for when a service provider wants to provide some API methods for use by the client application in general, instead of methods that apply to a certain resource owner.

Usage

See Prerequisites for OAuth Client Credentials