Compartilhar via

Personalizar tokens

  • Artigo

Como desenvolvedor, sua principal interação com o Microsoft Entra ID está em solicitar um token para identificar o usuário. Você também solicita um token para obter autorização para chamar uma API Web. O token da API da Web determina o que essa API pode fazer quando atende a uma solicitação específica. Neste artigo, você aprenderá sobre as informações que pode receber em tokens e como personalizar tokens. Essa prática recomendada para desenvolvedores de Zero Trust melhora a flexibilidade e o controle enquanto aumenta a segurança do aplicativo com menos privilégios.

Seus motivos para personalizar seus tokens de aplicativo dependem do processo que você está usando para gerar uma autorização mais granular no seus aplicativos e APIs. Por exemplo, você pode ter diferentes funções de usuário, níveis de acesso e funcionalidades em seu aplicativo que dependem de informações de tokens.

A API do Microsoft Graph fornece um conjunto robusto de informações de diretório e dados no Microsoft 365. É possível desenvolver um sistema de autorização refinado e rico com base nos dados do Microsoft Graph. Por exemplo, você pode acessar informações da associação de grupo do usuário, dados de perfil detalhados, SharePoint e Outlook para usar na suas decisões de autorização. Você também pode incluir dados de autorização no token do Microsoft Entra ID.

Autorização em nível de aplicativo

É possível que os profissionais de TI adicionem autorização no nível do aplicativo sem personalizar o token nem fazer com que o desenvolvedor adicione qualquer código.

Profissionais de TI podem impedir que tokens sejam emitidos para qualquer aplicativo no locatário usando o sinalizador de atribuição de usuário necessária para garantir que apenas um conjunto de usuários possa iniciar sessão no aplicativo. Sem esse sinalizador, todos os usuários em um locatário podem acessar o aplicativo. Com ele, somente usuários e grupos atribuídos podem acessar o aplicativo. Quando um usuário atribuído acessa o aplicativo, o aplicativo recebe um token. Se o usuário não tiver uma atribuição, o aplicativo não receberá um token. Lembre-se de sempre lidar com solicitações de token que não recebem tokens.

Métodos de personalização de token

Há duas maneiras de personalizar tokens: declarações opcionais e mapeamento de declarações.

Declarações opcionais

Declarações opcionais especificam quais declarações você deseja que o Microsoft Entra ID envie ao seu aplicativo em tokens. Você pode usar declarações opcionais para:

  • Selecione mais declarações para incluir nos tokens do aplicativo.
  • Altere o comportamento de declarações retornadas em tokens pela plataforma de identidade da Microsoft.
  • Adicione e acesse as declarações personalizadas para o aplicativo.

As declarações opcionais destravam do objeto de registro do aplicativo com um esquema definido. Eles são aplicáveis ao aplicativo, não importa onde ele estava sendo executado. Quando você está escrevendo um aplicativo multilocatário, as declarações opcionais funcionam bem porque são consistentes em todos os locatários do Microsoft Entra ID. Por exemplo, um endereço IP não é específico do locatário, enquanto um aplicativo tem um endereço IP.

Por padrão, os usuários convidados em um locatário também podem entrar no seu aplicativo. Se quiser bloquear usuários convidados, aceite a declaração opcional (conta). Se for 1, o usuário tem uma classificação de convidado. Se você quiser bloquear convidados, bloqueie tokens com acct==1.

Políticas de mapeamento de declarações

No Microsoft Entra ID, objetos de política representam conjuntos de regras em aplicativos individuais ou em todos os aplicativos de uma organização. Uma política de mapeamento de declarações modifica as declarações emitidas pelo Microsoft Entra ID em tokens para aplicativos específicos.

Você usa o mapeamento de declarações para informações específicas do locatário que não têm esquema (por exemplo, EmployeeID, DivisionName). O mapeamento de declarações se aplica no nível da entidade de serviço que o administrador do locatário controla. O mapeamento de declarações corresponde ao aplicativo corporativo ou à entidade de serviço desse aplicativo. Cada locatário pode ter seu próprio mapeamento de declarações.

Se você estiver desenvolvendo um aplicativo de linha de negócios, poderá examinar especificamente o que seu locatário faz (quais declarações específicas seu locatário tem disponíveis que você pode usar no seu token). Por exemplo, se uma organização tiver uma propriedade de nome de divisão do usuário (não um campo padrão no Microsoft Entra ID) em seu Active Directory local, você poderá usar o Microsoft Entre Connect para sincronizá-lo com o Microsoft Entra ID.

É possível usar um dos atributos de extensão padrão para conter essas informações. Você pode definir seu token com uma declaração de nome de divisão que você pode redigir da extensão correspondente (mesmo que ele não se aplique a todos os locatários). Por exemplo, uma organização coloca seu nome de divisão no atributo de extensão 13.

Com o mapeamento de declarações, você pode fazer com que funcione para outro locatário que coloca seu nome de divisão no atributo sete.

Planejar a personalização do token

O token que você personaliza depende do seu tipo de aplicativo: aplicativo cliente ou API. Não há diferença no que você pode fazer para personalizar seu token. O que você pode colocar no token é o mesmo para cada um deles. O token a ser escolhido para personalização depende de qual token seu aplicativo consome.

Personalizar tokens de ID

Se estiver desenvolvendo um aplicativo cliente, personalize o Token de identificação que é o token que você solicita para identificar o usuário. Um token pertence ao aplicativo quando a declaração de público-alvo (aud) no token corresponde ao ID do cliente do seu aplicativo. Para um aplicativo cliente que chama APIs, mas não as implementa, certifique-se de personalizar apenas o token de ID do aplicativo.

O portal do Azure e a API do Microsoft Graph também permitem personalizar o token de acesso para seu aplicativo, mas essas personalizações não têm efeito. Não é possível personalizar um token de acesso para uma API que você não possui. Lembre-se, seu aplicativo não deve tentar decodificar ou inspecionar um token de acesso que seu aplicativo cliente recebe como autorização para chamar uma API.

Personalizar tokens de acesso

Se estiver desenvolvendo uma API, você personaliza o token de acesso porque sua API recebe tokens de acesso como parte da chamada do cliente à sua API.

Os aplicativos cliente sempre personalizam o token de ID que recebem para identificar o usuário. As APIs personalizam os tokens de acesso que a API recebe como parte da chamada à API.

Grupos e funções de aplicativos

Uma das técnicas de autorização mais comuns é basear o acesso na associação de grupo de um usuário ou funções atribuídas. Configurar declarações de grupo e funções de aplicativo em tokens mostra como configurar seus aplicativos com definições de função de aplicativo e atribuir grupos de segurança a funções de aplicativo. Esses métodos ajudam a melhorar a flexibilidade e o controle, ao mesmo tempo que aumentam a segurança de confiança zero do aplicativo com menos privilégios.

Próximas etapas