Skip to main content

Gerenciamento de Domínios para Federação de Identidade

Para utilizar a federação na Magalu Cloud, o primeiro passo fundamental é registrar o seu domínio de e-mail corporativo (por exemplo, suaempresa.com.br).

O gerenciamento de domínios garante que a plataforma saiba para qual Provedor de Identidade (IdP) deve redirecionar seus colaboradores no momento do login. Além disso, o processo de registro exige uma comprovação de titularidade. Esta é uma medida de segurança vital para impedir que terceiros mal-intencionados tentem configurar federações usando o nome da sua empresa e interceptem os acessos.

Regras de Segurança​

Para garantir a integridade e a segurança do ecossistema, o gerenciamento de domínios segue algumas regras rigorosas:

  • Exclusividade Global: Cada domínio só pode ser cadastrado uma única vez. Não podem existir duas organizações na Magalu Cloud com o mesmo domínio verificado.
  • Privacidade e Isolamento: Sua organização só tem permissão para visualizar e gerenciar os domínios que ela mesma cadastrou. É impossível acessar ou alterar configurações de domínios pertencentes a outras empresas.
  • Limite de Federação: Um domínio pode ter apenas uma federação ativa por vez. Ou seja, você deve escolher entre integrar via OIDC ou SAML para aquele domínio específico, não sendo possível manter ambos simultaneamente. Caso precise mudar de protocolo, entre em contato com o nosso suporte.
  • Obrigatoriedade de Verificação: Apenas registrar o domínio não ativa o roteamento de login. Para que os usuários sejam efetivamente redirecionados para o seu provedor de identidade, o domínio precisa estar validado (verificado) e um método de federação deve ser configurado (OIDC ou SAML). Sem essa verificação, seus colaboradores continuarão acessando a plataforma via login padrão com senha.

1. Criando um Domínio​

O primeiro passo é a criação do recurso de domínio, onde você declara o nome de domínio que deseja utilizar para a federação.

Execute o seguinte comando, garantindo que você está no Contexto da Organização correta:

mgc federation domains create --domain [DOMAIN_NAME]

Parâmetros:

  • [DOMAIN_NAME]: Nome do domínio a ser criado (ex: empresa.com.br).

Exemplo de retorno:

{
    "domain": "empresa.com.br",
    "id": "111111-2222-3333-4444-555555555555",
    "created_at": "2026-04-23T19:58:20.669Z",
    "updated_at": "2026-04-23T19:58:20.669Z",
    "txt_name": "mgc_abcd",
    "txt_value": "mgc_abcdefghijklm...",
    "verified": false,
    "verified_at": null
}
Atenção ao formato do domínio

O domínio cadastrado deve ser exatamente igual ao domínio presente nos e-mails corporativos dos seus usuários. Letras maiúsculas e minúsculas importam (use sempre minúsculas).

Exemplos práticos:

  • ✅ Se os e-mails são @empresa.com.br → cadastre empresa.com.br
  • ✅ Se os e-mails são @subdomain.empresa.com → cadastre subdomain.empresa.com
  • ❌ Não cadastre www.empresa.com.br se os e-mails são @empresa.com.br

Por quê? Durante o login, o sistema extrai a informação logo após o @ do e-mail do usuário e procura uma federação configurada para aquele domínio exato.

2. Listar Domínios​

Você pode listar os domínios já cadastrados pela sua organização para consultar o status de verificação ou recuperar os dados de DNS.

Execute o comando abaixo no terminal:

mgc federation domains list

3. Configurar o Registro DNS​

Antes de criar a federação (OIDC ou SAML), é obrigatório verificar o seu domínio. Esse processo garante que o domínio cadastrado realmente pertence à sua organização.

Para realizar a verificação, acesse a plataforma de gerenciamento de DNS do seu domínio (onde ele está hospedado) e crie um novo registro do tipo TXT inserindo os valores txt_name e txt_value obtidos no passo de criação (ou listagem).

Tempo de propagação

A propagação DNS pode levar de alguns minutos até 48 horas, dependendo do provedor utilizado e das configurações de TTL (Time to Live) do seu domínio.

4. Verificar o Domínio​

Com o registro DNS configurado e propagado, execute o comando de verificação para que a Magalu Cloud confirme a propriedade.

Execute o comando abaixo referenciando o ID do domínio:

mgc federation domains check-dns --domain-id [DOMAIN_ID]

Parâmetros:

  • [DOMAIN_ID]: ID do domínio gerado no passo de criação.
O que esse comando faz?

Este comando dispara a validação DNS:

  1. A plataforma consulta o registro TXT no DNS público do seu domínio.
  2. Compara o valor encontrado com o txt_value esperado.
  3. Se os valores baterem, o domínio é atualizado para verified: true.

Exemplo de retorno:

{
    "domain": "empresa.com.br",
    "id": "111111-2222-3333-4444-555555555555",
    "created_at": "2026-04-23T19:58:20.669Z",
    "updated_at": "2026-04-23T20:13:17.042Z",
    "txt_name": "mgc_abcd",
    "txt_value": "mgc_abcdefghijklm...",
    "verified": true,
    "verified_at": "2026-04-23T20:13:17.042Z"
}

✅ Verificação concluída! Note que a flag verified mudou para true e o campo verified_at foi preenchido.

Solução de Problemas (Troubleshooting)​

❌ Verificação falhou (DNS não encontrado)​

Sintoma: Após executar o comando check-dns, o domínio continua retornando verified: false.

Causas possíveis e soluções:

  1. O DNS ainda não propagou:
    • Solução: Aguarde mais tempo. Em casos extremos de cache, pode levar até 48 horas. Você pode testar manualmente usando ferramentas de terminal como dig ou nslookup.
  2. Registro DNS configurado incorretamente:
    • Solução: Revise os valores inseridos no seu provedor de DNS.
    • Erros comuns: Esquecer de copiar o valor completo do txt_value; adicionar aspas duplas desnecessárias; criar um registro tipo A/CNAME em vez de TXT; ou configurar na zona de DNS errada.
  3. Registro adicionado na raiz em vez do host correto:
    • Errado: Criar o TXT na raiz empresa.com.br contendo o valor mgc_abcd.
    • Certo: Criar o TXT no host/nome mgc_abcd (que resultará em mgc_abcd.empresa.com.br) contendo a string criptográfica fornecida no txt_value.

❌ Domínio já cadastrado por outra organização​

Sintoma: Erro de conflito ao tentar rodar o comando create.

Causa: Pela regra de exclusividade global, o domínio já existe no banco de dados.

Solução: Se você é o dono legítimo do domínio e não sabe quem o cadastrou, entre em contato com o suporte técnico. Se o domínio foi cadastrado por outra equipe da sua própria empresa, solicite acesso ao Contexto (Tenant/Organização) correto.

Próximos Passos: Agora que o seu domínio está verificado, ele está pronto para ser federado! Siga para o guia do protocolo de sua escolha: