SSO empresarial no AAA Sentinel: guia prático com o Auth0 (e o que muda com o Microsoft Entra ID ou o Okta)

O AAA Sentinel vê dados sensíveis: a fatura das suas clouds, as contas ligadas, o gasto em modelos de IA e a postura de segurança. Quando a equipa cresce, gerir acessos com palavras-passe soltas deixa de escalar: alguém sai da empresa e o acesso continua ativo, outra pessoa precisa de permissões de administrador durante uma semana e ninguém se lembra de as retirar. O SSO empresarial resolve isto ligando o AAA Sentinel ao diretório que a sua empresa já usa.

Porquê usar SSO empresarial

Com o SSO ativo, o seu fornecedor de identidade (IdP) passa a ser a única porta de entrada:

• Saídas num só sítio: desativa a pessoa no diretório e ela deixa de poder iniciar sessão no AAA Sentinel, sem mexer na plataforma.
• Funções sincronizadas: cada grupo do IdP corresponde a uma função (Administrador, Aprovador, Finanças ou Visualizador) e a função é recalculada em cada início de sessão.
• As políticas da sua empresa aplicam-se também aqui: MFA, acesso condicional ou duração da sessão são decididos pelo seu IdP.
• Domínio verificado: só entra por SSO quem tem um email de um domínio que demonstrou controlar com um registo DNS.
• Menos palavras-passe e menos suporte: ninguém tem de memorizar mais uma palavra-passe nem pedir que a reponham.

Como se configura no AAA Sentinel

O SSO está disponível no plano Business e é configurado pelo proprietário da organização em Gestão → Configurações, no cartão «SSO empresarial». São cinco passos:

• Escolha o protocolo, SAML ou OIDC. Fica fixo ao guardar; para o mudar é preciso eliminar a configuração.
• Copie para o seu IdP os dados que o painel mostra: com SAML, o URL de resposta (ACS), o identificador de entidade e o URL de fim de sessão; com OIDC, o URL de redirecionamento.
• Preencha os dados do IdP (o URL de metadados em SAML; issuer, client ID e segredo em OIDC), o claim do email, o dos grupos e a tabela grupo → função.
• Verifique o seu domínio publicando o registo TXT que o painel indica. A correspondência tem de ser exata.
• Clique em «Testar ligação»: abre o início de sessão do seu IdP noutro separador e confirma que tudo responde, sem alterar a sua sessão. Com tudo a verde, ative o SSO.

SAML ou OIDC: qual escolher

Os dois protocolos funcionam. A diferença está nos detalhes:

• SAML: o fim de sessão é completo (ao sair do AAA Sentinel também termina a sessão do IdP) e os grupos viajam como atributo multivalor. É a opção recomendada para sincronizar funções com o Microsoft Entra ID ou o Okta.
• OIDC: configura-se com menos dados (issuer, client ID e segredo). O AAA Sentinel termina também a sessão do IdP desde que este publique um end_session_endpoint e permita terminá-la com o client ID.
• Em ambos os casos, desativar o SSO suspende quem entra por ele, porque não tem palavra-passe, e deixa de contar como lugar. Voltam ao reativá-lo se ainda couberem no plano.

Caso prático: o Auth0 como fornecedor de identidade

Testámos a integração completa com um tenant gratuito do Auth0, primeiro com SAML e depois com OIDC. O que é comum aos dois faz-se uma só vez: uma Action que publica as funções de cada pessoa (Actions → Library → Build Custom, com o trigger Login / Post Login) e as definições da aplicação. A mesma Action serve para os dois protocolos:

// Actions → Library → Build Custom → Login / Post Login
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles ?? []
  const joined = roles.join(',')

  // OIDC: claim com namespace, no ID token e no access token (o AAA Sentinel lê-o do userinfo)
  api.idToken.setCustomClaim('https://aaa-sentinel.com/groups', joined)
  api.accessToken.setCustomClaim('https://aaa-sentinel.com/groups', joined)

  // SAML: atributo multivalor "groups"
  if (api.samlResponse) api.samlResponse.setAttribute('groups', roles)
}

• Use os Roles do Auth0 (User Management → Roles) como grupos: crie um por cada função que queira mapear e atribua-o a cada pessoa. O nome do Role é exatamente o que vai escrever depois no mapeamento do painel.
• Allowed Callback URLs e Allowed Logout URLs aceitam vários URLs separados por vírgulas: com os da tabela fica coberto para SAML e para OIDC. Clique em Save Changes no fim da página.

