OAuth 2授权
Destination SDK支持对目标的多种授权方法。 其中一种是使用 OAuth 2授权框架.
本页介绍了Destination SDK支持的各种OAuth 2授权流程,并提供了有关为目标设置OAuth 2授权的说明。
支持的集成类型 supported-integration-types
有关哪些类型的集成支持此页面上描述的功能,请参阅下表。
如何将OAuth 2授权详细信息添加到您的目标配置 how-to-setup
系统中的先决条件 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中需要做什么 to-do-in-destination-sdk
要为Experience Platform中的目标设置OAuth 2授权,您必须将OAuth 2详细信息添加到 目标配置,位于 customerAuthenticationConfigurations
参数。 请参阅 客户身份验证 以了解详细示例。 根据您的OAuth 2授权授予类型,关于您需要向配置模板添加哪些字段的具体说明,请参阅本页下面的内容。
支持的OAuth 2授权类型 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,带有授权代码 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配置 customize-configuration
上节中描述的配置描述了标准OAuth 2授权。 但是,由Adobe设计的系统提供了灵活性,因此您可以将自定义参数用于OAuth 2授权中的任何变体。 要自定义标准OAuth 2设置,请使用 authenticationDataFields
参数,如以下示例所示。
示例1:使用 authenticationDataFields
捕获来自授权响应的信息 example-1
在此示例中,目标平台的刷新令牌在一定时间后过期。 在这种情况下,合作伙伴将设置 refreshTokenExpiration
用于从获取刷新令牌到期的自定义字段 refresh_token_expires_in
API响应中的字段。
{
"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
提供特殊的刷新令牌 example-2
在此示例中,合作伙伴设置其目标以提供特殊的刷新令牌。 此外,API响应中不会返回访问令牌的过期日期,因此它们可以对默认值进行硬编码,在本例中为3600秒。
"authenticationDataFields": [
{
"name": "refreshToken",
"value": "special_refresh_token"
},
{
"name": "expiresIn",
"value": 3600
}
]
示例3:用户在配置目标时输入客户端ID和客户端密码 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
访问令牌刷新 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
- 使用
PEBBLE_V1
如果将模板用于中的值accessTokenRequest.urlBasedDestination.url.value
. - 使用
NONE
如果字段中的值accessTokenRequest.urlBasedDestination.url.value
是一个常量。
accessTokenRequest.urlBasedDestination.url.value
accessTokenRequest.httpTemplate.requestBody.templatingStrategy
- 使用
PEBBLE_V1
如果对中的值使用模板accessTokenRequest.httpTemplate.requestBody.value
. - 使用
NONE
如果字段中的值accessTokenRequest.httpTemplate.requestBody.value
是一个常量。
accessTokenRequest.httpTemplate.requestBody.value
accessTokenRequest.httpTemplate.httpMethod
POST
.accessTokenRequest.httpTemplate.contentType
例如:
application/x-www-form-urlencoded
或 application/json
.accessTokenRequest.httpTemplate.headers
accessTokenRequest.responseFields.templatingStrategy
- 使用
PEBBLE_V1
如果对中的值使用模板accessTokenRequest.responseFields.value
. - 使用
NONE
如果字段中的值accessTokenRequest.responseFields.value
是一个常量。
accessTokenRequest.responseFields.value
accessTokenRequest.validations.name
accessTokenRequest.validations.actualValue.templatingStrategy
- 使用
PEBBLE_V1
如果对中的值使用模板accessTokenRequest.validations.actualValue.value
. - 使用
NONE
如果字段中的值accessTokenRequest.validations.actualValue.value
是一个常量。
accessTokenRequest.validations.actualValue.value
accessTokenRequest.validations.expectedValue.templatingStrategy
- 使用
PEBBLE_V1
如果对中的值使用模板accessTokenRequest.validations.expectedValue.value
. - 使用
NONE
如果字段中的值accessTokenRequest.validations.expectedValue.value
是一个常量。
accessTokenRequest.validations.expectedValue.value
模板惯例 templating-conventions
根据您的授权自定义,您可能需要访问授权响应中的数据字段,如上一节所示。 为此,请熟悉 卵石模板化语言 供Adobe使用,并参阅下面的模板惯例以自定义您的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
后续步骤 next-steps
阅读本文后,您现在了解了Adobe Experience Platform支持的OAuth 2授权模式,并知道如何使用OAuth 2授权支持配置您的目标。 接下来,您可以使用Destination SDK设置支持OAuth 2的目标。 读取 使用Destination SDK配置目标 以了解后续步骤。