OAuth 2.0 client credential profiles enable you to globally configure authentication settings for OAuth 2.0 as a client. An OAuth 2.0 credential profile is the combination of OAuth service provider details and a specific OAuth client application. An OAuth service provider defines the authorization and token endpoints. API Gateway includes three preconfigured OAuth providers:
-
API Gateway
-
Google
-
SalesForce
Client applications must be registered with the service provider to obtain a client ID and secret as well as to register additional details like the OAuth flow type and redirect URL (where required). Google applications can be registered at https://cloud.google.com/console, SalesForce applications can be registered at https://www.salesforce.com, and API Gateway applications can be registered in the client application registry or API Manager (ports 8089 and 8075 respectively).
The API Gateway provider represents OAuth services running on an API Gateway. For more information on
setting up the OAuth server on API Gateway, see Set up API Gateway OAuth 2.0.
The API Gateway provider uses the existing OAuth server samples for authorization and token endpoints
(https://127.0.0.1:8089/api/oauth/authorize and https://127.0.0.1:8089/api/oauth/token).
The Google and SalesForce provider settings ship with the current public endpoints.
You can also add new OAuth providers. See the section called “Add OAuth 2.0 provider” for more information.
Each OAuth 2.0 provider can have multiple client application credentials. Each set of credentials represents an application that has been registered with the provider. Upon registering, the application is assigned a client ID and secret and can designate a redirect URL for receiving access codes.
To add an application for an existing OAuth 2.0 provider, click an OAuth 2.0 client credential node (for example, Google), and click the Add button on the OAuth2 Credentials tab of the OAuth2 Credential Profile window. Complete the following fields on the Add OAuth2 Application dialog:
Name:
Enter a suitable name for this client application.
Client ID:
This identifies the client responsible for the OAuth request. This ID is assigned by the OAuth provider.
Client Secret:
This is a confidential secret key used for authentication. This secret is assigned by the OAuth provider.
OAuth Flow Type:
Select an OAuth flow type. The options are:
-
Authz Code
-
Client Credentials
-
JWT
-
Resource Owner
-
SAML
For more details on the authentication flows that API Gateway supports, see the API Gateway OAuth 2.0 authentication flows topic.
Redirect URL:
Enter the URL of the client's redirect endpoint (for example,
https://localhost:8088/oauth_callback). This is the URL registered with the
provider for receiving access codes via a redirect from the authorization server. This must
match a listener configured on API Gateway (see Redirect URL Listener).
To configure client scopes, SAML bearer settings, JWT settings, or other advanced settings, click the appropriate tabs.
You can configure the scopes that a client application can access on the Scopes tab. Click Add to add a scope. This is the set of scopes required by the application, and this list must match, or be a subset of, the required scopes registered with the OAuth provider. For more information on scopes, see the section called “Manage OAuth scopes”.
You can configure SAML bearers on the SAML Bearer tab. According to the IETF draft document SAML 2.0 Profile for OAuth 2.0, a SAML assertion can be used to request an access token when a client wishes to utilize an existing trust relationship, expressed through the semantics of the SAML assertion, without a direct user approval step at the authorization server. When a client application is configured to use the SAML grant type a SAML assertion must be either configured/generated or made available on the message board.
To generate an assertion select the Generate assertion using following configuration option and complete the following fields:
Use private key to sign SAML assertion:
Click Signing Key to select a private key to use to sign the assertion. This will be the private key certificate registered with the OAuth provider.
Resource Owner ID:
Enter the identity of the resource owner as expected by the resource server. This can be specified using
a selector (for example, ${authentication.subject.id}).
Assertion expires in:
Enter the time duration that the assertion is valid for. Expressed in days, hours, minutes, and seconds.
Drift time (secs):
Enter a drift time in seconds to allow for clock skew.
Alternatively, you can generate the assertion through other means and take it from the message
board by selecting the option Get assertion from message attribute named: and entering
the name of the attribute (for example, ${oauth.saml.assertion}).
![[Important]](../common_oracle/images/admon/important.png) |
Important |
|---|---|
|
The IETF draft document also describes how to use SAML 2.0 for client authentication. This is not supported in API Gateway. |
You can configure JWT on the JWT tab. This enables you to configure JWT for authorization grant, as defined by the IETF draft document JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants.
|
Important |
|---|---|
|
API Gateway only supports the use of JWT as authorization grant and does not support JWT for client authentication. |
Configure the following fields:
Sign using private key:
Select this option and click Signing Key to select a private key certificate that has been registered with the OAuth provider, and use it to sign the JWT claim.
Sign using client secret:
Select this option to sign the JWT claim using a client secret issued by the OAuth provider.
JWT expiry (in secs):
Enter the expiry time for the JWT claim, in seconds.
Add additional JWT claims:
Click the Add button to add additional JWT claims. You can also Edit or Delete existing claims.
By default a JWT is generated with the following claim set:
| Claim | Dafault Value |
|---|---|
|
|
The application client ID |
|
|
The token endpoint of the provider |
|
|
The expiry time from the field JWT expiry (in secs) |
|
|
The issued assertion time, the time the assertion was issued measured in seconds since 00:00:00 UTC, January 1, 1970. |
These claims can be overridden by adding additional claims. It is also possible to add claims like
scope to define scopes, and prn (for SalesForce), or sub (as
defined in the IETF draft doc) to identify the resource owner for whom a token is being requested.
![[Note]](../common_oracle/images/admon/note.png) |
Note |
|---|---|
|
Scopes must be added to a claim on this tab if they are required by the provider to be present in a claim. The scopes defined on the Scopes tab are added to the query string of the token request, but for flexibility they are not automatically added to the claim. The reason for this is because JWT authorization grants are non-normative and claim sets must be agreed in advance with individual OAuth providers. For example, SalesForce does not allow the addition of scopes to a JWT claim, whereas Google requires a scope claim. Automatically adding scopes from the Scopes tab to a claim could preclude a JWT grant flow where scopes must be present in the request but not the claim. |
You can use the following options to specify where to add the client credentials in token requests. The Authorization Header or The Query String. This option applies to all standard grant types excluding JWT and SAML.
In Authorization Header:
Select this option to add the client credentials to the authorization header.
In Query String:
Select this option to add the client credentials to the query string.
Use the following options to specify where to find resource owner credentials, for the resource owner grant type.
Resource Owner ID:
Enter the resource owner ID. This can be specified as a selector.
Resource Owner Password:
Enter the resource owner password. This can be specified as a selector.
Finally, in the Properties table you can add additional properties to pass with
authorization or token requests. These properties can be used to set up provider-specific options,
for example, Google authorization requests require the parameter access_type=offline to
issue a refresh token.
After you have configured your OAuth 2.0 client credentials globally, you can select the client credential profile to use for authentication on the Authentication tab of your filter (for example, in the Connection and Connect To URL filters). For more information, see the API Gateway User Guide.
To configure a new OAuth 2.0 provider, right-click OAuth2, and select Add OAuth2 Client Credential. Complete the following fields on the OAuth2 Provider Configuration dialog:
Profile Name:
Enter a suitable name for this OAuth provider configuration (for example, Google
or Microsoft).
Authorization Endpoint:
Enter the URL of the OAuth provider's authorization endpoint (for example,
https://accounts.google.com/o/oauth2/auth). This is a public
URL where a resource owner is directed to authorize a client application. This is used in the
authorization code flow.
Token Endpoint:
Enter the URL of the OAuth provider's token endpoint (for example,
https://accounts.google.com/o/oauth2/token). This is a public
URL where a client application can request a token.
Token Store:
Click the browse button to choose an access token store. This is where received tokens are persisted.
You can configure OAuth access token stores globally under the Libraries node in the Policy Studio tree. These can then be selected in the Access Token Store field. For more details on configuring access token stores, see the section called “Manage access tokens and authorization codes”.
Store OAuth State in this Cache:
Click the browse button to choose a cache. This is where the state of an authorization request is stored. This is used in the authorization code flow to maintain state when the user is directed to the authorization server for authorization.
![[Tip]](../common_oracle/images/admon/tip.png) |
Tip |
|---|---|
| To change the configuration of an existing OAuth 2.0 provider, click the OAuth client credential node, and edit the settings on the OAuth2 Provider Settings tab of the OAuth2 Credential Profile window. |
The callback URL that is registered with an OAuth provider is implemented very simply by creating a matching relative path in an HTTP listener. The policy for this path needs only to add an Authorize Client with Server filter (see Authorize client with server). The filter must be configured with a reference to the relevant provider profile for this callback URL.
