Adicionar funções de aplicação à aplicação e recebê-las no token

O controle de acesso baseado em função (RBAC) é um mecanismo popular 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 funções de aplicativo e declarações de função, os desenvolvedores podem impor a autorização com segurança em seus aplicativos com menos esforço.

Outra abordagem é usar grupos do Microsoft Entra e declarações de grupo, conforme mostrado no exemplo de código active-directory-aspnetcore-webapp-openidconnect-v2 no GitHub. Os grupos e funções de aplicativo do Microsoft Entra não são mutuamente exclusivos; eles podem ser usados juntos para fornecer um controle de acesso ainda mais refinado.

Declarar funções para um aplicativo

Você define as funções do aplicativo usando o centro de administração do Microsoft Entra durante o processo de registro do aplicativo. As funções de aplicação são definidas num registo de aplicação e representam um serviço, uma aplicação ou uma API. Quando um usuário entra no aplicativo, o ID do Microsoft Entra emite uma roles declaração para cada função que o usuário ou entidade de serviço recebeu, que pode ser usada para implementar a autorização baseada em declaração. As funções do 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 para outro aplicativo ou à entidade de serviço para uma identidade gerenciada.

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

As funções de aplicativo são declaradas usando a interface do usuário de funções de aplicativo no centro de administração do Microsoft Entra:

O número de funções adicionadas conta para os limites de manifesto do aplicativo impostos pela ID do Microsoft Entra. 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 de funções do 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 de aplicativo de aplicativos>de identidade>e selecione o aplicativo no qual você deseja definir funções de aplicativo.

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

   

5. No painel Criar função de aplicação, introduza as definições da função. A tabela a seguir à imagem descreve cada configuração e seus parâmetros.

   

   Campo	Description	Exemplo
   Nome a apresentar	Nome para exibição da função de aplicativo que aparece nas experiências de consentimento de administrador e atribuição de aplicativo. Este valor pode conter espaços.	Survey Writer
   Tipos de membros 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 do aplicativo aparecem como permissões de aplicativo na seção Gerenciar permissões >> da API de um registro de aplicativo Adicionar uma permissão > Minhas APIs > Escolha 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 do aplicativo exibida durante as experiências de atribuição e consentimento do aplicativo de administrador.	Writers can create surveys.
   Deseja habilitar essa função de aplicativo?	Especifica se a função do 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 do aplicativo enquanto pode desativá-la temporária ou permanentemente sem removê-la completamente.	Verificada

6. Selecione Aplicar para guardar as 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. Estes podem ser tokens de acesso quando a sua aplicação é a API que está a ser chamada por uma aplicação ou tokens de ID quando a sua aplicação está a iniciar sessão num utilizador. Se definido como desativado, ele se torna inativo e não pode mais ser atribuível. Todos os cessionários anteriores mantêm a função de aplicativo incluída em seus tokens, mas ela não tem efeito, pois ela não é mais ativamente atribuível.

Atribuir proprietário do aplicativo

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

1. No registo da sua aplicação, em Gerir, selecione Proprietários e Adicionar proprietários.
2. Na nova janela, localize e selecione o(s) proprietário(s) que deseja atribuir ao aplicativo. Os proprietários selecionados aparecem no painel direito. Uma vez feito, confirme com Select e o(s) proprietário(s) do aplicativo aparecerão na lista do proprietário.

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. Geralmente, as permissões de aplicação são utilizadas por aplicações daemon ou serviços de back-end que precisam de autenticar e fazer chamadas à API autorizadas como elas próprias, sem a interação de um utilizador.

Para atribuir funções de aplicativo a um aplicativo 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. Navegue até Registros de aplicativos de identidade>>e selecione Todos os aplicativos.
3. Selecione Todas as aplicações para ver uma lista de todas as aplicações. Se a aplicação não aparecer na lista, utilize os filtros na parte superior da lista Todas as aplicações para restringir a lista ou desloque-se para baixo para localizar a aplicação.
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 deseja atribuir.
8. Selecione o botão Adicionar permissões para completar a adição das funções.

