Procedimiento: Incorporación de roles de aplicación a una aplicación y su recepción en el tokenHow to: Add app roles to your application and receive them in the token

El control de acceso basado en rol (RBAC) es un mecanismo popular para exigir la autorización en las aplicaciones.Role-based access control (RBAC) is a popular mechanism to enforce authorization in applications. Cuando se usa RBAC, un administrador concede permisos a roles y no a usuarios individuales o grupos.When using RBAC, an administrator grants permissions to roles, and not to individual users or groups. El administrador, a continuación, puede asignar roles a diferentes usuarios y grupos para controlar quién tiene acceso a qué contenido y funcionalidad.The administrator can then assign roles to different users and groups to control who has access to what content and functionality.

Mediante el uso de RBAC con roles de aplicación y notificaciones de rol, los desarrolladores pueden exigir de forma segura la autorización en las aplicaciones con menos esfuerzo.Using RBAC with Application Roles and Role Claims, developers can securely enforce authorization in their apps with less effort.

Otro enfoque consiste en usar grupos de Azure AD y notificaciones de grupo, como se muestra en el ejemplo de código active-directory-aspnetcore-webapp-openidconnect-v2 en 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. Los grupos de Azure AD y los roles de aplicación no son mutuamente excluyentes y se pueden usar en conjunto para proporcionar un control de acceso aún más preciso.Azure AD Groups and Application Roles are not mutually exclusive; they can be used in tandem to provide even finer-grained access control.

Declaración de roles para una aplicaciónDeclare roles for an application

Los roles de aplicación se definen en Azure Portal.You define app roles by using the Azure portal. Los roles de aplicación se definen normalmente en un registro de aplicación que representa un servicio, una aplicación o una API.App roles are usually defined on an application registration representing a service, app or API. Cuando un usuario inicia sesión en la aplicación, Azure AD emite una notificación roles por cada rol que se ha concedido al usuario o entidad de servicio de manera individual y por su pertenencia a grupos.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. Se puede usar para implementar una autorización basada en notificaciones.This can be used to implement claim-based authorization. Los roles de aplicación se pueden asignar a un usuario o a un grupo de usuarios.App roles can be assigned to a user or a group of users. Los roles de aplicación también se pueden asignar a la entidad de servicio de otra aplicación o a la entidad de servicio de una identidad administrada.App roles can also be assigned to the service principal for another application, or to the service principal for a managed identity.

Importante

Actualmente, si agrega una entidad de servicio a un grupo y, a continuación, asigna un rol de aplicación a ese grupo, Azure AD no agrega la notificación roles a los tokens que emite.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.

Hay dos maneras de declarar los roles de aplicación mediante Azure Portal:There are two ways to declare app roles by using the Azure portal:

La cantidad de roles que agrega está restringida por los límites de los manifiestos de la aplicación que impone Azure Active Directory.The number of roles you add counts toward application manifest limits enforced by Azure Active Directory. Para obtener información sobre estos límites, consulte la sección Límites de manifiesto de la referencia del manifiesto de aplicación de Azure Active Directory.For information about these limits, see the Manifest limits section of Azure Active Directory app manifest reference.

Interfaz de usuario de roles de aplicación | Versión preliminarApp roles UI | Preview

Importante

La característica de interfaz de usuario del portal de roles de aplicación está en versión preliminar pública.is in public preview. Esta versión preliminar se ofrece sin contrato de nivel de servicio y no es aconsejable usarla en las cargas de trabajo de producción.This preview is provided without a service-level agreement and isn't recommended for production workloads. Es posible que algunas características no sean compatibles o que tengan funcionalidades limitadas.Some features might be unsupported or have constrained capabilities. Para obtener más información, consulte Términos de uso complementarios de las Versiones preliminares de Microsoft Azure.For more information, see Supplemental terms of use for Microsoft Azure previews.The app roles portal UI feature está en versión preliminar pública.is in public preview. Esta versión preliminar se ofrece sin contrato de nivel de servicio y no es aconsejable usarla en las cargas de trabajo de producción.This preview is provided without a service-level agreement and isn't recommended for production workloads. Es posible que algunas características no sean compatibles o que tengan funcionalidades limitadas.Some features might be unsupported or have constrained capabilities. Para obtener más información, consulte Términos de uso complementarios de las Versiones preliminares de Microsoft Azure.For more information, see Supplemental terms of use for Microsoft Azure previews.

