OAuth 2 authorization
Destination SDK supports several authorization methods to your destination. Among these is the option to authenticate to your destination by using the OAuth 2 authorization framework.
This page describes the various OAuth 2 authorization flows supported by Destination SDK, and provides instructions to set up OAuth 2 authorization for your destination.
Supported integration types supported-integration-types
Refer to the table below for details on which types of integrations support the functionality described on this page.
How to add OAuth 2 authorization details to your destination configuration how-to-setup
Prerequisites in your system prerequisites
As a first step, you must create an app in your system for Adobe Experience Platform, or otherwise register Experience Platform in your system. The goal is to generate a client ID and client secret, which are needed to authenticate Experience Platform to your destination.
As part of this configuration in your system, you need the Adobe Experience Platform OAuth 2 redirect/callback URLs, which you can get from the list below.
https://platform-va7.adobe.io/data/core/activation/oauth/api/v1/callback
https://platform-nld2.adobe.io/data/core/activation/oauth/api/v1/callback
https://platform-aus5.adobe.io/data/core/activation/oauth/api/v1/callback
https://platform-can2.adobe.io/data/core/activation/oauth/api/v1/callback
https://platform-gbr9.adobe.io/data/core/activation/oauth/api/v1/callback
https://platform.adobe.io/data/core/activation/oauth/api/v1/callback
At the end of this step, you should have:
- A client ID;
- A client secret;
- Adobe’s callback URL (for the authorization code grant).
What you need to do in Destination SDK to-do-in-destination-sdk
To set up OAuth 2 authorization for your destination in Experience Platform, you must add your OAuth 2 details to the destination configuration, under the customerAuthenticationConfigurations
parameter. See customer authentication for detailed examples. Specific instructions about which fields you need to add to your configuration template, depending on your OAuth 2 authorization grant type, are further below on this page.
Supported OAuth 2 grant types oauth2-grant-types
Experience Platform supports the three OAuth 2 grant types in the table below. If you have a custom OAuth 2 setup, Adobe is able to support it with the help of custom fields in your integration. Refer to the sections for each grant type for more information.
- You provide the input parameters as instructed in the sections below. Adobe-internal systems connect to your platform’s authorization system and grab output parameters, which are used to authenticate the user and maintain authorization to your destination.
- The input parameters highlighted in bold in the table are required parameters in the OAuth 2 authorization flow. The other parameters are optional. There are other custom input parameters that are not shown here, but are described at length in the sections Customize your OAuth 2 configuration and Access token refresh.
- clientId
- clientSecret
- scope
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- scope
- accessTokenUrl
- username
- password
- accessToken
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- scope
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
The above table lists the fields that are used in standard OAuth 2 flows. In addition to these standard fields, various partner integrations may require additional inputs and outputs. Adobe has designed a flexible OAuth 2 authorization framework for Destination SDK that can handle variations to the above standard fields pattern while supporting a mechanism to automatically regenerate invalid outputs, such as expired access tokens.
The output in all cases includes an access token, which is used by Experience Platform to authenticate and maintain authorization to your destination.
The system that Adobe has designed for OAuth 2 authorization:
- Supports all three OAuth 2 grants while accounting for any variations in them, such as additional data fields, non-standard API calls, and more.
- Supports access tokens with varying lifetime values, be it 90 days, 30 minutes, or any other lifetime value that you specify.
- Supports OAuth 2 authorization flows with or without refresh tokens.
OAuth 2 with Authorization Code authorization-code
If your destination supports a standard OAuth 2.0 Authorization Code flow (read the RFC standards specs) or a variation of it, consult the required and optional fields below:
- clientId
- clientSecret
- scope
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
To set up this authorization method for your destination, add the following lines to your configuration, when you create a destination configuration:
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_AUTHORIZATION_CODE",
"accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
"authorizationUrl": "https://www.moviestar.com/dialog/OAuth",
"refreshTokenUrl": "https://api.moviestar.com/OAuth/refresh_token",
"clientId": "Experience-Platform-client-id",
"clientSecret": "Experience-Platform-client-secret",
"scope": ["read", "write"]
}
]
//...
}
authType
grant
accessTokenUrl
authorizationUrl
refreshTokenUrl
refreshTokenUrl
is the same as the accessTokenUrl
.clientId
clientSecret
scope
OAuth 2 with Password Grant
For the OAuth 2 Password grant (read the RFC standards specs), Experience Platform requires the user’s username and password. In the authorization flow, Experience Platform exchanges these credentials for an access token and, optionally, a refresh token.
Adobe makes use of the standard inputs below to simplify destination configuration, with the ability to override values:
- clientId
- clientSecret
- scope
- accessTokenUrl
- username
- password
- accessToken
- expiresIn
- refreshToken
- tokenType
username
and password
in the configuration below. When you add "grant": "OAUTH2_PASSWORD"
in the destination configuration, the system will request the user to provide a username and password in the Experience Platform UI, when they authenticate to your destination.To set up this authorization method for your destination, add the following lines to your configuration, when you create a destination configuration:
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_PASSWORD",
"accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
"clientId": "Experience-Platform-client-id",
"clientSecret": "Experience-Platform-client-secret",
"scope": ["read", "write"]
}
]
authType
grant
accessTokenUrl
clientId
clientSecret
scope
OAuth 2 with Client Credentials Grant
You can configure an OAuth 2 Client Credentials (read the RFC standards specs) destination, which supports the standard inputs and outputs listed below. You have the ability to customize the values. See Customize your OAuth 2 configuration for details.
- clientId
- clientSecret
- scope
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
To set up this authorization method for your destination, add the following lines to your configuration, when you create a destination configuration:
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_CLIENT_CREDENTIALS",
"accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
"refreshTokenUrl": "https://api.moviestar.com/OAuth/refresh_token",
"clientId": "Experience-Platform-client-id",
"clientSecret": "Experience-Platform-client-secret",
"scope": ["read", "write"]
}
]
//...
}
authType
grant
accessTokenUrl
refreshTokenUrl
refreshTokenUrl
is the same as the accessTokenUrl
.clientId
clientSecret
scope
Customize your OAuth 2 configuration customize-configuration
The configurations described in the sections above describe standard OAuth 2 grants. However, the system designed by Adobe provides flexibility so you can use custom parameters for any variations in the OAuth 2 grant. To customize the standard OAuth 2 settings, use the authenticationDataFields
parameters, as shown in the examples below.
Example 1: Using authenticationDataFields
to capture information coming from the authorization response example-1
In this example, a destination platform has refresh tokens that expire after a certain amount of time. In this case, the partner sets up the refreshTokenExpiration
custom field to get the refresh token expiration from the refresh_token_expires_in
field in the API response.
{
"customerAuthenticationConfigurations":[
{
"authType":"OAUTH2",
"options":{
},
"grant":"OAUTH2_AUTHORIZATION_CODE",
"accessTokenUrl":"https://api.moviestar.com/OAuth/access_token",
"authorizationUrl":"https://api.moviestar.com/OAuth/authorization",
"scope":[
"read",
"write",
"delete"
],
"refreshTokenUrl":"https://api.moviestar.com/OAuth/accessToken",
"clientSecret":"client-secret-here",
"authenticationDataFields":[
{
"name":"refreshTokenExpiration",
"title":"Refresh Token Expires In",
"description":"Time in seconds when the refresh token will expire",
"type":"string",
"isRequired":false,
"source":"CUSTOMER",
"authenticationResponsePath":"refresh_token_expires_in"
}
]
}
]
}
Example 2: Using authenticationDataFields
to provide a special refresh token example-2
In this example, a partner sets up their destination to provide a special refresh token. Furthermore, the expiration date for access tokens is not returned in the API response so they can hardcode a default value, in this case 3600 seconds.
"authenticationDataFields": [
{
"name": "refreshToken",
"value": "special_refresh_token"
},
{
"name": "expiresIn",
"value": 3600
}
]
Example 3: The user inputs client ID and client secret when they configure the destination example-3
In this example, instead of creating a global client ID and client secret as shown in the section Prerequisites in your system, the customer is required to input client ID, client secret, and account ID (the ID that the customer uses to log into the destination)
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_CLIENT_CREDENTIALS",
"authenticationDataFields": [
{
"name": "clientId",
"title": "Client ID",
"description": "Client ID",
"type": "string",
"isRequired": true,
"source": "CUSTOMER"
},
{
"name": "clientSecret",
"title": "Client Secret",
"description": "Client Secret",
"type": "string",
"isRequired": true,
"format": "password",
"source": "CUSTOMER"
},
{
"name": "moviestarId",
"title": "Moviestar ID",
"description": "Moviestar ID",
"type": "string",
"isRequired": true,
"source": "CUSTOMER"
}
],
"accessTokenRequest": {
"destinationServerType": "URL_BASED",
"urlBasedDestination": {
"url": {
"templatingStrategy": "PEBBLE_V1",
"value": "https://{{ authData.moviestarId }}.yourdestination.com/identity/oauth/token"
}
},
"httpTemplate": {
"requestBody": {
"templatingStrategy": "PEBBLE_V1",
"value": "{{ formUrlEncode('grant_type', 'client_credentials', 'client_id', authData.clientId, 'client_secret', authData.clientSecret) | raw }}"
},
"httpMethod": "POST",
"contentType": "application/x-www-form-urlencoded"
},
"responseFields": [
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.access_token }}",
"name": "accessToken"
},
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.scope }}",
"name": "scope"
},
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.token_type }}",
"name": "tokenType"
},
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.expires_in }}",
"name": "expiresIn"
}
]
}
}
]
//...
}
You can use the following parameters in authenticationDataFields
to customize your OAuth 2 configuration:
authenticationDataFields.name
authenticationDataFields.title
authenticationDataFields.description
authenticationDataFields.type
Accepted values:
string
, boolean
, integer
authenticationDataFields.isRequired
authenticationDataFields.format
"format":"password"
, Adobe encrypts the value of the authorization data field. When used with "fieldType": "CUSTOMER"
, this also hides the input in the UI when the user types into the field.authenticationDataFields.fieldType
authenticationDataFields.value
authenticationDataFields.type
.authenticationDataFields.authenticationResponsePath
Access token refresh access-token-refresh
Adobe has designed a system which refreshes expired access tokens without requiring the user to log back into your platform. The system is able to generate a new token so that the activation to your destination will continue seamlessly for the customer.
To set up access token refresh, you may need to configure a templatized HTTP request that allows Adobe to get a new access token, using a refresh token. If the access token has expired, Adobe takes the templated request provided by you, adding the parameters you supplied. Use the accessTokenRequest
parameter to configure an access token refresh mechanism.
{
"customerAuthenticationConfigurations":[
{
"authType":"OAUTH2",
"grant":"OAUTH2_CLIENT_CREDENTIALS",
"accessTokenRequest":{
"destinationServerType":"URL_BASED",
"urlBasedDestination":{
"url":{
"templatingStrategy":"PEBBLE_V1",
"value":"https://{{authData.customerId}}.yourdestination.com/identity/oauth/token"
}
},
"httpTemplate":{
"requestBody":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ formUrlEncode('grant_type', 'client_credentials', 'client_id', authData.clientId, 'client_secret', authData.clientSecret) | raw }}"
},
"httpMethod":"POST",
"contentType":"application/x-www-form-urlencoded",
"headers":[
]
},
"responseFields":[
{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ response.body.expires_in }}",
"name":"expiresIn"
},
{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ response.body.access_token }}",
"name":"accessToken"
}
],
"validations":[
{
"name":"access_token validation",
"actualValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{response.body.access_token is empty }}"
},
"expectedValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"false"
}
},
{
"name":"response status",
"actualValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ response.status }}"
},
"expectedValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"200"
}
}
]
}
}
]
}
You can use the following parameters in accessTokenRequest
to customize your token refresh process:
accessTokenRequest.destinationServerType
URL_BASED
.accessTokenRequest.urlBasedDestination.url.templatingStrategy
- Use
PEBBLE_V1
if you use templates for the value inaccessTokenRequest.urlBasedDestination.url.value
. - Use
NONE
if the value in the fieldaccessTokenRequest.urlBasedDestination.url.value
is a constant.
accessTokenRequest.urlBasedDestination.url.value
accessTokenRequest.httpTemplate.requestBody.templatingStrategy
- Use
PEBBLE_V1
if you use templates for the values inaccessTokenRequest.httpTemplate.requestBody.value
. - Use
NONE
if the value in the fieldaccessTokenRequest.httpTemplate.requestBody.value
is a constant.
accessTokenRequest.httpTemplate.requestBody.value
accessTokenRequest.httpTemplate.httpMethod
POST
.accessTokenRequest.httpTemplate.contentType
For example:
application/x-www-form-urlencoded
or application/json
.accessTokenRequest.httpTemplate.headers
accessTokenRequest.responseFields.templatingStrategy
- Use
PEBBLE_V1
if you use templates for the values inaccessTokenRequest.responseFields.value
. - Use
NONE
if the value in the fieldaccessTokenRequest.responseFields.value
is a constant.
accessTokenRequest.responseFields.value
accessTokenRequest.validations.name
accessTokenRequest.validations.actualValue.templatingStrategy
- Use
PEBBLE_V1
if you use templates for the values inaccessTokenRequest.validations.actualValue.value
. - Use
NONE
if the value in the fieldaccessTokenRequest.validations.actualValue.value
is a constant.
accessTokenRequest.validations.actualValue.value
accessTokenRequest.validations.expectedValue.templatingStrategy
- Use
PEBBLE_V1
if you use templates for the values inaccessTokenRequest.validations.expectedValue.value
. - Use
NONE
if the value in the fieldaccessTokenRequest.validations.expectedValue.value
is a constant.
accessTokenRequest.validations.expectedValue.value
Templating conventions templating-conventions
Depending on your authorization customization, you might need to access data fields in the authorization response, as shown in the previous section. To do that, please familiarize yourself with the Pebble templating language used by Adobe and refer to the templating conventions below to customize your OAuth 2 implementation.
{{ authData.accessToken }}
{{ response.body.access_token }}
{{ response.status }}
{{ response.headers.server[0] }}
{{ userContext.sandboxName }}
{{ userContext.sandboxId }}
{{ userContext.imsOrgId }}
{{ userContext.client }} // the client executing the authorization attempt
Next steps next-steps
By reading this article, you now have an understanding of the OAuth 2 authorization patterns supported by Adobe Experience Platform and know how to configure your destination with OAuth 2 authorization support. Next, you can set up your OAuth 2-supported destination using Destination SDK. Read Use Destination SDK to configure your destination for next steps.