As funções recém-adicionadas devem aparecer no painel de permissões da API de registro do aplicativo.

Conceder consentimento do administrador

Uma vez que estas são permissões de aplicação, e não permissões delegadas, um administrador tem de dar consentimento para utilizar as funções de aplicação atribuídas à aplicação.

1. No painel de permissões da API de registro do aplicativo, selecione Conceder consentimento de 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 da função de aplicativo que entra nos usuários em seu cenário de aplicativo, primeiro defina as funções do aplicativo em Registros de aplicativo. Em seguida, um administrador os atribui a usuários e grupos no painel Aplicativos corporativos. Dependendo do cenário, essas funções de aplicativo atribuídas são incluídas em tokens diferentes emitidos para seu aplicativo. Por exemplo, para um aplicativo que entra em usuários, as declarações de funções são incluídas no token de ID. Quando seu aplicativo chama uma API, as declarações de funções são incluídas no token de acesso.

Se estiver a implementar lógica de negócio da função de aplicação num cenário de API de chamada de aplicação, terá dois registos de aplicação. Um registro de aplicativo é para o aplicativo e um segundo registro de aplicativo é para a API. Neste caso, defina as funções da aplicação e atribua-as ao utilizador ou grupo no registo de aplicação da API. Quando o utilizador se autentica com a aplicação e pede um token de acesso para chamar a API, é incluída uma afirmação de funções no token. Sua próxima etapa é adicionar código à sua API da Web para verificar essas funções quando a API for chamada.

Para saber como adicionar autorização à sua API da Web, consulte API da Web protegida: verificar escopos e funções do aplicativo.

Funções do aplicativo vs. grupos

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

Os programadores podem utilizar funções de aplicação para controlar se um utilizador pode iniciar sessão numa aplicação ou se uma aplicação pode obter um token de acesso para uma API Web. Para alargar este controlo de segurança a grupos, os programadores e administradores também podem atribuir grupos de segurança a funções de aplicações.

Os desenvolvedores preferem usar funções de aplicativo quando desejam descrever e controlar os parâmetros de autorização em seu próprio aplicativo. Por exemplo, um aplicativo que usa grupos para autorização será interrompido no próximo locatário, pois o ID e o nome do grupo podem ser diferentes. Um aplicativo que usa funções de aplicativo permanece seguro. Na verdade, os aplicativos SaaS geralmente atribuem grupos a funções de aplicativo pelos mesmos motivos, pois permitem 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 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 programaticamente usando o Microsoft Graph. Quando os usuários atribuídos às várias funções entram no aplicativo, seus tokens têm as funções atribuídas na roles declaração.

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 de identidade>>Aplicativos corporativos.
4. Selecione Todas as aplicações para ver uma lista de todas as aplicações. Se a aplicação não aparecer na lista, utilize os filtros na parte superior da lista Todas as aplicações para restringir a lista ou desloque-se para baixo para localizar a aplicação.
5. Selecione a aplicação na qual quer atribuir utilizadores ou grupos de segurança a funções.
6. Em Gerir, selecione Utilizadores e grupos.
7. Selecione Adicionar utilizador para abrir o painel Adicionar Atribuição.
8. Selecione o seletor Utilizadores e grupos no painel Adicionar Atribuição. É apresentada uma lista de utilizadores e grupos de segurança. Pode procurar um determinado utilizador ou grupo e selecionar vários utilizadores e grupos que apareçam 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 selecione o botão Selecionar.
11. Selecione o botão Atribuir para concluir a atribuição de utilizadores e grupos à aplicação.

Confirme se os usuários e grupos adicionados aparecem na lista Usuários e grupos .

Próximos passos

Saiba mais sobre as funções do aplicativo com os seguintes recursos.

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