Como: Adicionar funções de aplicação à sua aplicação e recebê-las no tokenHow to: Add app roles to your application and receive them in the token

O controlo de acesso baseado em funções (RBAC) é um mecanismo popular para impor a autorização em aplicações.Role-based access control (RBAC) is a popular mechanism to enforce authorization in applications. Ao utilizar o RBAC, um administrador concede permissões a funções e não a utilizadores ou grupos individuais.When using RBAC, an administrator grants permissions to roles, and not to individual users or groups. O administrador pode então atribuir funções a diferentes utilizadores e grupos para controlar quem tem acesso a que conteúdo e funcionalidade.The administrator can then assign roles to different users and groups to control who has access to what content and functionality.

Utilizando o RBAC com Funções de Aplicação e Reivindicações de Funções, os desenvolvedores podem impor de forma segura a autorização nas suas apps com menos esforço.Using RBAC with Application Roles and Role Claims, developers can securely enforce authorization in their apps with less effort.

Outra abordagem é utilizar os grupos AD E as Reivindicações de Grupo Azure, como mostrado na amostra de código activa-aspnetcore-webapp-openidconnect-v2 no GitHub.Another approach is to use Azure AD Groups and Group Claims as shown in the active-directory-aspnetcore-webapp-openidconnect-v2 code sample on GitHub. Os grupos AD Azure e as Funções de Aplicação não são mutuamente exclusivos; podem ser usados em conjunto para fornecer um controlo de acesso ainda mais fino.Azure AD Groups and Application Roles are not mutually exclusive; they can be used in tandem to provide even finer-grained access control.

Declarar funções para uma aplicaçãoDeclare roles for an application

Define as funções de aplicação utilizando o portal Azure.You define app roles by using the Azure portal. As funções de aplicação são geralmente definidas num registo de aplicação representando um serviço, app ou API.App roles are usually defined on an application registration representing a service, app or API. Quando um utilizador assina a aplicação, a Azure AD emite uma roles reclamação por cada papel que o utilizador ou titular do serviço foi concedido individualmente ao utilizador e da sua filiação em grupo.When a user signs in to the application, Azure AD emits a roles claim for each role that the user or service principal has been granted individually to the user and from their group membership. Isto pode ser usado para implementar uma autorização baseada em sinistros.This can be used to implement claim-based authorization. As funções da aplicação podem ser atribuídas a um utilizador ou a um grupo de utilizadores.App roles can be assigned to a user or a group of users. As funções da app também podem ser atribuídas ao principal do serviço para outra aplicação, ou ao principal do serviço para uma identidade gerida.App roles can also be assigned to the service principal for another application, or to the service principal for a managed identity.

Importante

Atualmente, se adicionar um principal de serviço a um grupo e, em seguida, atribuir um papel de app a esse grupo, a Azure AD não adiciona a roles alegação aos tokens que problema.Currently if you add a service principal to a group, and then assign an app role to that group, Azure AD does not add the roles claim to tokens it issues.

Existem duas formas de declarar os papéis da aplicação utilizando o portal Azure:There are two ways to declare app roles by using the Azure portal:

O número de funções que adiciona conta para os limites manifestos de aplicação imposto pelo Azure Ative Directory.The number of roles you add counts toward application manifest limits enforced by Azure Active Directory. Para obter informações sobre estes limites, consulte a secção Desproteturas da aplicação Azure Ative Directory.For information about these limits, see the Manifest limits section of Azure Active Directory app manifest reference.

Funções de aplicativo UI | previsualizarApp roles UI | Preview

Importante

A funcionalidade UI do portal de funções de aplicativos está em pré-visualização pública.is in public preview. Esta pré-visualização é fornecida sem um acordo de nível de serviço e não é recomendada para cargas de trabalho de produção.This preview is provided without a service-level agreement and isn't recommended for production workloads. Algumas funcionalidades podem não ser suportadas ou ter capacidades restritas.Some features might be unsupported or have constrained capabilities. Para obter mais informações, consulte termos de utilização suplementares para pré-visualizações do Microsoft Azure.For more information, see Supplemental terms of use for Microsoft Azure previews.The app roles portal UI feature está em pré-visualização pública.is in public preview. Esta pré-visualização é fornecida sem um acordo de nível de serviço e não é recomendada para cargas de trabalho de produção.This preview is provided without a service-level agreement and isn't recommended for production workloads. Algumas funcionalidades podem não ser suportadas ou ter capacidades restritas.Some features might be unsupported or have constrained capabilities. Para obter mais informações, consulte termos de utilização suplementares para pré-visualizações do Microsoft Azure.For more information, see Supplemental terms of use for Microsoft Azure previews.

