Criando uma Federação SAML

A federação de identidade via protocolo SAML (Security Assertion Markup Language) na Magalu Cloud permite que sua organização delegue a autenticação dos usuários para o Provedor de Identidade (IdP) corporativo, promovendo uma experiência segura de Single Sign-On (SSO).

Sendo um protocolo maduro e consolidado desde 2005, o SAML é amplamente utilizado em ambientes corporativos e governamentais que exigem máxima segurança e auditabilidade, especialmente em sistemas legados e infraestruturas enterprise.

Pré-requisitos

Antes de começar, certifique-se de que:

• Você possui um domínio verificado na Magalu Cloud.
  • Se não, veja: Gerenciamento de Domínios
• Você tem acesso administrativo ao seu IdP SAML.
• Seu IdP suporta o padrão SAML 2.0.
• Você possui permissões para configurar Service Providers (Aplicações) no IdP.
• O domínio não possui outra federação (Lembre-se da regra: 1 domínio = 1 federação).

1. Configurar o Service Provider no seu IdP

Para que seu IdP SAML confie na Magalu Cloud e permita a autenticação federada, você precisa registrar a plataforma como um Service Provider (SP) autorizado.

Informações do Service Provider (Magalu Cloud)

Você precisará configurar estes valores de recebimento no painel do seu IdP:

Metadados SAML da Magalu Cloud

Campo	Valor	Descrição
Client Type	SAML	Protocolo utilizado para a federação.
Entity ID / Client ID	Ex: magalu-cloud-saml	Identificador único da sua aplicação no IdP. Escolha um nome claro.
Root URL / Base URL	https://api.magalu.cloud/federation/	URL base da aplicação.
ACS URL (Assertion Consumer Service)	https://api.magalu.cloud/federation/api/v1/authflow/saml/callback	A URL exata para onde o IdP enviará o XML de resposta (Callback).

Atenção às URLs

As URLs (especialmente a ACS URL) devem ser configuradas exatamente como fornecido. Qualquer erro de digitação, falta de barra (/) no final ou uso de HTTP em vez de HTTPS fará com que o processo falhe silenciosamente.

2. Obter Informações do IdP

Após configurar o Service Provider, seu IdP fornecerá os dados necessários para que a Magalu Cloud consiga validar a origem das requisições. Reúna as seguintes informações:

• Entity ID (IdP): O identificador único do provedor.
• SSO URL: A URL de redirecionamento (Single Sign-On Service) para onde a Magalu Cloud enviará o usuário no momento do login.
• Certificado X.509: O certificado público em formato Base64 usado para validar as assinaturas digitais do arquivo XML SAML gerado pelo IdP.

3. Criar a Federação SAML via CLI

Com o domínio verificado e as informações do IdP em mãos, execute o comando na CLI para registrar a federação no banco de dados.

>_ CLI

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

mgc federation saml --domain-id [DOMAIN_ID] \
  --name [FEDERATION_NAME] \
  --entity-id [ENTITY_ID] \
  --sso-url [SSO_URL] \
  --idp-certificate [IDP_CERTIFICATE]

Parâmetros:

• [DOMAIN_ID]: ID do domínio verificado (Obtenha via mgc federation domains list).
• [FEDERATION_NAME]: Nome amigável para a sua federação.
• [ENTITY_ID]: Identificador único do seu Identity Provider (IdP Entity ID) ou o ID do seu Client.
• [SSO_URL]: URL de redirecionamento para a tela de login do IdP.
• [IDP_CERTIFICATE]: O texto completo do certificado público usado para validar a assinatura.

Formato do Certificado

Ao enviar o [IDP_CERTIFICATE] via CLI, cole apenas a string Base64 em uma única linha, sem quebras, e remova as tags -----BEGIN CERTIFICATE----- e -----END CERTIFICATE-----.

4. Listar Federações do Domínio

Após criar a federação, você pode listar as configurações ativas para confirmar o cadastro.

>_ CLI

Execute o comando abaixo:

mgc federation list --domain-id [DOMAIN_ID]

5. Atualizar a Federação

Caso precise corrigir alguma URL ou atualizar o certificado (se ele expirar), você pode alterar a federação existente.

>_ CLI

Execute o comando referenciando o ID da federação:

mgc federation update --domain-id [DOMAIN_ID] --federation-id [FEDERATION_ID]

