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 Authorization Code Policy

OAuth Authorization Code Policy

To support invoking of REST APIs secured with the OAuth-code-authorization grant, use the OAUTH_AUTHORIZATION_CODE_CREDENTIALS managed security policy. You can customize the security policy as needed for a connection definition.

Overview

The Authorization Code security policy is an OAuth flow where the resource owner is required to provide consent before an access token can be granted to the client application. This policy has two sections: Basic properties and extensibility properties.

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.

To add the OAuth Authorization Code 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.myappusercontent.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.auth.code.uri

Authorization Code URI

for example: https://accounts.myapp.com/o/oauth2/auth

This endpoint is the target of the initial request.

It handles active session lookup, authenticating the user, and user consent.

String

Yes

oauth.access.token.uri

Access Token URI

for example: https://accounts.myapp.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

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

    AuthorizationURL

    The authorization server expects the authorization URL.

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

    <oauth.auth.code.uri>?client_id=[YOUR_CLIENT_ID]&response_type=code&redirect_uri=[client's call back uri]&scope=[scope]

    The AccessTokenRequest that is expected by the authorization server.

    Determine the information that is needed and how the information must be sent to the authorization server to obtain an access token.

    The content sent in the HTTP body depends on the content type defined in the HTTP header. Rapid Adapter Builder supports two content types: "application/x-www-form-urlencoded" and "application/json".

    Example 1: With the content type as "application/x-www-form-urlencoded". 

    {
    "method": "POST",
    "uri": "<oauth.access.token.uri>",
    "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "body": {
            "code": "${auth_code}",
            "client_id": "[your_client_id]",
            "redirect_uri": "${redirect_uri}",
            "client_secret": "[your_client_secret]",
            "grant_type": "authorization_code"
        }
}

    In this case, the body is sent as: grant_type=authorization_code&code=tGzv3JOkF0XG5Qx2TlKWIA&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw&redirect_uri=https://your-app.com/oauth2/callback

    Example 2: With the content type as "application/json". 

    {
    "method": "POST",
    "uri": "<oauth.access.token.uri>",
    "headers": {
        "Content-Type": "application/json"
    },
    "body": {
            "code": "${auth_code}",
            "client_id": "[your_client_id]",
            "redirect_uri": "${redirect_uri}",
            "client_secret": "[your_client_secret]",
            "grant_type": "authorization_code"
        }
}

    In this case, the body is sent as: 

    {
                "code": "tGzv3JOkF0XG5Qx2TlKWIA",
                "client_id": "s6BhdRkqt3",
                "redirect_uri": "https://your-app.com/oauth2/callback",
                "client_secret": "7Fjfp0ZBr1KtDRbnfVdmIw",
                "grant_type": "authorization_code"
              }

    Example 3: With jq expressions for the uri field and an additional header. 

    {
            "method": "POST",
            "uri": "${.securityProperties.\"oauth.access.token.uri\"}",
            "headers": {
              "Content-Type": "application/x-www-form-urlencoded",
              "Authorization" : "${\"Basic \" + ((.securityProperties.\"oauth.client.id\")+\":\"+(.securityProperties.\"oauth.client.secret\") | @base64)}"
            },
            "body": {
              "grant_type": "authorization_code",
              "code": "${auth_code}",
              "redirect_uri": "${redirect_uri}"
            }
          }

    Example 4: Customized with a non-standard query parameter. 

    {
    "method": "POST",
    "uri": "<oauth.access.token.uri>",
    "params": {
        "template": {},
        "query": {
            "api-key": "${api-key}",
        }
    },
    "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "body": {
            "code": "${auth_code}",
            "client_id": "[your_client_id]",
            "redirect_uri": "${redirect_uri}",
            "client_secret": "[your_client_secret]",
            "grant_type": "authorization_code"
        }
}

    Response of the AccessTokenRequest

    The following code sample shows the response to the access token request:

    {
  "token_type": "Bearer",
  "access_token": "the access token value",
  "refresh_token": "the refresh token value"
  "expires_in": "3600"
}

    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 to refresh an expired access token.

    The content sent in the HTTP body depends on the content type defined in the HTTP header. Rapid Adapter Builder supports two content types: "application/x-www-form-urlencoded" and "application/json".

    Example 1: With the content type as "application/x-www-form-urlencoded". 

    "refreshTokenRequest": {
  "method": "POST",
  "uri": "https://www.sampleapis.com/oauth2/v4/token",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "body": {
    "refresh_token": "${refresh_token}",
    "client_id": "${.securityProperties.\"oauth.client.id\"}",
    "client_secret": "${.securityProperties.\"oauth.client.secret\"}",
    "grant_type": "refresh_token"
  }
}

    In this case, the body is sent as: grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw

    Example 2: With the content type as "application/json". 

    "refreshTokenRequest": {
  "method": "POST",
  "uri": "https://www.sampleapis.com/oauth2/v4/token",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "refresh_token": "${refresh_token}",
    "client_id": "${.securityProperties.\"oauth.client.id\"}",
    "client_secret": "${.securityProperties.\"oauth.client.secret\"}",
    "grant_type": "refresh_token"
  }
}

    In this case, the body is sent as: 

    {
                "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
                "client_id": "s6BhdRkqt3",
                "client_secret": "7Fjfp0ZBr1KtDRbnfVdmIw",
                "grant_type": "refresh_token"
              }

    Example 3: With jq expressions for the uri field and an additional header. 

    {
            "method": "POST",
            "uri": "${.securityProperties.\"oauth.access.token.uri\"}",
            "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}"
            }

    Example 4: Customized with non-standard query and body parameters. 

    {
    "method": "POST",
    "uri": "<oauth.access.token.uri>",
    "params": {
        "template": {},
        "query": {
            "api-key": "${api-key}",
        }
    },
    "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "body": 
   {
            "refresh_token": "${refresh_token}",
            "client_id": "[your_client_id]",
            "client_secret": "[your_client_secret]",
            "grant_type": "refresh_token",
            "account_id": "${account_id}"
        }
}

    Response of the RefreshTokenRequest

    The following code sample shows the response to the refresh token request:

    {
  "token_type": "Bearer",
  "access_token": "the access token value",
  "refresh_token": "the refresh token value"
  "expires_in": "3600"
}

    Method by which the application expects the access token to be sent along with the request
    Many applications expect additional information besides just 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 Authorization Code

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

  • oauth.auth.code.uri: Default value is https://accounts.sample.com/o/oauth2/auth
  • oauth.access.token.uri: Default value is https://www.sampleapis.com/oauth2/v4/token
  • oauth.scope: Default value is https://www.sampleapis.com/auth/drive
  • clientAuthentication: Default value is client_credentials_as_body