Para criar uma função de aplicação utilizando a interface de utilizador do portal Azure:To create an app role by using the Azure portal's user interface:

  1. Inicie sessão no portal do Azure.Sign in to the Azure portal.

  2. Selecione o filtro de subscrição Directory + no menu superior e, em seguida, escolha o inquilino do Azure Ative Directory que contém o registo da aplicação ao qual pretende adicionar uma função de app.Select the Directory + subscription filter in top menu, and then choose the Azure Active Directory tenant that contains the app registration to which you want to add an app role.

  3. Procure e selecione Azure Active Directory.Search for and select Azure Active Directory.

  4. Em Manage, selecione registos de Aplicações e, em seguida, selecione a aplicação em que pretende definir funções de aplicação.Under Manage, select App registrations, and then select the application you want to define app roles in.

  5. Selecione funções de aplicação | Pré-visualizar e, em seguida, selecionar Criar o papel da aplicação.Select App roles | Preview, and then select Create app role.

    Um painel de funções de aplicação de registo de aplicações no portal Azure

  6. No painel de funções da aplicação Create, introduza as definições para o papel.In the Create app role pane, enter the settings for the role. A tabela que segue a imagem descreve cada definição e os seus parâmetros.The table following the image describes each setting and their parameters.

    As funções de aplicação de um registo de aplicações criam um painel de contexto no portal Azure

    CampoField DescriçãoDescription ExemploExample
    Nome a apresentarDisplay name Mostrar o nome para o papel da aplicação que aparece nas experiências de consentimento de administração e atribuição de aplicações.Display name for the app role that appears in the admin consent and app assignment experiences. Este valor pode conter espaços.This value may contain spaces. Survey Writer
    Tipos de membros permitidosAllowed member types Especifica se esta função da app pode ser atribuída a utilizadores, aplicações ou ambos.Specifies whether this app role can be assigned to users, applications, or both.

    Quando disponível para applications , as funções da aplicação aparecem como permissões de aplicação na secção de Gestão de uma aplicação > permissões de API > Adicionar uma permissão > As minhas APIs > Escolha uma API > Permissões de Aplicação.When available to applications, app roles appear as application permissions in an app registration's Manage section > API permissions > Add a permission > My APIs > Choose an API > Application permissions.
    Users/Groups
    ValorValue Especifica o valor das funções alegando que a aplicação deve esperar no token.Specifies the value of the roles claim that the application should expect in the token. O valor deve corresponder exatamente à cadeia referenciada no código da aplicação.The value should exactly match the string referenced in the application's code. O valor não pode conter espaços.The value cannot contain spaces. Survey.Create
    DescriçãoDescription Uma descrição mais detalhada da função da aplicação exibida durante a atribuição de aplicações de administração e experiências de consentimento.A more detailed description of the app role displayed during admin app assignment and consent experiences. Writers can create surveys.
    Deseja ativar esta função de aplicação?Do you want to enable this app role? Especifica se a função da aplicação está ativada.Specifies whether the app role is enabled. Para eliminar uma função de aplicação, desmarcar esta caixa de verificação e aplicar a alteração antes de tentar a operação de eliminação.To delete an app role, deselect this checkbox and apply the change before attempting the delete operation. VerificadoChecked
  7. Selecione Aplicar para guardar as alterações.Select Apply to save your changes.

Editor manifesto de aplicativoApp manifest editor

