Autorização OAuth 2
O Destination SDK suporta vários métodos de autorização para o seu destino. Entre eles está a opção para autenticar em seu destino usando a estrutura de autorização OAuth 2.
Esta página descreve os vários fluxos de autorização OAuth 2 suportados pelo Destination SDK e fornece instruções para configurar a autorização OAuth 2 para o seu destino.
Tipos de integração compatíveis supported-integration-types
Consulte a tabela abaixo para obter detalhes sobre quais tipos de integrações suportam a funcionalidade descrita nesta página.
Como adicionar detalhes de autorização do OAuth 2 à configuração de destino how-to-setup
Pré-requisitos em seu sistema prerequisites
Como primeira etapa, você deve criar um aplicativo no sistema para Adobe Experience Platform ou registrar o Experience Platform no sistema. O objetivo é gerar uma ID do cliente e um segredo do cliente, que são necessários para autenticar o Experience Platform no seu destino.
Como parte dessa configuração no seu sistema, você precisa dos URLs de redirecionamento/retorno de chamada OAuth 2 do Adobe Experience Platform, que podem ser obtidos na lista abaixo.
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
No final desta etapa, você deve ter:
- Uma ID de cliente;
- Um segredo de cliente;
- URL de retorno de chamada de Adobe (para a concessão de código de autorização).
O que você precisa fazer no Destination SDK to-do-in-destination-sdk
Para configurar a autorização OAuth 2 para o seu destino no Experience Platform, adicione os detalhes do OAuth 2 à configuração de destino, no parâmetro customerAuthenticationConfigurations
. Consulte autenticação do cliente para obter exemplos detalhados. Instruções específicas sobre quais campos você precisa adicionar ao seu modelo de configuração, dependendo do tipo de concessão de autorização OAuth 2, estão mais abaixo nesta página.
Tipos de concessão OAuth 2 compatíveis oauth2-grant-types
O Experience Platform suporta os três tipos de concessão OAuth 2 na tabela abaixo. Se você tiver uma configuração OAuth 2 personalizada, o Adobe poderá oferecer suporte a ela com a ajuda de campos personalizados na integração. Consulte as seções para cada tipo de concessão para obter mais informações.
- Você fornece os parâmetros de entrada conforme instruído nas seções abaixo. Os sistemas internos de Adobe se conectam ao sistema de autorização da sua plataforma e capturam parâmetros de saída, que são usados para autenticar o usuário e manter a autorização no seu destino.
- Os parâmetros de entrada destacados em negrito na tabela são parâmetros obrigatórios no fluxo de autorização do OAuth 2. Os outros parâmetros são opcionais. Há outros parâmetros de entrada personalizados que não são mostrados aqui, mas que estão descritos detalhadamente nas seções Personalizar a configuração do OAuth 2 e Atualizar o token de acesso.
- clientId
- clientSecret
- escopo
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- escopo
- accessTokenUrl
- username
- senha
- accessToken
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- escopo
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
A tabela acima lista os campos usados em fluxos OAuth 2 padrão. Além desses campos padrão, várias integrações de parceiros podem exigir entradas e saídas adicionais. O Adobe projetou uma estrutura de autorização OAuth 2 flexível para o Destination SDK que pode lidar com variações do padrão de campos acima, enquanto oferece suporte a um mecanismo para regenerar automaticamente saídas inválidas, como tokens de acesso expirados.
A saída em todos os casos inclui um token de acesso, que é usado pelo Experience Platform para autenticar e manter a autorização no seu destino.
O sistema que o Adobe projetou para autorização OAuth 2:
- Suporta todas as três concessões OAuth 2 enquanto contabiliza quaisquer variações entre elas, como campos de dados adicionais, chamadas de API não padrão e muito mais.
- Suporta tokens de acesso com valores de tempo de vida variáveis, seja 90 dias, 30 minutos ou qualquer outro valor de tempo de vida especificado.
- Oferece suporte a fluxos de autorização OAuth 2 com ou sem tokens de atualização.
OAuth 2 com código de autorização authorization-code
Se o seu destino suportar um fluxo de código de autorização OAuth 2.0 padrão (leia as especificações de padrões RFC) ou uma variação dele, consulte os campos obrigatórios e opcionais abaixo:
- clientId
- clientSecret
- escopo
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
Para definir esse método de autorização para o seu destino, adicione as seguintes linhas à sua configuração quando você criar uma configuração de destino:
{
//...
"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
é o mesmo que accessTokenUrl
.clientId
clientSecret
scope
OAuth 2 com concessão de senha
Para a concessão de Senha do OAuth 2 (leia as especificações de padrões da RFC), o Experience Platform exige o nome de usuário e a senha do usuário. No fluxo de autorização, o Experience Platform troca essas credenciais por um token de acesso e, opcionalmente, um token de atualização.
O Adobe usa as entradas padrão abaixo para simplificar a configuração de destino, com a capacidade de substituir valores:
- clientId
- clientSecret
- escopo
- accessTokenUrl
- username
- senha
- accessToken
- expiresIn
- refreshToken
- tokenType
username
e password
na configuração abaixo. Quando você adicionar "grant": "OAUTH2_PASSWORD"
na configuração de destino, o sistema solicitará que o usuário forneça um nome de usuário e senha na interface do usuário do Experience Platform quando ele se autenticar no seu destino.Para definir esse método de autorização para o seu destino, adicione as seguintes linhas à sua configuração quando você criar uma configuração de destino:
{
//...
"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 com concessão de credenciais do cliente
Você pode configurar um destino de Credenciais de Cliente OAuth 2 (leia as especificações de padrões RFC), que oferece suporte às entradas e saídas padrão listadas abaixo. Você pode personalizar os valores. Consulte Personalizar a configuração do OAuth 2 para obter detalhes.
- clientId
- clientSecret
- escopo
- accessTokenUrl
- accessToken
- expiresIn
- refreshToken
- tokenType
Para definir esse método de autorização para o seu destino, adicione as seguintes linhas à sua configuração quando você criar uma configuração de destino:
{
//...
"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
é o mesmo que accessTokenUrl
.clientId
clientSecret
scope
Personalizar a configuração do OAuth 2 customize-configuration
As configurações descritas nas seções acima descrevem as concessões OAuth 2 padrão. No entanto, o sistema criado pelo Adobe oferece flexibilidade para que você possa usar parâmetros personalizados para quaisquer variações na concessão OAuth 2. Para personalizar as configurações padrão do OAuth 2, use os parâmetros authenticationDataFields
, conforme mostrado nos exemplos abaixo.
Exemplo 1: uso de authenticationDataFields
para capturar informações provenientes da resposta de autorização example-1
Neste exemplo, uma plataforma de destino tem tokens de atualização que expiram após um determinado período. Nesse caso, o parceiro configura o campo personalizado refreshTokenExpiration
para obter a expiração do token de atualização do campo refresh_token_expires_in
na resposta da 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"
}
]
}
]
}
Exemplo 2: usar authenticationDataFields
para fornecer um token de atualização especial example-2
Neste exemplo, um parceiro configura seu destino para fornecer um token de atualização especial. Além disso, a data de expiração dos tokens de acesso não é retornada na resposta da API para que eles possam codificar um valor padrão, nesse caso, 3600 segundos.
"authenticationDataFields": [
{
"name": "refreshToken",
"value": "special_refresh_token"
},
{
"name": "expiresIn",
"value": 3600
}
]
Exemplo 3: o usuário insere a ID do cliente e o segredo do cliente quando configura o destino example-3
Neste exemplo, em vez de criar uma ID de cliente global e um segredo de cliente como mostrado na seção Pré-requisitos em seu sistema, o cliente precisa inserir a ID do cliente, o segredo do cliente e a ID da conta (a ID que o cliente usa para fazer logon no destino)
{
//...
"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"
}
]
}
}
]
//...
}
Você pode usar os seguintes parâmetros no authenticationDataFields
para personalizar sua configuração do OAuth 2:
authenticationDataFields.name
authenticationDataFields.title
authenticationDataFields.description
authenticationDataFields.type
Valores aceitos:
string
, boolean
, integer
authenticationDataFields.isRequired
authenticationDataFields.format
"format":"password"
, o Adobe criptografa o valor do campo de dados de autorização. Quando usado com "fieldType": "CUSTOMER"
, isso também oculta a entrada na interface do usuário quando o usuário digita no campo.authenticationDataFields.fieldType
authenticationDataFields.value
authenticationDataFields.type
.authenticationDataFields.authenticationResponsePath
Atualização do token de acesso access-token-refresh
O Adobe projetou um sistema que atualiza tokens de acesso expirados sem exigir que o usuário faça logon novamente em sua plataforma. O sistema é capaz de gerar um novo token para que a ativação no destino continue perfeitamente para o cliente.
Para configurar a atualização do token de acesso, talvez seja necessário configurar uma solicitação HTTP com modelo que permita ao Adobe obter um novo token de acesso, usando um token de atualização. Se o token de acesso tiver expirado, o Adobe aceitará a solicitação de modelo fornecida por você, adicionando os parâmetros fornecidos. Use o parâmetro accessTokenRequest
para configurar um mecanismo de atualização do token de acesso.
{
"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"
}
}
]
}
}
]
}
Você pode usar os seguintes parâmetros no accessTokenRequest
para personalizar o processo de atualização do token:
accessTokenRequest.destinationServerType
URL_BASED
.accessTokenRequest.urlBasedDestination.url.templatingStrategy
- Use
PEBBLE_V1
se você usar modelos para o valor emaccessTokenRequest.urlBasedDestination.url.value
. - Use
NONE
se o valor no campoaccessTokenRequest.urlBasedDestination.url.value
for uma constante.
accessTokenRequest.urlBasedDestination.url.value
accessTokenRequest.httpTemplate.requestBody.templatingStrategy
- Use
PEBBLE_V1
se você usar modelos para os valores emaccessTokenRequest.httpTemplate.requestBody.value
. - Use
NONE
se o valor no campoaccessTokenRequest.httpTemplate.requestBody.value
for uma constante.
accessTokenRequest.httpTemplate.requestBody.value
accessTokenRequest.httpTemplate.httpMethod
POST
.accessTokenRequest.httpTemplate.contentType
Por exemplo:
application/x-www-form-urlencoded
ou application/json
.accessTokenRequest.httpTemplate.headers
accessTokenRequest.responseFields.templatingStrategy
- Use
PEBBLE_V1
se você usar modelos para os valores emaccessTokenRequest.responseFields.value
. - Use
NONE
se o valor no campoaccessTokenRequest.responseFields.value
for uma constante.
accessTokenRequest.responseFields.value
accessTokenRequest.validations.name
accessTokenRequest.validations.actualValue.templatingStrategy
- Use
PEBBLE_V1
se você usar modelos para os valores emaccessTokenRequest.validations.actualValue.value
. - Use
NONE
se o valor no campoaccessTokenRequest.validations.actualValue.value
for uma constante.
accessTokenRequest.validations.actualValue.value
accessTokenRequest.validations.expectedValue.templatingStrategy
- Use
PEBBLE_V1
se você usar modelos para os valores emaccessTokenRequest.validations.expectedValue.value
. - Use
NONE
se o valor no campoaccessTokenRequest.validations.expectedValue.value
for uma constante.
accessTokenRequest.validations.expectedValue.value
Convenções de modelos templating-conventions
Dependendo da sua personalização de autorização, talvez seja necessário acessar campos de dados na resposta de autorização, como mostrado na seção anterior. Para fazer isso, familiarize-se com a linguagem de modelo Pebble usada pelo Adobe e consulte as convenções de modelo abaixo para personalizar a implementação do 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
Próximas etapas next-steps
Ao ler este artigo, você agora entende os padrões de autorização OAuth 2 compatíveis com o Adobe Experience Platform e sabe como configurar seu destino com suporte à autorização OAuth 2. Em seguida, você pode configurar o destino compatível com OAuth 2 usando o Destination SDK. Leia Usar o Destination SDK para configurar seu destino para as próximas etapas.