SSO para apps internos: mapear atributos SAML/OIDC para funções e equipes

Por que o mapeamento de atributos importa para apps internos

Single sign-on parece simples: clicar em "Entrar com Okta" ou "Entrar com Azure AD" e pronto. O problema é o que acontece depois. Sem um mapeamento claro de atributos, pessoas acabam com acesso demais (um agente de suporte vê folha de pagamento) ou de menos (um novo contratado não consegue abrir a ferramenta no primeiro dia).

Apps internos são mais complicados que apps públicos porque são compartilhados por vários times e mudam o tempo todo. Uma única ferramenta pode ser usada por Suporte, Financeiro e Vendas ao mesmo tempo. Organogramas mudam, contratados entram e saem, e equipes são renomeadas ou divididas. Se as regras de acesso vivem só na cabeça das pessoas, o SSO vai copiar essa bagunça para seu app.

O mapeamento de atributos é como você transforma os dados de identidade do seu provedor de identidade (IdP), como grupos, departamento ou cargo, em permissões que o app entende. Normalmente isso significa decidir:

• Quais funções existem no app (admin, gerente, visualizador, etc.)
• A quais equipes ou workspaces os usuários pertencem
• O que cada função pode fazer e o que cada equipe pode ver
• Quem obtém acesso automaticamente e quem precisa de aprovação

Dois riscos causam a maior parte dos problemas:

• Mapeamentos errados. Um nome de grupo corresponde à função errada, ou um grupo amplo "Todos os funcionários" concede admin por engano.
• Atributos ausentes. O IdP não envia grupos para alguns usuários, um atributo está em branco ou o token é grande demais e é cortado.

Seu app precisa de padrões seguros para que dados ausentes ou inesperados nunca virem acesso acidental.

SAML vs OIDC em termos simples

Quando você faz login com SSO, o IdP envia ao app um pequeno pacote de fatos sobre você. Cada fato é um atributo (claim), basicamente um campo rotulado como "email = [email protected]" ou "department = Finance".

SAML e OIDC podem carregar fatos semelhantes, mas os embalam de formas diferentes.

SAML é comum em setups empresariais mais antigos. Normalmente envia um documento XML (uma assertion) com atributos. Esses atributos são os claims que seu app lê.

OIDC é mais novo e baseado em OAuth 2.0. Geralmente envia um token JSON assinado (ID token) mais informações opcionais do usuário, onde os campos dentro do token são os claims.

Para apps internos, normalmente você se importa com um conjunto pequeno de claims:

• Endereço de email
• Um ID de usuário estável do IdP (subject)
• Nome completo (ou nome e sobrenome)
• Filiação a grupos (equipes, grupos de segurança)
• Departamento ou cargo

Uma distinção evita muita confusão:

Autenticação responde "quem é este usuário?" Claims como um ID estável e email ajudam a vincular o login SSO à conta certa.

Autorização responde "o que ele pode fazer?" Claims como grupos ou departamento ajudam a mapear o usuário para funções e equipes dentro do app.

Duas pessoas podem autenticar com sucesso, mas só aquela com o claim de grupo "Finance" deve acessar uma tela de cobrança.

Funções e equipes: decida o que mapear

Antes de mapear atributos SAML ou converter claims OIDC em permissões, deixe claro duas coisas que seu app precisa saber:

• Funções definem o que alguém pode fazer (permissões).
• Equipes definem onde a pessoa pertence (escopo).

Funções respondem perguntas como: esta pessoa pode ver, editar, aprovar, exportar, gerenciar usuários ou alterar configurações?

Equipes respondem perguntas como: em qual departamento, região, fila ou centro de custo essa pessoa trabalha, e quais registros ela deve ver?

Mantenha as funções pequenas e estáveis. A maioria dos apps internos precisa de poucas funções que mudam raramente, mesmo quando as pessoas se movem. Equipes devem refletir a realidade do dia a dia: Suporte Tier 2, cobertura EMEA, um responsável por uma fila temporária.

Menor privilégio é o padrão mais seguro. Muitos apps internos se viram bem com três funções:

• Visualizador: pode ler dados e fazer buscas
• Editor: pode criar e atualizar registros
• Admin: pode gerenciar configurações, usuários e regras de acesso

Escreva, em linguagem simples, o que cada função permite. Isso evita "admin surpresa" quando um nome de grupo muda e facilita revisões depois.

