CLOUD SINGLE SIGN-ON
Integração SAML 2.0
Manual de configuração e integração
Como cadastrar uma aplicação SAML 2.0 no CSSO e preparar a aplicação para autenticar os usuários pelo CSSO.
VERSÃO DO DOCUMENTO 2.0
DATA Setembro de 2026
PÚBLICO Administradores do CSSO e desenvolvedores de aplicações
1. Antes de começar #
1.1 O que este manual cobre #
Este manual mostra, em 4 passos, como integrar uma aplicação ao Cloud Single Sign-On (CSSO) usando SAML 2.0:
1. Cadastrar a aplicação no CSSO.
2. Configurar o SAML da aplicação no CSSO.
3. Configurar a aplicação com os dados do CSSO.
4. Testar o login.
Nos exemplos, https://.sso.e-trust.com.br é o endereço do seu ambiente CSSO e é o identificador que o CSSO gera para a aplicação.
1.2 Como funciona #
• O CSSO autentica o usuário. No SAML, ele é o Identity Provider (IdP).
• A aplicação confia no CSSO. Ela é o Service Provider (SP) e nunca recebe a senha do usuário: recebe do CSSO uma resposta assinada dizendo quem é o usuário.
• O login começa pela aplicação: ela envia o usuário ao CSSO com um pedido (AuthnRequest). O CSSO autentica o usuário e devolve a resposta (SAMLResponse) para um endereço da aplicação, o ACS (Assertion Consumer Service). • Se o usuário já tem sessão no CSSO, ele entra sem digitar a senha (Single Sign-On).

Figura 1 — Fluxo de login SAML iniciado pela aplicação
1.3 Informações necessárias para a integração #
| Informação | Onde é usada |
|---|---|
| EntityID da aplicação (identificador) | campo EntityID no CSSO |
| URL do ACS da aplicação | campo Assertion Consumer Service Endpoint no CSSO |
| URL de logout da aplicação (opcional) | campo Single Logout Service Endpoint no CSSO |
| Certificado público da aplicação | campo SP X.509 Cert (mesmo utilizado para criptografia feita pelo SP e verificação de assinatura feita pelo IdP) no CSSO |
| Identificador do usuário e atributos esperados (ex.: e-mail, nome, grupos) | NameID e atributos no CSSO |
| Metadata URL do CSSO | configuração da aplicação |
Nota: o caminho mais rápido é trocar metadata. O administrador importa o XML de metadados da aplicação e exporta (ou fornece) a URL de metadados do CSSO.
2. Passo 1 — Cadastrar a aplicação no CSSO #
1. No portal de administração do CSSO, crie uma nova aplicação.
2. Preencha o Nome da Aplicação.
3. Preencha a URL da Página Inicial da Aplicação. É o endereço quando o usuário clica na aplicação no portal do CSSO.
4. Em Protocolo de Autenticação, selecione SAML.
5. Para restringir o acesso, escolha os Grupos de Permissão.
6. Clique em Salvar.
7. Abra a aplicação novamente: as opções SAML aparecem agora.

Figura 2 — Cadastro da aplicação com o protocolo SAML
No topo da configuração SAML ficam os endereços que o CSSO gerou para esta aplicação, somente para leitura:
| Na tela | Para que serve |
|---|---|
| Metadata URL, com os botões para download do Metadata e Certificado | configurar a aplicação |
| SSO REDIRECT URL e SSO POST URL | para onde a aplicação envia o pedido de login |
| SLO URL | para onde a aplicação envia o usuário ao sair |
3. Passo 2 — Configurar o SAML da aplicação no CSSO #
3.1 Com a metadata da aplicação (recomendado) #
Em Importar Metadata SAML, selecione o arquivo XML da aplicação. O CSSO preenche o EntityID, os endereços, o NameID Format e o certificado. Depois confira os pontos:
☐ Audience, Recipient e Destination: caso não preenchido automaticamente. Preencha conforme a seção 3.2.
☐ Assertion Consumer Service Endpoint com binding HTTP-POST e Single Logout Service Endpoint com binding HTTP-REDIRECT. Se a metadata tiver vários endereços, o CSSO usa o primeiro.
☐ Certificado do Provedor de Serviço com um único certificado. Se vierem dois, deixe só o que a aplicação usa.
☐ Assinatura, algoritmos e NameID conforme a seção 3.2. Depois de conferir, clique em Salvar.
3.2 Campos a preencher #
| Campo na tela | O que informar | Exemplo |
|---|---|---|
| EntityID | identificador da aplicação, igual ao que ela envia no pedido | acme |
| Assertion Consumer Service Endpoint | URL da aplicação que recebe a resposta | https://app.acme.com.br/saml/acs |
| Method Binding (do ACS) | HTTP-POST ou HTTP-REDIRECT. Recomendado: HTTP-POST | HTTP-POST |
| Audience | o mesmo valor do EntityID | https://app.acme.com.br/saml/metadata |
| Recipient | a URL do ACS | https://app.acme.com.br/saml/acs |
| Destination | a URL do ACS | https://app.acme.com.br/saml/acs |
| NameID Format | o formato que a aplicação espera (seção 3.3) | emailAddress |
| Necessita que a SAML Response seja assinada | Sim ou Não, conforme a aplicação exigir. | Sim |
| Necessita que a Assertion seja assinada | Sim ou Não, conforme a aplicação exigir. | Não |
| Signature Algorithm | rsa-sha256 ou rsa-sha1, conforme a aplicação exigir. | rsa-sha1 |
| Digest Algorithm | sha256 ou sha1, no mesmo padrão do Signature Algorithm. | sha1 |
| Single Logout Service Endpoint (opcional) | URL de logout da aplicação | https://app.acme.com.br/saml/logout |
| Method Binding (do Single Logout) | HTTP-POST ou HTTP-REDIRECT. | HTTP-REDIRECT |
| SP X.509 Cert – Mesmo utilizado para criptografia feita pelo SP e verificação de assinatura feita pelo IdP | Certificado público da aplicação | Conteúdo PEM (—–BEGIN CERTIFICATE—– …) |
Importante: os valores precisam ser exatamente iguais aos da aplicação. Barra no final, http × https e letras maiúsculas fazem diferença.

