OAuth 2授权

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

主题：
目标

创建对象：

管理员
用户

Destination SDK支持对目标的多种授权方法。其中有一个选项可使用OAuth 2授权框架向您的目标进行身份验证。

本页介绍了Destination SDK支持的各种OAuth 2授权流程，并提供了有关为目标设置OAuth 2授权的说明。

IMPORTANT

Destination SDK支持的所有参数名称和值均区分大小写****。为避免出现区分大小写错误，请完全按照文档中的说明使用参数名称和值。

支持的集成类型 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

IMPORTANT

只有授权代码为🔗的OAuth 2授予类型才需要执行在系统中注册Adobe Experience Platform的重定向/回调URL的步骤。对于其他两种受支持的授权类型（密码和客户端凭据），您可以跳过此步骤。

在此步骤结束时，您应该：

客户端ID；
客户密码；
Adobe的回调URL（用于授权代码授权）。

在Destination SDK中需要做什么 to-do-in-destination-sdk

要为Experience Platform中的目标设置OAuth 2授权，您必须在customerAuthenticationConfigurations参数下将OAuth 2详细信息添加到目标配置。有关详细示例，请参阅客户身份验证。根据您的OAuth 2授权授予类型，关于您需要向配置模板添加哪些字段的具体说明，请参阅本页下面的内容。

支持的OAuth 2授权类型 oauth2-grant-types

Experience Platform支持下表中的三个OAuth 2授权类型。如果您设置了自定义OAuth 2，则Adobe可以在集成中的自定义字段的帮助下支持它。有关更多信息，请参阅每种授权类型的章节。

IMPORTANT

您可以按照以下各节中的说明提供输入参数。 Adobe内部系统连接到您平台的授权系统并获取输出参数，这些参数用于验证用户并保持对目标的授权。
表格中以粗体突出显示的输入参数是OAuth 2授权流中的必需参数。其他参数是可选的。此处未显示其他自定义输入参数，但这些参数在自定义您的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标准规范）或其变体，请查阅下面的必需和可选字段：

OAuth 2授权

输入

输出

授权码

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

字符串

使用“OAUTH2”。

grant

字符串

使用“OAUTH2_AUTHORIZATION_CODE”。

accessTokenUrl

字符串

您这边的URL，用于发出访问令牌并（可选）刷新令牌。

authorizationUrl

字符串

授权服务器的URL，您可以在其中将用户重定向到您的应用程序。

refreshTokenUrl

字符串

可选。 您这边的URL，这会产生刷新令牌的问题。通常，refreshTokenUrl与accessTokenUrl相同。

clientId

字符串

系统分配给Adobe Experience Platform的客户端ID。

clientSecret

字符串

系统分配给Adobe Experience Platform的客户端密码。

scope

字符串列表

可选。设置访问令牌允许Experience Platform对您的资源执行的范围。示例：“read， write”。

具有密码授予的OAuth 2

对于OAuth 2密码授予（请阅读RFC标准规范），Experience Platform需要用户的用户名和密码。在授权流中，Experience Platform将这些凭据交换为访问令牌和（可选）刷新令牌。
Adobe使用以下标准输入来简化目标配置，并能够覆盖值：

OAuth 2授权

输入

输出

密码

clientId
客户端密钥
范围
accessTokenUrl
用户名
密码

accessToken
expiresIn
refreshToken
tokentype

NOTE

您不需要在下面的配置中为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

字符串

使用“OAUTH2”。

grant

字符串

使用“OAUTH2_PASSWORD”。

accessTokenUrl

字符串

您这边的URL，用于发出访问令牌并（可选）刷新令牌。

clientId

字符串

系统分配给Adobe Experience Platform的客户端ID。

clientSecret

字符串

系统分配给Adobe Experience Platform的客户端密码。

scope

字符串列表

可选。设置访问令牌允许Experience Platform对您的资源执行的范围。示例：“read， write”。

具有客户端凭据授权的OAuth 2

您可以配置OAuth 2客户端凭据（读取RFC标准规范）目标，该目标支持下面列出的标准输入和输出。您可以自定义值。有关详细信息，请参阅自定义您的OAuth 2配置。

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

字符串

使用“OAUTH2”。

grant

字符串

使用“OAUTH2_CLIENT_CREDENTIALS”。

accessTokenUrl

字符串

授权服务器的URL，它会颁发一个访问令牌和一个可选的刷新令牌。

refreshTokenUrl

字符串

可选。 您这边的URL，这会产生刷新令牌的问题。通常，refreshTokenUrl与accessTokenUrl相同。

clientId

字符串

系统分配给Adobe Experience Platform的客户端ID。

clientSecret

字符串

系统分配给Adobe Experience Platform的客户端密码。

scope

字符串列表

可选。设置访问令牌允许Experience Platform对您的资源执行的范围。示例：“read， write”。

自定义您的OAuth 2配置 customize-configuration

