SAML vs OIDC: Como escolher e o que realmente importa

O que é o SAML 2.0 na prática

SAML é o Security Assertion Markup Language. A versão 2.0 foi ratificada pela OASIS em 2005 e tem sido a espinha dorsal do SSO web corporativo desde então.

A mecânica é simples quando se remove a complexidade do XML. Um usuário acessa sua aplicação — o provedor de serviço (SP) — que não sabe quem ele é, e por isso redireciona o navegador para o provedor de identidade (IdP). O IdP autentica o usuário e gera uma asserção: um documento XML assinado declarando quem é o usuário, quais atributos ele possui e por quanto tempo ela é válida. O navegador envia essa asserção via POST para a URL do Assertion Consumer Service (ACS) do SP, e o SP verifica a assinatura usando o certificado X.509 do IdP.

Três propriedades decorrem disso, e elas explicam a maioria dos prós e contras:

• O navegador é o meio de transporte. Não é necessária uma chamada via back-channel entre o SP e o IdP, portanto o SAML funciona onde os dois servidores não conseguem se comunicar diretamente.
• A confiança é um certificado fixado. Quando ele expira, o SSO deixa de funcionar para todos simultaneamente.
• Trata-se de um protocolo para navegadores. O SAML não possui um conceito nativo de token de acesso para APIs.

O que é o OIDC na prática

O OpenID Connect é uma camada de identidade sobre o OAuth 2.0, publicada pela OpenID Foundation em 2014. O OAuth 2.0 resolveu a autorização delegada e deliberadamente omitiu a identidade do usuário. O OIDC adiciona essa camada.

O fluxo é o authorization code flow do OAuth com um escopo adicional, openid. A aplicação redireciona para o endpoint de autorização do IdP, o usuário se autentica e o IdP redireciona de volta com um código de autorização de curta duração. Em seguida, a aplicação chama o endpoint de token por uma conexão back-channel e troca esse código por um token de acesso, opcionalmente um token de atualização (refresh token) e um ID token.

O ID token é o elemento central do OIDC: um JSON Web Token assinado com JWS, tipicamente RS256, contendo sub, iss, aud, exp e geralmente email. Ele é validado usando uma chave do endpoint JWKS do IdP.

Duas propriedades são fundamentais:

• A descoberta é automática. Todo IdP compatível publica <issuer>/.well-known/openid-configuration listando todos os endpoints, permitindo que a aplicação leia as configurações automaticamente em vez de exigir a colagem manual de URLs.
• As chaves são rotacionadas automaticamente. O endpoint JWKS fornece as chaves públicas atuais, permitindo que o IdP as rotacione e sua aplicação acompanhe a mudança sem intervenção manual para controlar datas de expiração.

SAML vs OIDC: a comparação que realmente importa

Afinal, qual opção você deve escolher?

A resposta direta, que as páginas de comparação de fornecedores costumam omitir:

Para autenticar usuários em uma aplicação web corporativa no navegador, qualquer um dos dois funciona, e a diferença de segurança é insignificante. Ambos são maduros e utilizam assinaturas digitais. Nenhuma empresa sofreu um incidente de segurança unicamente por ter optado por SAML em vez de OIDC.

Geralmente, a decisão já está tomada. Se a sua equipe de IdP possui quarenta aplicações em SAML e um procedimento operacional padrão definido, adicionar a quadragésima primeira leva vinte minutos, enquanto a primeira aplicação em OIDC exigirá reuniões de alinhamento. Siga o padrão estabelecido.

A diferença de engenharia só se manifesta em cenários específicos — mas esses cenários são relevantes:

• A rotação de certificados é o maior custo operacional do SAML. Uma expiração não planejada bloqueia o acesso de todos os usuários simultaneamente. O JWKS elimina esse problema.
• Clientes fora do navegador. No momento em que um aplicativo móvel, CLI ou SPA precisa se autenticar, o SAML atinge seu limite e exige a criação de soluções intermediárias. O OIDC com PKCE oferece suporte nativo a esses cenários.
• Tokens de API. O SAML valida a identidade, mas não fornece um token de acesso. Se a mesma sessão de login precisar autorizar chamadas de API posteriormente, o OIDC já realiza esse processo nativamente.

Onde o SAML ainda é superior: ele funciona quando o SP e o IdP não conseguem se comunicar diretamente, pois o navegador faz o intermédio de todos os dados — um AD FS on-premises atrás de um firewall é o caso de uso clássico.

Erros comuns cometidos pelas equipes

