1. Using the REST Adapter with Oracle Integration Generation 2
  2. Implement Common Patterns Using the REST Adapter
  3. OAuth-Protected Patterns

OAuth-Protected Patterns

You can use the REST Adapter to implement the following common patterns using OAuth protection.

Configure the REST Adapter to Consume a REST API Protected with OAuth Custom Two Legged Token-Based Authentication

This section provides an overview of the OAuth Custom Two Legged Flow security policy. This policy is useful when the Basic Authentication security policy is not sufficient.

Most HTTP services typically use the OAuth authorization framework to protect their resources. In accordance with the OAuth 2.0 specification, the OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service or by enabling the third-party application to obtain access on its own behalf.

The REST Adapter enables you to integrate with any REST-enabled service including OAuth services. To interact with an OAuth endpoint, you must create a one-time reusable connection on the Connections page of Oracle Integration. Configure the connection with the base URI and security configuration.

The following security policy options are available on the Connections page for the REST Adapter.
Description of custom_2_leg_flow.png follows
Description of the illustration custom_2_leg_flow.png

Each option is applicable in a different context and is used to negotiate and obtain a valid access token. Read your REST service provider documentation to identify the applicable policy.

The following section describes a flexible OAuth security policy that can be used in OAuth custom two legged flows called as an OAuth Custom Two Legged Flow.

OAuth 2.0 specification defines the following OAuth flows:

  • OAuth Client Credentials

  • OAuth Resource Owner Password Credentials

  • OAuth Authorization Code Credentials

  • OAuth Implicit Grant Authorization

The OAuth Client Credentials and OAuth Resource Owner Password Credentials options are categorized as OAuth custom two legged flows because the client application directly obtains access on its own without the resource owner’s intervention.

An HTTP request is typically sent to the authorization server passing the client application credentials (note that these are different from the resource owner credentials and can be obtained by registering the client application with the authorization server), the grant type and scope, and other required properties. The authorization server responds to this request by sending an access token, optionally with a token type, an expiry, and sometimes a refresh token.

The following example describes a sample access token request with Twitter (a popular microblogging site that supports OAuth2). For more information about Twitter developer documentation, visit https://dev.twitter.com/oauth/application-only.
POST /oauth2/token HTTP/1.1
Host: api.twitter.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic a3NmM1yRnFweAx==

grant_type=client_credentials

According to the Twitter developer documentation, this request is required to obtain an access token from Twitter. An HTTP basic authentication header is created by using the client ID and client secret.

If the request is formatted correctly, the server responds with a JSON-encoded payload. This is fairly straight forward. 
{"token_type":"bearer","access_token":"AAAAAAAAAA"}

The following steps describe the OAuth Custom Two Legged Flow security policy and each field in the context of this scenario.

Step 1: Configure the Access Token Request


Description of oic_3_custom_2_leg_flow2_old.png follows
Description of the illustration oic_3_custom_2_leg_flow2_old.png

The Access Token Request field is formed using the URI syntax of the HTTP request used to fetch the access token. The URI syntax resembles cURL but 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
Multiple -d options in the OAuth custom two legged flow security policy can be compressed into a single -d as follows:
-d "grant_type=client_credentials&client_id=123"

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 curl syntax. Remove the curl from the beginning to get the URI syntax. The following example shows URI syntax: 

    -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: 
Basic a3NmM0J6czJG==" -d 'grant_type=client_credentials' 
https://api.twitter.com/oauth2/token
The URI syntax allows you to control the access token request. The following is a typical access token response.
{
  "access_token": "1-253912-240049694-f85c1d679211c",
  "expires_in": 21599,
  "token_type": "Bearer",
  "refresh_token": "5707efdf04912f53b61cb5ec5dc7f166"
}

Step 2: Parse and Extract Tokens from Access Token Response

Note:

Skip this step if the access token response has properties as highlighted previously.

If the request is good, the authorization server returns an HTTP response with a success status. The response contains the access token and may also contain several operational details about the token such as the type of the token, its expiry, and refresh token as described previously.


Description of oic3_custom_2_leg_flow3.png follows
Description of the illustration oic3_custom_2_leg_flow3.png

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
$access_token access.[tT]oken access_token
$refresh_token refresh.[tT]oken refresh_token
$expiry expires_in expires_in
$token_type token.?[tT]ype token_type

The default values match the sample response. Therefore, 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.

For example, assume the access token response is as follows:
{   "access_token": "1-253912-240049694-f85c1d679211c", "expiry": 21599, 
"token_type": "Bearer",   "extended_token": "5707efdf04912f53b61cb5ec5dc7f166" }