Parâmetros de atualização disponíveis:

• --saml.name
• --saml.entity-id
• --saml.sso-url
• --saml.idp-certificate

note

Obtenha o [FEDERATION_ID] usando o comando de listagem do Passo 4.

6. Testar o Login Federado

Com a federação criada, é hora de validar se o fluxo corporativo está funcional.

Como testar:

1. Abra uma janela anônima (ou aba privada) no navegador.
2. Acesse o Console da Magalu Cloud: https://console.magalu.cloud
3. Na tela de login, digite um e-mail do domínio federado (Ex: joao@empresa.com.br).
4. Clique em Continuar ou Login.

O que deve acontecer:

✅ Fluxo de sucesso:

1. O sistema detecta que a terminação @empresa.com.br é federada via SAML.
2. Você é redirecionado para a tela de login do seu IdP.
3. Após fazer login com as credenciais corporativas, o IdP envia um XML assinado de volta.
4. Você é redirecionado para a Magalu Cloud e o acesso é concedido instantaneamente.

Sobre o Primeiro Login do Usuário

O sistema utiliza um modelo de provisionamento Just-In-Time (JIT). No primeiro login federado de um colaborador:

• A Magalu Cloud cria automaticamente a conta dele, baseada nas informações do XML fornecido pelo IdP.
• Não é necessário cadastro prévio manual.
• Nos próximos logins, o usuário é reconhecido automaticamente.

---

Solução de Problemas (Troubleshooting)

❌ Erro 409: Conflict

• Sintoma: Ao tentar criar federação, recebe erro HTTP 409 Conflict.
• Causa: Já existe uma federação (OIDC ou SAML) para esse domínio.
• Solução: Como não há exclusão autônoma de federação, entre em contato com o suporte técnico para solicitar a remoção da federação anterior.

❌ Erro 404: Domain not found

• Sintoma: O comando falha informando que o domínio não foi encontrado.
• Causa: O ID do domínio informado está inválido ou pertence a outra organização.
• Solução: Confirme que está no contexto (tenant) correto. Liste os domínios via mgc federation domains list e use o ID exato exibido.

❌ Login não redireciona para o IdP

• Causas e Soluções:
  1. Domínio não verificado: Verifique se o domínio consta como verified: true executando mgc federation domains list.
  2. Federação não criada: Confirme se a federação foi gerada com sucesso executando mgc federation list.
  3. Callback URL Incorreto: Revise se a ACS URL no seu IdP está EXATAMENTE configurada para: https://api.magalu.cloud/federation/api/v1/authflow/saml/callback

❌ Erro: "Invalid SAML Response"

• Causas e Soluções:
  1. Certificado incorreto na CLI: Certifique-se de que copiou o certificado completo na criação da federação, garantindo que removeu os cabeçalhos (-----BEGIN CERTIFICATE-----) e que a string é apenas o conteúdo Base64.
  2. Assinatura SAML inválida ou divergente: O IdP pode estar usando um certificado diferente para assinar a mensagem do que aquele que você cadastrou no banco. Verifique se o certificado expirou.
  3. Resposta malformada: Verifique nos logs do IdP se o XML de resposta enviado é um SAML 2.0 válido.

❌ Erro: "No email in SAML Response"

• Causa: O seu IdP concluiu a autenticação, mas não enviou o atributo email no corpo da resposta SAML.
• Solução: Verifique o mapeamento de atributos (Attribute Mappers) no painel do seu IdP e garanta que ele esteja enviando ativamente a propriedade de e-mail junto com o pacote SAML.

❌ Erro: "Flow domain doesn't match email domain"

• Causa: O e-mail retornado pelo IdP não corresponde ao domínio da federação criada.
• Exemplo: A federação foi configurada para empresa.com.br, mas o IdP validou e retornou o usuário joao@outraempresa.com.
• Solução: Garanta que os usuários se autentiquem com os e-mails corretos do domínio. Verifique o atributo email retornado pelo IdP.

❌ Erro: "Audience mismatch"

• Causa: O Entity ID configurado no IdP difere do Entity ID fornecido na criação da federação.
• Solução: Confirme que o Entity ID (que atua como o identificador do público da mensagem) está idêntico em ambas as pontas. Lembrando que o campo é case-sensitive (diferencia maiúsculas e minúsculas).