Criando uma federação OIDC

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

Sendo um protocolo ágil baseado em estruturas JSON e construído sobre o OAuth 2.0, o OIDC centraliza o controle de acesso e elimina a necessidade de novas senhas, resolvendo desafios complexos de gestão de credenciais.

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 Provedor de Identidade (IdP).
• Seu IdP suporta o padrão OpenID Connect 1.0.
• Você tem permissão para criar aplicações/clients no IdP.
• O domínio não possui outra federação (Lembre-se da regra: 1 domínio = 1 federação).

1. Configurar a Aplicação no seu IdP

Para que seu IdP confie na Magalu Cloud e permita a autenticação federada, você precisa registrar a plataforma como uma aplicação (client) autorizada.

O que você vai fazer:

No painel administrativo do seu Provedor de Identidade, crie uma nova aplicação (ou client) do tipo "Web Application" ou "OpenID Connect".

Informações a serem configuradas:

Durante a criação da aplicação no IdP, você precisará fornecer:

URLs de Redirecionamento (Redirect URIs)

Configure exatamente estes valores (eles diferenciam maiúsculas de minúsculas):

• Origens Autorizadas (Allowed Origins): https://api.magalu.cloud/federation/
• URI de Callback (Redirect URI): https://api.magalu.cloud/federation/api/v1/authflow/oidc/callback

URLs Obrigatórias

IMPORTANTE: Esses valores devem ser configurados EXATAMENTE como mostrado.

❌ Erros comuns que causarão falhas de redirecionamento:

• Esquecer a barra / no final de /federation/.
• Usar http:// em vez de https://.
• Adicionar espaços extras no início ou no final.
• Usar variações do domínio (como api.magalucloud.com).

Informações Adicionais

Dependendo do seu IdP, você pode precisar configurar:

• Nome da Aplicação: Magalu Cloud Federation (ou um nome de sua escolha).
• Tipo de Aplicação: Web Application / Server-Side App.
• Tipo de Grant (Grant Type): Authorization Code Flow.
• Escopos (Scopes) Necessários:
  • openid (obrigatório)
  • email (obrigatório)
  • profile (recomendado — para extrair nome e foto do usuário)

Credenciais Geradas

Após criar a aplicação, o IdP irá gerar as chaves de acesso:

Credencial	Descrição	Exemplo
Client ID	Identificador público da aplicação.	abc123.apps.example.com
Client Secret	Senha secreta da aplicação. NUNCA a compartilhe publicamente!	GOCSPX-abc123...

Guarde as Credenciais com Segurança

• ✅ Copie e guarde ambos os valores em um local seguro.
• ✅ O Client Secret deve ser tratado como uma senha sensível. Não o salve em repositórios de código.
• ✅ Você precisará deles no próximo passo. Se perder o Client Secret, será necessário gerar um novo no painel do IdP.

Endpoints do IdP

Você também precisará obter as URLs dos endpoints OIDC do seu provedor. A maioria dos IdPs modernos expõe essas informações automaticamente via Discovery Document.

Método 1: Discovery Automático (Recomendado)

A maioria dos IdPs publica um documento de descoberta em: https://[seu-idp]/.well-known/openid-configuration

Como usar:

1. Acesse essa URL no seu navegador.
2. Você verá um arquivo JSON contendo todas as URLs necessárias.
3. Copie os valores correspondentes aos campos exigidos no próximo passo.

Exemplo de resposta do Discovery Document:

{
  "issuer": "[https://accounts.example.com](https://accounts.example.com)",
  "authorization_endpoint": "[https://accounts.example.com/o/oauth2/v2/auth](https://accounts.example.com/o/oauth2/v2/auth)",
  "token_endpoint": "[https://oauth2.example.com/token](https://oauth2.example.com/token)",
  "userinfo_endpoint": "[https://openidconnect.example.com/v1/userinfo](https://openidconnect.example.com/v1/userinfo)",
  "jwks_uri": "[https://www.example.com/oauth2/v3/certs](https://www.example.com/oauth2/v3/certs)"
}

Método 2: Consultar Documentação do IdP

Se o discovery document não estiver disponível, consulte a documentação oficial do seu IdP para localizar manualmente:

• Authorization Endpoint: Onde o usuário insere as credenciais.
• Token Endpoint: Onde a plataforma troca o código de autorização por um token.
• UserInfo Endpoint: Onde a plataforma busca os dados do perfil do usuário.
• JWKS URI: Onde estão hospedadas as chaves públicas para validação de assinaturas.

tip

Anote todos esses valores! Você precisará deles em instantes para executar o comando de criação da federação via CLI.

