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 grupos do Microsoft Entra e declarações de grupo, conforme mostrado na amostra de código 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 funções de aplicativo 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, a ID do Microsoft Entra emite uma roles declaração para cada função concedida ao usuário ou entidade de serviço, que pode ser usada para implementar a autorização baseada em declaração. As funções de aplicativo podem ser atribuídas a um usuário ou a um grupo de usuários. As funções de aplicativo também podem ser atribuídas à entidade de serviço de 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 obter informações sobre esses limites, consulte a seção Limites de manifesto da referência de manifesto do aplicativo Microsoft Entra.

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

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 um Administrador de Aplicativos na 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éregistros do aplicativo> e selecione o aplicativo no qual você deseja definir funções de aplicativo.

4. Em Gerenciamento, selecione Funções de aplicativo e, em seguida, selecione Criar função de aplicativo.

   

5. No painel Criar função de aplicativo , insira as configurações da 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ível para applications, as funções de aplicativo aparecem como permissões de aplicativo na seção Gerenciar do registro de aplicativo >Permissões da 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 essa 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 suas alterações.

Quando a função de aplicativo é definida como Habilitada, todos os usuários, aplicativos ou grupos atribuídos 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.

Quando a função de aplicativo é definida como Desabilitada, ela se torna inativa e não é mais atribuível. No entanto, as atribuições de função de aplicativo atuais para usuários, grupos e aplicativos permanecerão e a função de aplicativo continuará a passar os tokens. Remova a função de aplicativo do usuário, grupo ou aplicativo para garantir que a função de aplicativo também seja removida dos tokens.

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 donos 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 programaticamente usando o Microsoft Graph. A atribuição de uma função de aplicativo a um aplicativo não deve ser confundida com a atribuição de funções aos 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 um Administrador de Aplicativos na Nuvem.
2. Navegue até Entra ID>registros do aplicativo e selecione Todos os aplicativos.
3. Selecione Todos os aplicativos para exibir uma lista de 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 role para baixo na lista para localizar seu aplicativo.
4. Selecione o aplicativo ao qual você deseja atribuir uma função de aplicativo.
5. Selecione permissões> de APIAdicionar uma permissão.
6. Selecione a guia Minhas APIs e selecione o aplicativo para o qual você definiu as 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 recém-adicionadas 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, não permissões delegadas, um administrador deve conceder consentimento para usar as funções de aplicativo atribuídas ao aplicativo.

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

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

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

Se você estiver implementando a lógica de negócios de funções de aplicativo que faz login dos 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 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 à sua API Web, consulte 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

Depois de adicionar funções de aplicativo em seu aplicativo, você pode atribuir usuários e grupos às 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 programaticamente 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 um Administrador de Aplicativos na 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é aplicativos Entra ID>Enterprise.
4. Selecione Todos os aplicativos para exibir uma lista de 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 role para baixo na 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. Selecione o seletor usuários e grupos no 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. Selecione 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 clique no botão Selecionar.
11. Selecione o botão Atribuir para concluir a atribuição de usuários e grupos ao aplicativo.

Confirme se os usuários e grupos adicionados aparecem na lista 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 app Microsoft Entra
• Vídeo: Implementar autorização em seus aplicativos com a plataforma de identidade da Microsoft (1:01:15)