Autorización de OAuth 2

Destination SDK admite varios métodos de autorización para el destino. Entre estas está la opción de autenticarse en su destino usando el Marco de autorización de OAuth 2.

En esta página se describen los distintos flujos de autorización de OAuth 2 admitidos por el Destination SDK y se proporcionan instrucciones para configurar la autorización de OAuth 2 para el destino.

Tipos de integración admitidos

Consulte la tabla siguiente para obtener detalles sobre qué tipos de integraciones admiten la funcionalidad descrita en esta página.

Cómo añadir detalles de autorización de OAuth 2 a la configuración de destino

Requisitos previos en el sistema

Como primer paso, debe crear una aplicación en el sistema para Adobe Experience Platform o, de lo contrario, registrar un Experience Platform en el sistema. El objetivo es generar un ID de cliente y un secreto de cliente, que son necesarios para autenticar al Experience Platform en el destino. Como parte de esta configuración en su sistema, necesita las URL de redireccionamiento/llamada de retorno de OAuth 2 de Adobe Experience Platform, que puede obtener de la lista siguiente.

• 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

Al final de este paso, debería tener:

• Un ID de cliente;
• Un secreto de cliente;
• URL de devolución de llamada de Adobe (para la concesión del código de autorización).

Qué debe hacer en Destination SDK

Para configurar la autorización de OAuth 2 para su destino en Experience Platform, debe añadir los detalles de OAuth 2 a configuración de destino, en customerAuthenticationConfigurations parámetro. Consulte autenticación de clientes para ver ejemplos detallados. A continuación, en esta página, se proporcionan instrucciones específicas sobre qué campos debe añadir a la plantilla de configuración, según el tipo de concesión de autorización de OAuth 2.

Tipos de concesión de OAuth 2 admitidos

El Experience Platform admite los tres tipos de concesión de OAuth 2 que aparecen en la siguiente tabla. Si tiene una configuración de OAuth 2 personalizada, Adobe puede admitirla con la ayuda de campos personalizados en la integración. Consulte las secciones de cada tipo de concesión para obtener más información.

En la tabla anterior se enumeran los campos que se utilizan en los flujos de OAuth 2 estándar. Además de estos campos estándar, varias integraciones de socios pueden requerir entradas y salidas adicionales. El Adobe ha diseñado un marco de autorización de OAuth 2 flexible para Destination SDK que puede gestionar variaciones del patrón de campos estándar anterior y, al mismo tiempo, admitir un mecanismo para regenerar automáticamente salidas no válidas, como tokens de acceso caducados.

La salida en todos los casos incluye un token de acceso, que el Experience Platform utiliza para autenticar y mantener la autorización en el destino.

El sistema que el Adobe ha diseñado para la autorización de OAuth 2:

• Admite las tres concesiones de OAuth 2, teniendo en cuenta cualquier variación en ellas, como campos de datos adicionales, llamadas de API no estándar y más.
• Admite tokens de acceso con distintos valores de duración, ya sea 90 días, 30 minutos o cualquier otro valor de duración especificado.
• Admite flujos de autorización de OAuth 2 con o sin tokens de actualización.

OAuth 2 con código de autorización

Si su destino admite un flujo de código de autorización de OAuth 2.0 estándar (lea la Especificaciones de estándares RFC) o una variación del mismo, consulte los campos obligatorios y opcionales a continuación:

Para configurar este método de autorización para el destino, agregue las siguientes líneas a la configuración cuando crear una configuración 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 con concesión de contraseña

Para la concesión de contraseña de OAuth 2 (lea la Especificaciones de estándares RFC), el Experience Platform requiere el nombre de usuario y la contraseña del usuario. En el flujo de autorización, Experience Platform intercambia estas credenciales por un token de acceso y, opcionalmente, un token de actualización.
Adobe utiliza las entradas estándar siguientes para simplificar la configuración de destino, con la capacidad de anular los valores:

Para configurar este método de autorización para el destino, agregue las siguientes líneas a la configuración cuando crear una configuración 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 con concesión de credenciales de cliente

