OAuth 2授权
Destination SDK支持对目标的多种授权方法。 其中有一个选项可使用OAuth 2授权框架向您的目标进行身份验证。
本页介绍了Destination SDK支持的各种OAuth 2授权流程,并提供了有关为目标设置OAuth 2授权的说明。
支持的集成类型 :headding-anchor:supported-integration-types
有关哪些类型的集成支持此页面上描述的功能,请参阅下表。
如何将OAuth 2授权详细信息添加到您的目标配置 :headding-anchor:how-to-setup
系统中的先决条件 :headding-anchor:prerequisites
第一步,您必须在系统中为Adobe Experience Platform创建应用程序,或在系统中注册Experience Platform。 目标是生成客户端ID和客户端密钥,这是验证Experience Platform到您的目标时所必需的。
在您的系统中,作为此配置的一部分,您需要Adobe Experience Platform OAuth 2重定向/回调URL,可从以下列表中获取该URL。
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
在此步骤结束时,您应该:
- 客户端ID;
- 客户密码;
- Adobe的回调URL(用于授权代码授权)。
在Destination SDK中需要做什么 :headding-anchor:to-do-in-destination-sdk
要为Experience Platform中的目标设置OAuth 2授权,您必须在customerAuthenticationConfigurations
参数下将OAuth 2详细信息添加到目标配置。 有关详细示例,请参阅客户身份验证。 根据您的OAuth 2授权授予类型,关于您需要向配置模板添加哪些字段的具体说明,请参阅本页下面的内容。
支持的OAuth 2授权类型 :headding-anchor:oauth2-grant-types
Experience Platform支持下表中的三个OAuth 2授权类型。 如果您设置了自定义OAuth 2,则Adobe可以在集成中的自定义字段的帮助下支持它。 有关更多信息,请参阅每种授权类型的章节。
- 您可以按照以下各节中的说明提供输入参数。 Adobe内部系统连接到您平台的授权系统并获取输出参数,这些参数用于验证用户并保持对目标的授权。
- 表格中以粗体突出显示的输入参数是OAuth 2授权流中的必需参数。 其他参数是可选的。 此处未显示其他自定义输入参数,但这些参数在自定义您的OAuth 2配置和访问令牌刷新部分中有详细介绍。
- clientId
- 客户端密钥
- 范围
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokentype
- clientId
- 客户端密钥
- 范围
- accessTokenUrl
- 用户名
- 密码
- accessToken
- expiresIn
- refreshToken
- tokentype
- clientId
- 客户端密钥
- 范围
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokentype
上表列出了标准OAuth 2流程中使用的字段。 除了这些标准字段之外,各种合作伙伴集成可能还需要其他输入和输出。 Adobe已经为Destination SDK设计了一个灵活的OAuth 2授权框架,该框架可以处理上述标准字段模式的变化,同时支持自动重新生成无效输出的机制,例如过期的访问令牌。
在所有情况下,输出都包括访问令牌,Experience Platform使用该令牌进行身份验证并维护对目标的授权。
本Adobe设计的用于OAuth 2授权的系统:
- 支持所有三个OAuth 2授权,并会考虑其中的任何变量,例如附加数据字段、非标准API调用等。
- 支持具有不同生命周期值(90天、30分钟或您指定的任何其他生命周期值)的访问令牌。
- 支持使用或不使用刷新令牌的OAuth 2授权流。
OAuth 2,带有授权代码 :headding-anchor:authorization-code
如果您的目标支持标准OAuth 2.0授权代码流(请阅读RFC标准规范)或其变体,请查阅下面的必需和可选字段:
- clientId
- 客户端密钥
- 范围
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokentype
要为您的目标设置此授权方法,请在您创建目标配置时,将以下行添加到您的配置中:
{
//...
"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
与accessTokenUrl
相同。clientId
clientSecret
scope
具有密码授予的OAuth 2
对于OAuth 2密码授予(请阅读RFC标准规范),Experience Platform需要用户的用户名和密码。 在授权流中,Experience Platform将这些凭据交换为访问令牌和(可选)刷新令牌。
Adobe使用以下标准输入来简化目标配置,并能够覆盖值:
- clientId
- 客户端密钥
- 范围
- accessTokenUrl
- 用户名
- 密码
- accessToken
- expiresIn
- refreshToken
- tokentype
username
和password
添加任何参数。 在目标配置中添加"grant": "OAUTH2_PASSWORD"
时,当用户对您的目标进行验证时,系统将请求Experience Platform在UI中提供用户名和密码。要为您的目标设置此授权方法,请在您创建目标配置时,将以下行添加到您的配置中:
{
//...
"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
您可以配置OAuth 2客户端凭据(读取RFC标准规范)目标,该目标支持下面列出的标准输入和输出。 您可以自定义值。 有关详细信息,请参阅自定义您的OAuth 2配置。
- clientId
- 客户端密钥
- 范围
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokentype
要为您的目标设置此授权方法,请在您创建目标配置时,将以下行添加到您的配置中:
{
//...
"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
与accessTokenUrl
相同。clientId
clientSecret
scope
自定义您的OAuth 2配置 :headding-anchor:customize-configuration
上节中描述的配置描述了标准OAuth 2授权。 但是,由Adobe设计的系统提供了灵活性,因此您可以将自定义参数用于OAuth 2授权中的任何变体。 要自定义标准OAuth 2设置,请使用authenticationDataFields
参数,如以下示例所示。
示例1:使用authenticationDataFields
捕获来自授权响应的信息 :headding-anchor:example-1
在此示例中,目标平台的刷新令牌在一定时间后过期。 在这种情况下,合作伙伴设置refreshTokenExpiration
自定义字段以从API响应中的refresh_token_expires_in
字段获取刷新令牌过期时间。
{
"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"
}
]
}
]
}
示例2:使用authenticationDataFields
提供特殊刷新令牌 :headding-anchor:example-2
在此示例中,合作伙伴设置其目标以提供特殊的刷新令牌。 此外,API响应中不会返回访问令牌的过期日期,因此它们可以对默认值进行硬编码,在本例中为3600秒。
"authenticationDataFields": [
{
"name": "refreshToken",
"value": "special_refresh_token"
},
{
"name": "expiresIn",
"value": 3600
}
]
示例3:用户在配置目标时输入客户端ID和客户端密码 :headding-anchor:example-3
在此示例中,客户需要输入客户端ID、客户端密钥和帐户ID(客户用于登录到目标的ID),而不是创建全局客户端ID和客户端密钥,如系统必备项部分中所示
{
//...
"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"
}
]
}
}
]
//...
}
您可以在authenticationDataFields
中使用以下参数来自定义OAuth 2配置:
authenticationDataFields.name
authenticationDataFields.title
authenticationDataFields.description
authenticationDataFields.type
接受的值:
string
、boolean
、integer
authenticationDataFields.isRequired
authenticationDataFields.format
"format":"password"
时,Adobe将加密授权数据字段的值。 与"fieldType": "CUSTOMER"
一起使用时,这也会在用户键入字段时隐藏UI中的输入。authenticationDataFields.fieldType
authenticationDataFields.value
authenticationDataFields.type
中选择的类型匹配。authenticationDataFields.authenticationResponsePath
访问令牌刷新 :headding-anchor:access-token-refresh
Adobe设计了一个系统,该系统无需用户登录回您的平台,即可刷新过期的访问令牌。 系统能够生成新的令牌,以便客户能够继续无缝地激活您的目标。
要设置访问令牌刷新,您可能需要配置一个模板化HTTP请求,以允许Adobe使用刷新令牌获取新的访问令牌。 如果访问令牌已过期,则Adobe会采用您提供的模板化请求,并添加您提供的参数。 使用accessTokenRequest
参数配置访问令牌刷新机制。
{
"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"
}
}
]
}
}
]
}
您可以在accessTokenRequest
中使用以下参数自定义令牌刷新过程:
accessTokenRequest.destinationServerType
URL_BASED
。accessTokenRequest.urlBasedDestination.url.templatingStrategy
- 如果您对
accessTokenRequest.urlBasedDestination.url.value
中的值使用模板,请使用PEBBLE_V1
。 - 如果字段
accessTokenRequest.urlBasedDestination.url.value
中的值为常量,则使用NONE
。
accessTokenRequest.urlBasedDestination.url.value
accessTokenRequest.httpTemplate.requestBody.templatingStrategy
- 如果您对
accessTokenRequest.httpTemplate.requestBody.value
中的值使用模板,请使用PEBBLE_V1
。 - 如果字段
accessTokenRequest.httpTemplate.requestBody.value
中的值为常量,则使用NONE
。
accessTokenRequest.httpTemplate.requestBody.value
accessTokenRequest.httpTemplate.httpMethod
POST
。accessTokenRequest.httpTemplate.contentType
例如:
application/x-www-form-urlencoded
或application/json
。accessTokenRequest.httpTemplate.headers
accessTokenRequest.responseFields.templatingStrategy
- 如果您对
accessTokenRequest.responseFields.value
中的值使用模板,请使用PEBBLE_V1
。 - 如果字段
accessTokenRequest.responseFields.value
中的值为常量,则使用NONE
。
accessTokenRequest.validations.name
accessTokenRequest.validations.actualValue.templatingStrategy
- 如果您对
accessTokenRequest.validations.actualValue.value
中的值使用模板,请使用PEBBLE_V1
。 - 如果字段
accessTokenRequest.validations.actualValue.value
中的值为常量,则使用NONE
。
accessTokenRequest.validations.actualValue.value
accessTokenRequest.validations.expectedValue.templatingStrategy
- 如果您对
accessTokenRequest.validations.expectedValue.value
中的值使用模板,请使用PEBBLE_V1
。 - 如果字段
accessTokenRequest.validations.expectedValue.value
中的值为常量,则使用NONE
。
accessTokenRequest.validations.expectedValue.value
模板惯例 :headding-anchor:templating-conventions
根据您的授权自定义,您可能需要访问授权响应中的数据字段,如上一节所示。 为此,请熟悉Adobe使用的Pebble模板语言,并参阅下面的模板惯例以自定义您的OAuth 2实施。
{{ 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
后续步骤 :headding-anchor:next-steps
阅读本文后,您现在了解了Adobe Experience Platform支持的OAuth 2授权模式,并知道如何使用OAuth 2授权支持配置您的目标。 接下来,您可以使用Destination SDK设置支持OAuth 2的目标。 阅读使用Destination SDK配置目标以了解后续步骤。