Adicionar funções de aplicativo a seu aplicativo e recebê-las no token

O RBAC (controle de acesso baseado em função) é um mecanismo comum usado para impor a autorização em aplicativos. O RBAC permite que os administradores concedam permissões a funções em vez de a usuários ou grupos específicos. O administrador pode, então, atribuir funções a diferentes usuários e grupos para controlar quem tem acesso a qual conteúdo e funcionalidade.

Usando o RBAC com declarações de função e funções de aplicativo, os desenvolvedores podem impor a autorização nos aplicativos de maneira segura e com menos esforço.

Outra abordagem é usar os grupos do Microsoft Entra e as declarações de grupo do código de exemplo active-directory-aspnetcore-webapp-openidconnect-v2 no GitHub. As funções de aplicativos e os grupos do Microsoft Entra não são mutuamente excludentes e podem ser usados em conjunto para fornecer um controle de acesso ainda mais refinado.

Declarar funções para um aplicativo

Você define as funções de aplicativos usando o centro de administração do Microsoft Entra durante o processo de registro do aplicativo. As funções de aplicativos são definidas em um registro de aplicativo que representa um serviço, um aplicativo ou uma API. Quando um usuário entra no aplicativo, o Microsoft Entra ID emite uma declaração roles para cada função que foi concedida ao usuário ou à entidade de serviço, a qual pode ser usada para implementar a autorização baseada em declarações. As funções de aplicativo podem ser atribuídas a um usuário ou grupo de usuários. As funções de aplicativo também podem ser atribuídas à entidade de serviço para outro aplicativo ou à entidade de serviço para uma identidade gerenciada.

No momento, se você adicionar uma entidade de serviço a um grupo e atribuir uma função de aplicativo a esse grupo, o Microsoft Entra ID não adicionará a declaração roles aos tokens emitidos.

As funções de aplicativos são declaradas usando a UI de funções de aplicativos no centro de administração do Microsoft Entra:

O número de funções que você adiciona é calculado para os limites de manifesto do aplicativo impostos pelo Microsoft Entra ID. Para saber mais sobre esses limites, consulte a seção Limites de manifesto da referência de manifesto de aplicativo do Microsoft Entra.

Interface do usuário das funções de aplicativo

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Para criar uma função de aplicativo usando a interface do usuário do centro de administração do Microsoft Entra:

1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.

2. Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário que contém o registro do aplicativo no menu Diretórios + assinaturas.

3. Navegue até Identidade>Aplicativos>Registros de aplicativo e, em seguida, selecione o aplicativo no qual você deseja definir nas funções de aplicativo.

4. Em gerenciar, selecioneFunções de aplicativo e, em seguida,Criar função de aplicativo.

   

5. No painel Criar função de aplicativo, insira as configurações para a função. A tabela a seguir descreve cada configuração e seus parâmetros.

   

   Campo	Descrição	Exemplo
   Nome de exibição	Nome para exibição da função do aplicativo que aparece nas experiências de atribuição de aplicativo e consentimento do administrador. Esse valor pode conter espaços.	Survey Writer
   Tipos de membro permitidos	Especifica se essa função de aplicativo pode ser atribuída a usuários, aplicativos ou ambos. Quando disponíveis para applications, as funções de aplicativo aparecem como permissões de aplicativo na seção Gerenciar>Permissões de API> Adicionar uma permissão > Minhas APIs > Escolher uma API > Permissões de aplicativo.	Users/Groups
   Valor	Especifica o valor da declaração de funções que o aplicativo deve esperar no token. O valor deve corresponder exatamente à cadeia de caracteres referenciada no código do aplicativo. O valor não pode conter espaços.	Survey.Create
   Descrição	Uma descrição mais detalhada da função de aplicativo exibida durante as experiências de atribuição e consentimento do aplicativo de administração.	Writers can create surveys.
   Deseja habilitar esta função de aplicativo?	Especifica se a função de aplicativo está habilitada. Para excluir uma função de aplicativo, desmarque essa caixa de seleção e aplique a alteração antes de tentar a operação de exclusão. Essa configuração controla o uso e a disponibilidade da função de aplicativo enquanto pode desabilitá-la temporariamente ou permanentemente sem removê-la totalmente.	Verificado

6. Selecione Aplicar para salvar as alterações.

