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
• Security Properties
• Extending the Security Policy
• Sample Code: OAuth Authorization Code
• Sample Code: OAuth Authorization Code, Extended

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 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: { "method": "POST", "uri": "<oauth.access.token.uri>", "params": { "template": {}, "query": { "code": "${auth_code}", "client_id": "[your_client_id]", "redirect_uri": "${redirect_uri}", "client_secret": "[your_client_secret]", "grant_type": "authorization_code" } }, "headers": { "Content-Type": "application/x-www-form-urlencoded" }, "body": "false" }
   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. The following code snippet shows the access token usage according to RFC 6749: { "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. { "method": "POST", "uri": "<oauth.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" }
   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. The following code sample shows the refresh token response: { "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.myapp.com/o/oauth2/auth
• oauth.access.token.uri: Default value is https://www.myappapis.com/oauth2/v4/token
• oauth.scope: Default value is https://www.myappapis.com/auth/drive
• clientAuthentication: Default value is client_credentials_as_body

"securityPolicies": [
    {
      "type": "managed",
      "policy": "OAUTH_AUTHORIZATION_CODE_CREDENTIALS",
      "description": "OAuth Authorization Code Policy",
      "displayName": "OAuth Authorization Code Policy",
      "scope": "ACTION",
      "securityProperties": [
        {
          "name": "oauth.client.id",
          "displayName": "OAuth2 Client ID",
          "description": "OAuth2  Client ID",
          "shortDescription": "OAuth2 Client ID",
          "hidden": false,
          "required": true
        },
        {
          "name": "oauth.client.secret",
          "displayName": "OAuth2 Client Secret",
          "description": "OAuth2 Client secret",
          "shortDescription": "OAuth2 Client secret",
          "hidden": false,
          "required": true
        },
        {
          "name": "oauth.auth.code.uri",
          "default": "https://accounts.myapp.com/o/oauth2/auth",
          "hidden": true,
          "required": true
        },
        {
          "name": "oauth.access.token.uri",
          "default": "https://www.myappapis.com/oauth2/v4/token",
          "hidden": true,
          "required": true
        },
        {
          "name": "oauth.scope",
          "default": "https://www.myappapis.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": "Authorization Policy",
        "displayName": "Authorization 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.myapp.com/o/oauth2/token",
            "required": false,
            "hidden": true
          },
          {
            "name": "oauth.scope",
            "default": "https://www.myappapis.com/auth/youtube",
            "required": false,
            "hidden": true
          },
          {
            "name": "oauth.auth.code.uri",
            "default": "https://accounts.myapp.com/o/oauth2/v2/auth",
            "required": false,
            "hidden": true
          },
          {
            "name": "clientAuthentication",
            "default": "client_credentials_in_header",
            "required": false,
            "hidden": true
          }
        ],
        "authExtension": {
          "authorizationURL": {
            "uri": "https://accounts.myapp.com/o/oauth2/auth",
            "params": {
              "template": {
              },
              "query": {
                "response_type": "code",
                "client_id": "[your_client_id]",
                "redirect_uri": "${redirect_uri}",
                "scope": "[your_scope]",
                "access_type": "offline",
                "approval_prompt": "force"
              }
            }
          },
          "accessTokenRequest": {
            "method": "POST",
            "uri": "https://www.myappapis.com/oauth2/v4/token",
            "params": {
              "template": {
              },
              "query": {
                "code": "${auth_code}",
                "client_id": "[your_client_id]",
                "redirect_uri": "${redirect_uri}",
                "client_secret": "[your_client_secret]",
                "grant_type": "authorization_code"
              }
            },
            "headers": {
              "Content-Type": "application/x-www-form-urlencoded"
            },
            "body": "false"
          },
          "refreshTokenRequest": {
            "method": "POST",
            "uri": "https://www.myappapis.com/oauth2/v4/token",
            "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": {
            "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}"
            },
            "params": {
            }
          }
        }
      }
    ],
    "test": "flow:testConnectionFlow"
  }