Para crear un rol de aplicación con la interfaz de usuario de Azure Portal:To create an app role by using the Azure portal's user interface:

  1. Inicie sesión en Azure Portal.Sign in to the Azure portal.

  2. En el menú superior, seleccione el filtro Directorio + suscripción y, a continuación, elija el inquilino de Azure Active Directory que contiene el registro de la aplicación al que desea agregar un rol de aplicación.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. Busque y seleccione Azure Active Directory.Search for and select Azure Active Directory.

  4. En Administrar, seleccione Registros de aplicaciones y, a continuación, seleccione la aplicación en la que desea definir los roles de aplicación.Under Manage, select App registrations, and then select the application you want to define app roles in.

  5. Seleccione Roles de aplicación | Versión preliminar y, a continuación, seleccione Crear rol de aplicación.Select App roles | Preview, and then select Create app role.

    Panel de roles de aplicación durante el registro de una aplicación en Azure Portal

  6. En el panel Crear rol de aplicación, escriba la configuración del rol.In the Create app role pane, enter the settings for the role. La tabla que sigue a la imagen describe cada configuración y sus parámetros.The table following the image describes each setting and their parameters.

    Panel contextual de creación de roles de aplicación durante el registro de una aplicación en Azure Portal

    CampoField DescripciónDescription EjemploExample
    Nombre para mostrarDisplay name Nombre para mostrar para el rol de aplicación que aparece en las experiencias de asignación de la aplicación y de consentimiento del administrador.Display name for the app role that appears in the admin consent and app assignment experiences. Este valor puede incluir espacios.This value may contain spaces. Survey Writer
    Tipos de miembros permitidoAllowed member types Especifica si este rol de aplicación puede asignarse a usuarios, aplicaciones o ambos.Specifies whether this app role can be assigned to users, applications, or both.

    Cuando está disponible para applications, los roles de aplicación aparecen como permisos de aplicación en la sección Administrar > Permisos de API > Agregar un permiso > Mis API > Elegir una API > Permisos de la aplicación de un registro de aplicación.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 el valor de la notificación de roles que debería esperar la aplicación en los tokens de acceso y autenticación.Specifies the value of the roles claim that the application should expect in the token. El valor debe coincidir exactamente con la cadena a la que se hace referencia en el código de la aplicación.The value should exactly match the string referenced in the application's code. El valor no puede contener espacios.The value cannot contain spaces. Survey.Create
    DescripciónDescription Una descripción más detallada del rol de aplicación que se muestra durante la asignación de aplicaciones de administración y las experiencias de consentimiento.A more detailed description of the app role displayed during admin app assignment and consent experiences. Writers can create surveys.
    ¿Quiere habilitar este rol de aplicación?Do you want to enable this app role? Especifica si está habilitado el rol de aplicación.Specifies whether the app role is enabled. Para eliminar un rol de aplicación, desactive esta casilla y aplique el cambio antes de intentar la operación de eliminación.To delete an app role, deselect this checkbox and apply the change before attempting the delete operation. ActivadaChecked
  7. Seleccione Aplicar para guardar los cambios.Select Apply to save your changes.

Editor de manifiestos de la aplicaciónApp manifest editor

Para agregar roles mediante la edición directa del manifiesto:To add roles by editing the manifest directly:

  1. Inicie sesión en Azure Portal.Sign in to the Azure portal.
  2. En el menú superior, seleccione el filtro Directorio + suscripción y, a continuación, elija el inquilino de Azure Active Directory que contiene el registro de la aplicación al que desea agregar un rol de aplicación.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. Busque y seleccione Azure Active Directory.Search for and select Azure Active Directory.
  4. En Administrar, seleccione Registros de aplicaciones y, a continuación, seleccione la aplicación en la que desea definir los roles de aplicación.Under Manage, select App registrations, and then select the application you want to define app roles in.
  5. Nuevamente en Administrar, seleccione Manifiesto.Again under Manage, select Manifest.
  6. Para editar el manifiesto de la aplicación, localice la opción de configuración appRoles y agregue sus roles de aplicación.Edit the app manifest by locating the appRoles setting and adding your application roles. Puede definir roles de aplicación dirigidos a users, applications o ambos.You can define app roles that target users, applications, or both. Los fragmentos de código JSON siguientes muestran ejemplos de ambas opciones.The following JSON snippets show examples of both.
  7. Guarde el manifiesto.Save the manifest.

Cada definición de rol de aplicación en el manifiesto debe tener un GUID único para su valor id.Each app role definition in the manifest must have a unique GUID for its id value.

La propiedad value de cada definición de rol de la aplicación debe coincidir exactamente con las cadenas que se usan en el código de la aplicación.The value property of each app role definition should exactly match the strings that are used in the code in the application. La propiedad value no puede contener espacios.The value property can't contain spaces. Si es así, recibirá un error al guardar el manifiesto.If it does, you'll receive an error when you save the manifest.