Tratar a escolha do protocolo como uma decisão de segurança. Equipes frequentemente passam semanas debatendo SAML versus OIDC e dedicam poucos minutos para verificar se a claim de grupo está configurada corretamente. O segundo ponto determina os acessos de cada usuário; o primeiro define apenas a tela de configuração a ser preenchida.

Assumir que os grupos são enviados por padrão. A maioria dos IdPs não envia a claim de grupos a menos que ela seja explicitamente configurada, e vários a enviam sob um namespace como http://schemas.xmlsoap.org/ws/2005/05/identity/claims/groups. O SSO funciona, todos os usuários recebem a função padrão e a falha de atribuição de privilégios pode passar despercebida por dias.

Ignorar o destino do tráfego de autenticação. Independentemente do protocolo escolhido, algum componente receberá a asserção ou o ID token. Se esse componente estiver localizado fora do seu perímetro de rede, a escolha do protocolo torna-se secundária em relação à arquitetura de tráfego.

Quer ver os dois caminhos lado a lado?

Crie um tenant na TrueFoundry e conecte seu IdP via SAML ou OIDC em uma única sessão.

Comece gratuitamente

Como isso funciona na TrueFoundry

A TrueFoundry oferece suporte equivalente para OIDC e SAML 2.0, disponibilizando guias para Entra ID, Okta, Google Workspace, JumpCloud, OneLogin, Auth0, Keycloak, AD FS, PingOne e Rippling, além de opções para Custom SAML e Custom OIDC.

A configuração é feita em Platform → Settings → SSO: ative a opção Enabled, selecione seu SSO Provider e escolha OIDC ou SAML v2.

A escolha mais importante: o modelo de implantação

Antes de definir o protocolo, determine por onde trafegará o fluxo de autenticação.

Opção 1 — TrueFoundry Auth Server combinado com seu IdP. Modelo padrão, disponível nas modalidades SaaS e on-prem. O servidor de autenticação em login.truefoundry.com atua entre o seu plano de controle e o seu IdP: o plano de controle redireciona a requisição para o servidor de autenticação, que por sua vez a repassa ao seu IdP. Em seguida, ele valida a resposta, cria ou atualiza o registro do usuário e retorna os tokens.

Apenas o e-mail do usuário e a contagem de requisições são enviados para login.truefoundry.com, para fins de licenciamento e roteamento de tenants. Em contrapartida, a TrueFoundry gerencia de forma centralizada as especificidades de OIDC e SAML, a rotação de chaves e os endpoints SCIM, permitindo a troca de IdPs sem a necessidade de novos deploys. As requisições para o IdP são assinadas com um par de chaves RS256 e a asserção de destino SAML permanece ativada.

Opção 2 — Integração direta com o IdP. Exclusiva para modalidades on-prem no plano Enterprise. O plano de controle comunica-se diretamente com o seu IdP. O endereço login.truefoundry.com não participa do fluxo, e nem os e-mails dos usuários nem a contagem de requisições saem da sua rede. O plano de controle é configurado durante a instalação com o emissor OIDC ou os metadados SAML do seu IdP através dos valores do Helm, e os tokens são assinados localmente usando o valor INTERNAL_JWT_JWKS fornecido pelo suporte.

Ambas as opções suportam os mesmos IdPs e os dois protocolos. A única diferença reside em o tráfego de autenticação cruzar ou não o seu perímetro de rede — este é o ponto relevante a ser analisado pela equipe de segurança, em vez da discussão entre XML e JWT.

Opção 1: o mapeamento de campos no OIDC

Da TrueFoundry para o seu IdP há exatamente um valor, idêntico para todos os clientes:

https://login.truefoundry.com/oauth2/callback

Defina esse valor como Redirect URI, Sign-in redirect URI ou Reply URL na aplicação do seu IdP.

Do seu IdP para a TrueFoundry:

Essa opção representa a vantagem prática do OIDC. Ao mantê-la ativada, a TrueFoundry identifica automaticamente os endpoints de autorização, token, userinfo e JWKS. Se for desativada — o que só é necessário caso o seu IdP não publique um documento de descoberta —, todos os quatro endpoints devem ser preenchidos manualmente.

Opção 1: o mapeamento de campos no SAML

O SAML exige uma troca bidirecional de informações, razão pela qual é necessário salvar as configurações iniciais antes de finalizar a inclusão dos dados no IdP.

Do seu IdP para a TrueFoundry:

Esse fluxo ilustra a diferença de complexidade entre os padrões. O OIDC requer apenas uma Callback URL fixa, enquanto o SAML exige a troca de quatro valores em ambos os sentidos, além da gestão de um certificado com data de expiração.

