Integração do Redtrust com um IdP via SAML 2.0

Visão geral

Este tutorial mostra como integrar o Redtrust com um Provedor de Identidade (IdP) usando Security Assertion Markup Language (SAML) 2.0 para habilitar o login único (SSO). Ele é destinado a desenvolvedores e administradores de TI e presume que você tenha conhecimento básico sobre IdPs comuns, como o Microsoft Entra ID (anteriormente conhecido como Azure Active Directory) ou o Google Workspace.

Como funciona a integração SAML

O SAML 2.0 permite que um Provedor de Serviço (SP) — o Redtrust, neste caso — confie em um Provedor de Identidade (IdP) para autenticar seus usuários. Quando um usuário faz login, o IdP envia ao SP uma asserção assinada: um documento XML que atesta a identidade do usuário e carrega atributos como e-mail e nome.

Estabelecer essa confiança é uma troca em dois sentidos. Você copia alguns valores do seu IdP para o Redtrust e alguns valores do Redtrust para o seu IdP:

Provedor de identidade

IdP

Seu diretório: Entra ID, Google Workspace, Okta ou qualquer provedor SAML 2.0. Ele autentica seus usuários.

Você copia no Redtrust →

• URL de login
• Certificado de assinatura
• Nomes dos atributos

• Entity ID
• URL ACS (Reply)
• Certificado de assinatura (opcional)

← Você copia no IdP

Redtrust

Provedor de serviço · SP

Confia no IdP para autenticar os usuários. Ao fazer login, recebe uma asserção assinada que atesta a identidade do usuário.

Tenha esta imagem em mente ao trabalhar: a Etapa 1 registra o Redtrust no seu IdP e a Etapa 2 configura o Redtrust com os detalhes do seu IdP. A Etapa 3 é opcional e só se aplica se o seu IdP exigir solicitações de autenticação assinadas.

Cada IdP usa nomes ligeiramente diferentes para os mesmos valores. Use esta tabela para fazer a equivalência entre eles:

O que o Redtrust precisa	Microsoft Entra ID	Google Workspace	Termo SAML genérico
URL de login	Login URL	SSO URL	URL de SSO / login
Certificado de assinatura do IdP	Certificate (Base64)	Certificate	Certificado de assinatura X.509
Atributos do usuário	Attributes & Claims	Attribute mapping	Atributos / claims da asserção

Você pode, opcionalmente, configurar o Redtrust para assinar digitalmente as solicitações de autenticação SAML, o que alguns IdPs exigem. É possível ativar essa opção ao criar o domínio ou posteriormente, editando as configurações do domínio.

Antes de começar

Certifique-se de que você tem:

• Acesso de administrador ao Redtrust e permissão para criar domínios na seção Acesso.
• Acesso de administrador ao IdP que você está integrando, com permissão para criar aplicativos.
• Os atributos do usuário (e-mail, nome, sobrenome) disponíveis no diretório do seu IdP.

info

Se você já tem um domínio SAML e deseja apenas adicionar a configuração de solicitação assinada, vá até o item opcional da Etapa 2 e depois até a Etapa 3.

nota

Se o seu IdP exigir, você pode baixar os metadados SP do Redtrust a partir do console de administração. Vá até Acesso > Domínios e clique em Exportar metadatos SP nas opções ⋯ do seu domínio SAML.

Etapa 1: Registrar o Redtrust no seu IdP

Nesta etapa, você informa o seu IdP sobre o Redtrust registrando-o como um aplicativo, para que o IdP saiba para onde enviar os usuários autenticados. Faça login no console correspondente como administrador e siga as etapas para o seu IdP.

Microsoft Entra ID

1. No Microsoft Entra admin center, vá até Enterprise apps.

2. Selecione + New application > Create your own application.

3. No painel Create your own application, insira Redtrust como o nome do aplicativo. Certifique-se de que a opção Integrate any other application you don't find in the gallery (Non-gallery) está selecionada e clique em Create.

4. Na página Overview do aplicativo, vá até a seção Getting Started e selecione Set up single sign on > Get started, depois escolha SAML como método. Você chega à página Set up Single Sign-On with SAML, organizada como uma série de painéis numerados que você percorre de cima para baixo.

5. No painel Basic SAML Configuration, clique em Edit (o ícone de lápis no canto superior direito do painel) e insira estes dois valores:

   Identifier (Entity ID): como o IdP nomeia o Redtrust de forma única

   https://SEU_IP_REDTRUST/SEU_DOMÍNIO

   Reply URL (Assertion Consumer Service URL): para onde o IdP envia sua resposta

   https://SEU_IP_REDTRUST/Auth/SamlConsumer

   Onde:

   • SEU_IP_REDTRUST é o endereço IP ou nome de host do seu servidor Redtrust.
   • SEU_DOMÍNIO é o alias de domínio que você cria na Etapa 2.

   Clique em Save.

6. Mantenha esta aba do navegador aberta, você copiará vários valores dela na Etapa 2.

Para o procedimento completo, consulte o artigo da Microsoft Enable SAML single sign-on for an enterprise application.

