SSO - Passo 2: obter a chave de entrada (custom_sso)

Com o De/Para gravado, o seu sistema troca o identificador do usuário por uma chave de entrada (key). É essa chave que leva o usuário para dentro do portal já autenticado, no Passo 3.

Antes de começar

• As credenciais da sua instância, reunidas em Comece por aqui: credenciais para integrar com a API da Engage.
• O De/Para do usuário gravado — veja SSO — Passo 1: ligar o usuário do seu sistema ao usuário da Engage.
• A aplicação (client_id) cadastrada como confidencial. Aplicações registradas pela área administrativa ou pela API já nascem assim — veja Registrar a aplicação de integração pela API. Se a sua aplicação é antiga, confirme com o Suporte antes de ir para produção.
• Teste em homologação: https://sandbox.engage.bz/api/v1.

Obter a chave

1Chame o POST /auth com custom_sso

POST https://sandbox.engage.bz/api/v1/auth
Content-Type: application/x-www-form-urlencoded

grant_type=custom_sso
&customer_id={customer_id}
&customer_token={customer_token}
&client_id={client_id}
&client_secret={client_secret}
&user_identifier={identificador_do_usuario}

Esta chamada não leva Authorization: a autenticação acontece nela. No Postman: pasta 04 - SSO e identificadores, request SSO — obter a key (custom_sso). O script do request guarda a chave na variável ssoKey e não a imprime no console, de propósito.

Corpo do request SSO — obter a key (custom_sso) no Postman, com os campos preenchidos por variáveis e um identificador fictício

2Pegue a key da resposta

A resposta é a mesma de um login comum, com um campo a mais: a key. Valores fictícios:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "0f3c9d1a...",
  "user_id": "1234",
  "key": "00000000-0000-4000-8000-000000000000",
  "is_blocked": false,
  "is_admin": false
}

A key é usada no Passo 3. O tempo de vida da sessão vem em expires_in, em segundos: ele é definido no cadastro da aplicação e não é fixo.

Cuidados

• O usuário final não precisa ser administrador nem ter senha na Engage. Quem autentica é o seu sistema. Quem precisa de permissão é o usuário de serviço do Passo 1.
• O que continua sendo validado: usuário ativo e não bloqueado, licença da instância, janela de horário de acesso e lista de IPs permitidos.
• Este fluxo não passa pelo segundo fator (2FA) da instância. Se a sua política exige MFA, aplique no seu sistema antes de chamar o custom_sso.
• Não repita a chamada "por garantia". Cada chamada bem-sucedida abre uma sessão nova e derruba a anterior do mesmo usuário, na mesma aplicação e no mesmo device.
• O customer_token não é segredo. Ele identifica a instância e pode ser obtido sem autenticação. O que protege o fluxo é o client_secret junto com um identificador não adivinhável.
• Não faça SSO com o usuário de serviço. Para logins internos, a resposta vem sem a key.

Problemas comuns