Claims personalizadas com atributos de extensão no Entra ID

Objetivo e variantes de intenção

Objetivo principal: emitir dados de utilizador personalizados (por exemplo, identificadores de patrocínio) em tokens SAML/OIDC apenas para grupos selecionados. Variantes relacionadas: mapear atributos do Graph, controlar claims por grupo, personalizar tokens OIDC, emitir atributos de diretório, automatizar mapeamento de claims.

Resumo rápido do processo

1. Registrar atributos de extensão para a aplicação via Microsoft Graph.
2. Atribuir valores desses atributos aos utilizadores com PATCH no Graph.
3. Criar claims na aplicação empresarial e condicionar por grupo.
4. Se necessário, ajustar o manifest para aceitar claims mapeados.
5. Testar com uma autenticação real e inspecionar o token.

Passo a passo detalhado

Passo 1: Registar atributos de extensão (Directory Extension Attributes)

Use o Graph Explorer ou uma chamada Graph API para registar atributos personalizados, por exemplo sponsorid1 e sponsorid2, na aplicação alvo.

Envie um POST para:

POST https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties

Exemplo de corpo da requisição:

{ “name”: “sponsorid1”, “dataType”: “String”, “targetObjects”: [“User”] }

Repita para sponsorid2. Após o registo, o Graph retorna nomes completos no formato:

extension_sponsorid1 extension_sponsorid2

Anote exatamente esses nomes — serão usados mais adiante.

Passo 2: Atribuir atributos aos utilizadores

Atribua valores aos utilizadores com PATCH ao objeto do utilizador no Graph:

PATCH https://graph.microsoft.com/v1.0/users/{UserObjectId}

Corpo da requisição de exemplo:

{ “extension__sponsorid1”: “ABC123” }

Faça isto para cada utilizador que deve receber um valor. Para muitos utilizadores, prefira automatizar via script PowerShell, Azure Automation ou fluxo do Microsoft Graph.

Passo 3: Criar claims na aplicação empresarial (Enterprise Application)

No portal do Entra ID:

Entra ID > Aplicações empresariais > [Nome da App] > Single sign‑on > Attributes & claims

1. Clique em Add new claim
2. Dê um nome (ex.: sponsorClaim1)
3. Em Claim conditions escolha Member e selecione o grupo que deve receber a claim
4. Em Source attribute use o nome do atributo de extensão (ex.: extension__sponsorid1)

Repita para o segundo grupo/atributo.

Passo 4: Resolver erro de mapeamento de claims

Erro comum: “Application requires custom signing key to customize claims”.

Solução temporária (quando aceitar risco operacional): editar o manifesto da app registration e definir:

“acceptMappedClaims”: true

Isto permite a personalização de claims sem fornecer uma chave de assinatura personalizada. Avalie impacto de segurança e conformidade antes de aplicar em produção.

Passo 5: Testar a configuração

Solicite um token OIDC/SAML usando um endpoint de autorização e inicie sessão com utilizadores pertencentes aos grupos definidos. Exemplo de URL para teste OIDC (substitua Tenant ID e Client ID):

https://login.microsoftonline.com/(Tenant ID)/oauth2/v2.0/authorize?client_id=(Client ID)&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

Inspecione o token em https://jwt.ms — deverá conter a claim sponsorid1 ou sponsorid2 apenas para os utilizadores dos grupos configurados. Utilizadores fora desses grupos não receberão a claim.

Mini‑metodologia recomendada

• Planeamento: defina quais grupos devem receber quais atributos.
• Registo: crie atributos de extensão numa aplicação dedicada (evita poluir apps de produção).
• Atribuição: automatize via scripts e controle de alterações (Change Control).
• Mapeamento: faça o mapeamento por grupo em Enterprise Applications.
• Testes: valide tokens com contas de cada grupo e com contas fora dos grupos.
• Auditoria: registe quem alterou atributos e mapeamentos.

Checklist por função

• Administrador de Identidade

  • Registrar atributos de extensão e anotar nomes retornados.
  • Editar manifesto se necessário e documentar alteração.

• Administrador de Aplicações

  • Adicionar claims na App Enterprise e condicionar por grupo.
  • Testar fluxo SSO e validar tokens.

• Engenheiro DevOps

  • Automatizar PATCH de utilizadores (scripts/fluxos).
  • Integrar testes automatizados que validem emission de claims.

• Segurança/Conformidade

  • Avaliar sensibilidade dos dados colocados nos tokens.
  • Verificar necessidade de chaves de assinatura personalizadas.

Critérios de aceitação / Testes

• Teste 1: Utilizador do Grupo A recebe claim sponsorClaim1 no token.
• Teste 2: Utilizador do Grupo B recebe claim sponsorClaim2 no token.
• Teste 3: Utilizador fora dos grupos não recebe nenhuma claim sponsorid.
• Teste 4: Modificar o valor do atributo no Graph reflete no token após novo login.

Critério: todos os testes devem passar sem exibir dados de outros grupos.

Quando isso pode falhar (contraexemplos)

• Atributo mal registado: usar o nome errado extension… impedirá o mapeamento.
• Permissões Graph insuficientes: a chamada PATCH falhará sem scopes adequados (User.ReadWrite.All ou equivalente).
• Token size: inserir muitos atributos no token pode exceder limites de tamanho do token para SAML/OIDC.
• Aplicação com regras de assinatura rígidas: se a app exigir chave de assinatura personalizada, não será possível mapear claims sem essa chave.

Abordagens alternativas

• Usar Microsoft Graph ClaimsMappingPolicy para cenários mais avançados de transformação.
• Guardar atributos em um serviço central (API interna) e consultar pós‑autenticação em vez de embutir no token.
• Utilizar grupos dinâmicos ou atributos do Azure AD (non-extension) quando aplicável.

Segurança, privacidade e conformidade

• Minimizar dados sensíveis nos tokens (evite PII se possível).
• Tokens são expostos aos clientes; trate-os como dados sensíveis durante logs e transmissões.
• Avalie impacto GDPR/local: transferência de atributos entre tenants/aplicações pode exigir base legal.
• Revisar e auditar quem pode modificar atributos de extensão e manifestos de aplicações.

Dicas práticas

• Use uma aplicação dedicada para atributos de extensão para facilitar identificação de extension_.
• Versione scripts que escrevem atributos e inclua testes end‑to‑end.
• Documente o mapeamento (grupo → atributo → claim) num ficheiro de configuração legível.

Resumo final

Emitir claims personalizadas via atributos de extensão do Entra ID é uma solução eficaz para fornecer informações específicas do utilizador apenas a aplicações e grupos autorizados. O maior cuidado é controlar quem altera atributos e avaliar o impacto de segurança de adicionar dados ao token.

Importante: antes de aplicar em ambientes de produção, valide permissões Graph, impactos no tamanho do token e requisitos de assinatura da aplicação.