Claims: o elemento que define o acesso

Independentemente do protocolo selecionado, a TrueFoundry lê os mesmos atributos. Os valores padrão são email e sub, que podem ser alterados em Show advanced fields nas opções Email Claim e Unique ID Claim. A claim groups é utilizada para RBAC.

Em vez de alterar os nomes das claims na TrueFoundry, é recomendável criar aliases no lado do IdP para que os padrões sejam mantidos:

Com esse mapeamento configurado, a associação aos times ocorre diretamente. O valor de uma claim é vinculado a uma equipe através dos campos Identity Provider FQN e Claim Value da equipe — se o seu IdP utiliza groups como a claim de equipe e o token contém ml-platform, insira ml-platform nesse campo.

Essa equipe recebe então suas respectivas permissões: ao atribuir uma função de tenant a ela, todos os membros herdam esse acesso; alternativamente, uma função de recurso pode ser atribuída diretamente a partir da página de Access Control do recurso correspondente.

Esse vínculo funciona de forma idêntica em ambos os protocolos. Para entender a estrutura de papéis, consulte API auth e RBAC no gateway, e para o cenário no nível de ferramentas, veja Controle de acesso no MCP.

Opção 2: os mesmos protocolos, configurados via Helm

Nesta abordagem, o mapeamento de campos é realizado no arquivo values.yaml, sob servicefoundryServer.env. Ambos os protocolos também exigem as configurações INCLUDE_TRUEFOUNDRY_MANAGED_JWKS: "false", INTERNAL_JWT_SERVICE_ENABLED: "true", a chave INTERNAL_JWT_JWKS fornecida pelo suporte e ENABLE_EXTERNAL_OAUTH: "true" no gateway.

OIDC: OAUTH_PROVIDER_TYPE: "EXTERNAL" combinado com EXTERNAL_OAUTH_ISSUER, EXTERNAL_OAUTH_CLIENT_ID e EXTERNAL_OAUTH_CLIENT_SECRET. A URI de redirecionamento passa a ser <CONTROL_PLANE_URL>/auth/callback, a descoberta deve estar acessível em <ISSUER_URL>/.well-known/openid-configuration, e os escopos padrão definidos são openid email profile offline_access.

SAML: OAUTH_PROVIDER_TYPE: "EXTERNAL_SAML" acompanhado de EXTERNAL_SAML_IDP_ENDPOINT e do certificado codificado em base64 em EXTERNAL_SAML_CERTIFICATE. A URL do ACS é <CONTROL_PLANE_URL>/api/svc/v1/saml/acs e o Default Relay State é <CONTROL_PLANE_URL>. As claims podem ser sobrescritas via EXTERNAL_SAML_EMAIL_CLAIM, EXTERNAL_SAML_UNIQUE_ID_CLAIM e EXTERNAL_SAML_GROUPS_CLAIM, utilizando EXTERNAL_SAML_ROLE_MAPPING_TENANT_ADMIN_GROUPS para especificar quais grupos recebem acesso de administrador do tenant. Armazene as credenciais em Kubernetes secrets.

O logout apresenta a maior diferença operacional entre as opções. Com OIDC, a TrueFoundry identifica seu end_session_endpoint automaticamente; a única etapa necessária é registrar <CONTROL_PLANE_URL> como uma URI de redirecionamento pós-logout, caso contrário o IdP retornará um erro HTTP 400. Com SAML, o Single Logout exige a geração de um par de chaves de assinatura do SP via openssl, a codificação em base64 da chave privada em EXTERNAL_SAML_SP_PRIVATE_KEY, o envio do certificado correspondente e a configuração da URL de Single Logout do IdP apontando para <CONTROL_PLANE_URL>/api/svc/v1/saml/slo.

Tokens de sessão após a autenticação

Após a conclusão da troca de credenciais, o plano de controle grava os tokens de acesso e de atualização (refresh tokens) como cookies HttpOnly, que passam a ser enviados em todas as requisições subsequentes para fins de autenticação e autorização.

Os tempos de vida padrão na Opção 1 são de 1 dia para o token de acesso e 7 dias para o token de atualização, ajustáveis via suporte. Na Opção 2 com SAML, a variável EXTERNAL_SAML_ACCESS_TOKEN_EXPIRY_SECONDS define a expiração do token de acesso, cujo padrão é de 3600 segundos. Usuários desativados são bloqueados durante o fluxo de autenticação, momento em que a resposta do IdP é associada ao registro do usuário pelo endereço de e-mail.