In this case, the authorization server returns a response, but chooses to specify the expiry and the refresh token differently. This step is required to map these properties to the variables.

Variable Name Default Mapping to a Property with Name Example Property Name
$refresh_token extended_token extended_token
$expiry Expiry Expiry

Variables can be used in the configuration using the ${variable} syntax once a value has been assigned. For example, $access_token is assigned a value after an access token request is made. The value of this variable may be useful while specifying the access_token usage or the refresh_token_request later.

Step 3: 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 passes the negotiated access token to the endpoint.


Description of oic3_custom_2_leg_flow4_old.png follows
Description of the illustration oic3_custom_2_leg_flow4_old.png

The default value for this field is:

-H Authorization: ${token_type} ${access_token}

At runtime, the values of ${token_type} and ${access_token} are retrieved based on the fetch rule and passed as an authorization header along with the endpoint request.

The literal value can also be used as follows: 
-H API-Token: Bearer ${access_token}
Access Token Usage Description Example 
-H Authorization: ${token_type} ${access_token}
 The access token is passed as a header at runtime for accessing the protected resource. -H Authorization: Bearer AASDFADADX 
?api_key=${access_token}
 The access token is passed as a query parameter at runtime for accessing the protected resource. http://someapi.com/employee?api_key=ASDFADAX

Step 4: Refresh Token Request (Optional)

Some providers provide a mechanism to refresh a given access token. This sort of method is generally part of a resource owner password credentials (ROPC) flow. However, there have been instances where you also use this with client credentials even when the specification says otherwise.

The refresh token request typically takes the refresh token and returns a new access token as a response along with operational attributes such as the type of token, its expiry, and another refresh token.

The refresh token request must also be specified in a syntax similar to the access token request and prescribes to the same rules.

A sample refresh token request is as follows:

-X POST 'https://sample.com/oauth2/token?refresh_token=${refresh_token}
&client_id=[YOUR_CLEINT_ID]&client_secret=[YOUR_CLIENT_SECRET]&grant_type=refresh_token'

This request contains a variable that is replaced with the actual value of the current refresh token at runtime.

See Configure Connection Security.

Configure the REST Adapter to Consume a REST API Protected with OAuth Custom Three Legged Flow 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 a typical 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 oic3_custom_3_leg_flow_old.png follows
Description of the illustration oic3_custom_3_leg_flow_old.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 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
Multiple -d options in the OAuth Custom Three Legged Flow security policy can be compressed into a single -d as follows:
-d "grant_type=client_credentials&client_id=123"

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 passes the negotiated access token to the endpoint.

See Configure Connection Security.

Configure the REST Adapter to Consume a REST API Protected with OAuth 1.0 One-Legged Authentication

This section provides an overview of the OAuth 1.0 One-Legged Authentication security policy in the Connections page. This protocol enables web sites or applications (consumers) to access protected resources from a web service (a service provider) through an API without requiring you to disclose your service provider credentials to consumers.

Note:

No customization is required in this policy. This is a standard OAuth policy unlike custom 2-legged and custom 3-legged OAuth policies.
You can use this security policy with service providers such as the following:

  • Oracle NetSuite can expose restlets as REST APIs that are protected by OAuth 1.0 One-Legged Authentication. For example: 

    https://rest.netsuite.com/app/site/hosting/restlet.nl?script=474&deploy=1

    You must be a member of Oracle NetSuite to access this restlet.

    This restlet returns a greeting in HTML.

  • Twitter accounts can be protected by OAuth 1.0 One-Legged Authentication.

Configure the following fields on the Credentials dialog of the Connections page. These credentials are provided by the service provider (Oracle NetSuite or Twitter).


Description of one_legged_auth.png follows
Description of the illustration one_legged_auth.png


Description of oic3_one_legged_auth2.png follows
Description of the illustration oic3_one_legged_auth2.png

  • Consumer Key — Specify the key that identifies the client making the request.

  • Consumer Secret — Specify the consumer secret that authorizes the client making the request.

  • Token — Specify the token that accesses the protected resource.

  • Token Secret — Specify the token secret that generates the signature for the request.

  • Realm — Specify the realm that identifies the account.

See Configure Connection Security.

Allow Client Applications to Consume an Integration Exposed as an OAuth-Protected REST API

Integrations in Oracle Integration configured using the REST Adapter as a trigger are automatically exposed as OAuth-protected REST resources. These integrations/resources can be consumed using OAuth access tokens. To access an Oracle Integration endpoint using an OAuth token, you must first acquire the token.

See Authenticate Requests for Invoking Oracle Integration Flows.