OAuth Client Credentials

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

• Overview
• Security Properties
• Extending the Security Policy
• Sample Code: OAuth Client Credentials
• Sample Code: OAuth Client Credentials, Extended

Overview

The client application accesses resources from a third party application without using resource owner intervention.

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

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": "${.securityProperties.oauth.access.token.uri}", "params": { "template": {}, "query": { "client_id": "${.securityProperties.oauth.client.id}", "redirect_uri": "${redirect_uri}", "client_secret": "${.securityProperties.oauth.client.secret}", "grant_type": "authorization_code" } }, "headers": { "Content-Type": "application/x-www-form-urlencoded", "Authorization" : "Basic " + ((.securityProperties.oauth.client.id)+\":\"+(.securityProperties.oauth.client.secret") | @base64) }, "body": "grant_type=client_credentials&scope=${.securityProperties.oauth.scope}" }
   Response of the AccessTokenRequest	Determine how the authorization server returns the response to an access token request and 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" }
   The method by which the application expects the access token to be sent along with the request while calling the API	Many applications expect additional information beyond the access token. For example, most applications expect a valid access token to be sent as a header, as the following example illustrates with the request. The following code snippet shows the access token usage according to RFC 6749: -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 Client Credentials

The following sample code shows the implementation for the Client Credentials security policy.

"securityPolicies": [
         {
             "type": "managed",
             "policy": "OAUTH_CLIENT_CREDENTIALS",
             "description": "OAUTH2 CLIENT CREDENTIALS Policy",
             "displayName": "OAUTH2 CLIENT 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/01131-a123-4321-a999-347dh4/oauth2/token",
                     "required": false,
                     "hidden": true
                 }, {
                     "name": "oauth.scope",
                     "default": "",
                     "required": false,
                     "hidden": true
                 }, {
                     "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 Client Credentials, Extended

The following code sample shows extended code authorization policy.

"securityPolicies": [
      {
        "type": "managed",
        "policy": "OAUTH_CLIENT_CREDENTIALS",
        "description": "OAuth Client Credentials Policy",
        "displayName": "OAuth Client 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://accounts.abacxyz.com/o/oauth2/token",
            "required": false,
            "hidden": true
          },
          {
            "name": "oauth.scope",
            "default": "https://www.abcxyz.com/auth/videos",
            "required": false,
            "hidden": true
          },
          {
            "name": "clientAuthentication",
            "default": "client_credentials_in_header",
            "required": false,
            "hidden": true
          }
        ],
        "authExtension": {
          "accessTokenRequest": {
            "method": "POST",
            "uri": "https://www.googleapis.com/oauth2/v4/token",
            "params": {
              "template": {
              },
              "query": {
                "client_id": "[your_client_id]",
                "client_secret": "[your_client_secret]",
                "grant_type": "client_credentials"
              }
            },
            "headers": {
              "Content-Type": "application/x-www-form-urlencoded"
            },
            "body": "false"
          },
          "fetchRules": {
            "access_token": "access.[tT]oken",
            "expiry": "expires.*",
            "token_type": "token.?[tT]ype"
          },
          "accessTokenUsage": {
            "headers": {
              "Authorization": "Bearer : ${access_token}"
            }
          }
        }
      }
    ],
    "test": "flow:testConnectionFlow"
  }