Acesso baseado em grupos: como pensar nos grupos do IdP

Acesso baseado em grupos significa que seu app não decide permissão por pessoa. Em vez disso, confia no IdP para manter a associação a grupos, e o app mapeia esses grupos para funções e equipes.

Comece decidindo o que um grupo concede. Em muitas ferramentas, um grupo mapeia para uma função (como "Agente de Suporte") e opcionalmente para uma equipe (como "Tier 2"). O importante é que o mapeamento seja previsível: o mesmo grupo sempre significa o mesmo acesso.

Quando usuários estão em múltiplos grupos

Pessoas frequentemente pertencem a mais de um grupo do IdP. Você precisa de uma regra para resolver isso, e deve mantê-la estável.

Abordagens comuns:

• Regras aditivas: combine permissões de todos os grupos que batem (funciona quando permissões são bem delimitadas)
• Regras por prioridade: escolha o grupo de maior prioridade e ignore o resto (útil quando funções conflitam)
• Híbrido: aditivo para equipes, prioridade para funções

O que quer que escolha, documente. Mudar isso depois pode fazer usuários ganharem ou perderem acesso de repente.

Use uma convenção de nomes que escale

Nomes de grupos claros diminuem erros e facilitam auditorias. Um padrão prático é:

• --

Por exemplo, support-tool-prod-agent ou finance-tool-staging-viewer. Isso ajuda a evitar reaproveitar nomes vagos como "Admins" entre vários apps.

Se um usuário não pertence a nenhum grupo relevante, padrão para sem acesso (ou um estado de convidado claramente limitado) e mostre uma mensagem explicando como solicitar acesso.

Vinculação de contas: associar usuários SSO a contas do app

SSO prova quem alguém é, mas seu app ainda precisa decidir a qual conta existente anexar essa identidade. Sem vinculação de contas, a mesma pessoa pode acabar com múltiplas contas ao longo do tempo porque identificadores mudam: novo email, atualizações de nome, mudança entre subsidiárias, troca de IdP.

Escolha uma chave estável e única como correspondência principal.

• Para OIDC, geralmente é o claim sub (subject).
• Para SAML, costuma ser um NameID persistente ou um atributo de usuário imutável dedicado.

Armazene esse valor como o "IdP user ID" junto com o issuer/entity ID do IdP, para que o mesmo sub de um IdP diferente não colida.

O email é útil, mas trate-o como chave de conveniência, não como fonte de verdade. Pessoas mudam de email por renomes, migrações de domínio ou fusões. Aliases e caixas compartilhadas também podem gerar correspondências inesperadas. Se fizer correspondência por email, faça apenas quando o sinal do IdP for verificado e considere um passo de confirmação único.

No primeiro login, a maioria das ferramentas internas escolhe um padrão de onboarding:

• Criação automática: cria uma conta imediatamente e atribui acesso mínimo.
• Somente por convite: apenas logins para usuários pré-criados (ou pré-aprovados) no seu app.
• Fluxo de aprovação: cria a conta, mas bloqueia o acesso até que um gerente ou admin aprove a função/equipe.

Um padrão seguro é criar automaticamente sem permissões por padrão, e então conceder acesso com base em grupos ou por um passo de aprovação.

Passo a passo: mapear atributos para funções e equipes

Um bom mapeamento faz o SSO parecer invisível: pessoas entram e caem no lugar certo com o acesso certo.

Comece escrevendo seu modelo de acesso em linguagem simples. Liste cada função (Visualizador, Agente, Gerente, Admin) e cada equipe (Suporte, Financeiro, TI), mais quem deveria recebê-las e por quê.

Então confirme o que seu IdP realmente pode enviar. Para SAML ou OIDC, normalmente você quer um ID de usuário estável (subject ou NameID), email e um ou mais atributos de grupo. Capture os valores exatos dos grupos como aparecem, incluindo maiúsculas, minúsculas e prefixos. "Support" e "support" não são a mesma coisa.

Um fluxo prático:

• Defina funções e equipes, e nomeie um dono para cada uma (alguém que possa aprovar mudanças).
• Liste os claims disponíveis e os nomes exatos de grupos do IdP, incluindo casos de borda (contratados, caixas compartilhadas).
• Escreva regras de mapeamento: grupo-para-função, grupo-para-equipe, e uma ordem de override quando múltiplos grupos baterem.
• Teste com 3 a 5 tipos reais de usuário (novo contratado, gerente, contratado temporário, admin) usando contas reais do IdP.
• Para cada usuário de teste, escreva primeiro o resultado esperado de função/equipe, depois faça login e compare.