Puede configurar las credenciales de cliente de OAuth 2 (lea la Especificaciones de estándares RFC), que admite las entradas y salidas estándar que se enumeran a continuación. Tiene la capacidad de personalizar los valores. Consulte Personalizar la configuración de OAuth 2 para obtener más información.

Para configurar este método de autorización para el destino, agregue las siguientes líneas a la configuración cuando crear una configuración 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 la configuración de OAuth 2

Las configuraciones descritas en las secciones anteriores describen concesiones de OAuth 2 estándar. Sin embargo, el sistema diseñado por Adobe proporciona flexibilidad para que pueda utilizar parámetros personalizados para cualquier variación en la concesión de OAuth 2. Para personalizar la configuración estándar de OAuth 2, utilice el authenticationDataFields parámetros, como se muestra en los ejemplos siguientes.

Ejemplo 1: Uso de authenticationDataFields para capturar información proveniente de la respuesta de autorización

En este ejemplo, una plataforma de destino tiene tokens de actualización que caducan después de una determinada cantidad de tiempo. En este caso, el socio configura el refreshTokenExpiration campo personalizado para obtener la caducidad del token de actualización de la refresh_token_expires_in en la respuesta de 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"
            }
         ]
      }
   ]
}

Ejemplo 2: Uso de authenticationDataFields para proporcionar un token de actualización especial

En este ejemplo, un socio configura su destino para proporcionar un token de actualización especial. Además, la fecha de caducidad de los tokens de acceso no se devuelve en la respuesta de la API para que puedan codificar un valor predeterminado, en este caso de 3600 segundos.

      "authenticationDataFields": [
        {
            "name": "refreshToken",
            "value": "special_refresh_token"
        },
        {
            "name": "expiresIn",
            "value": 3600
        }
      ]

Ejemplo 3: El usuario introduce el ID de cliente y el secreto de cliente cuando configura el destino

En este ejemplo, en lugar de crear un ID de cliente global y un secreto de cliente, como se muestra en la sección Requisitos previos en el sistema, el cliente debe introducir el ID de cliente, el secreto de cliente y el ID de cuenta (el ID que utiliza el cliente para iniciar sesión en el 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"
                    }
                ]
            }
        }
    ]
//...
}

Puede utilizar los siguientes parámetros en authenticationDataFields para personalizar la configuración de OAuth 2:

Actualización de token de acceso

El Adobe ha diseñado un sistema que actualiza los tokens de acceso caducados sin que sea necesario que el usuario vuelva a iniciar sesión en su plataforma. El sistema puede generar un nuevo token para que la activación en su destino continúe sin problemas para el cliente.

Para configurar la actualización de tokens de acceso, es posible que tenga que configurar una solicitud HTTP con plantilla que permita al Adobe obtener un nuevo token de acceso mediante un token de actualización. Si el token de acceso ha caducado, el Adobe toma la solicitud con plantilla proporcionada por usted y agrega los parámetros proporcionados. Utilice el accessTokenRequest para configurar un mecanismo de actualización de token de acceso.

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

Puede utilizar los siguientes parámetros en accessTokenRequest para personalizar el proceso de actualización de tokens:

Convenciones de plantilla

Según la personalización de la autorización, es posible que deba acceder a los campos de datos de la respuesta de autorización, como se muestra en la sección anterior. Para ello, familiarícese con el Lenguaje de creación de plantillas Pebble se utiliza en el Adobe de y consulte las convenciones de creación de plantillas que aparecen a continuación para personalizar la implementación de OAuth 2.

Pasos siguientes

Al leer este artículo, ahora comprende los patrones de autorización de OAuth 2 admitidos por Adobe Experience Platform y sabe cómo configurar su destino con compatibilidad con la autorización de OAuth 2. A continuación, puede configurar el destino compatible con OAuth 2 mediante Destination SDK. Leer Use el Destination SDK para configurar el destino para ver los pasos siguientes.