1. Using the Rapid Adapter Builder with Oracle Integration 3
  2. Work with the Adapter Definition Document
  3. Update Connection Definitions
  4. Understand Security Policies in Connection Definitions
  5. Learn About Security Policies for Invoke Connections
  6. OAuth Resource Owner Password Credentials

OAuth Resource Owner Password Credentials

To support invoking of REST APIs secured using the OAuth ROPC grant, use the OAUTH_RESOURCE_OWNER_PASSWORD_CREDENTIALS managed security policy. You can customize the security policy as needed for a connection definition.

Overview

With the OAuth Resource Owner Password Credentials security policy, you make a REST call to get an access token, and you use the access token to call an API.

Since the resource owner shares its credentials with the client, this policy is used when there is a high degree of trust between the resource owner and the client. Oracle Integration ensures that credentials are stored securely in a vault.

The default implementation of this policy is RFC 6749. However, an implementation may vary from how the RFC illustrates. Therefore, you extend the RFC 6749 compliant policy to override one or more steps. For example:

  • To get the access token, you must provide the request to the authorization server in a specific format. RFC 6749 defines the format. However, different providers might require a different format. For instance, a server might require additional information beyond the authorization header; or a server might require the request to be part of a JSON body. Review the documentation for the authorization server to determine the required format.
  • After you make a valid request for an access token, the authorization server returns a 200 response with some body. RFC 6749 specifies the format of the response. However, some authorization servers customize the response. For instance, the response might be XML instead of JSON. Often, the response is nested JSON that includes a lot of metadata and a nested token. You need to be able to find the access token and its expiry in the response. Review the documentation for the authorization server to understand the format of the response.

To add the OAuth Resource Owner Password Credentials policy to your document, use the available authentication scheme template. See Implement a New Connection Definition.

Security Properties

A connection definition that uses this security policy defines the following properties in the securityProperties section. See Connection Properties and Sample Code.

The values in the name, displayName, shortDescription, and description columns list the default values that appear when you insert a security policy into an adapter definition document. You can update these values if needed.

name displayName shortDescription description Data type Required

oauth.client.id

Client Id

for example: 123-xxx.apps.googleusercontent.com

Used to identify the client(the software requesting an access token) that is making the request.

The value passed in this parameter must exactly match the value shown in your API console project.

String

Yes

oauth.client.secret

Client Secret

<unique random string matches your API console project>

Used to authorize the client(the software requesting an access token) that is making the request.

The value passed in this parameter must exactly match the value shown in your API console project.

Password

Yes

oauth.access.token.uri

Access Token URI

for example: https://accounts.google.com/o/oauth2/token

A request should be sent to this URI for obtaining an access token.

String

Yes

oauth.scope

Scope

for example: read,write.

Permissions your application is requesting on behalf of the user.

String

No

username

Username

Use UserName

A username credential

String

Yes

password

Password

Enter Password

A password credential

Password

Yes

Extending the Security Policy

If needed, extend the security policy.

A security policy defines the structure of an HTTP request. The default implementation of this security policy is RFC 6749. However, an implementation may vary from how the RFC illustrates. If the application for which you're creating an adapter supports the standard security policy but requires additional information, you can extend the RFC 6749 compliant policy to override one or more steps. When you extend a security policy, you change the structure of the request.

  1. Read your OAuth provider documentation and collect the following information.
    Information to collect Description

    AccessTokenRequest

    The authorization server expects the AccessTokenRequest. Determine the information that is needed and the method for sending the information to the authorization server.

    The following example is sample code for accessing a token request according to RFC 6749:

    {
    "method": "POST",
    "uri": "<oauth.access.token.uri>",
    "params": {
        "template": {},
        "query": {
        }
    },
    "headers": {
        "Content-Type": "application/x-www-form-urlencoded",
        "Accept": "application/json",
        "Authorization" : "Basic " + ((.securityProperties.oauth.client.id)+\":\"+(.securityProperties.oauth.client.secret") | @base64)
    },
    "body": "grant_type=password&client_id=&client_secret=&username=&password="
}

    Response of the AccessTokenRequest

    Determine how the authorization server returns a response to an access token request, as well as the information that is returned in the response. The type of response is different for each provider. Most providers return an access token response, as shown in the following example:

    {
  "token_type": "Bearer",
  "access_token": "the access token value"
}

    RefreshTokenRequest that is expected by the authorization server

    Determine the information that is needed and how the information must be sent to the authorization server.

    The following code snippet shows the access token usage according to RFC 6749:

    {
    "method": "POST",
    "uri": "<oauth.access.token.uri>",
    "params": {
        "template": {},
        "query": {
        }
    },
    "headers": {
        "Content-Type": "application/x-www-form-urlencoded",
        "Authorization" : "Basic " + ((.securityProperties.oauth.client.id)+\":\"+(.securityProperties.oauth.client.secret") | @base64)
    },
    "body": "grant_type=refresh_token&refresh_token=${refresh_token}
}

    Response of the RefreshTokenRequest

    Determine how the authorization server returns the response to a refresh token request and the information that is returned in the response.

    {
  "token_type": "Bearer",
  "access_token": "the access token value"
}

    The method by which the application expects the access token to be sent along with the request
    Many applications expect additional information beyond the access token. 
    -H "Authorization: Bearer [access_token]"
  2. Extend the managed security policy as required by modifying one or more steps in the OAuth flow.