Auth0 com SAML

No separador Addons da aplicação, ative SAML2 Web App. No separador Settings do addon, Application Callback URL é o URL de resposta do painel e o campo Settings leva este JSON, com o bloco logout para o fim de sessão único:

{
  "audience": "<identificador de entidade que o painel mostra>",
  "recipient": "https://auth.aaa-sentinel.com/saml2/idpresponse",
  "destination": "https://auth.aaa-sentinel.com/saml2/idpresponse",
  "nameIdentifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "nameIdentifierProbes": [
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  ],
  "logout": {
    "callback": "https://auth.aaa-sentinel.com/saml2/logout",
    "slo_enabled": true
  }
}

• O URL de metadados está no separador Usage do addon, em Identity Provider Metadata: copie-o com o botão direito → «copiar endereço da ligação». Um clique normal descarrega o XML, e o painel precisa do URL.

Auth0 com OIDC

Com OIDC não é preciso nenhum addon: basta a aplicação e a Action acima. No painel do AAA Sentinel vão estes valores:

• O issuer leva a barra final: é exatamente o valor que o Auth0 publica como issuer.
• O segredo não pode ser lido de volta: escreva-o de novo sempre que guardar a configuração.
• O AAA Sentinel lê os grupos do endpoint userinfo, não só do ID token. Por isso a Action publica um claim com namespace, também no access token, com as funções separadas por vírgulas.
• Ao sair do AAA Sentinel também termina a sessão do Auth0, através do seu end_session_endpoint. Para isso, https://app.aaa-sentinel.com/login tem de estar em Allowed Logout URLs, como na tabela da aplicação.

Os erros que nos fizeram perder mais tempo

Nenhum é uma falha da plataforma, mas vistos de fora parecem-se todos: «entro, mas não com a função certa». Esta é a lista a rever:

• Nomes de grupo que não coincidem: o mapeamento distingue maiúsculas e plurais. Uma função chamada finops-admin não corresponde a finops-admins, e a pessoa entra com a função por omissão.
• A Action com deploy feito mas fora do fluxo: o Auth0 não envia nenhum grupo e toda a gente entra com a função por omissão.
• Um email que não pertence ao domínio verificado: o SSO não lhe é oferecido. Os utilizadores de teste precisam de um email do domínio, mesmo sem caixa de correio.
• Sessões do IdP que continuam abertas: se ao mudar de utilizador entra sem lhe pedirem palavra-passe, confirme que o URL de fim de sessão está permitido no IdP.

E com o Microsoft Entra ID ou o Okta?

Os passos no AAA Sentinel são os mesmos com qualquer fornecedor; o que muda é a configuração no IdP. O que fizemos no Auth0 (a Action e o namespace do claim) é próprio do Auth0. Estes são os pontos a vigiar nos outros dois:

• Microsoft Entra ID: por omissão envia os grupos como Object ID (um GUID) e não como nome, por isso o mapeamento grupo → função preenche-se com esses identificadores, a menos que configure o claim para enviar nomes. Os utilizadores sem caixa de correio têm o email vazio: mapeie o email para o UPN. O domínio .onmicrosoft.com não pode ser verificado; precisa de um domínio próprio. E o Entra não devolve os grupos no userinfo, por isso use SAML para sincronizar funções.
• Okta: o claim de grupos define-se no servidor de autorização e tem de ser incluído para qualquer scope, porque o AAA Sentinel só pede openid e email. O seu fim de sessão OIDC exige um token que a plataforma não guarda, por isso com OIDC a sessão do Okta continua aberta ao sair; com SAML o fim de sessão é completo.
• Com qualquer fornecedor: use «Testar ligação» antes de ativar e entre com um utilizador de cada grupo para validar as funções.

Checklist antes de ativar

Com tudo isto em ordem, no dia em que alguém sair da empresa basta desativá-lo no diretório para que não volte a iniciar sessão. Se também quiser terminar uma sessão que tenha aberta, remova-o em Usuários.

• Plano Business e acesso como proprietário da organização.
• Um domínio próprio e acesso ao respetivo DNS para publicar o registo TXT.
• Os grupos do IdP criados, com os nomes exatos que vai mapear.
• O URL de resposta e o de fim de sessão registados no IdP.
• O teste de ligação a verde e três utilizadores de teste validados.