Para adicionar papéis editando o manifesto diretamente:To add roles by editing the manifest directly:

  1. Inicie sessão no portal do Azure.Sign in to the Azure portal.
  2. Selecione o filtro de subscrição Directory + no menu superior e, em seguida, escolha o inquilino do Azure Ative Directory que contém o registo da aplicação ao qual pretende adicionar uma função de app.Select the Directory + subscription filter in top menu, and then choose the Azure Active Directory tenant that contains the app registration to which you want to add an app role.
  3. Procure e selecione Azure Active Directory.Search for and select Azure Active Directory.
  4. Em Manage, selecione registos de Aplicações e, em seguida, selecione a aplicação em que pretende definir funções de aplicação.Under Manage, select App registrations, and then select the application you want to define app roles in.
  5. Novamente em Manage, selecione Manifesto.Again under Manage, select Manifest.
  6. Edite o manifesto da aplicação localizando a appRoles definição e adicionando as suas funções de aplicação.Edit the app manifest by locating the appRoles setting and adding your application roles. Pode definir funções de aplicativo que users applications visam, ou ambos.You can define app roles that target users, applications, or both. Os seguintes snippets JSON mostram exemplos de ambos.The following JSON snippets show examples of both.
  7. Salve o manifesto.Save the manifest.

Cada definição de função de aplicação no manifesto deve ter um GUID único para o seu id valor.Each app role definition in the manifest must have a unique GUID for its id value.

A value propriedade de cada definição de função da aplicação deve corresponder exatamente às cordas que são usadas no código na aplicação.The value property of each app role definition should exactly match the strings that are used in the code in the application. A value propriedade não pode conter espaços.The value property can't contain spaces. Se isso acontecer, receberá um erro quando guardar o manifesto.If it does, you'll receive an error when you save the manifest.

Exemplo: Função de aplicativo de utilizadorExample: User app role

Este exemplo define uma função de aplicação nomeada Writer que pode atribuir User a:This example defines an app role named Writer that you can assign to a User:

"appId": "8763f1c4-0000-0000-0000-158e9ef97d6a",
"appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "displayName": "Writer",
      "id": "d1c2ade8-0000-0000-0000-6d06b947c66f",
      "isEnabled": true,
      "description": "Writers Have the ability to create tasks.",
      "value": "Writer"
    }
  ],
"availableToOtherTenants": false,

Exemplo: Função de aplicação de aplicação de aplicação de aplicaçõesExample: Application app role

Quando disponível para applications , as funções da aplicação aparecem como permissões de aplicação na secção de Gestão de uma aplicação > permissões de API > Adicionar uma permissão > As minhas APIs > Escolha uma API > Permissões de Aplicação.When available to applications, app roles appear as application permissions in an app registration's Manage section > API permissions > Add a permission > My APIs > Choose an API > Application permissions.

Este exemplo mostra uma função de aplicação direcionada Application a:This example shows an app role targeted to an Application:

"appId": "8763f1c4-0000-0000-0000-158e9ef97d6a",
"appRoles": [
    {
      "allowedMemberTypes": [
        "Application"
      ],
      "displayName": "ConsumerApps",
      "id": "47fbb575-0000-0000-0000-0f7a6c30beac",
      "isEnabled": true,
      "description": "Consumer apps have access to the consumer data.",
      "value": "Consumer"
    }
  ],
"availableToOtherTenants": false,

Atribuir utilizadores e grupos a funçõesAssign users and groups to roles

Uma vez adicionadas funções de aplicação na sua aplicação, pode atribuir utilizadores e grupos às funções.Once you've added app roles in your application, you can assign users and groups to the roles. A atribuição de utilizadores e grupos a funções pode ser feita através da UI do portal, ou utilizando programáticamente o Microsoft Graph.Assignment of users and groups to roles can be done through the portal's UI, or programmatically using Microsoft Graph. Quando os utilizadores atribuídos às várias funções da aplicação iniciarem o sessão na aplicação, os seus tokens terão as suas funções atribuídas na roles reclamação.When the users assigned to the various app roles sign in to the application, their tokens will have their assigned roles in the roles claim.