Sample Code: OAuth Resource Owner Password Credentials

In the example, the following security properties have default values and are hidden:

  • oauth.access.token.uri: Default value is https://login.eloqua.com/auth/oauth2/token
  • oauth.scope: Default value is https://www.googleapis.com/auth/drive
  • clientAuthentication: Default value is client_credentials_as_header
  • oauth.request.content.type: Default value is application/x-www-form-urlencoded
"securityPolicies": [
         {
             "type": "managed",
             "policy": "OAUTH_RESOURCE_OWNER_PASSWORD_CREDENTIALS",
             "description": "OAuth Resource Owner Password Credentials",
             "displayName": "OAuth Resource Owner Password Credentials",
             "scope": "ACTION",
             "securityProperties": [
                 {
                     "name": "oauth.client.id",
                     "displayName": "Client Id",
                     "description": "Client Id",
                     "shortDescription": "Client Id",
                     "required": true,
                     "hidden": false
                 }, {
                     "name": "oauth.client.secret",
                     "displayName": "Client Secret",
                     "description": "Client Secret",
                     "shortDescription": "Client Secret",
                     "required": true,
                     "hidden": false
                 }, {
                     "name": "oauth.access.token.uri",
                     "default": "https://login.eloqua.com/auth/oauth2/token",
                     "required": false,
                     "hidden": true
                 }, {
                     "name": "oauth.scope",
                     "default": "",
                     "required": false,
                     "hidden": false
                 }, {
                     "name": "username",
                     "displayName": "Username",
                     "description": "The resource owner user name.",                        
                     "required": true,
                     "hidden": false
                 }, {
                     "name": "password",                        
                     "displayName": "Password",
                     "description": "The resource owner user password.",                        
                     "required": true,
                     "hidden": false                     
                 }, {                         
                     "name": "oauth.request.content.type",
                     "default": "application/x-www-form-urlencoded",
                     "required": false,
                     "hidden": true
                 }, {
                     "name": "clientAuthentication",
                     "default": "client_credentials_as_header",
                     "required": false,
                     "hidden": true
                 }
             ]                 
         }
     ],
     "test": "flow:TestConnectionFlow"

Sample Code: OAuth Resource Owner Password Credentials, Extended

The following code sample shows extended code authorization policy:

"securityPolicies": [
      {
        "type": "managed",
        "policy": "OAUTH_RESOURCE_OWNER_PASSWORD_CREDENTIALS",
        "description": "OAuth Resource Owner Password Credentials Policy",
        "displayName": "OAuth Resource Owner Password Credentials Policy",
        "scope": "ACTION",
        "securityProperties": [
                    {
                       "name": "oauth.client.id",
                       "displayName": "Client Id",
                       "description": "Client Id",
                       "shortDescription": "Client Id",
                       "required": true,
                       "hidden": false
                   }, {
                       "name": "oauth.client.secret",
                       "displayName": "Client Secret",
                       "description": "Client Secret",
                       "shortDescription": "Client Secret",
                       "required": true,
                       "hidden": false
                   }, {
                       "name": "oauth.access.token.uri",
                       "default": "https://login.ABCXYZ.com/auth/oauth2/token",
                       "required": false,
                       "hidden": true
                   }, {
                       "name": "oauth.scope",
                       "default": "",
                       "required": false,
                       "hidden": false
                   }, {
                       "name": "username",
                       "displayName": "Username",
                       "description": "The resource owner user name.",                        
                       "required": true,
                       "hidden": false
                   }, {
                       "name": "password",                        
                       "displayName": "Password",
                       "description": "The resource owner user password.",                        
                       "required": true,
                       "hidden": false                     
                   }, {                         
                       "name": "oauth.request.content.type",
                       "default": "application/x-www-form-urlencoded",
                       "required": false,
                       "hidden": true
                   }, {
                       "name": "clientAuthentication",
                       "default": "client_credentials_as_header",
                       "required": false,
                       "hidden": true
                   }
        ],
        "authExtension": {
          "accessTokenRequest": {
            "method": "POST",
            "uri": "<authorization_uri>",
            "params": {
              "template": {
              },
              "query": {
                "client_id": "[your_client_id]",
                "client_secret": "[your_client_secret]",
                "grant_type": "password"
              }
            },
            "headers": {
              "Content-Type": "application/x-www-form-urlencoded",
              "Authorization": "Basic " + ({.securityProperties.oauth.client.id}+\":\"+{.securityProperties.oauth.client.secret"}) | @base64)
            },
            "body": "false"
          },
          "refreshTokenRequest": {
            "method": "POST",
            "uri": "<access_token_uri>",
            "params": {
              "template": {
              },
              "query": {
                "refresh_token": "${refresh_token}",
                "client_id": "[your_client_id]",
                "client_secret": "[your_client_secret]",
                "grant_type": "refresh_token"
              }
            },
            "headers": {
              "Content-Type": "application/x-www-form-urlencoded"
            },
            "body": "false"
          },
          "fetchRules": {
            "access_token": "access.[tT]oken",
            "refresh_token": "refresh.[tT]oken",
            "expiry": "expires.*",
            "token_type": "token.?[tT]ype"
          },
          "accessTokenUsage": {
            "headers": {
              "Authorization": "Bearer : ${access_token}"
            }
          }
        }
      }
    ],
    "test": "flow:testConnectionFlow"
  }