How Do I Configure the REST Adapter to Consume a REST API Protected with 3-Legged OAuth Token-Based Authentication?

This section provides an overview of the OAuth Custom Three Legged Flow security policy.

The following steps are performed as part of OAuth authorization code credentials flow.


Description of icsre_dt_001.png follows
Description of the illustration icsre_dt_001.png

Step Description
1 The user specifies the authorization request URI. The user is redirected by the user agent (browser) to the authorization URI.
2 The resource owner logs in to authenticate and provide consent to the client application to access its resources.
3 The authorization server sends a callback request to the client application and sends the authorization code.
4 The client application extracts the authorization code from the request and uses it to send another request to the authorization server to get an access token.   
5 The authorization server responds to the access token request by sending an access token to the client application.
6 The client application uses the access token to make requests for protected resources.  
This flow is defined in the OAuth specification. However, how to perform each step in the flow is determined by the authorization server implementing the OAuth flow. There are several variations to this flow.
  • The OAuth provider expects that some query parameters are passed when the user is redirected to the authorization URI.

  • The provider calls the authorization code something else.

  • The call for the access token should include the authorization code. However, some providers may expect it as a header or a query parameter or maybe as part of the data.

  • The access token response may also wary. Some providers may return a refresh token (for example, call it extended_token or something else). Providers are known to return an expiry, whereas some providers return a JWT token, where the expiry is embedded as a claim within the token.

  • Providers may also declare a custom token type.

  • The call to refresh the access token may also vary from provider to provider.

  • The call to access resources using the access token may also vary. Providers may expect it to be a header or a query parameter. Some providers ask the token to be passed as an authorization header. Few providers expect a custom header, and so on.

The REST Adapter provides a security policy called the OAuth Authorization Code Credentials Flow. This policy provides a specific implementation of the OAuth as illustrated in the OAuth specification. For all other cases, OAuth Custom Three Legged Flow can be used to address these customizations.

Step 1: Configure the Authorization Request


Description of rest_adapter_three_leg.png follows
Description of the illustration rest_adapter_three_leg.png

Specify the authorization URI where the resource owner authenticates and provides consent in the Authorization Request field. The client ID and scope are typically passed as query parameters with the redirect URI from where the authorization server must send a callback and the authentication code.

Oracle Integration Cloud Service has a fixed endpoint to receive this callback so you can specify the URI directly or pass a reference ${refresh_token} that is automatically resolved by the platform. For example:
https://AUTH_URI?response_type=code&client_id=YOUR_CLIENT_ID &redirect_uri=${redirect_uri}&scope=app_scope

Step 2: Configure the Access Token Request

When the resource owner provides consent, the authorization server sends a callback to the client application along with the authorization code. The next step is for the client application to send a request for the access token using this authorization code.

If the authorization server returns the authorization code in a property named as anything but code, you must map the property name with $auth_code.

The access token request is used to make a call for the access token. It is supposed to send the authorization code that is not resolved until the flow is executed. Therefore, the authorization code is passed by reference as ${auth_code} in the request.

The rules for creating the access token request remain unchanged from the OAuth Custom Two legged Flow option.

The Access Token Request value is formed using a URI syntax of the HTTP request used to fetch the access token. The URI syntax resembles cURL, but it is more basic and only supports the following options.

Option Value Description Required
-X GET | PUT | POST The HTTP verb in the access token request. Yes
-H -H “key: value” Add each header key value pair as described. There can be multiple headers. No
-d -d ‘data-as-string’ String data enclosed within single quotes. Escape any quotes within the data string. No
URI Uri (within quotes) - - Yes

Note:

  • Other curl options are not supported.

  • The easiest way to build this request is to use a free tool such as POSTMAN to build and validate the HTTP request to obtain an access token and then use the Generate Code Snippet/Code option to get a cURL syntax. Remove the curl from the beginning to get the URI syntax. The following example shows the URI syntax:

    -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'false' 'https://access_token_URI?code=${auth_code}&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=${redirect_uri}&grant_type=authorization_code'

Step 3: Optionally Configure the Refresh Token Request

Similar to an access token request, specify the refresh token request in URI syntax, if the authorization server supports a refresh.

Step 4: Define the Fetch Rules for Intermediate Tokens

By default, the $variables are mapped to property names containing relevant tokens as follows:

Property Name Default Mapping to a Property with Name Example Property Name
$auth_code code code
$access_token access.[tT]oken access_token
$refresh_token refresh.[tT]oken refresh_token
$token_type token.?[tT]ype token_type
$expiry expires_in expires_in

This step is not required and can be skipped.

However, if the access token response is not standard, then you must define rules to fetch tokens from the access token response.

Step 5: Define the Access Token Usage (Important)

Access token usage describes how to pass the access token to access a resource. Enter this information carefully because this usage governs how Oracle Integration Cloud Service passes the negotiated access token to the endpoint.