Ejemplo: Rol de aplicación de un usuarioExample: User app role

En este ejemplo se define un rol de aplicación denominado Writer que puede asignar a un User: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,

Ejemplo: Rol de aplicación de una aplicaciónExample: Application app role

Cuando está disponible para applications, los roles de aplicación aparecen como permisos de aplicación en la sección Administrar > Permisos de API > Agregar un permiso > Mis API > Elegir una API > Permisos de la aplicación de un registro de aplicación.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.

En este ejemplo se muestra un rol de aplicación dirigido a una Application: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,

Asignación de usuarios y grupos a rolesAssign users and groups to roles

Una vez que haya agregado los roles de aplicación en la aplicación, puede asignar usuarios y grupos a estos roles.Once you've added app roles in your application, you can assign users and groups to the roles. La asignación de usuarios y grupos a los roles se puede realizar mediante la interfaz de usuario del portal o mediante programación con Microsoft Graph.Assignment of users and groups to roles can be done through the portal's UI, or programmatically using Microsoft Graph. Cuando los usuarios asignados a los distintos roles de aplicación inicien sesión en la aplicación, los tokens tendrán sus roles asignados en la notificación roles.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 asignar usuarios y grupos a roles con Azure Portal:To assign users and groups to roles by using the Azure portal:

  1. Inicie sesión en Azure Portal.Sign in to the Azure portal.
  2. En Azure Active Directory, seleccione Aplicaciones empresariales en el menú de navegación de la izquierda.In Azure Active Directory, select Enterprise applications in the left-hand navigation menu.
  3. Seleccione Todas las aplicaciones para ver una lista de todas las aplicaciones.Select All applications to view a list of all your applications. Si la aplicación no aparece en la lista, use los filtros de la parte superior de la lista Todas las aplicaciones para restringir la lista o desplácese hacia abajo en la lista para localizar la aplicación.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. Seleccione la aplicación en la que desea asignar usuarios o grupos de seguridad a los roles.Select the application in which you want to assign users or security group to roles.
  5. En Administrar, seleccione Usuarios y grupos.Under Manage, select Users and groups.
  6. Seleccione Agregar miembro para abrir el panel Agregar asignación.Select Add user to open the Add Assignment pane.
  7. Seleccione el selector Usuarios y grupos del panel Agregar asignación.Select the Users and groups selector from the Add Assignment pane. Se muestra una lista de usuarios y grupos de seguridad.A list of users and security groups is displayed. Puede buscar un usuario o grupo determinados y seleccionar varios usuarios y grupos que aparecen en la lista.You can search for a certain user or group as well as select multiple users and groups that appear in the list.
  8. Una vez que haya seleccionado usuarios y grupos, seleccione el botón Seleccionar para continuar.Once you've selected users and groups, select the Select button to proceed.
  9. Elija Seleccionar un rol en el panel Agregar asignación.Select Select a role in the Add assignment pane. Se muestran todos los roles que ha definido para la aplicación.All the roles that you've defined for the application are displayed.
  10. Elija un rol y seleccione el botón Seleccionar.Choose a role and select the Select button.
  11. Seleccione el botón Asignar para finalizar las asignaciones de usuarios y grupos a la aplicación.Select the Assign button to finish the assignment of users and groups to the app.

Confirme que los usuarios y grupos que agregó aparecen en la lista Usuarios y grupos.Confirm that the users and groups you added appear in the Users and groups list.

Asignación de roles de aplicación a aplicacionesAssign app roles to applications

Una vez que haya agregado roles de aplicación en la aplicación, puede asignar un rol de aplicación a una aplicación cliente a través de Azure Portal o mediante programación con 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.

Cuando asigna roles de aplicación a una aplicación, crea permisos de aplicación.When you assign app roles to an application, you create application permissions. Los permisos de aplicación se suelen usar en aplicaciones de demonio o servicios de back-end que necesitan autenticarse y hacer llamadas API autorizadas como ellos mismos, sin la interacción de un usuario.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 asignar roles de aplicación a una aplicación mediante Azure Portal:To assign app roles to an application by using the Azure portal:

  1. Inicie sesión en Azure Portal.Sign in to the Azure portal.
  2. En Azure Active Directory, seleccione Registros de aplicaciones en el menú de navegación de la izquierda.In Azure Active Directory, select App registrations in the left-hand navigation menu.
  3. Seleccione Todas las aplicaciones para ver una lista de todas las aplicaciones.Select All applications to view a list of all your applications. Si la aplicación no aparece en la lista, use los filtros de la parte superior de la lista Todas las aplicaciones para restringir la lista o desplácese hacia abajo en la lista para localizar la aplicación.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. Seleccione la aplicación a la que quiera asignar un rol de aplicación.Select the application to which you want to assign an app role.
  5. Seleccione Permisos de API > Agregar un permiso.Select API permissions > Add a permission.
  6. Seleccione la pestaña Mis API y, luego, la aplicación para la que definió los roles de aplicación.Select the My APIs tab, and then select the app for which you defined app roles.
  7. Seleccione Permisos de aplicación.Select Application permissions.
  8. Seleccione los roles que quiere asignar.Select the role(s) you want to assign.
  9. Seleccione el botón Agregar permisos para terminar de agregar los roles.Select the Add permissions button complete addition of the role(s).