Quando a função de aplicativo é definida como Habilitada, todos os usuários, aplicativos ou grupos atribuídos a ela têm a função de aplicativo incluída em seus tokens. Eles podem ser tokens de acesso quando seu aplicativo é a API que está sendo chamada por um aplicativo, ou tokens de ID quando seu aplicativo está conectando um usuário. Se definida como desabilitada, ela se tornará inativa e não poderá mais ser atribuída. Os destinatários anteriores mantêm a função de aplicativo incluída em seus tokens, mas isso não terá efeito, pois ela não pode mais ser atribuída ativamente.

Atribuir proprietário do aplicativo

Antes de poder atribuir funções de aplicativo a aplicativos, você precisa se designar como o proprietário do aplicativo.

1. No registro do aplicativo, em Gerenciar, selecione Proprietários e Adicionar proprietários.
2. Na nova janela, localize e selecione os proprietários que você quer atribuir ao aplicativo. Os proprietários selecionados aparecem no painel direito. Depois de concluído, confirme com Selecionar e os proprietários do aplicativo aparecerão na lista de proprietários.

Observação

Verifique se o aplicativo de API e o aplicativo ao qual você quer adicionar permissões têm um proprietário; caso contrário, a API não será listada ao solicitar permissões de API.

Atribuir funções de aplicativo a aplicativos

Depois de adicionar funções de aplicativo em seu aplicativo, você pode atribuir uma função de aplicativo a um aplicativo cliente usando o centro de administração do Microsoft Entra ou de forma programática usando o Microsoft Graph. Atribuir uma função de aplicativo a um aplicativo não deve ser confundido com atribuir funções a usuários.

Ao atribuir funções de aplicativo a um aplicativo, você cria permissões de aplicativo. As permissões de aplicativo normalmente são usadas por aplicativos daemon ou por serviços de back-end que precisam autenticar e fazer chamadas à API autorizadas, sem a interação de um usuário.

Para atribuir funções de aplicativo a um aplicativo usando o centro de administração Microsoft Entra:

1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
2. Navegue até Identidade>Aplicativos>Registros de aplicativo e, em seguida, selecione Todos os Aplicativos.
3. Selecione Todos os aplicativos para exibir uma lista com todos os seus aplicativos. Se o aplicativo não aparecer na lista, use os filtros na parte superior da lista Todos os aplicativos para restringir a lista ou percorra a lista para localizar a lista para localizar seu aplicativo.
4. Selecione o aplicativo ao qual você deseja atribuir uma função de aplicativo.
5. Selecione Permissões de API>Adicionar uma permissão.
6. Selecione a guia Minhas APIs e, em seguida, selecione o aplicativo para o qual você definiu funções de aplicativo.
7. Em Permissão, selecione as funções que você deseja atribuir.
8. Selecione o botão Adicionar permissões para concluir a adição das funções.

As funções adicionadas recentemente devem aparecer no painel de Permissões de API do registro de aplicativo.

Conceder consentimento do administrador

Como essas são permissões de aplicativo, permissões não delegadas, um administrador deve conceder consentimento para usar as funções de aplicativo atribuídas ao aplicativo.

1. No painel Permissões de API do registro de aplicativo, selecione Atribuir consentimento do administrador para <nome do locatário>.
2. Selecione Sim quando solicitado a conceder consentimento para as permissões solicitadas.

A coluna Status deve indicar que o consentimento foi Concedido para <nome do locatário>.

Cenário de uso de funções de aplicativo

Se você estiver implementando uma lógica de negócios da função de aplicativo que conecta os usuários no seu cenário de aplicativo, primeiro, defina as funções de aplicativo em Registros de aplicativo. Em seguida, um administrador os atribui a usuários e grupos no painel de aplicativos empresariais. Dependendo do cenário, essas funções de aplicativo atribuídas estão incluídas em diferentes tokens que são emitidos para seu aplicativo. Por exemplo, para um aplicativo que faz logon de usuários, as declarações de funções estão incluídas no token de ID. Quando seu aplicativo chama uma API, as declarações de funções estão incluídas no token de acesso.

Se você estiver implementando uma lógica de negócios da função de aplicativo em um cenário de API de chamada de aplicativo, terá dois registros de aplicativo. Um registro de aplicativo é para o aplicativo, e um segundo registro de aplicativo é para a API. Nesse caso, defina as funções de aplicativo e as atribua ao usuário ou grupo no registro de aplicativo da API. Quando o usuário se autentica no aplicativo e solicita um token de acesso para chamar a API, uma declaração de funções é incluída no token de acesso. A próxima etapa é adicionar código à API Web para verificar essas funções quando a API é chamada.