上节中描述的配置描述了标准OAuth 2授权。但是，由Adobe设计的系统提供了灵活性，因此您可以将自定义参数用于OAuth 2授权中的任何变体。要自定义标准OAuth 2设置，请使用authenticationDataFields参数，如以下示例所示。

示例1：使用`authenticationDataFields`捕获来自授权响应的信息 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`提供特殊刷新令牌 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

字符串

指示当合作伙伴（您）在Experience Platform中设置您的目标时，输入是来自合作伙伴还是用户。

authenticationDataFields.value

字符串。布尔型。整数

自定义数据字段的值。该值与authenticationDataFields.type中选择的类型匹配。

authenticationDataFields.authenticationResponsePath

字符串

指示您正在引用API响应路径中的哪个字段。

访问令牌刷新 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

字符串

Experience Platform请求访问令牌的URL。

accessTokenRequest.httpTemplate.requestBody.templatingStrategy

字符串

如果您对accessTokenRequest.httpTemplate.requestBody.value中的值使用模板，请使用PEBBLE_V1。
如果字段accessTokenRequest.httpTemplate.requestBody.value中的值为常量，则使用NONE。

accessTokenRequest.httpTemplate.requestBody.value

字符串

使用模板化语言自定义访问令牌端点的HTTP请求中的字段。有关如何使用模板自定义字段的信息，请参阅模板约定部分。

accessTokenRequest.httpTemplate.httpMethod

字符串

指定用于调用访问令牌端点的HTTP方法。在大多数情况下，此值为POST。

accessTokenRequest.httpTemplate.contentType

字符串

指定对您的访问令牌端点的HTTP调用的内容类型。
例如： application/x-www-form-urlencoded或application/json。

accessTokenRequest.httpTemplate.headers

字符串

指定是否应将任何标头添加到对访问令牌端点的HTTP调用中。

accessTokenRequest.responseFields.templatingStrategy

字符串

如果您对accessTokenRequest.responseFields.value中的值使用模板，请使用PEBBLE_V1。
如果字段accessTokenRequest.responseFields.value中的值为常量，则使用NONE。

accessTokenRequest.responseFields.value

字符串

使用模板化语言从访问令牌端点访问HTTP响应中的字段。有关如何使用模板自定义字段的信息，请参阅模板约定部分。

accessTokenRequest.validations.name

字符串

指示为此验证提供的名称。

accessTokenRequest.validations.actualValue.templatingStrategy

字符串

如果您对accessTokenRequest.validations.actualValue.value中的值使用模板，请使用PEBBLE_V1。
如果字段accessTokenRequest.validations.actualValue.value中的值为常量，则使用NONE。

accessTokenRequest.validations.actualValue.value

字符串

使用模板化语言访问HTTP响应中的字段。有关如何使用模板自定义字段的信息，请参阅模板约定部分。

accessTokenRequest.validations.expectedValue.templatingStrategy

字符串

如果您对accessTokenRequest.validations.expectedValue.value中的值使用模板，请使用PEBBLE_V1。
如果字段accessTokenRequest.validations.expectedValue.value中的值为常量，则使用NONE。

accessTokenRequest.validations.expectedValue.value

字符串

使用模板化语言访问HTTP响应中的字段。有关如何使用模板自定义字段的信息，请参阅模板约定部分。

模板惯例 templating-conventions

根据您的授权自定义，您可能需要访问授权响应中的数据字段，如上一节所示。为此，请熟悉Adobe使用的Pebble模板语言，并参阅下面的模板惯例以自定义您的OAuth 2实施。

前缀

描述

示例

authData

访问任何合作伙伴或客户数据字段的值。

{{ authData.accessToken }}

response.body

HTTP响应正文

{{ response.body.access_token }}

response.status

HTTP响应状态

{{ response.status }}

response.headers

HTTP响应标头

{{ response.headers.server[0] }}

userContext

访问有关当前授权尝试的信息

{{ 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配置目标以了解后续步骤。

recommendation-more-help

7f4d1967-bf93-4dba-9789-bb6b505339d6

OAuth 2授权

支持的集成类型 supported-integration-types

如何将OAuth 2授权详细信息添加到您的目标配置 how-to-setup

系统中的先决条件 prerequisites

在Destination SDK中需要做什么 to-do-in-destination-sdk

支持的OAuth 2授权类型 oauth2-grant-types

OAuth 2，带有授权代码 authorization-code

具有密码授予的OAuth 2

具有客户端凭据授权的OAuth 2

自定义您的OAuth 2配置 customize-configuration

示例1：使用authenticationDataFields捕获来自授权响应的信息 example-1

示例2：使用authenticationDataFields提供特殊刷新令牌 example-2

示例3：用户在配置目标时输入客户端ID和客户端密码 example-3

访问令牌刷新 access-token-refresh

模板惯例 templating-conventions

后续步骤 next-steps

示例1：使用`authenticationDataFields`捕获来自授权响应的信息 example-1

示例2：使用`authenticationDataFields`提供特殊刷新令牌 example-2