X

An Oracle blog about Adapters

  • March 10, 2017

OAuth Custom Two Legged Security Policy In Oracle Integration Cloud

Oracle REST Adapter provides a comprehensive way for consuming external RESTful APIs including secure APIs. The available methods of connecting securely with REST APIs are presented in this blog post.

Nowadays, most of the HTTP services use the OAuth authorization framework for protecting their resources. 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 allowing the third-party application to obtain access on its own behalf.

Oracle REST Adapter provides the following security policies interacting with OAuth 2 protected resources.

  • OAuth Client Credentials
  • OAuth Resource Owner Password Credentials
  • OAuth Authorization Code Credentials

The OAuth2 specification deliberately leaves out the exact mechanism for client authentication. Access token attributes and the methods used to access protected resources are also beyond the scope of this specification. As a result, there are many implementations of OAuth2 that cannot be addressed using the standard security policies listed above.

In this blog post, we will look at the more flexible OAuth Custom Two Legged security policy and how it can be used to integrate with services that are protected using OAuth Client Credentials or OAuth Resource Owner Password Credentials.

Oracle Integration cloud provides a re-usable connection that can be used to specify the security policy for accessing protected APIs. Once configured, users can test, save and complete the connection and use this in integration flows just like any other connection.


Figure 1 Security Policies Available in the Generic Rest Adapter


 

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

Usually an HTTP request is sent to the authorization server passing the client application credentials (please note 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.

Let's look at a sample access token request with twitter (a popular microblogging site that supports OAuth2)



@ref: https://dev.twitter.com/oauth/application-only

According to the documentation, the following HTTP request is required to obtain an access token. The authorization header is obtained by HTTP Basic Auth by using the clientid and client secret.

If the request was formatted correctly, the server will respond with a JSON-encoded payload:

This is fairly straightforward. Now let's take a closer look at the OAuth Custom Two Legged security policy and describe each field in the context of this problem. 
 

Step 1: Configure the access token request
 


Figure 2 : OAuth Custom Two Legged Flow


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

SNO.

Option

value

description

Required

1.       

-X

GET|PUT|POST

http verb
in the access token request

Yes

2.       

-H

-H “key:
value”

Each
header key value pair should be added as described. There can be multiple
headers.

No

3.       

-d

-d
‘data-as-string’

String
data enclosed within single quotes. Any quotes within the data string should
be escaped.

No

4.       

Uri

URI within
quotes

The authorization service endpoint.

Yes

Figure 3 URI Syntax options

* Please note: other curl options are not supported. 


The easiest way to build this request is by using a free tool like POSTMAN or Restlet Client 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 head to get the URI syntax.

Exmaple URI Syntax:


-X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Basic 3NmM0J6czJG==" -d 'grant_type=client_credentials' https://api.twitter.com/oauth2/token

 

The URI syntax allows the user to control the access token request
 

Step 2: Parse and extract tokens from Access token response.

If all is well with the request, then the authorization server will usually return with a response with a success status. The response would typically contain the access token and may also contain a few operational details about the token like the type of this token, its expiry and a refresh token as shown below.


To be able to retrieve the relevant parameters from the response, the user is required to provide the appropriate property names that contain the relevant values. This configuration is referred to as the fetch rules.

Figure 4 Variables along with property mapping

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

Sno.

Variable
name

Default
mapping to a property with name

Example
property name

1.       

$access_token

access.[tT]oken

access_token

2.       

$refresh_token

refresh.[tT]oken

refresh_token

3.       

$token_type

token.?[tT]ype

token_type

4.       

$expiry

expires_in

expires_in

Figure 5 Default variables and their property mappings

As you can see, the default values match the sample response above so this step is not required and can be skipped. However, if the access token response is not standard, then users need to define rules to fetch tokens from the access token response.

For example, let’s assume the access token response was as follows:



In this case, we can see that the authorization server returned a response but chose to specify the access token as api-key and the expiry as expiry and the refresh token as extended-key. Fetch rules allow to map these properties to the variables.

Sno.

Variable
name

Default
mapping to a property with name

New value

1.       

$access_token

access.[tT]oken : regex

api-key

2.       

$expiry

expires_in

expiry

3. $refresh_token refresh.[tT]oken : regex extended-key

      
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 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)

Once an access token is obtained, it is important to know how this will be used to access protected resources. Access token usage describes how the access token should be passed for accessing a resource. Please enter this information carefully since this usage will govern how Oracle REST Adapter will pass the negotiated access token to the endpoint.

Figure 6 Access Token Usage

The default value for this field is:

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

At runtime, the value of ${token_type} and ${access_token} is retrieved depending on the fetch rule and passed as an Authorization header along with the endpoint request.

* Literal value can also be used in the usage as follows:

-H api-key: Bearer ${access_token}

 

Sno.

Access
token usage

Description

example

1.       

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

Access
token is passed as a header at runtime for accessing the protected resource.

-H
Authorization: Bearer AASDFADADX

2.       

?api_key=${access_token}

Access
token is passed as a query parameter at runtime for accessing the protected
resource

http://someapi.com/employee?api_key=ASDFADAX

 

Step 3: Refresh token request (optional)

Some providers provide a mechanism to refresh a given access token. This sort of thing is generally part of Resource Owner Password Credentials flow but we have seen instances where people use this with client credentials as well even when the spec says otherwise.

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

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

Sample refresh token request:

-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 which is replaced with the actual value of the current refresh token at runtime.

In this first series, we saw some of the basic constructs of OAUTH Custom Two Legged Policy. In the next part we will see how OAUTH Custom Three Legged Policy works. In the final part will list down the sample configuration for some of the popular OAUTH Protected services.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.