Autorización de OAuth 2
Destination SDK admite varios métodos de autorización para el destino. Entre ellas se encuentra la opción de autenticarse en el destino mediante 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 supported-integration-types
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 how-to-setup
Requisitos previos en el sistema prerequisites
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/callbackhttps://platform-nld2.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-aus5.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-can2.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform-gbr9.adobe.io/data/core/activation/oauth/api/v1/callbackhttps://platform.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 to-do-in-destination-sdk
Para configurar la autorización de OAuth 2 para su destino en Experience Platform, debe agregar los detalles de OAuth 2 a la configuración de destino, en el parámetro customerAuthenticationConfigurations. Consulte autenticación de cliente 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 oauth2-grant-types
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.
- Proporcione los parámetros de entrada como se indica en las secciones siguientes. Los sistemas internos del Adobe se conectan al sistema de autorización de su plataforma y obtienen parámetros de salida, que se utilizan para autenticar al usuario y mantener la autorización en su destino.
- Los parámetros de entrada resaltados en negrita en la tabla son parámetros obligatorios en el flujo de autorización de OAuth 2. Los demás parámetros son opcionales. Hay otros parámetros de entrada personalizados que no se muestran aquí, pero que se describen en detalle en las secciones Personalizar la configuración de OAuth 2 y Actualización de token de acceso.
- clientId
- clientSecret
- ámbito
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- token de acceso
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- ámbito
- accessTokenUrl
- nombre de usuario
- contraseña
- token de acceso
- expiresIn
- refreshToken
- tokenType
- clientId
- clientSecret
- ámbito
- accessTokenUrl
- token de acceso
- expiresIn
- refreshToken
- tokenType
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 authorization-code
Si su destino admite un flujo de código de autorización de OAuth 2.0 estándar (lea las especificaciones de estándares RFC) o una variación de este, consulte los campos obligatorios y opcionales que aparecen a continuación:
- clientId
- clientSecret
- ámbito
- authorizationUrl
- accessTokenUrl
- refreshTokenUrl
- token de acceso
- expiresIn
- refreshToken
- tokenType
Para configurar este método de autorización para su destino, agregue las siguientes líneas a su configuración cuando cree 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"]
}
]
//...
}
authTypegrantaccessTokenUrlauthorizationUrlrefreshTokenUrlrefreshTokenUrl es el mismo que accessTokenUrl.clientIdclientSecretscopeOAuth 2 con concesión de contraseña
Para la concesión de contraseña de OAuth 2 (lea las especificaciones de los 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:
- clientId
- clientSecret
- ámbito
- accessTokenUrl
- nombre de usuario
- contraseña
- token de acceso
- expiresIn
- refreshToken
- tokenType
username y password en la configuración siguiente. Cuando agregue "grant": "OAUTH2_PASSWORD" a la configuración de destino, el sistema solicitará al usuario que proporcione un nombre de usuario y una contraseña en la interfaz de usuario del Experience Platform cuando se autentique en el destino.Para configurar este método de autorización para su destino, agregue las siguientes líneas a su configuración cuando cree 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"]
}
]
authTypegrantaccessTokenUrlclientIdclientSecretscopeOAuth 2 con concesión de credenciales de cliente
Puede configurar un destino de credenciales de cliente de OAuth 2 (lea las especificaciones de estándares RFC), que admita 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.
- clientId
- clientSecret
- ámbito
- accessTokenUrl
- token de acceso
- expiresIn
- refreshToken
- tokenType
Para configurar este método de autorización para su destino, agregue las siguientes líneas a su configuración cuando cree 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"]
}
]
//...
}
authTypegrantaccessTokenUrlrefreshTokenUrlrefreshTokenUrl es el mismo que accessTokenUrl.clientIdclientSecretscopePersonalizar la configuración de OAuth 2 customize-configuration
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 los parámetros authenticationDataFields, como se muestra en los ejemplos siguientes.
Ejemplo 1: Usar authenticationDataFields para capturar información proveniente de la respuesta de autorización example-1
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 campo personalizado refreshTokenExpiration para obtener la caducidad del token de actualización del campo refresh_token_expires_in en la respuesta de la 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: Usar authenticationDataFields para proporcionar un token de actualización especial example-2
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 example-3
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 de su sistema, el cliente debe especificar 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 usar los siguientes parámetros en authenticationDataFields para personalizar la configuración de OAuth 2:
authenticationDataFields.nameauthenticationDataFields.titleauthenticationDataFields.descriptionauthenticationDataFields.typeValores aceptados:
string, boolean, integerauthenticationDataFields.isRequiredauthenticationDataFields.format"format":"password", el Adobe cifra el valor del campo de datos de autorización. Cuando se utiliza con "fieldType": "CUSTOMER", esto también oculta la entrada en la interfaz de usuario cuando el usuario escribe en el campo.authenticationDataFields.fieldTypeauthenticationDataFields.valueauthenticationDataFields.type.authenticationDataFields.authenticationResponsePathActualización de token de acceso access-token-refresh
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 parámetro 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 usar los siguientes parámetros en accessTokenRequest para personalizar el proceso de actualización de tokens:
accessTokenRequest.destinationServerTypeURL_BASED.accessTokenRequest.urlBasedDestination.url.templatingStrategy- Use
PEBBLE_V1si usa plantillas para el valor deaccessTokenRequest.urlBasedDestination.url.value. - Use
NONEsi el valor del campoaccessTokenRequest.urlBasedDestination.url.valuees una constante.
accessTokenRequest.urlBasedDestination.url.valueaccessTokenRequest.httpTemplate.requestBody.templatingStrategy- Use
PEBBLE_V1si usa plantillas para los valores deaccessTokenRequest.httpTemplate.requestBody.value. - Use
NONEsi el valor del campoaccessTokenRequest.httpTemplate.requestBody.valuees una constante.
accessTokenRequest.httpTemplate.requestBody.valueaccessTokenRequest.httpTemplate.httpMethodPOST.accessTokenRequest.httpTemplate.contentTypePor ejemplo:
application/x-www-form-urlencoded o application/json.accessTokenRequest.httpTemplate.headersaccessTokenRequest.responseFields.templatingStrategy- Use
PEBBLE_V1si usa plantillas para los valores deaccessTokenRequest.responseFields.value. - Use
NONEsi el valor del campoaccessTokenRequest.responseFields.valuees una constante.
accessTokenRequest.responseFields.valueaccessTokenRequest.validations.nameaccessTokenRequest.validations.actualValue.templatingStrategy- Use
PEBBLE_V1si usa plantillas para los valores deaccessTokenRequest.validations.actualValue.value. - Use
NONEsi el valor del campoaccessTokenRequest.validations.actualValue.valuees una constante.
accessTokenRequest.validations.actualValue.valueaccessTokenRequest.validations.expectedValue.templatingStrategy- Use
PEBBLE_V1si usa plantillas para los valores deaccessTokenRequest.validations.expectedValue.value. - Use
NONEsi el valor del campoaccessTokenRequest.validations.expectedValue.valuees una constante.
accessTokenRequest.validations.expectedValue.valueConvenciones de plantilla templating-conventions
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 idioma de creación de plantillas Pebble que usa el Adobe y consulte las convenciones de creación de plantillas a continuación para personalizar su implementación de 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
Pasos siguientes next-steps
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. Lee Usar Destination SDK para configurar tu destino para los siguientes pasos.