Configuración de la autenticación para un conector de Streaming SDK
Se requiere la autenticación para todos los conectores creados con Streaming SDK. Antes de enviar o liberar un conector, configure un mecanismo de autenticación compatible:
Configure el mecanismo que coincida con el modelo de integración del conector.
Antes de empezar
Asegúrese de que dispone de:
- Se ha completado una implementación del conector de Streaming SDK.
- Un punto final de API de ingesta de transmisión de ensayo o prueba.
- Una organización de Adobe y zona protegida de prueba.
- Una carga útil de evento de prueba.
- Plan para almacenar y rotar credenciales de forma segura.
- Una forma de recopilar detalles de solicitudes y respuestas sin exponer secretos.
Requisitos adicionales de OAuth
Si utiliza OAuth 2.0, asegúrese de que dispone de lo siguiente:
- Acceso a Adobe Developer Console.
- El perfil de producto o API requerido para el conector.
- El ID de cliente y el secreto de cliente de la credencial seleccionada.
- Los ámbitos necesarios.
- El extremo de token y flujo de OAuth requerido por el conector.
Para obtener el tipo de credencial de Adobe y los detalles de implementación adecuados, consulte:
Requisitos adicionales de HMAC
Si utiliza HMAC, asegúrese de que dispone de:
- Un secreto compartido configurado para el webhook o el conector.
- Una ubicación segura para almacenar el secreto.
- Código que puede calcular una firma HMAC-SHA256.
- El cuerpo del evento serializado exacto que se enviará a Adobe.
- Procedimiento de prueba para secretos válidos, no válidos, faltantes y girados.
Configuración de OAuth 2.0
1. Crear o seleccionar una credencial de Adobe
En primer lugar, debe crear o seleccionar las credenciales de Adobe Developer Console que requiere el conector.
Configurar:
- El tipo de credencial.
- El perfil de producto o la API de Adobe necesarios.
- Los ámbitos necesarios.
- La configuración de redireccionamiento o consentimiento, si corresponde al flujo de OAuth seleccionado.
No utilice un tipo de credencial que no sea compatible con el modelo de integración del conector.
2. Almacene la configuración de OAuth de forma segura
Almacene los siguientes valores de forma segura:
- ID de cliente.
- Secreto del cliente.
- Ámbitos requeridos.
- Extremo del token.
- Cualquier valor de inquilino, organización o entorno específico del conector.
No confirme secretos de cliente al control de código fuente ni los incluya en registros, mensajes de error, capturas de pantalla ni resultados de pruebas.
3. Añada la configuración de OAuth al conector
Almacene los valores de configuración de OAuth en la configuración o el servicio propios del conector. Streaming SDK no define un campo de especificación de conexión para este paso de autenticación, ya que rige la forma en que el conector llama a la API de ingesta de transmisión, no la forma en que Experience Platform se conecta al origen.
La configuración del conector debe incluir lo siguiente:
- Tipo de autenticación.
- ID de cliente.
- Secreto del cliente.
- Ámbitos.
- Extremo del token.
- Cualquier valor de inquilino u organización adicional que requiera su tipo de credencial.
4. Obtener un token de acceso
Implemente el flujo de OAuth documentado para su tipo de credencial.
El conector debe:
- Autentique con las credenciales de OAuth configuradas.
- Solicite los ámbitos requeridos por la integración de Streaming SDK.
- Almacene el token de acceso en la memoria o en otra ubicación segura.
- Actualice o vuelva a adquirir el token según la duración del token.
- Evite registrar el token o el secreto de cliente.
5. Añadir el token de acceso a las solicitudes
Incluya el token de acceso como token de portador en las solicitudes enviadas por el conector:
Authorization: Bearer {ACCESS_TOKEN}
Utilice HTTPS para todas las solicitudes.
6. Controlar errores de token
El conector debe detectar y gestionar los errores de autenticación, incluidos los siguientes:
- Faltan tokens de acceso
- Tokens de acceso caducados.
- Credenciales de cliente no válidas.
- Ámbitos insuficientes.
- Credenciales revocadas o deshabilitadas.
Cuando caduque un token, obtenga un nuevo token con el flujo de OAuth documentado y vuelva a intentarlo solo cuando la operación sea segura para reintentar.
Configurar la autenticación basada en HMAC
1. Configuración del secreto compartido
Cree o consiga el secreto compartido que requiere el conector y configúrelo en la configuración del conector o del gancho web.
El secreto debe ser:
- Almacenado de forma segura.
- Disponible para el código de firma en tiempo de ejecución.
- Excluido del control de código fuente y los registros.
- Se rota según la directiva de seguridad.
2. Serialice el evento
Serialice el evento antes de calcular la firma.
La firma debe calcularse a partir del mismo mensaje serializado que envía el conector en el cuerpo de la solicitud.
serializedMessage = serialize(event)
No calcule la firma desde una representación del evento y envíe otra representación. Los cambios en el espacio en blanco, el orden de las propiedades, el escape, la codificación o los extremos de línea pueden provocar errores en la validación de la firma.
3. Calcular la firma HMAC-SHA256
Calcule el valor HMAC-SHA256 mediante:
- Clave: El secreto compartido configurado.
- Mensaje: El cuerpo de solicitud serializado.
signature = HMAC-SHA256(secret, serializedMessage)
4. Añadir el encabezado HMAC
Agregar la firma calculada a la solicitud como encabezado x-hmac-sha256:
POST <streaming-ingestion-endpoint>
Content-Type: application/json
x-hmac-sha256: {CALCULATED_SIGNATURE}
<serialized-message>
Por ejemplo, el encabezado se resuelve en un valor similar a:
{
"x-hmac-sha256": "5f2c8b7e0d9c3a4e6b1f2d3c4a5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
}
El valor del encabezado debe representar el cálculo HMAC-SHA256 para el cuerpo de solicitud exacto enviado a Adobe.
5. Enviar la solicitud
Envíe la solicitud firmada a través de HTTPS al extremo de la API de ingesta de transmisión.
La API de ingesta de transmisión verifica la firma antes de procesar el evento. Se rechazan las solicitudes con una firma que falta o no es válida.
6. Rotar el secreto de forma segura
Cuando gire un secreto, siga esta secuencia:
- Cree un nuevo secreto en el sistema de administración de credenciales.
- Mantenga el secreto existente activo mientras implementa el nuevo secreto, si se admiten secretos superpuestos.
- Actualice la configuración del conector con el nuevo secreto.
- Implemente o guarde la configuración.
- Envíe una solicitud de prueba y compruebe que la autenticación se haya realizado correctamente.
- Supervise los errores de autenticación y, a continuación, revoque el secreto antiguo después de que todas las instancias del conector utilicen el nuevo.
Compruebe el conector
Pruebe el conector en situaciones de autenticación correctas e incorrectas.
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| Prueba | Resultado esperado |
| Solicitud con un token de acceso válido | El evento se acepta y se procesa. |
| Solicitud sin token de acceso | Se rechaza la solicitud. |
| Solicitud con un token de acceso caducado | La solicitud se rechaza o el conector obtiene un nuevo token y reintenta según su política de reintentos. |
| Solicitud con un token de acceso no válido | Se rechaza la solicitud. |
| Solicitud con ámbitos insuficientes | Se rechaza la solicitud. |
| Solicitud después de la rotación de credenciales | El conector obtiene y utiliza la nueva credencial correctamente. |
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 | |
|---|---|
| Prueba | Resultado esperado |
| Solicitud con una firma válida y secreto actual | El evento se acepta y se procesa. |
Solicitud sin x-hmac-sha256 |
Se rechaza la solicitud. |
| Solicitud con una firma no válida | Se rechaza la solicitud. |
| Solicitud firmada con el secreto incorrecto | Se rechaza la solicitud. |
| Cuerpo de solicitud modificado después de la generación de firma | Se rechaza la solicitud. |
| Solicitud firmada con un secreto anterior válido durante la rotación | El resultado sigue el comportamiento de rotación de secretos documentado. |
| Solicitud firmada con un secreto eliminado | Se rechaza la solicitud. |
Registre lo siguiente para cada prueba:
- Método de solicitud y extremo.
- Encabezados de solicitud, con secretos y tokens eliminados.
- Cuerpo de solicitud serializado.
- Mecanismo de autenticación utilizado.
- Estado de respuesta y cuerpo.
- Marca de tiempo y correlación o identificador de seguimiento, si están disponibles.
- Si el evento se ha introducido correctamente.
Resolución de problemas
Errores de autenticación de OAuth
Compruebe lo siguiente:
- Se ha generado el token de acceso para la organización y el entorno de Adobe correctos.
- El ID de cliente y el secreto de cliente pertenecen a la credencial configurada.
- Los ámbitos solicitados son correctos.
- El token de acceso no ha caducado.
- El token se envía utilizando el esquema Autorización: Portador.
- El conector utiliza el extremo de token correcto.
- La credencial tiene acceso a la API o al perfil de producto requerido.
Errores de autenticación HMAC
Compruebe lo siguiente:
- El encabezado
x-hmac-sha256está presente. - El nombre y el valor del encabezado están escritos correctamente.
- El conector utiliza el secreto correcto.
- La firma se calcula con HMAC-SHA256.
- La firma se calcula sobre el cuerpo exacto de la solicitud serializada.
- No se vuelve a dar formato al cuerpo de la solicitud después de calcular la firma.
- La codificación de firma y el formato de letra requeridos son correctos.
- El conector utiliza la corriente correcta o el secreto anterior durante la rotación.
- El secreto está disponible para el tiempo de ejecución y no se ha truncado ni alterado.
Requisitos de envío
Antes de enviar o soltar el conector, confirme lo siguiente:
- El conector utiliza la autenticación basada en OAuth 2.0 o HMAC para cada solicitud a la API de ingesta de transmisión.
- Ha probado los escenarios en Compruebe el conector y ha registrado los resultados.
- El conector rechaza las solicitudes no autenticadas y autenticadas incorrectamente.
- Sus secretos y tokens no están comprometidos con el control de código fuente, los registros, los mensajes de error ni las capturas de pantalla.
Próximos pasos
Con la autenticación configurada y verificada, continúa Probar y enviar el origen. Para obtener información sobre cómo documentar los requisitos de autenticación para su origen, consulte Documentar su origen (Streaming SDK).