Configurar autenticação para um conector de SDK de streaming
A autenticação é necessária para todos os conectores criados com o Streaming SDK. Antes de enviar ou liberar um conector, configure um mecanismo de autenticação com suporte:
Configure o mecanismo que corresponde ao modelo de integração do conector.
Antes de começar
Verifique se você tem:
- Uma implementação concluída do conector de transmissão do SDK.
- Um endpoint de API de assimilação de streaming de preparo ou teste.
- Uma organização e uma sandbox de teste do Adobe.
- Uma carga de evento de teste.
- Um plano para armazenar e girar credenciais com segurança.
- Uma maneira de capturar detalhes de solicitação e resposta sem expor segredos.
Requisitos adicionais do OAuth
Se você usar o OAuth 2.0, verifique se:
- Acesso ao Adobe Developer Console.
- A API ou o perfil de produto necessário para o conector.
- A ID do cliente e o segredo do cliente para a credencial selecionada.
- Os escopos necessários.
- O fluxo OAuth e o ponto de extremidade do token exigidos pelo conector.
Para obter o tipo de credencial da Adobe apropriado e detalhes de implementação, consulte:
Requisitos adicionais de HMAC
Se você usa HMAC, certifique-se de ter:
- Um segredo compartilhado configurado para o webhook ou conector.
- Um local seguro para armazenar o segredo.
- Código que pode calcular uma assinatura HMAC-SHA256.
- O corpo exato do evento serializado que será enviado para o Adobe.
- Um procedimento de teste para segredos válidos, inválidos, ausentes e girados.
Configurar o OAuth 2.0
1. Criar ou selecionar uma credencial do Adobe
Primeiro, você deve criar ou selecionar a credencial do Adobe Developer Console exigida pelo conector.
Configurar:
- O tipo de credencial.
- A API do Adobe ou o perfil de produto necessário.
- Os escopos necessários.
- As configurações de redirecionamento ou consentimento, se aplicáveis ao fluxo OAuth selecionado.
Não use um tipo de credencial sem suporte no modelo de integração do conector.
2. Armazene a configuração do OAuth com segurança
Armazene os seguintes valores com segurança:
- ID do cliente.
- Segredo do cliente.
- Escopos necessários.
- Endpoint do token.
- Quaisquer valores de locatário, organização ou ambiente específicos do conector.
Não confirme segredos do cliente no controle do código-fonte nem inclua em logs, mensagens de erro, capturas de tela ou resultados de teste.
3. Adicionar a configuração OAuth ao conector
Armazene os valores de configuração do OAuth na própria configuração ou serviço do conector. O Streaming SDK não define um campo de especificação de conexão para essa etapa de autenticação, pois ele controla como seu conector chama a API de assimilação de streaming, não como o Experience Platform se conecta à sua origem.
A configuração do conector deve incluir:
- Tipo de autenticação.
- ID do cliente.
- Segredo do cliente.
- Escopos.
- Endpoint do token.
- Qualquer valor adicional de locatário ou organização exigido por seu tipo de credencial.
4. Obter um token de acesso
Implemente o fluxo OAuth documentado para o seu tipo de credencial.
O conector deve:
- Autentique usando as credenciais do OAuth configuradas.
- Solicite os escopos exigidos pela integração do Streaming SDK.
- Armazene o token de acesso na memória ou em outro local seguro.
- Atualize ou adquira novamente o token de acordo com seu tempo de vida útil.
- Evite registrar o token ou o segredo do cliente.
5. Adicionar o token de acesso às solicitações
Inclua o token de acesso como um token de portador em solicitações enviadas pelo conector:
Authorization: Bearer {ACCESS_TOKEN}
Use HTTPS para todas as solicitações.
6. Manipular falhas de token
O conector deve detectar e lidar com falhas de autenticação, incluindo:
- Tokens de acesso ausentes.
- Tokens de acesso expirados.
- Credenciais de cliente inválidas.
- Escopos insuficientes.
- Credenciais revogadas ou desabilitadas.
Quando um token expirar, obtenha um novo token usando o fluxo OAuth documentado e tente novamente somente quando a operação for segura.
Configurar autenticação baseada em HMAC
1. Configurar o segredo compartilhado
Crie ou obtenha o segredo compartilhado exigido pelo conector e configure-o no conector ou na configuração do webhook.
O segredo deve ser:
- Armazenado com segurança.
- Disponível para o código de assinatura no tempo de execução.
- Excluído do controle de origem e logs.
- Alternada de acordo com sua política de segurança.
2. Serializar o evento
Serialize o evento antes de calcular a assinatura.
A assinatura deve ser calculada a partir da mesma mensagem serializada que o conector envia no corpo da solicitação.
serializedMessage = serialize(event)
Não calcule a assinatura de uma representação do evento e envie outra representação. Alterações nos espaços em branco, ordem de propriedade, escape, codificação ou terminações de linha podem causar falha na validação da assinatura.
3. Calcular a assinatura HMAC-SHA256
Calcule o valor HMAC-SHA256 usando:
- Chave: o segredo compartilhado configurado.
- Mensagem: O corpo da solicitação serializada.
signature = HMAC-SHA256(secret, serializedMessage)
4. Adicionar o cabeçalho HMAC
Adicionar a assinatura calculada à solicitação como o cabeçalho x-hmac-sha256:
POST <streaming-ingestion-endpoint>
Content-Type: application/json
x-hmac-sha256: {CALCULATED_SIGNATURE}
<serialized-message>
Por exemplo, o cabeçalho é resolvido como um valor semelhante a:
{
"x-hmac-sha256": "5f2c8b7e0d9c3a4e6b1f2d3c4a5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
}
O valor do cabeçalho deve representar o cálculo HMAC-SHA256 para o corpo de solicitação exato enviado ao Adobe.
5. Enviar a solicitação
Envie a solicitação assinada por HTTPS para o endpoint da API de assimilação de streaming.
A API de assimilação de streaming verifica a assinatura antes de processar o evento. Solicitações com uma assinatura ausente ou inválida são rejeitadas.
6. Girar o segredo em segurança
Ao girar um segredo, siga esta sequência:
- Crie um novo segredo em seu sistema de gerenciamento de credenciais.
- Caso haja suporte para segredos sobrepostos, mantenha o segredo existente ativo enquanto implanta o novo segredo.
- Atualize a configuração do conector com o novo segredo.
- Implante ou salve a configuração.
- Envie uma solicitação de teste e verifique se a autenticação tem êxito.
- Monitore falhas de autenticação e revogue o segredo antigo depois que todas as instâncias do conector usarem o novo.
Verifique o conector
Teste o conector com cenários de autenticação bem-sucedidos e malsucedidos.
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| Teste | Resultado esperado |
| Solicitação com um token de acesso válido | O evento é aceito e processado. |
| Solicitação sem um token de acesso | A solicitação foi rejeitada. |
| Solicitação com um token de acesso expirado | A solicitação é rejeitada ou o conector obtém um novo token e tentativas de acordo com sua política de tentativas. |
| Solicitação com um token de acesso inválido | A solicitação foi rejeitada. |
| Solicitação com escopos insuficientes | A solicitação foi rejeitada. |
| Solicitação após a rotação de credencial | O conector obtém e usa a nova credencial com sucesso. |
| 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 | |
|---|---|
| Teste | Resultado esperado |
| Solicitação com uma assinatura válida e um segredo atual | O evento é aceito e processado. |
Solicitação sem x-hmac-sha256 |
A solicitação foi rejeitada. |
| Solicitação com uma assinatura inválida | A solicitação foi rejeitada. |
| Solicitação assinada com o segredo errado | A solicitação foi rejeitada. |
| Corpo da solicitação modificado após a geração da assinatura | A solicitação foi rejeitada. |
| Solicitação assinada com um segredo anterior válido durante a rotação | O resultado segue o comportamento de rotação secreta documentado. |
| Solicitação assinada com um segredo removido | A solicitação foi rejeitada. |
Registre o seguinte para cada teste:
- Método de solicitação e ponto de extremidade.
- Cabeçalhos de solicitação, com segredos e tokens ocultos.
- Corpo da solicitação serializada.
- Mecanismo de autenticação usado.
- Status e corpo da resposta.
- Carimbo de data e hora e identificador de correlação ou rastreamento, se disponível.
- Se o evento foi assimilado com êxito.
Solução de problemas
Falhas de autenticação do OAuth
Verifique o seguinte:
- O token de acesso foi gerado para a organização e o ambiente corretos do Adobe.
- A ID do cliente e o segredo do cliente pertencem à credencial configurada.
- Os escopos solicitados estão corretos.
- O token de acesso não expirou.
- O token é enviado usando o esquema Autorização: Portador.
- O conector está usando o ponto de extremidade de token correto.
- A credencial tem acesso à API ou ao perfil de produto necessário.
Falhas de autenticação HMAC
Verifique o seguinte:
- O cabeçalho
x-hmac-sha256está presente. - O nome e o valor do cabeçalho são escritos corretamente.
- O conector está usando o segredo correto.
- A assinatura é calculada com HMAC-SHA256.
- A assinatura é calculada sobre o corpo exato da solicitação serializada.
- O corpo da solicitação não é reformatado após o cálculo da assinatura.
- A codificação de assinatura e letra maiúscula necessárias estão corretas.
- O conector está usando o segredo atual ou anterior correto durante a rotação.
- O segredo está disponível para o tempo de execução e não foi truncado ou alterado.
Requisitos de envio
Antes de enviar ou liberar o conector, confirme o seguinte:
- Seu conector usa OAuth 2.0 ou autenticação baseada em HMAC para cada solicitação para a API de assimilação de streaming.
- Você testou os cenários em Verificar o conector e registrou os resultados.
- Seu conector rejeita solicitações não autenticadas e autenticadas incorretamente.
- Seus segredos e tokens não estão comprometidos com o controle do código-fonte, registros, mensagens de erro ou capturas de tela.
Próximas etapas
Com a autenticação configurada e verificada, continue em Testar e enviar sua origem. Para saber como documentar os requisitos de autenticação para sua origem, consulte Documentar sua origem (Streaming SDK).