Como construí minha primeira integração SAML — e o que é SSO de verdade
Em 2019 precisei integrar um sistema com o provedor de identidade de um cliente. Não sabia o que era SAML. Aprendi na raça. Aqui está o que você precisa saber antes de começar.
O cliente disse: "precisa integrar com nosso SSO."
Não sabia o que era SSO. Sabia que era "Single Sign-On" — login único para vários sistemas. Não sabia como funcionava tecnicamente.
Fui pesquisar. Voltei com perguntas. "Vocês usam SAML ou OIDC?" O cliente não sabia. O departamento de TI deles sabia: "SAML 2.0 com Azure AD."
Ótimo. Agora eu tinha o problema definido. Ainda não sabia como resolver.
SSO: você faz login uma vez, acessa vários sistemas. Entre empresas diferentes, o protocolo que implementa isso é SAML 2.0. Três partes: o IdP (Identity Provider — Azure AD, Okta, Google Workspace — quem verifica sua identidade), o SP (Service Provider — sua aplicação), e o usuário.
O fluxo: usuário acessa sua app → app redireciona para o IdP → usuário faz login no IdP → IdP manda de volta um "assertion" (XML assinado dizendo "esse usuário é quem diz ser") → sua app valida o assertion e cria sessão. Simples na teoria. Na prática, esse XML vai te dar trabalho.
O que me pegou de surpresa: XML. SAML usa XML extensivamente — verboso, com namespace, com assinaturas digitais incorporadas. Não é JSON. Certificados: a assertion é assinada com certificado do IdP, e se o certificado expirar (e expira), a integração quebra silenciosamente. Mapeamento de atributos: o nome do atributo no IdP raramente é o que você esperava — http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress em vez de simplesmente email. E environments diferentes: IdP geralmente tem configuração separada para dev e produção — perdi horas até descobrir que estava usando configuração de dev em produção.
Como não entrar em pânico: use uma biblioteca. Não implemente SAML na mão. Tem biblioteca para toda linguagem principal — python-saml, passport-saml (Node), onelogin/ruby-saml. Peça o metadata XML do IdP — é um arquivo com tudo que você precisa: endpoint, certificado público, bindings suportados. Importa esse arquivo na biblioteca e metade da configuração já está feita. Teste com um IdP de desenvolvimento antes de ir para o do cliente. Okta tem tier grátis. E quando algo der errado (vai), habilita o log detalhado — o erro geralmente é específico, mas sem log você não sabe qual dos 10 problemas possíveis está acontecendo.
Hoje, se você está implementando SSO num sistema novo, prefira OIDC (OpenID Connect) sobre SAML. Usa JSON em vez de XML, é mais simples, tem suporte melhor em bibliotecas modernas. SAML ainda existe por uma razão: legado enterprise. Se o cliente tem Active Directory ou sistema de identidade antigo, provavelmente vai ser SAML.
O modelo mental é simples: alguém verifica a identidade (IdP), manda um comprovante assinado (assertion/token), e você valida esse comprovante (SP). Tudo mais é detalhe de implementação.
Essa semana: se você nunca implementou SSO, procura um tutorial de OIDC com Google como IdP. É o fluxo mais simples e te dá o modelo mental que você vai reusar para entender SAML, OAuth, e qualquer outro protocolo de identidade.