Em cenários corporativos, é comum a necessidade de incluir informações específicas dos usuários — como identificadores internos, informações de patrocínio ou outros atributos personalizados — nos tokens de autenticação durante fluxos de Single Sign-On. O Microsoft Entra ID permite essa flexibilidade por meio dos chamados directory extension attributes, que podem ser registrados e depois referenciados como claims em aplicações empresariais.
O primeiro passo é criar os atributos de extensão no tenant. Para isso, utiliza-se o Graph Explorer com uma requisição POST apontada ao recurso de extensionProperties do objeto de aplicação. No corpo da requisição, é preciso informar o nome desejado (por exemplo, “sponsorid1”), o tipo de dado (como String) e os tipos de objeto alvo (geralmente usuários). Após a criação, o sistema retorna os nomes completos desses atributos no formato extension_<AppClientID>_<attributeName>, que serão usados nas próximas etapas.
Com os atributos registrados, o próximo passo é configurá-los como claims a serem emitidos nos tokens. Isso é feito na área de configuração de autenticação da aplicação empresarial dentro do portal do Entra ID. É necessário entrar na seção de Single Sign-On, editar a lista de atributos e claims, adicionar um novo claim e, na origem dos dados (Source), escolher “Directory schema extension” e especificar o aplicativo onde o atributo foi definido. Assim, o claim passará a incluir o valor armazenado para cada usuário no atributo de extensão.
Para cenários que exigem emissão condicional de claims — por exemplo, enviar um determinado atributo apenas se o usuário pertencer a um grupo específico — utiliza-se a Claims Mapping Policy. Essa política, aplicada a um service principal, permite definir condições, transformações e quais claims incluir ou excluir no token final. Ela oferece flexibilidade para moldar os tokens conforme regras corporativas, sendo possível adicionar scripts de transformação ou manipulação de valores, como concatenar atributos ou modificar formatos.
Por fim, essa abordagem amplia o controle sobre os dados enviados durante a autenticação, garantindo que aplicações possam receber informações específicas de negócio diretamente no token, sem necessidade de chamadas adicionais ou reconfigurações no próprio aplicativo.
Passo 1 – Registrar o aplicativo que conterá os atributos de extensão
No portal do Microsoft Entra ID, acesse “Registros de aplicativo” e crie um novo registro. Esse registro será usado apenas para armazenar os directory extension attributes. Dê um nome descritivo e mantenha a configuração padrão para tipos de conta, salvo se precisar de algo específico para múltiplos tenants. Após salvar, anote o Application (client) ID, pois ele fará parte do nome interno do atributo.
Passo 2 – Criar o atributo de extensão no Graph API
Você pode usar o Graph Explorer ou o PowerShell (exemplo usando o Graph Explorer - método POST):
Endpoint:
https://graph.microsoft.com/v1.0/applications/{AppObjectId}/extensionProperties
Corpo da requisição:
{
"name": "sponsorid1",
"dataType": "String",
"targetObjects": ["User"]
}
No retorno, observe o campo "name" que aparecerá como:
extension_<AppClientID>_sponsorid1
Esse nome completo será usado no mapeamento do claim.
Passo 3 – Preencher o atributo para um usuário
Via PowerShell, você pode usar: powershell_scripts/Microsoft/Graph/guest_user.ps1 at main · iamjrbro/powershell_scripts
Isso grava o valor no atributo para aquele usuário.
Passo 4 – Mapear o atributo como claim no token
No portal do Microsoft Entra ID, abra a Aplicação Empresarial usada no SSO, vá em Single Sign-On e depois em Editar atributos e claims.
Escolha “Adicionar novo claim” e, no campo “Origem”, selecione Directory schema extension. Escolha o aplicativo onde o atributo foi criado e selecione o atributo desejado (extension_<AppClientID>_sponsorid1). Salve as alterações.
Passo 5 – Criar uma Claims Mapping Policy (opcional, para cenários avançados)
No PowerShell: powershell_scripts/Microsoft/Graph/claims_mapping_policy.ps1 at main · iamjrbro/powershell_scripts
Passo 6 – Testar o token emitido
Você pode gerar um token JWT usando o Postman, Azure CLI ou outro método de autenticação e decodificá-lo em jwt.ms. No payload, procure pelo claim SponsorID (ou pelo nome padrão do atributo) e verifique se o valor corresponde ao gravado no passo 3.
O uso de atributos de extensão e declarações personalizadas é especialmente útil em integrações corporativas complexas, ambientes híbridos ou sistemas legados que precisam de dados específicos para autenticação e autorização.
Ao implementar essa configuração, a organização ganha em eficiência operacional e em capacidade de personalização, alinhando a autenticação à realidade do negócio.
Comments
Post a Comment