"securityPolicies": [
      {
        "type": "managed",
        "policy": "OAUTH_AUTHORIZATION_CODE_CREDENTIALS",
        "description": "Sample Authorization Policy",
        "displayName": "Sample Authorization Policy",
        "scope": "ACTION",
        "securityProperties": [
          {
            "name": "oauth.client.id",
            "displayName": "Sample Client ID",
            "description": "Sample Client ID",
            "shortDescription": "Sample Client ID",
            "hidden": false,
            "required": true
          },
          {
            "name": "oauth.client.secret",
            "displayName": "Sample Client Secret",
            "description": "Sample Client secret",
            "shortDescription": "Sample Client secret",
            "hidden": false,
            "required": true
          },
          {
            "name": "oauth.auth.code.uri",
            "default": "https://accounts.sample.com/o/oauth2/auth",
            "hidden": true,
            "required": true
          },
          {
            "name": "oauth.access.token.uri",
            "default": "https://www.sampleapis.com/oauth2/v4/token",
            "hidden": true,
            "required": true
          },
          {
            "name": "oauth.scope",
            "default": "https://www.sampleapis.com/auth/drive",
            "hidden": true,
            "required": true
          },
          {
            "name": "clientAuthentication",
            "default": "client_credentials_as_body",
            "hidden": true,
            "required": true
          }
        ]

Sample Code: OAuth Authorization Code, Extended

The following code sample shows extended code authorization policy.

"securityPolicies": [
      {
        "type": "managed",
        "policy": "OAUTH_AUTHORIZATION_CODE_CREDENTIALS",
        "description": "Sample Authorization Policy",
        "displayName": "Sample Authorization Policy",
        "scope": "ACTION",
        "securityProperties": [
          {
            "name": "oauth.client.id",
            "displayName": "Sample Client ID",
            "description": "Sample Client ID",
            "shortDescription": "Sample Client ID",
            "hidden": false,
            "required": true
          },
          {
            "name": "oauth.client.secret",
            "displayName": "Sample Client Secret",
            "description": "Sample Client secret",
            "shortDescription": "Sample Client secret",
            "hidden": false,
            "required": true
          },
          {
            "name": "oauth.auth.code.uri",
            "default": "https://accounts.sample.com/o/oauth2/auth",
            "hidden": true,
            "required": true
          },
          {
            "name": "oauth.access.token.uri",
            "default": "https://www.sampleapis.com/oauth2/v4/token",
            "hidden": true,
            "required": true
          },
          {
            "name": "oauth.scope",
            "default": "https://www.sampleapis.com/auth/drive",
            "hidden": true,
            "required": true
          },
          {
            "name": "clientAuthentication",
            "default": "client_credentials_as_body",
            "hidden": true,
            "required": true
          }
        ],
        "authExtension": {
          "authorizationURL": {
            "uri": "${.securityProperties.\"oauth.auth.code.uri\"}",
            "params": {
              "query": {
                "response_type": "code",
                "client_id": "${.securityProperties.\"oauth.client.id\"}",
                "redirect_uri": "${redirect_uri}",
                "scope": "${.securityProperties.\"oauth.scope\"}",
                "access_type": "offline"
              }
            }
          },
          "accessTokenRequest": {
            "method": "POST",
            "uri": "${.securityProperties.\"oauth.access.token.uri\"}",
            "headers": {
              "Content-Type": "application/x-www-form-urlencoded",
              "Authorization" : "${\"Basic \" + ((.securityProperties.\"oauth.client.id\")+\":\"+(.securityProperties.\"oauth.client.secret\") | @base64)}"
            },
            "body": {
              "grant_type": "authorization_code",
              "code": "${auth_code}",
              "redirect_uri": "${redirect_uri}"
            }
          },
          "refreshTokenRequest": {
            "method": "POST",
            "uri": "${.securityProperties.\"oauth.access.token.uri\"}",
            "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}"
            }
          },
          "fetchRules": {
            "auth_code": "code",
            "access_token": "access.[tT]oken",
            "refresh_token": "refresh.[tT]oken",
            "expiry": "expires.*",
            "token_type": "token.?[tT]ype"
          },
          "accessTokenUsage": {
            "headers": {
              "Authorization": "Bearer ${access_token}"
            }
          }
        }
      }
    ]