Personalizar tokens

Como desenvolvedor, sua principal interação com o Microsoft Entra ID é solicitar um token para identificar o usuário. Você também solicita um token para obter autorização para chamar uma API da 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 você pode receber em tokens e como você pode personalizar tokens. Essas práticas recomendadas para desenvolvedores Zero Trust melhoram a flexibilidade e o controle, ao mesmo tempo em que aumentam a segurança do aplicativo com o menor privilégio.

Suas razões para personalizar seus tokens de aplicativo dependem do processo que você está usando para gerar uma autorização mais granular em 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. Você pode desenvolver um sistema de autorização refinado e rico aproveitando os dados no 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 em suas decisões de autorização. Você também pode incluir dados de autorização no token do Microsoft Entra ID.

Autorização ao nível da aplicação

É 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 nenhum código.

Os 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 entrar no aplicativo. Sem esse sinalizador, todos os usuários em um locatário podem acessar o aplicativo. Com esse sinalizador, apenas 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 graciosamente 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.

Pedidos facultativos

As declarações opcionais especificam quais declarações você deseja que o Microsoft Entra ID envie para seu aplicativo em tokens. Pode utilizar as afirmações opcionais para:

• Selecione mais declarações para incluir em seus tokens de aplicativo.
• Altere o comportamento das declarações que a plataforma de identidade da Microsoft retorna em tokens.
• Adicionar e aceder a afirmações personalizadas da aplicação.

As declarações opcionais ficam suspensas do objeto de registro do aplicativo com um esquema definido. Eles se aplicam 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 no 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 você quiser bloquear usuários convidados, opte pela reivindicação opcional (acct). Se for 1, o usuário terá uma classificação de convidado. Se você quiser bloquear convidados, bloqueie tokens com acct==1.

Políticas de mapeamento de sinistros

No Microsoft Entra ID, os objetos de política representam conjuntos de regras em aplicativos individuais ou em todos os aplicativos em uma organização. Uma política de mapeamento de declarações modifica as declarações que o Microsoft Entra ID emite 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 aplica-se ao nível da entidade de serviço que o administrador do inquilino controla. O mapeamento de declarações corresponde ao aplicativo corporativo ou à entidade de serviço desse aplicativo. Cada inquilino pode ter o seu próprio mapeamento de reclamações.

Se estiver a desenvolver uma aplicação de linha de negócio, pode analisar especificamente o que o seu inquilino faz (que declarações específicas o seu inquilino tem disponíveis e que pode utilizar no seu token). Por exemplo, se uma organização tiver a propriedade de nome de divisão de um usuário (não um campo padrão no Microsoft Entra ID) em seu Ative Directory local, você poderá usar o Microsoft Entra Connect para sincronizá-lo com o Microsoft Entra ID.

Você pode 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 compor a partir da extensão correspondente (mesmo que ela 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 coloque o nome da 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 que você escolhe personalizar depende de qual token seu aplicativo consome.

Personalizar tokens de ID

Se estiver desenvolvendo um aplicativo cliente, você personaliza o token de ID porque é o token que você solicita para identificar o usuário. Um token pertence ao seu aplicativo quando a declaração de audiência (aud) no token corresponde à 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 seu aplicativo.

O portal do Azure e a API do Microsoft Graph também permitem que você personalize 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 não é sua. 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 você estiver desenvolvendo uma API, personalizará o token de acesso porque sua API recebe tokens de acesso como parte da chamada do cliente para 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 para a API.

Grupos e funções do aplicativo

Uma das técnicas de autorização mais comuns é basear o acesso na associação ao grupo de um usuário ou nas 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 e, ao mesmo tempo, aumentam a segurança de confiança zero do aplicativo com o menor privilégio.

Próximos passos

• O mapeamento de declarações de usuário de colaboração B2B descreve o suporte ao Microsoft Entra ID para personalizar as declarações emitidas no token SAML (Security Assertion Markup Language) para usuários de colaboração B2B.
• Personalize as declarações de token SAML do aplicativo quando um usuário se autentica em um aplicativo por meio da plataforma de identidade da Microsoft usando o protocolo SAML 2.0.
• A Proteção de API descreve as práticas recomendadas para proteger sua API por meio de registro, definição de permissões e consentimento e imposição de acesso para atingir suas metas de Zero Trust.
• As práticas recomendadas de autorização ajudam você a implementar os melhores modelos de autorização, permissão e consentimento para seus aplicativos.
• Use as práticas recomendadas de desenvolvimento de gerenciamento de acesso e identidade Zero Trust em seu ciclo de vida de desenvolvimento de aplicativos para criar aplicativos seguros.