Google Workspace

1. No Google Workspace Admin console, vá até Apps > Web and mobile apps.

2. Clique em Add app e selecione Add custom SAML app. Isso abre o assistente de configuração de aplicativo SAML personalizado, que o guia por quatro páginas: App details, Google Identity Provider details, Service provider details e Attribute mapping.

3. Na página App details, insira o nome Redtrust e clique em Continue.

4. Na página Google Identity Provider details, use a Option 2: copie a SSO URL, o Entity ID e o certificate. Você precisa desses valores na Etapa 2. Clique em Continue.

5. Na página Service provider details, insira estes dois valores e clique em Continue:

   ACS URL: para onde o Google envia sua resposta

   https://SEU_IP_REDTRUST/Auth/SamlConsumer

   Entity ID: como o Google nomeia o Redtrust de forma única

   https://SEU_IP_REDTRUST/SEU_DOMÍNIO

   Onde:

   • SEU_IP_REDTRUST é o endereço IP ou nome de host do seu servidor Redtrust.
   • SEU_DOMÍNIO é o alias de domínio que você cria na Etapa 2.

6. Na página Attribute mapping, clique em Add mapping para cada atributo que o Redtrust precisa. Para cada um, use o menu Select field para escolher o Google Directory attribute (por exemplo, Primary email, First name, Last name) e depois insira o nome do App attribute correspondente. Anote os nomes de app attribute que você insere, pois precisará deles na Etapa 2. Em seguida, conclua o assistente.

Para o procedimento completo, consulte o artigo do Google Set up your own custom SAML application.

Outros IdPs

O Redtrust funciona com qualquer IdP compatível com SAML 2.0. As etapas exatas dependem do seu IdP, portanto consulte a documentação dele. De modo geral:

1. No seu IdP, crie um novo aplicativo SAML 2.0.

2. Registre os seguintes valores do Redtrust como provedor de serviço (SP):

   Entity ID: como o IdP nomeia o Redtrust de forma única

   https://SEU_IP_REDTRUST/SEU_DOMÍNIO

   ACS URL (Reply URL): para onde o IdP envia sua resposta

   https://SEU_IP_REDTRUST/Auth/SamlConsumer

   Onde:

   • SEU_IP_REDTRUST é o endereço IP ou nome de host do seu servidor Redtrust.
   • SEU_DOMÍNIO é o alias de domínio que você cria na Etapa 2.

3. Configure o IdP para incluir na asserção os atributos de e-mail, nome e sobrenome, além de um NameID (o identificador único que o IdP usa para o usuário).

4. Obtenha do seu IdP a URL de login, o certificado de assinatura e os nomes dos atributos. Você precisa deles na Etapa 2.

Para alguns IdPs comuns, consulte a documentação de configuração SAML:

• AD FS — Criar uma relação de confiança (relying party trust).
• Okta — Criar uma integração de aplicativo SAML.
• PingOne for Enterprise — Adicionar um aplicativo SAML.
• JumpCloud — Criar um conector de aplicativo SAML personalizado.

Etapa 2: Criar o domínio no Redtrust

Agora configure o Redtrust com os valores do seu IdP.

1. No Redtrust, vá até Acesso > Domínios e clique em Novo.
2. Na caixa de diálogo:
   1. Adicione o alias que deseja atribuir ao domínio. O domínio pode corresponder ao domínio do e-mail dos usuários, ou seja, a parte depois do @.
   2. Selecione SAML 2 como o tipo de domínio e clique em Avançar para ver todas as opções de configuração.

A tabela abaixo mapeia cada campo do Redtrust para o local onde você encontra o valor correspondente no seu IdP.

Microsoft Entra ID

3. Usando a aba do Entra ID que você deixou aberta na Etapa 1, preencha cada campo do Redtrust:

   Campo do Redtrust	Onde encontrá-lo no Entra ID
   URL de login (HTTP-redirect)	Painel Set up Redtrust > Login URL.
   Certificado X509 do IdP (para assinatura)	Painel SAML Certificates > Certificate (Base64). Baixe o arquivo, abra-o em um editor de texto e copie o conteúdo.
   E-mail	Painel Attributes & Claims > a claim emailaddress.
   Nome	Painel Attributes & Claims > a claim givenname (o usuário do Entra ID deve ter um nome configurado).
   Sobrenome	Painel Attributes & Claims > a claim surname (o usuário do Entra ID deve ter um sobrenome configurado).

4. Preencha o restante dos campos:

   • Domínio: o domínio do Entra ID no qual você deseja habilitar o SSO.
   • Diferencia maiúsculas de minúsculas?: Não
   • ACS por índice: Não

5. (Opcional) Selecione Solicitação assinada se quiser assinar as solicitações de autenticação SAML. Em Origem do certificado, escolha Gerar certificado autoassinado ou Carregar certificado PFX/P12. Essa é a parte pública do certificado de assinatura, e você precisa dela na Etapa 3. Se gerar um certificado autoassinado, você o baixa na próxima etapa.

Google Workspace