Figura 4 — Dados da aplicação: EntityID, ACS, Audience, Recipient e Destination

Figura 5 — Opções de assinatura e algoritmos
3.3 Identificador do usuário (NameID) #
O NameID é o valor que identifica o usuário para a aplicação. O NameID Format só declara o tipo do valor; o valor em si depende de onde o usuário faz login:
| O usuário entra por | Onde escolher o valor enviado |
|---|---|
| Base interna do CSSO | Selecione o identificador de usuários da base de dados interna: Nome de usuário ou E-mail |
| Conexão LDAP / Active Directory | Configure o atributo do identificador imutável para cada conexão: atributo do diretório, como mail ou userPrincipalName |
| Access Manager | Selecione o identificador de usuários do Access Manager |
Combine formato e valor: emailAddress com o e-mail, ou unspecified com o nome de usuário.

Figura 6 — Opções de NameID
3.4 Atributos (opcional) #
Se a aplicação precisa de outros dados do usuário (e-mail, nome, grupos), cadastre cada um em Atributos do usuário: informe o Nome do atributo exatamente como a aplicação espera, escolha o valor (E-mail, Nome, Username, Grupos, atributo de uma Conexão ou do Access Manager) e clique em Inserir.
Para enviar grupos, prefira Atributo multivalorado em Método de inclusão de grupos na resposta SAML. É o formato que a maioria das bibliotecas espera.
4. Passo 3 — Configurar a aplicação #
4.1 Dados do CSSO #
A maioria das bibliotecas SAML aceita a Metadata URL e se configura sozinha. Se a sua pedir os dados um a um:
| Parâmetro da biblioteca | Valor |
|---|---|
| IdP Entity ID / Issuer | Metadata URL: https://{organizacao}.sso.e-trust.com.br/idp/saml/metadata/{clientId} |
| IdP SSO URL | SSO REDIRECT URL (ou a SSO POST URL) |
| IdP SLO URL | SLO URL |
| Certificado do IdP | o certificado do CSSO (botão Certificado) |
| SP Entity ID | o EntityID cadastrado no CSSO |
| SP ACS URL | o Assertion Consumer Service Endpoint cadastrado no CSSO |
| NameID Format | o mesmo configurado no CSSO |
4.2 Regras para a aplicação #
• Use HTTPS e uma biblioteca SAML pronta (Spring Security SAML2, python3-saml, node-saml/passport-saml, Sustainsys ou ITfoxtec, SimpleSAMLphp). Não é recomendado utilizar validação da assinatura manualmente.
• O login começa pela aplicação. O CSSO não envia resposta sem pedido.
• A URL da Página Inicial da Aplicação deve ter um botão ou link para o login, porque é ela que abre quando o usuário clica na aplicação no portal do CSSO.
• O Issuer do pedido deve ser igual ao EntityID cadastrado e, se o pedido informar o ACS, igual ao ACS cadastrado.
• O pedido vale por 5 minutos: mantenha o relógio do servidor sincronizado (NTP).
• Assinar o pedido é opcional.
5. Passo 4 — Testar o login #
1. Abra a aplicação com um usuário que não tem sessão no CSSO.
2. A aplicação leva você à tela de login do CSSO.
3. Entre com usuário e senha (e MFA, se o ambiente exigir).
4. O CSSO devolve você à aplicação, já autenticado.
Se isso funcionou, a integração está pronta. Confira também:
☐ Clicar na aplicação no portal do CSSO abre a aplicação já autenticada.
☐ Com sessão ativa no CSSO, a aplicação entra sem pedir senha.
☐ O identificador (NameID) e os atributos chegam com os valores esperados, para cada origem de usuário usada (base interna, LDAP/AD, Access Manager).
☐ Um usuário fora dos Grupos de Permissão não acessa, se houver restrição.
Nota: para ver as mensagens SAML durante o teste, use a extensão SAML-tracer (Firefox e Chrome).
6. Logout #
6.1 O usuário sai pelo portal do CSSO #
O CSSO encerra a sessão e avisa a aplicação no Single Logout Service Endpoint com um LogoutRequest, que identifica o usuário pelo NameID e pelo SessionIndex. A aplicação deve encerrar a sessão local desse usuário. Sem esse endereço cadastrado, a aplicação não é avisada e a sessão dela dura até expirar.
6.2 O usuário sai pela aplicação #
A aplicação encerra a sessão local e redireciona o navegador para a SLO URL do CSSO. O CSSO encerra a sessão daquela aplicação e leva o usuário para a URL de redirecionamento após o logout, se configurada, ou para o portal do CSSO.
7. Problemas comuns #
| Sintoma | O que fazer |
|---|---|
| A resposta volta com status Requester | o EntityID, o ACS ou o Destination do pedido não bate com o cadastro, ou o pedido tem mais de 5 minutos. Compare os valores exatamente e sincronize o relógio. |
| A resposta volta com status RequestDenied | a assinatura do pedido não confere. Cadastre no CSSO o certificado certo, só um. |
| A resposta volta com status Responder | pedido assinado ou Assertion criptografada sem o certificado da aplicação cadastrado. Cadastre o certificado. |
| A aplicação diz que a assinatura é inválida | atualize o certificado do CSSO na aplicação (ou use a Metadata URL) e confira o algoritmo e as opções de assinatura (seção 3.2). |
| A aplicação recusa Audience, Recipient ou Destination | preencha os três campos (seção 3.2). |
| A aplicação diz que a resposta expirou ou ainda não vale | sincronize o relógio do servidor (NTP). |
| A aplicação acusa InResponseTo inválido | o cookie de sessão da aplicação não volta no POST do CSSO. Use SameSite=None; Secure nesse cookie. |
| O usuário chega com o identificador errado | revise a origem do NameID (seção 3.3). |
| Atributos ou grupos não chegam | confira o nome do atributo e o método de grupos (seção 3.4). |
| O clique no portal do CSSO não faz login | a URL da Página Inicial da Aplicação deve iniciar o login SAML. |
| O logout pelo CSSO não encerra a sessão na aplicação | cadastre o Single Logout Service Endpoint e o binding, e veja a nota sobre SigAlg (seção 6.2). |
8. Referência rápida #
8.1 Endereços do CSSO #
| Nome na tela | Endereço |
|---|---|
| Metadata URL (também é o EntityID do CSSO) | /idp/saml/metadata/{clientId} |
| Certificado | /idp/saml/metadata/{clientId}/certificate |
| SSO REDIRECT URL | /idp/saml/redirect/sso/{clientId} |
| SSO POST URL | /idp/saml/post/sso/{clientId} |
| SLO URL | /idp/saml/redirect/slo/{clientId} |
Todos começam com https://.sso.e-trust.com.br.
8.2 Outras opções da tela #
| Opção | Quando usar |
|---|---|
| Necessita que a Assertion seja criptografada | só se a aplicação exigir; requer o certificado da aplicação |
| Authentication Context Class Reference | se a aplicação exigir um valor, como PasswordProtectedTransport; padrão unspecified |
| Tempo de sessão da asserção SAML | por quanto tempo a aplicação pode manter a sessão sem voltar ao CSSO; o padrão acompanha a sessão do CSSO |
| Converter o valor do atributo em ImmutableID | só em integrações com Microsoft 365 / Entra ID, a partir do objectGUID do Active Directory |
| URL de redirecionamento após o logout | para onde o usuário vai quando sai pela aplicação |
| Ocultar aplicação na dashboard do usuário | esconder o ícone da aplicação no portal do usuário. |
8.3 Formatos de NameID mais usados #
| Na tela | URI |
|---|---|
| emailAddress | urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress |
| unspecified | urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified |
| persistent | urn:oasis:names:tc:SAML:2.0:nameid-format:persistent |
8.4 Glossário #
| Termo | Significado |
|---|---|
| IdP (Identity Provider) | quem autentica o usuário: o CSSO |
| SP (Service Provider) | a aplicação integrada |
| EntityID | identificador único do CSSO ou da aplicação |
| AuthnRequest | pedido de login enviado pela aplicação |
| SAMLResponse | resposta do CSSO com os dados do usuário |
| Assertion | parte assinada da resposta que diz quem é o usuário |
| NameID | identificador do usuário na Assertion |
| ACS (Assertion Consumer Service) | endereço da aplicação que recebe a resposta |
| SLO (Single Logout) | logout único |
| Metadata | XML com a configuração do CSSO ou da aplicação |
