lxbfYeaa

>

Documento para o cliente implementar a geração do magic link em seu próprio sistema. > Versão do esquema: v2. Validade do link: 2 minutos.

Visão geral

O Login Externo permite que o seu sistema (intranet, portal etc.) gere um link de acesso que autentica automaticamente uma pessoa na plataforma, sem digitar senha.

Na v2, esse link é assinado criptograficamente (HMAC-SHA256) e tem validade curta (2 minutos). Você recebe da nossa equipe um par de chaves e monta a URL localmente — nenhuma chamada de rede é necessária para gerar o link.

---

O que você recebe da nossa equipe

Entregues uma única vez, por canal seguro:

Valor	O que é	Onde usar
external_login_id	Chave pública (identificador da empresa)	Vai dentro do link. Não é segredo.
external_login_secret	Chave privada (segredo de assinatura)	Fica só no seu servidor. Nunca vai no link.
url_empresa	URL base da sua plataforma (ex.: https://sua-empresa.exemplo.com)	Prefixo do link. Sem barra final.

>

⚠️ O external_login_secret é secreto. Guarde-o apenas no servidor (variável de ambiente ou configuração protegida). Nunca o coloque em código versionado público, no navegador, em logs ou na URL. Se suspeitar de vazamento, solicite a rotação do segredo à nossa equipe.

---

Formato do link

GET {url_empresa}/login_externo/acessar?v=2&d={payload}&s={assinatura}

• v=2 — versão do esquema (fixo).
• d — o payload em Base64 url-safe sem padding (JSON abaixo).
• s — a assinatura HMAC-SHA256 do valor de d, em hexadecimal.

Payload (JSON antes de codificar em d)

{
  "emp"&quot;emp&quot;:   "<&quot;&lt;external_login_id>"&gt;&quot;,
  "login"&quot;login&quot;: "<&quot;&lt;login_da_pessoa>"&gt;&quot;,
  "ts"&quot;ts&quot;:    1753800000
}

• emp — a sua chave pública (external_login_id).
• login — o login da pessoa na plataforma. Se for CPF, envie apenas os números (sem pontos ou traço).
• ts — o timestamp Unix (segundos) do momento da geração. O servidor aceita uma janela de ±120 segundos.

---

Algoritmo (agnóstico de linguagem)

1. Monte o objeto JSON com emp, login e ts (timestamp Unix em segundos).
2. Serialize esse JSON em texto (UTF-8).
3. Codifique em Base64 url-safe: Base64 padrão, trocando + por - e / por _, e removendo o = de padding do final. O resultado é o valor d.
4. Calcule s = HMAC-SHA256(mensagem = d, chave = external_login_secret) e represente em hexadecimal minúsculo.
5. Monte a URL: {url_empresa}/login_externo/acessar?v=2&d={d}&s={s}.

>

🔑 Ponto crítico: a assinatura é calculada sobre a string d (exatamente como ela vai na URL) — não sobre o JSON original. Isso significa que pequenas diferenças na serialização do JSON entre linguagens não quebram a validação, desde que você assine exatamente o mesmo d que envia na URL.

> > d e s usam apenas caracteres seguros para URL (A–Z a–z 0–9 - _ e hexadecimal), então não precisam de URL-encoding adicional.

---

Exemplos de código

Em todos: gere o link no momento do redirecionamento (ele expira em 2 minutos) e substitua os placeholders pelos valores recebidos.

PHP

<&lt;?php
    $externalLoginId     = '<&#039;&lt;external_login_id>'&gt;&#039;;      // chave PÚBLICA (vai na URL)
    $externalLoginSecret = '<&#039;&lt;external_login_secret>'&gt;&#039;;  // chave PRIVADA — nunca expor
    $urlEmpresa          = '&#039;https://<&lt;url-empresa>'&gt;&#039;;    // sem barra final
    $loginPessoa         = '<&#039;&lt;login_da_pessoa>'&gt;&#039;;         // CPF: só números

    $payload = array(
        'emp'&#039;emp&#039;   =>&gt; $externalLoginId,
        'login'&#039;login&#039; =>&gt; $loginPessoa,
        'ts'&#039;ts&#039;    =>&gt; time(),
    );

    // Base64 url-safe sem padding
    $d = rtrim(strtr(base64_encode(json_encode($payload)), '&#039;+/'&#039;, '&#039;-_'_&#039;), '&#039;='&#039;);

    // HMAC-SHA256 (hex) sobre o valor de $d
    $s = hash_hmac('sha256'&#039;sha256&#039;, $d, $externalLoginSecret);

    echo $urlEmpresa . '&#039;/login_externo/acessar?v=2&amp;d='&#039; . $d . '&#039;&amp;s='&#039; . $s;
?>&gt;

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class MagicLinkV2 {
    public static String gerar(String externalLoginId, String externalLoginSecret,
                               String urlEmpresa, String loginPessoa) throws Exception {

        long ts = System.currentTimeMillis() / 1000L;

        // Monte o JSON (use uma lib JSON se o login puder conter caracteres especiais)
        String json = ""{\""emp\"":\"""" + externalLoginId + ""\"",\""login\"":\"""" + loginPessoa + ""\"",\""ts\"":"" + ts + ""}"";

        // Base64 url-safe sem padding
        String d = Base64.getUrlEncoder().withoutPadding()
                .encodeToString(json.getBytes(StandardCharsets.UTF_8));

        // HMAC-SHA256 (hex) sobre o valor de d
        Mac mac = Mac.getInstance("HmacSHA256""HmacSHA256");
        mac.init(new SecretKeySpec(externalLoginSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256""HmacSHA256"));
        byte[] raw = mac.doFinal(d.getBytes(StandardCharsets.UTF_8));

        StringBuilder hex = new StringBuilder(raw.length * 2);
        for (byte b : raw) hex.append(String.format(""%02x"02x", b));
        String s = hex.toString();

        return urlEmpresa + ""/login_externo/acessar?v=2&d="" + d + ""&s="" + s;
    }
}

Node.js

const crypto = require('crypto''crypto');

function gerarLink(externalLoginId, externalLoginSecret, urlEmpresa, loginPessoa) {
    const payload = {
        emp:   externalLoginId,
        login: loginPessoa,
        ts:    Math.floor(Date.now() / 1000),
    };

    // Base64 url-safe sem padding (Node 16+ suporta 'base64url''base64url')
    const d = Buffer.from(JSON.stringify(payload)).toString('base64url''base64url');

    // HMAC-SHA256 (hex) sobre o valor de d
    const s = crypto.createHmac('sha256''sha256', externalLoginSecret).update(d).digest('hex''hex');

    return `${urlEmpresa}/login_externo/acessar?v=2&d=${d}&s=${s}`;
}

>

Em versões antigas do Node (sem 'base64url''base64url'), gere assim: > Buffer.from(JSON.stringify(payload)).toString('base64''base64').replace(/\+/g,''-'').replace(/\//g,'_''_').replace(/=+$/,'''')

Python

import base64, hmac, hashlib, json, time

def gerar_link(external_login_id, external_login_secret, url_empresa, login_pessoa):
    payload = {"emp""emp": external_login_id, "login""login": login_pessoa, "ts""ts": int(time.time())}

    # JSON compacto (sem espaços) em UTF-8
    raw = json.dumps(payload, separators=("","", "":"")).encode(""utf-8"8")

    # Base64 url-safe sem padding
    d = base64.urlsafe_b64encode(raw).rstrip(b"b"="").decode("ascii""ascii")

    # HMAC-SHA256 (hex) sobre o valor de d
    s = hmac.new(external_login_secret.encode(""utf-8"8"),
                 d.encode(""utf-8"8"), hashlib.sha256).hexdigest()

    return f"f"{url_empresa}/login_externo/acessar?v=2&d={d}&s={s}""

---

Regras operacionais

• Gere o link só na hora do redirecionamento. Ele expira em 2 minutos — não pré-gere nem faça cache de links.
• Mantenha o servidor com o relógio sincronizado (NTP). O ts é validado numa janela de ±120s; relógio muito defasado faz o link ser rejeitado.
• CPF como login: envie apenas os números (sem pontos/traço).
• Nunca exponha o external_login_secret — só no servidor. Ele nunca aparece na URL.
• Cada pessoa que vai acessar gera seu próprio link (com o login dela no payload).

---

Testando

1. Gere um link com o código acima para uma pessoa ativa e existente na plataforma.
2. Abra o link no navegador em até 2 minutos — o acesso deve ser efetuado automaticamente.
3. Nossa equipe também consegue validar o processo de geração pelo painel administrativo (diagnóstico item a item) — envie um link de exemplo caso precise de suporte.

Erros comuns

Sintoma	Causa provável
Link rejeitado logo após gerar	ts em milissegundos em vez de segundos; ou relógio do servidor defasado.
Sempre "acesso inválido"	Assinatura calculada sobre o JSON em vez do valor d; ou external_login_secret incorreto.
Funciona intermitentemente	Link pré-gerado/cacheado sendo aberto após os 2 minutos.
Caracteres estranhos na URL	d gerado em Base64 padrão (com +, /, =) em vez de url-safe sem padding.
Pessoa não encontrada	login divergente do cadastro (ex.: CPF com formatação, ou pessoa inativa).

---

Dúvidas

Em caso de dúvida na integração, entre em contato com a nossa equipe. Para rotação do segredo (troca do external_login_secret), solicite formalmente — a rotação invalida os links assinados com o segredo anterior.