Los roles que acaba de agregar debe aparecer en el panel Permisos de API del registro de la aplicación.The newly added roles should appear in your app registration's API permissions pane.

Dado que se trata de permisos de aplicación y no de permisos delegados, un administrador debe dar su consentimiento para usar los roles de aplicación asignados a la aplicación.Because these are application permissions, not delegated permissions, an admin must grant consent to use the app roles assigned to the application.

  1. En el panel Permisos de API del registro de la aplicación, seleccione Conceder consentimiento del administrador para <tenant name> .In the app registration's API permissions pane, select Grant admin consent for <tenant name>.
  2. Seleccione cuando se le pida conceder consentimiento para los permisos solicitados.Select Yes when prompted to grant consent for the requested permissions.

La columna Estado debe reflejar que hay consentimiento Concedido para <tenant name> .The Status column should reflect that consent has been Granted for <tenant name>.

Uso de roles de aplicación en la API webUse app roles in your web API

Una vez que define los roles de aplicación y los asigne a un usuario, grupo o aplicación, el paso siguiente es agregar código a la API web que comprueba esos roles cuando se llama a la API.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. Es decir, cuando una aplicación cliente solicita una operación de API que decidió que requiere autorización, el código de la API debe comprobar que los ámbitos están en el token de acceso que se presenta en la llamada de la aplicación 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 obtener información sobre cómo agregar autorización a la API web, consulte API web protegida: Comprobación de ámbitos y roles de aplicación.To learn how to add authorization to your web API, see Protected web API: Verify scopes and app roles.

Roles de aplicación frente a gruposApp roles vs. groups

Si bien puede usar roles de aplicación o grupos para la autorización, las diferencias clave entre ambos pueden influir en la opción que decida usar para el escenario en cuestión.Though you can use app roles or groups for authorization, key differences between them can influence which you decide to use for your scenario.

Roles de aplicaciónApp roles GruposGroups
Son específicos de una aplicación y se definen en el registro de la aplicación.They are specific to an application and are defined in the app registration. Se mueven con la aplicación.They move with the application. No son específicos de una aplicación, sino de un inquilino de Azure AD.They are not specific to an app, but to an Azure AD tenant.
Los roles de aplicación se quitan cuando se quita el registro de la aplicación.App roles are removed when their app registration is removed. Los grupos permanecen intactos incluso si se quita la aplicación.Groups remain intact even if the app is removed.
Se proporcionan en la notificación roles.Provided in the roles claim. Se proporcionan en la notificación groups.Provided in groups claim.

Los desarrolladores pueden usar los roles de aplicación para controlar si un usuario puede iniciar sesión en una aplicación o si una aplicación puede obtener un token de acceso para una 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 extender este control de seguridad a los grupos, los desarrolladores y administradores también pueden asignar grupos de seguridad a los roles de aplicación.To extend this security control to groups, developers and admins can also assign security groups to app roles.

Los desarrolladores prefieren los roles de aplicación cuando quieren describir y controlar los parámetros de autorización en sus propias aplicaciones.App roles are preferred by developers when they want to describe and control the parameters of authorization in their app themselves. Por ejemplo, una aplicación que usa grupos para la autorización se interrumpirá en el inquilino siguiente, ya que tanto el identificador como el nombre del grupo podrían ser distintos.For example, an app using groups for authorization will break in the next tenant as both the group ID and name could be different. Una aplicación que usa roles de aplicación sigue siendo segura.An app using app roles remains safe. De hecho, la asignación de grupos a roles de aplicación se usa mucho con las aplicaciones SaaS por las mismas razones.In fact, assigning groups to app roles is popular with SaaS apps for the same reasons.

Pasos siguientesNext steps

Obtenga más información sobre los roles de aplicación en los recursos siguientes.Learn more about app roles with the following resources.