2. Criar a Federação OIDC

>_ CLI

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

mgc federation oidc --domain-id [DOMAIN_ID] \
  --name [FEDERATION_NAME] \
  --scopes [SCOPES] \
  --client-id [CLIENT_ID] \
  --client-secret [CLIENT_SECRET] \
  --authorization-endpoint [AUTHORIZATION_ENDPOINT] \
  --token-endpoint [TOKEN_ENDPOINT] \
  --jwks-uri [JWKS_URI] \
  --userinfo-endpoint [USERINFO_ENDPOINT]

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 (ex: "IdP Matriz").
• [SCOPES]: Escopos fornecidos pelo IdP. Separe-os por espaço (ex: "openid email profile").
• [CLIENT_ID]: ID do client gerado no Passo 1.
• [CLIENT_SECRET]: Segredo do client gerado no Passo 1.
• [AUTHORIZATION_ENDPOINT]: Endpoint de autorização do seu IdP.
• [TOKEN_ENDPOINT]: Endpoint de troca de token do seu IdP.
• [JWKS_URI]: Endpoint contendo as chaves públicas do seu IdP.
• [USERINFO_ENDPOINT]: Endpoint para consulta de perfil do usuário.

3. Listar Federações do Domínio

Você pode listar as configurações ativas para confirmar se a federação foi criada com sucesso.

>_ CLI

Execute o comando abaixo:

mgc federation list --domain-id [DOMAIN_ID]

4. Atualizar a Federação

Caso precise corrigir alguma URL, atualizar o Client Secret ou alterar o nome, você pode atualizar 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:

• --oidc.name
• --oidc.scopes
• --oidc.client-id
• --oidc.client-secret
• --oidc.authorization-endpoint
• --oidc.token-endpoint
• --oidc.userinfo-endpoint
• --oidc.jwks-uri

(Nota: Obtenha o [FEDERATION_ID] usando o comando de listagem do Passo 3).

5. Testar o Login Federado

Com a federação criada, é hora de validar se a integração está funcionando.

Como testar:

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

O que deve acontecer:

✅ Fluxo de sucesso:

1. O sistema detecta que o domínio do e-mail possui uma federação ativa.
2. Você é redirecionado para a tela de login do seu provedor corporativo (IdP).
3. Após autenticar-se no IdP, ele confirma sua identidade.
4. Você é redirecionado de volta para a Magalu Cloud e o acesso é concedido.

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 no Contexto/Organização, baseada nas informações do IdP.
• Não é necessário cadastro prévio manual.
• Nos acessos subsequentes, o usuário é reconhecido e logado instantaneamente.

---

Solução de Problemas (Troubleshooting)

❌ Erro 409: Conflict

• Sintoma: Ao executar a criação, recebe o erro HTTP 409.
• Causa: Já existe uma federação (seja OIDC ou SAML) vinculada a este domínio.
• Solução: Como ainda não há exclusão autônoma, entre em contato com o suporte técnico caso precise remover a federação anterior.

❌ Erro 404: Domain not found

• Sintoma: O comando falha informando que o domínio não existe.
• Causa: O ID informado está incorreto ou pertence a outro Contexto.
• Solução: Verifique se você está operando no Contexto correto e confira o ID exato rodando o comando mgc federation domains list.

❌ 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 na listagem de domínios.
  2. Federação não efetivada: Confirme se a federação aparece quando você executa mgc federation list.

❌ Erro no IdP: "Invalid redirect_uri" ou "Mismatch"

• Sintoma: O redirecionamento acontece, mas o IdP exibe uma tela de erro dizendo que a URI de retorno é inválida.
• Causa: A URL de callback configurada no IdP não é idêntica à que a plataforma está enviando.
• Solução: Acesse o painel do seu IdP e garanta que o campo de Redirect URI/Callback contenha exatamente o valor: https://api.magalu.cloud/federation/api/v1/authflow/oidc/callback.

❌ Erro: "No id_token received"

• Causa: O seu IdP concluiu o login, mas não enviou o Token de Identidade (ID Token) de volta.
• Solução: Confirme se os escopos no IdP e na CLI incluem openid (obrigatório). Verifique também se o tipo de aplicação no IdP está configurada como Web Application e o fluxo (Grant Type) como Authorization Code.

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

• Causa: O e-mail autenticado no IdP possui um domínio diferente do domínio cadastrado na federação.
• Exemplo: A federação foi criada para empresa.com, mas o usuário logou no IdP usando joao@outraempresa.com.
• Solução: Garanta que os colaboradores utilizem os e-mails exatos correspondentes ao domínio federado.