Autenticação OAuth 2

Visão geral

Use o Destination SDK para permitir que o Adobe Experience Platform se conecte ao seu destino usando a variável Estrutura de autenticação do OAuth 2.

Esta página descreve os vários fluxos de autenticação OAuth 2 suportados pelo Destination SDK e fornece instruções para configurar a autenticação OAuth 2 para o seu destino.

Como adicionar detalhes de autenticação do OAuth 2 à configuração de destino

Pré-requisitos no seu sistema

Como primeira etapa, você deve criar um aplicativo no sistema para o Adobe Experience Platform ou registrar o Experience Platform no sistema. O objetivo é gerar uma ID de cliente e um segredo de cliente, que são necessários para autenticar o Experience Platform para o seu destino. Como parte dessa configuração em seu sistema, você precisa dos URLs de redirecionamento/retorno de chamada do Adobe Experience Platform OAuth 2, 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

No final desta etapa, você deve ter:

• Uma ID de cliente;
• Um segredo de cliente;
• URL de retorno de autorização (para concessão).

O que você precisa fazer no Destination SDK

Para configurar a autenticação OAuth 2 para o seu destino no Experience Platform, você deve adicionar os detalhes do OAuth 2 ao configuração de destinonos termos do customerAuthenticationConfigurations , usando o platform.adobe.io/data/core/activation/authoring/destinations Ponto de extremidade da API. Consulte a configuração de exemplo. Instruções específicas sobre quais campos você precisa adicionar ao modelo de configuração, dependendo do tipo de concessão de autenticação OAuth 2, estão mais abaixo nesta página.

Tipos de concessão OAuth 2 suportados

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á suportá-la com a ajuda de campos personalizados em sua integração. Consulte as seções para cada tipo de concessão para obter mais informações.

A tabela acima lista os campos usados nos 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 autenticação/autorização OAuth 2 flexível para o Destination SDK que pode lidar com variações no padrão de campos padrão acima, ao mesmo tempo em que oferece suporte a um mecanismo para gerar 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 autenticação no destino.

O sistema que o Adobe projetou para a autenticação OAuth 2:

• Suporta todas as três concessões OAuth 2, além de contabilizar quaisquer variações delas, como campos de dados adicionais, chamadas de API não padrão e muito mais.
• Suporta tokens de acesso com valores de vida variáveis, sejam eles 90 dias, 30 minutos ou qualquer outro valor de duração especificado.
• Suporta fluxos de autorização OAuth 2 com ou sem tokens de atualização.

OAuth 2 com código de autorização

Se o seu destino suportar um fluxo de Código de Autorização OAuth 2.0 padrão (leia o Especificações de padrões RFC) para obter uma variação, consulte os campos obrigatórios e opcionais abaixo:

Para configurar esse método de autenticação para o seu destino, adicione as seguintes linhas à sua configuração, no /destinations endpoint:

{
//...
  "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"]
    }
  ]
//...
}

OAuth 2 com concessão de senha

Para obter a concessão de Senha OAuth 2 (leia o Especificações de padrões RFC), o Experience Platform exige o nome de usuário e a senha do usuário. No fluxo de autenticação, o Experience Platform troca essas credenciais por um token de acesso e, opcionalmente, por 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:

Para configurar esse método de autenticação para o seu destino, adicione as seguintes linhas à sua configuração, no /destinations endpoint:

{
//...
  "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"]
    }
  ]

Concessão de credenciais de cliente do OAuth 2

Você pode configurar uma Credenciais do Cliente OAuth 2 (leia a Especificações de padrões RFC) destino, que suporta as entradas e saídas padrão listadas abaixo. Você pode personalizar os valores. Consulte Personalizar a configuração do OAuth 2 para obter detalhes.

Para configurar esse método de autenticação para o seu destino, adicione as seguintes linhas à sua configuração, no /destinations endpoint:

{
//...
  "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"]
    }
  ]
//...
}

Personalizar a configuração do OAuth 2

As configurações descritas nas seções acima descrevem as concessões padrão do OAuth 2. No entanto, o sistema projetado pelo Adobe oferece flexibilidade para que você possa usar parâmetros personalizados para quaisquer variações na concessão do OAuth 2. Para personalizar as configurações padrão do OAuth 2, use o authenticationDataFields , conforme mostrado nos exemplos abaixo.

Exemplo 1: Usando authenticationDataFields para capturar informações provenientes da resposta de autenticação

Neste exemplo, uma plataforma de destino tem tokens de atualização que expiram após um determinado período. Nesse caso, o parceiro configura a variável refreshTokenExpiration campo personalizado para obter a expiração do token de atualização do 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: Usando authenticationDataFields para fornecer um token de atualização especial

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 possam codificar um valor padrão, neste 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 ao configurar o destino

Neste exemplo, em vez de criar uma ID de cliente global e um segredo de cliente, como mostrado na seção Pré-requisitos no seu sistema, o cliente deve 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 em authenticationDataFields para personalizar a configuração do OAuth 2:

Atualizar token de acesso

O Adobe projetou um sistema que atualiza tokens de acesso expirados sem exigir que o usuário faça logon novamente na plataforma. O sistema pode gerar um novo token para que a ativação para seu destino continue perfeitamente para o cliente.

Para configurar a atualização do token de acesso, talvez seja necessário configurar uma solicitação HTTP templatizada que permita que o Adobe obtenha um novo token de acesso usando um token de atualização. Se o token de acesso tiver expirado, o Adobe aceitará a solicitação modelo fornecida por você, adicionando os parâmetros fornecidos. Use o accessTokenRequest para configurar um mecanismo de atualização de 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 em accessTokenRequest para personalizar o processo de atualização de token:

Convenções de modelo

Dependendo da personalização da autenticação, talvez seja necessário acessar campos de dados na resposta de autenticação, conforme mostrado na seção anterior. Para fazer isso, por favor, familiarize-se com o Idioma do modelo de bolha usado pelo Adobe e consulte as convenções de modelo abaixo para personalizar sua implementação do OAuth 2.

Próximas etapas

Ao ler este artigo, agora você compreende os padrões de autenticação OAuth 2 compatíveis com o Adobe Experience Platform e sabe configurar seu destino com o suporte de autenticação OAuth 2. Em seguida, você pode configurar o destino suportado do OAuth 2 usando o Destination SDK. Ler Use o Destination SDK para configurar seu destino para as próximas etapas.