Para atribuir utilizadores e grupos a funções utilizando o portal Azure:To assign users and groups to roles by using the Azure portal:

  1. Inicie sessão no portal do Azure.Sign in to the Azure portal.
  2. No Azure Ative Directory, selecione aplicações Enterprise no menu de navegação à esquerda.In Azure Active Directory, select Enterprise applications in the left-hand navigation menu.
  3. Selecione Todas as aplicações para ver uma lista de todas as suas aplicações.Select All applications to view a list of all your applications. Se a sua aplicação não aparecer na lista, utilize os filtros no topo da lista de aplicações para restringir a lista, ou desloque a lista para localizar a sua aplicação.If your application doesn't appear in the list, use the filters at the top of the All applications list to restrict the list, or scroll down the list to locate your application.
  4. Selecione a aplicação na qual pretende atribuir utilizadores ou grupo de segurança a funções.Select the application in which you want to assign users or security group to roles.
  5. Em Gerir, selecione Utilizadores e grupos.Under Manage, select Users and groups.
  6. Selecione Adicionar ao utilizador para abrir o painel de atribuição de adicionar.Select Add user to open the Add Assignment pane.
  7. Selecione o seletor de Utilizadores e grupos a partir do painel de atribuição de adicionar.Select the Users and groups selector from the Add Assignment pane. É apresentada uma lista de utilizadores e grupos de segurança.A list of users and security groups is displayed. Pode pesquisar por um determinado utilizador ou grupo, bem como selecionar vários utilizadores e grupos que aparecem na lista.You can search for a certain user or group as well as select multiple users and groups that appear in the list.
  8. Uma vez selecionados utilizadores e grupos, selecione o botão Select para proceder.Once you've selected users and groups, select the Select button to proceed.
  9. Selecione Selecionar uma função no painel de atribuição Adicionar.Select Select a role in the Add assignment pane. Todos os papéis que definiu para a aplicação são apresentados.All the roles that you've defined for the application are displayed.
  10. Escolha uma função e selecione o botão Select.Choose a role and select the Select button.
  11. Selecione o botão Atribuir para terminar a atribuição de utilizadores e grupos para a aplicação.Select the Assign button to finish the assignment of users and groups to the app.

Confirme que os utilizadores e grupos adicionados aparecem na lista de Utilizadores e grupos.Confirm that the users and groups you added appear in the Users and groups list.

Atribuir funções de aplicações a aplicaçõesAssign app roles to applications

Uma vez adicionados papéis de aplicação na sua aplicação, pode atribuir um papel de aplicação a uma aplicação de clientes utilizando o portal Azure ou programáticamente utilizando o Microsoft Graph.Once you've added app roles in your application, you can assign an app role to a client app by using the Azure portal or programmatically by using Microsoft Graph.

Quando atribui funções de aplicação a uma aplicação, cria permissões de aplicação.When you assign app roles to an application, you create application permissions. As permissões de aplicação são normalmente utilizadas por apps daemon ou serviços de back-end que precisam de autenticar e fazer chamadas autorizadas de API como si mesmos, sem a interação de um utilizador.Application permissions are typically used by daemon apps or back-end services that need to authenticate and make authorized API calls as themselves, without the interaction of a user.

Para atribuir funções de aplicação a uma aplicação utilizando o portal Azure:To assign app roles to an application by using the Azure portal:

  1. Inicie sessão no portal do Azure.Sign in to the Azure portal.
  2. No Azure Ative Directory, selecione registos de Aplicações no menu de navegação à esquerda.In Azure Active Directory, select App registrations in the left-hand navigation menu.
  3. Selecione Todas as aplicações para ver uma lista de todas as suas aplicações.Select All applications to view a list of all your applications. Se a sua aplicação não aparecer na lista, utilize os filtros no topo da lista de aplicações para restringir a lista, ou desloque a lista para localizar a sua aplicação.If your application doesn't appear in the list, use the filters at the top of the All applications list to restrict the list, or scroll down the list to locate your application.
  4. Selecione a aplicação à qual pretende atribuir uma função de aplicação.Select the application to which you want to assign an app role.
  5. Selecione permissões API > Adicione uma permissão.Select API permissions > Add a permission.
  6. Selecione o separador My APIs e, em seguida, selecione a aplicação para a qual definiu as funções da aplicação.Select the My APIs tab, and then select the app for which you defined app roles.
  7. Selecione permissões de aplicação.Select Application permissions.
  8. Selecione as funções que pretende atribuir.Select the role(s) you want to assign.
  9. Selecione o botão adicionar permissões completa adição da(s) função.Select the Add permissions button complete addition of the role(s).