Exemplo prático: Okta, SAML e uma equipe de plataforma

Considere um cenário com Okta, onde a equipe de segurança padronizou a integração em SAML, e o grupo ml-platform deve gerenciar clusters enquanto os demais usuários mantêm permissões apenas de leitura.

1. Crie a aplicação SAML no Okta utilizando valores temporários para a Single sign-on URL e a Audience URI.
2. Na TrueFoundry, em Platform → Settings → SSO, ative o SSO, selecione o Okta, escolha SAML v2 e cole a URL de SSO SAML do Okta juntamente com o certificado de assinatura X.509. Salve as alterações.
3. Retorne ao Okta e substitua os valores temporários pela Callback URL e pelo Issuer gerados pela TrueFoundry.
4. Configure os attribute statements no Okta mapeando sub, email e groups.
5. Crie uma equipe na TrueFoundry, preencha o campo Identity Provider FQN e defina o Claim Value como ml-platform.
6. Atribua a função Cluster Admin a essa equipe na página de Access Control do cluster. Os demais usuários permanecem com a função Member padrão, que concede permissões restritas a cluster:ReadCluster, environment:ListEnvironments, settings:ListSettings, user:ListUsers, repository:CreateRepository, secret-group:CreateSecretGroup e agent:CreateAgent.

O processo seria equivalente caso utilizado OIDC: as etapas 1 a 3 seriam unificadas em uma única URL de callback e três parâmetros de configuração, mantendo as etapas 4 a 6 idênticas. Essa é a diferença real na implementação de ambos os protocolos.

Para realizar o provisionamento automático de usuários e equipes antes do primeiro acesso, ative o SCIM em Settings → Security & Access → Provisioning, copie a SCIM Base URL, gere um Bearer token e insira ambas as informações no Okta.

Pronto para integrar seu IdP?

Configure SAML ou OIDC, mapeie seus grupos para equipes e coloque o RBAC em funcionamento no mesmo dia.

Comece gratuitamente na TrueFoundry

Pontos de atenção importantes

No Entra ID e no Okta, o SCIM exige a utilização de SAML. Este é o cenário específico em que a escolha do protocolo possui um impacto funcional direto na TrueFoundry. Se a sua organização utiliza algum desses IdPs e necessita de provisionamento automatizado, opte por SAML antes de iniciar a configuração de uma aplicação OIDC.

Nomes de grupos via SCIM possuem restrições de formato. O nome do grupo no IdP é convertido no nome da equipe: são permitidos apenas caracteres alfanuméricos, hífens e sublinhados, com limite de 36 caracteres. Um nome como ML Platform (EMEA) não será processado corretamente.

A remoção de uma configuração de SSO pode falhar exibindo um erro de dessincronização com o servidor de autenticação central. Nesses casos, execute novamente a remoção com o parâmetro force=true na API de configurações, o que exige a permissão Manage Settings no tenant.

Erros comuns no Single Logout com SAML. O envio de um certificado que não corresponda ao par público de EXTERNAL_SAML_SP_PRIVATE_KEY resultará na mensagem “Invalid Signature”; um SP Entity ID diferente de <CONTROL_PLANE_URL> gerará a mensagem “Issuer does not match”.

Leituras relacionadas

• API Auth e RBAC no Gateway
• Controle de Acesso no MCP — permissões no nível de ferramentas usando o mesmo modelo de papéis
• Controle de Acesso Enterprise no MCP — escalando permissões entre equipes
• Autenticação no MCP — autenticação de entrada e saída
• Framework de Governança de IA

Conclusão

A escolha entre SAML e OIDC possui um impacto prático menor do que o volume de discussões sobre o tema sugere. Ambos os protocolos oferecem autenticação segura e possuem amplo suporte de mercado. A recomendação é utilizar a estrutura já adotada pela sua equipe de identidade. Escolha OIDC para aplicações móveis, SPAs, uso de tokens de API ou para simplificar a gestão de expiração de certificados. Mantenha o uso de SAML quando a infraestrutura existente exigir, quando o SP e o IdP não puderem se comunicar diretamente, ou quando um recurso específico depender exclusivamente desse padrão.

O aspecto central a ser avaliado é a arquitetura do tráfego de autenticação. Na TrueFoundry, ambos os protocolos funcionam em qualquer modelo de implantação — porém, apenas a integração direta garante que todas as credenciais permaneçam exclusivamente dentro da sua rede. Em ambientes regulados, este é o requisito verificado em auditorias de segurança, independentemente da utilização de XML ou JWT.

Configure o SSO na TrueFoundry

Gratuito para começar