SSO - Passo 1: Ligar o usuário do seu sistema ao usuário da Engage

O SSO leva o usuário do seu sistema para o portal da Engage sem pedir senha. O primeiro passo é registrar, para cada usuário, o identificador que ele já tem no seu sistema — o "De/Para". Sem esse vínculo, a Engage não sabe de quem é o acesso.

Antes de começar

• As credenciais da sua instância, reunidas em Comece por aqui: credenciais para integrar com a API da Engage, e um token gerado em Passo 2 — Obtendo o access_token (POST /auth).
• O usuário de serviço precisa da permissão Gerenciar usuários.
• O usuário final já existe na Engage. Este passo não cria usuário — para isso, veja Integração de usuários: criar e atualizar.
• Teste em homologação: https://sandbox.engage.bz/api/v1.

Registrar o identificador

1Envie o De/Para

POST https://sandbox.engage.bz/api/v1/{customer_id}/users/identifiers?customerToken={customer_token}
Authorization: Bearer {access_token}
Content-Type: application/json

[
  {
    "user_login": "joao.silva",
    "client_application_id": "{client_id}",
    "identifier": "a3f1c2d4-55aa-4b7c-9e11-0d2b3c4d5e6f"
  }
]

No Postman: pasta 04 - SSO e identificadores, request De/Para — criar/atualizar identificador.

Corpo do request De/Para — criar/atualizar identificador no Postman, com valores fictícios

O corpo é sempre uma lista, mesmo para um usuário só. O customerToken vai na URL em toda chamada.

2Leia o resultado de cada usuário

A chamada responde HTTP 200 mesmo quando algum usuário é recusado. Cada item de results traz o seu próprio success, e o motivo da recusa vem em detail_messages[].event_code. A sua rotina precisa ler esses campos, não só o código HTTP.

Para conferir o que ficou gravado, use o request De/Para — conferir identificador gravado.

Cuidados

• Reenviar substitui. A chave do vínculo é o par user_login + client_application_id. Reenviar o par com outro identifier troca o anterior, que deixa de funcionar.
• Base antiga com identificadores sequenciais? Gere um valor novo e aleatório por usuário e reenvie o De/Para. O identificador antigo deixa de valer.
• O identificador é único por aplicação. Se ele já pertence a outro usuário, o registro é recusado.
• Usuário inativo não entra. O vínculo é gravado, mas o Passo 2 recusa o acesso.
• Logins internos da plataforma são recusados, como o do próprio usuário de serviço. Faça o De/Para só de usuários finais.

Problemas comuns