As funções recém-adicionadas devem aparecer no painel de permissões API do seu registo de aplicações.The newly added roles should appear in your app registration's API permissions pane.

Como se trata de permissões de aplicação, não permissões delegadas, um administrador deve conceder o consentimento para usar as funções da aplicação atribuídas à aplicação.Because these are application permissions, not delegated permissions, an admin must grant consent to use the app roles assigned to the application.

  1. No painel de permissões de API do registo da aplicação, selecione o consentimento de administração grant para <tenant name>.In the app registration's API permissions pane, select Grant admin consent for <tenant name>.
  2. Selecione Sim quando solicitado para conceder o consentimento para as permissões solicitadas.Select Yes when prompted to grant consent for the requested permissions.

A coluna status deve refletir que o consentimento foi concedido para <tenant name>.The Status column should reflect that consent has been Granted for <tenant name>.

Use funções de aplicativo na sua API webUse app roles in your web API

Uma vez definidas as funções da aplicação e as atribuiu a um utilizador, grupo ou aplicação, o seu próximo passo é adicionar código à sua API web que verifica essas funções quando a API é chamada.Once you've defined app roles and assigned them to a user, group, or application, your next step is to add code to your web API that checks for those roles when the API is called. Ou seja, quando uma aplicação de clientes solicita uma operação API que decidiu necessitar de autorização, o código da API deve verificar se os âmbitos estão no token de acesso apresentado na chamada da app do cliente.That is, when a client app requests an API operation you've decided requires authorization, your API's code must verify the scopes are in the access token presented in the client app's call.

Para aprender a adicionar autorização à sua API web, consulte a API web protegida: Verifique os âmbitos e as funções de aplicação.To learn how to add authorization to your web API, see Protected web API: Verify scopes and app roles.

Funções de aplicativo vs gruposApp roles vs. groups

Embora possa utilizar funções de aplicações ou grupos para autorização, as principais diferenças entre elas podem influenciar as quais decide usar para o seu cenário.Though you can use app roles or groups for authorization, key differences between them can influence which you decide to use for your scenario.

Funções de aplicativoApp roles GruposGroups
São específicos de uma aplicação e são definidos no registo da aplicação.They are specific to an application and are defined in the app registration. Eles movem-se com a aplicação.They move with the application. Não são específicos de uma aplicação, mas de um inquilino da AD Azure.They are not specific to an app, but to an Azure AD tenant.
As funções da aplicação são removidas quando o registo da aplicação é removido.App roles are removed when their app registration is removed. Os grupos permanecem intactos mesmo que a aplicação seja removida.Groups remain intact even if the app is removed.
Fornecido no roles pedido.Provided in the roles claim. Fornecido em groups reclamação.Provided in groups claim.

Os desenvolvedores podem usar as funções de aplicação para controlar se um utilizador pode iniciar sôm numa aplicação ou uma aplicação pode obter um token de acesso para uma API web.Developers can use app roles to control whether a user can sign in to an app or an app can obtain an access token for a web API. Para alargar este controlo de segurança a grupos, os desenvolvedores e administradores também podem atribuir grupos de segurança a funções de aplicações.To extend this security control to groups, developers and admins can also assign security groups to app roles.

As funções de aplicação são preferidas pelos desenvolvedores quando querem descrever e controlar os parâmetros de autorização na sua própria app.App roles are preferred by developers when they want to describe and control the parameters of authorization in their app themselves. Por exemplo, uma aplicação que usa grupos para autorização irá quebrar o próximo inquilino, uma vez que tanto o ID do grupo como o nome poderiam ser diferentes.For example, an app using groups for authorization will break in the next tenant as both the group ID and name could be different. Uma aplicação que usa funções de aplicativo permanece segura.An app using app roles remains safe. Na verdade, atribuir grupos a funções de apps é popular entre as aplicações do SaaS pelas mesmas razões.In fact, assigning groups to app roles is popular with SaaS apps for the same reasons.

Passos seguintesNext steps

Saiba mais sobre funções de aplicativos com os seguintes recursos.Learn more about app roles with the following resources.