Para saber como adicionar autorização à API Web, confira API Web protegida: verificar escopos e funções de aplicativo.

Funções de aplicativo versus grupos

Embora você possa usar funções de aplicativo ou grupos para autorização, as principais diferenças entre eles podem influenciar o que você decidir usar para seu cenário.

Funções de aplicativo	Grupos
Elas são específicas de um aplicativo e são definidas no registro do aplicativo. Eles se movem com o aplicativo.	Eles não são específicos de um aplicativo, mas de um locatário do Microsoft Entra.
As funções de aplicativo são removidas quando o registro do aplicativo é removido.	Os grupos permanecem intactos, mesmo que o aplicativo seja removido.
Fornecido na declaração roles.	Fornecido na declaração groups.

Os desenvolvedores podem usar funções de aplicativo para controlar se um usuário pode entrar em um aplicativo ou se um aplicativo pode obter um token de acesso para uma API Web. Para estender esse controle de segurança para grupos, os desenvolvedores e administradores também podem atribuir grupos de segurança a funções de aplicativo.

Os desenvolvedores preferem usar funções de aplicativo quando desejam descrever e controlar os parâmetros de autorização no próprio aplicativo. Por exemplo, um aplicativo que usa grupos para autorização será interrompido no próximo locatário, pois tanto a ID de grupo quanto o nome podem ser diferentes. Um aplicativo que usa funções de aplicativo permanece seguro. Na verdade, aplicativos SaaS frequentemente atribuem grupos a funções de aplicativo pelos mesmos motivos, pois isso permite que o aplicativo SaaS seja provisionado em vários locatários.

Atribuir usuários e grupos a funções do Microsoft Entra

Após adicionar funções de aplicativo em seu aplicativo, você pode atribuir usuários e grupos a funções do Microsoft Entra. A atribuição de usuários e grupos a funções pode ser feita por meio da interface do usuário do portal ou de maneira programática usando o Microsoft Graph. Quando os usuários atribuídos às várias funções entrarem no aplicativo, seus tokens terão suas funções atribuídas na declaração roles.

Para atribuir usuários e grupos a funções usando o centro de administração do Microsoft Entra:

1. Entre no Centro de administração do Microsoft Entra como pelo menos Administrador de Aplicativo de nuvem.
2. Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário que contém o registro do aplicativo no menu Diretórios + assinaturas.
3. Navegue até Identidade>Aplicativos>Aplicativos empresariais.
4. Selecione Todos os aplicativos para exibir uma lista com todos os seus aplicativos. Se o aplicativo não aparecer na lista, use os filtros na parte superior da lista Todos os aplicativos para restringir a lista ou percorra a lista para localizar a lista para localizar seu aplicativo.
5. Selecione o aplicativo no qual deseja atribuir funções a usuários ou grupos de segurança.
6. Em Gerenciar, selecione Usuários e grupos.
7. Selecione Adicionar usuário para abrir o painel Adicionar atribuição.
8. Clique no seletor Usuários e grupos do painel Adicionar Atribuição. É mostrada uma lista de usuários e grupos de segurança. É possível pesquisar determinado usuário ou grupo e selecionar vários usuários e grupos que aparecem na lista. Escolha o botão Selecionar para continuar.
9. Selecione Selecionar uma função no painel Adicionar atribuição. Todas as funções que você definiu para o aplicativo são exibidas.
10. Escolha uma função e selecione o botão Selecionar.
11. Selecione o botão Atribuir para finalizar a atribuição de usuários e grupos para o aplicativo.

Veja se os usuários e grupos que você adicionou aparecem na lista atualizada de Usuários e grupos.

Próximas etapas

Saiba mais sobre as funções de aplicativo com os recursos a seguir.

• Exemplo de código no GitHub
  • Adicionar autorização usando funções de aplicativo e declarações de funções a um aplicativo Web ASP.NET Core
• Documentação de referência
  • Manifesto do aplicativo do Microsoft Entra
• Vídeo: Implementar a autorização em seus aplicativos com a plataforma de identidade da Microsoft (1:01:15)