Autenticação OAuth 2

O Destination SDK suporta vários métodos de autenticação para o seu destino. Entre esses, está a opção de autenticar em seu destino usando o Estrutura de autenticação do OAuth 2.

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

Tipos de integração compatíveis

Consulte a tabela abaixo para obter detalhes sobre quais tipos de integrações suportam a funcionalidade descrita nesta página.

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

Pré-requisitos em seu sistema

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

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

Para configurar a autenticação OAuth 2 para o seu destino no Experience Platform, adicione os detalhes do OAuth 2 à configuração de destino, no âmbito do customerAuthenticationConfigurations parâmetro. 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 autenticação OAuth 2, estão mais abaixo nesta página.

Tipos de concessão OAuth 2 compatíveis

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.

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 flexível de autenticação/autorização OAuth 2 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 autenticação no seu destino.

O sistema que o Adobe projetou para a autenticaçã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

Se o destino suportar um fluxo de código de autorização OAuth 2.0 padrão (leia o Especificações de padrões RFC) ou uma variação dele, consulte os campos obrigatórios e opcionais abaixo:

Para definir esse método de autenticação para o seu destino, adicione as seguintes linhas na 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"]
    }
  ]
//...
}

OAuth 2 com concessão de senha

Para a concessão de Senha do 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, 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 definir esse método de autenticação para o seu destino, adicione as seguintes linhas na 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"]
    }
  ]

OAuth 2 com concessão de credenciais do cliente

Você pode configurar as Credenciais de cliente do OAuth 2 (leia o Especificações de padrões RFC), 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 definir esse método de autenticação para o seu destino, adicione as seguintes linhas na 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"]
    }
  ]
//...
}

Personalizar a configuração do OAuth 2

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 o authenticationDataFields como mostrado nos exemplos abaixo.

Exemplo 1: uso 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 o 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: uso 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 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

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

Atualização do token de acesso

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 accessTokenRequest parâmetro 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:

Convenções de modelos

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

Próximas etapas

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

Recursos do Business.Adobe.com