3. Usando os valores que você copiou do Google na Etapa 1, preencha cada campo do Redtrust:

   Campo do Redtrust	Onde encontrá-lo no Google Workspace
   URL de login (HTTP-redirect)	A SSO URL que você copiou na Etapa 1.
   Certificado X509 do IdP (para assinatura)	O certificate que você copiou na Etapa 1.
   E-mail	O nome do App attribute que você mapeou para o e-mail na página Attribute mapping.
   Nome	O nome do App attribute que você mapeou para o nome.
   Sobrenome	O nome do App attribute que você mapeou para o sobrenome.

4. Preencha o restante dos campos:

   • Domínio: o domínio no qual você deseja habilitar o SSO.
   • Diferencia maiúsculas de minúsculas?: Não
   • ACS por índice: Não

Outros IdPs

3. Preencha a configuração no Redtrust com os dados do seu IdP: a URL de login, o Certificado X509 do IdP (para assinatura) e os nomes dos atributos de E-mail, Nome e Sobrenome.

4. Preencha o restante dos campos:

   • Domínio: o domínio no qual você deseja habilitar o SSO.
   • Diferencia maiúsculas de minúsculas?: Não
   • ACS por índice: Não

Para ver a descrição de cada campo, consulte a documentação de domínios.

Etapa 3 (Opcional): Adicionar a configuração de solicitação assinada

Conclua esta etapa apenas se o seu IdP exigir solicitações de autenticação assinadas e você tiver selecionado Solicitação assinada na Etapa 2.

Microsoft Entra ID

1. Se você gerou um certificado autoassinado na Etapa 2, vá até Acesso > Domínios, selecione o domínio que você acabou de criar e baixe o certificado.

2. De volta ao aplicativo no Entra ID, abra o painel Verification certificates (optional) e clique em Edit (o ícone de lápis).

   1. Selecione Require verification certificates.

   2. Clique em Upload certificate, selecione seu certificado e depois clique em Ok e Save.

Google Workspace

info

O Google Workspace não oferece suporte à validação de solicitações de autenticação SAML assinadas, portanto não é possível ativar essa opção ao integrar com o Google como IdP.

Outros IdPs

Se o seu IdP exigir solicitações assinadas, vá até Acesso > Domínios, selecione o domínio, baixe o certificado e faça upload dele nas configurações de verificação de assinatura do seu IdP. Consulte a documentação do seu IdP para conhecer as etapas exatas.

Verificar a integração

Depois de configurar os dois lados, confirme que o SSO funciona de ponta a ponta. Use uma conta de teste que pertença ao domínio SAML configurado:

1. Em uma janela de navegação privada, abra a página de login do Redtrust e insira o endereço de e-mail de um usuário do domínio SAML.
2. O Redtrust reconhece o domínio e redireciona você para o seu IdP. Faça login nele.
3. O IdP redireciona você de volta ao Redtrust, e você chega autenticado.

Se você não for redirecionado ou a autenticação falhar, consulte Solução de problemas.

Solução de problemas

A maioria dos problemas de SAML vem de um valor que não corresponde nos dois lados. Verifique estes primeiro:

Sintoma	Causa provável	O que verificar
O IdP rejeita a solicitação ou informa uma audiência inválida	O Entity ID no IdP não corresponde ao Redtrust	Confirme que o Identifier (Entity ID) do IdP é exatamente https://SEU_IP_REDTRUST/SEU_DOMÍNIO, sem barra no final
O login entra em loop ou o IdP não retorna o usuário	A URL ACS (Reply) está incorreta	Confirme que a Reply URL é exatamente https://SEU_IP_REDTRUST/Auth/SamlConsumer
A validação de assinatura falha	O certificado de assinatura do IdP no Redtrust está incorreto ou expirado	Copie novamente o Certificate (Base64) atual do IdP para o Redtrust
O usuário faz login, mas o Redtrust mostra nome ou e-mail ausente	Os nomes dos atributos não correspondem à asserção do IdP	Alinhe os nomes dos atributos E-mail, Nome e Sobrenome com os que o IdP envia
Um erro de horário ou "response too old"	Diferença de relógio entre os servidores	Certifique-se de que os relógios do servidor do IdP e do Redtrust estão sincronizados (NTP)
Erros de solicitação assinada após ativar Solicitação assinada	O IdP não está verificando o certificado de assinatura do Redtrust	Conclua a Etapa 3 ou desmarque Solicitação assinada se o seu IdP não a exigir

Resumo

Neste tutorial, você configurou o Redtrust como um Provedor de Serviço (SP) e o integrou com um Provedor de Identidade (IdP) usando SAML 2.0 para habilitar o SSO. Você registrou o Redtrust no IdP, configurou o Redtrust para confiar no IdP e verificou o fluxo de login. Seus usuários agora podem se autenticar com as credenciais existentes, melhorando tanto a segurança quanto a experiência do usuário.

Próximas etapas

• Para uma descrição de cada campo do domínio SAML, consulte a documentação de domínios.
• Para exigir solicitações SAML assinadas no Entra ID, consulte o guia da Microsoft sobre configurar a verificação de assinatura de solicitações SAML.