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 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.
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.
{"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
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 |
-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 thecurl
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
{
"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.
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.
{ "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.
-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.
-H API-Token: Bearer ${access_token}
Access Token Usage | Description | Example |
---|---|---|
|
The access token is passed as a header at runtime for accessing the protected resource. | -H Authorization: Bearer AASDFADADX |
|
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.
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 icsre_dt_001.png follows](img/icsre_dt_001.png)
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. |
-
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
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.
${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 |
-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 thecurl
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.
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.-
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).
-
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.
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.