Mantenha um exemplo pequeno por perto para deixar as regras concretas. Se um usuário está em "okta-support", ele vira time Support com a função Agent. Se também está em "okta-support-managers", a função Manager substitui Agent.

Finalmente, adicione uma forma simples de depurar. Logue os claims brutos recebidos (com segurança), as regras que bateram e o resultado final de função/equipe. Quando alguém diz "entrei, mas não consigo ver minha ferramenta", isso transforma adivinhação em uma checagem rápida.

Padrões seguros quando os claims estão ausentes

Claims ausentes são normais. O IdP pode não enviar grupos para contas de serviço, um conector pode omitir um campo, ou um usuário pode estar em migração. Trate "sem dados" como "sem confiança."

O padrão mais seguro é negar por padrão: nenhuma função, nenhuma equipe, sem acesso. Se for preciso permitir entrada para solicitar acesso, mantenha-a apenas leitura e claramente limitada.

Escolha um comportamento e documente:

• Bloquear login com mensagem clara: "Sua conta não tem acesso atribuído. Contate o suporte."
• Permitir acesso limitado com aviso e desabilitar ações sensíveis.
• Criar o registro do usuário mas atribuir nenhuma função ou equipe até aprovação.

Nunca dê admin por padrão, nem mesmo temporariamente.

Planeje para dados parciais. Se receber um email mas nenhum grupo, você ainda pode criar uma conta e enviá-la para aprovação. Se receber grupos mas nenhum identificador estável, evite auto-vincular a uma conta existente, pois isso pode anexar a pessoa errada.

Tenha um caminho de escalonamento para falhas:

• Um dono nomeado (TI ou admin do app) que possa aprovar acesso
• Um fluxo manual de atribuição de função com anotação de auditoria
• Uma forma de re-checar claims no próximo login
• Um tempo limite para contas em "pendência de acesso"

Lidando com mudanças, remoções e offboarding

Pessoas mudam de time, trocam de gerente e saem da empresa. Seu setup de SSO deve tratar isso como normal.

Quando alguém muda de equipe, atualize o acesso no próximo login: reavalie os claims de grupo e aplique o mapeamento atual. Evite acessos "pegajosos" que ficam para sempre porque foram concedidos uma vez.

Quem sai é diferente. Esperar pelo próximo login não é suficiente. Você quer terminar o acesso rapidamente, mesmo que a sessão ainda esteja ativa. Isso normalmente significa desabilitar a conta no IdP, e seu app deve tratar uma identidade desabilitada ou ausente como bloqueada imediatamente.

A desprovisionamento deve ser previsível: desabilitar o usuário, remover associações a equipes e manter dados de auditoria. Muitas vezes é necessário preservar registros como aprovações, comentários e histórico para conformidade, enquanto se impede novas ações.

Contratados e acessos temporários merecem cuidado extra. Coloque-os em grupos com prazo no IdP, ou anexe uma data de revisão à função para que o acesso não permaneça após o fim do projeto.

Uma política prática de offboarding:

• Reavalie claims em todo login e atualize associação de equipes a partir do IdP
• Quando um usuário é removido de grupos necessários, revogue privilégios imediatamente (próximo login ou próxima sincronização)
• Desabilite a conta preservando trilhas de auditoria e histórico de propriedade
• Exija data de término para acesso de contratados e revise antes de renovar
• Faça revisões periódicas de acesso para funções sensíveis como finanças ou admin

Erros comuns e armadilhas a evitar

A maioria das falhas com SSO não vem de SAML ou OIDC serem "difíceis". Elas acontecem porque o app faz suposições inseguras sobre pessoas, grupos e identificadores.

Um erro comum é misturar mapeamento de função com mapeamento de equipe. Funções são "o que você pode fazer?" Equipes são "onde você pertence?" Se você mapear um grupo de equipe diretamente para uma função poderosa como Admin, frequentemente dará acesso amplo a quem estiver naquele time.

Outra armadilha é confiar apenas no email para vincular contas. Emails mudam, e aliases criam duplicados. Prefira um ID de usuário estável do IdP (como sub/NameID) como chave primária e trate o email como campo de exibição/ notificação.

Outros problemas frequentes:

• Abrir falhas quando grupos estão ausentes (use negar por padrão ou acesso baixo, não acesso total)
• Nomes de grupos pouco claros sendo reaproveitados entre dev, staging e produção
• Tratar associação a grupos como lista de permissões sem revisar o que cada grupo realmente significa
• Não lidar com usuários multi-equipes que precisam acessar mais de uma área sem virar admin
• Esquecer parceiros e contratados que devem ficar isolados de equipes só para empregados

Teste casos de borda antes do lançamento. Um analista financeiro em resposta a incidente pode precisar de duas equipes e uma função elevada. Se suas regras só permitem uma equipe, ele ou perde acesso ou recebe privilégios demais.

Checklist rápido antes de ir ao vivo

Antes de habilitar SSO para todos, faça um dry run com algumas contas de teste de cada time. A maioria dos problemas de acesso aparece na hora ao testar um novo contratado, uma mudança de função e um caso de offboarding.

Comece pela vinculação de conta. Escolha um identificador único que não mude ao longo do tempo e mantenha-o. No OIDC isso costuma ser sub. No SAML é frequentemente NameID ou um atributo imutável específico.

Depois, decida o que acontece quando claims estão ausentes. O padrão mais seguro é não conceder acesso elevado (e em muitos apps, nenhum acesso) quando claims de grupo ou função estão ausentes ou vazios. Garanta ter pelo menos uma função de baixo privilégio que deixe as pessoas entrar sem expor ações sensíveis, se isso fizer sentido para seu fluxo.

Um checklist simples pré-lançamento:

• Confirme que seu identificador de vinculação é estável e único (e você consegue vê-lo nos logs)
• Verifique que claims de grupo ausentes não concedem acesso além de uma função de baixo privilégio
• Exija que acesso admin corresponda a um grupo admin explícito, mais um segundo passo de aprovação (mesmo que manual)
• Teste remoção: quando um usuário sai de um grupo, o acesso cai no próximo login (ou na próxima sync)
• Escreva regras de mapeamento para que um colega entenda em uma página

Exemplo: uma ferramenta interna de suporte e financeiro com grupos SSO

Imagine uma ferramenta de operações usada por Suporte, Financeiro e alguns gerentes. Você quer que as pessoas entrem e imediatamente tenham as telas e ações corretas sem um admin corrigir contas manualmente.

Crie alguns grupos no IdP e mapeie para funções e equipes no app:

• ops-support -> Função: Support Agent, Equipe: Support
• ops-finance -> Função: Finance Analyst, Equipe: Finance
• ops-managers -> Função: Manager, Equipe: Management

Veja como funciona.

Agora um caso de mudança de email: Omar muda de [email protected] para [email protected]. Como o app vincula contas usando o ID estável do IdP (como sub para OIDC, ou um NameID persistente para SAML) em vez do email, ele não ganha conta duplicada. Mantém o histórico e trilha de auditoria.

Para verificar acesso sem adivinhação, mantenha uma visão de "acesso efetivo" que mostre a identidade vinculada do IdP do usuário, os grupos recebidos, a função resultante e a equipe. Quando algo parecer errado, dá para identificar rápido se é problema do IdP, regra de mapeamento ou claim ausente.

Próximos passos: manter o acesso previsível conforme a organização muda

A parte mais difícil não é o primeiro lançamento. É manter o acesso sob controle após reorganizações, novos times e exceções "temporárias".

Mantenha um documento de mapeamento de uma página que responda:

• Quais grupos do IdP mapeiam para quais funções e equipes do app
• Qual é o padrão quando um claim falta (e quem aprova mudanças)
• Quem é dono de cada função de alto risco (admin financeiro, admin de usuários, exportação de dados)
• Como contratados e contas de serviço são tratados
• Onde vive a fonte da verdade (IdP vs app)

Faça um piloto pequeno com um departamento de fronteiras claras, corrija casos de borda e então expanda sem inventar novas regras. Agende revisões recorrentes para acessos que possam causar dano real: mensal para admins e funções de alto risco, trimestral para funções normais.

Se você está construindo o app interno, ajuda muito quando funções, equipes e lógica de negócio ficam próximas no código para que mudanças sejam fáceis de testar. AppMaster (appmaster.io) é uma opção para times que querem modelar funções e workflows visualmente e regenerar backend, web e código móvel conforme os requisitos mudam, sem acumular correções pontuais de permissão.