Procedimientos: Configuración de la notificación de rol emitida en el token SAML para aplicaciones empresarialesHow to: Configure the role claim issued in the SAML token for enterprise applications

Mediante Azure Active Directory (Azure AD) se puede personalizar el tipo de notificación de la notificación de rol en el token de respuesta que se recibe después de autorizar una aplicación.By using Azure Active Directory (Azure AD), you can customize the claim type for the role claim in the response token that you receive after you authorize an app.

PrerequisitesPrerequisites

  • Una suscripción a Azure AD con configuración de directorios.An Azure AD subscription with directory setup.
  • Una suscripción que tenga el inicio de sesión único (SSO) habilitado.A subscription that has single sign-on (SSO) enabled. El inicio de sesión único se debe configurar con la aplicación.You must configure SSO with your application.

Cuándo usar esta característicaWhen to use this feature

Si la aplicación espera que se pasen roles personalizados en una respuesta de SAML, es preciso usar esta característica.If your application expects custom roles to be passed in a SAML response, you need to use this feature. Puede crear tantos roles como sea necesario devolver desde Azure AD a la aplicación.You can create as many roles as you need to be passed back from Azure AD to your application.

Creación de roles para una aplicaciónCreate roles for an application

  1. En el panel izquierdo de Azure Portal, seleccione el icono Azure Active Directory.In the Azure portal, in the left pane, select the Azure Active Directory icon.

    Icono de Azure Active Directory

  2. Seleccione Aplicaciones empresariales.Select Enterprise applications. Después, seleccione Todas las aplicaciones.Then select All applications.

    Panel Aplicaciones empresariales

  3. Para agregar una nueva aplicación, seleccione el botón Nueva aplicación en la parte superior del cuadro de diálogo.To add a new application, select the New application button on the top of the dialog box.

    Botón "Nueva aplicación"

  4. En el cuadro de búsqueda, escriba el nombre de la aplicación y seleccione la aplicación en el panel de resultados.In the search box, type the name of your application, and then select your application from the result panel. Seleccione el botón Agregar para agregar la aplicación.Select the Add button to add the application.

    Aplicación en la lista de resultados

  5. Después de agregar la aplicación, vaya a la página Propiedades y copie el identificador del objeto.After the application is added, go to the Properties page and copy the object ID.

    Página de propiedades

  6. Abra el Explorador de Microsoft Graph en otra ventana y siga estos pasos:Open Microsoft Graph Explorer in another window and take the following steps:

    a.a. Inicie sesión en el sitio del Probador de Graph con las credenciales de administrador o coadministrador global del inquilino.Sign in to the Graph Explorer site by using the global admin or coadmin credentials for your tenant.

    b.b. Para crear los roles es preciso tener permisos suficientes.You need sufficient permissions to create the roles. Seleccione Modificar permisos para obtener los permisos.Select modify permissions to get the permissions.

    Botón "Modificar permisos"

    c.c. Seleccione los siguientes permisos en la lista (si no los tiene ya) y seleccione Modificar permisos.Select the following permissions from the list (if you don't have these already) and select Modify Permissions.

    Lista de permisos y botón "Modificar permisos"

    Nota

    El rol de administrador de aplicaciones en la nube y de administrador de aplicaciones no funcionará en este escenario dado que se necesitan los permisos de administrador global para la lectura y escritura de directorios.Cloud App Administrator and App Administrator role will not work in this scenario as we need the Global Admin permissions for Directory Read and Write.

    d.d. Acepte el consentimiento.Accept the consent. Ha vuelto a iniciar sesión en el sistema.You're logged in to the system again.

    e.e. Cambie la versión a beta y recupere la lista de entidades de servicio del inquilino con la siguiente consulta:Change the version to beta, and fetch the list of service principals from your tenant by using the following query:

    https://graph.microsoft.com/beta/servicePrincipals

    Si usa varios directorios, siga este patrón: https://graph.microsoft.com/beta/contoso.com/servicePrincipalsIf you're using multiple directories, follow this pattern: https://graph.microsoft.com/beta/contoso.com/servicePrincipals

    Cuadro de diálogo del Probador de Graph, con la consulta para capturar entidades de servicio

    Nota

    Ya estamos en proceso de actualizar las API para que los clientes puedan ver alguna interrupción en el servicio.We are already in the process of upgrading the APIs so customers might see some disruption in the service.

    f.f. En la lista de entidades de servicio capturadas, seleccione la que necesita modificar.From the list of fetched service principals, get the one that you need to modify. También puede usar Ctrl + F para buscar la aplicación en todas las entidades de servicio enumeradas.You can also use Ctrl+F to search the application from all the listed service principals. Busque el identificador de objeto que copió de la página Propiedades y use la consulta siguiente para acceder a la entidad de servicio:Search for the object ID that you copied from the Properties page, and use the following query to get to the service principal:

    https://graph.microsoft.com/beta/servicePrincipals/<objectID>

    Consulta para obtener la entidad de servicio que necesita modificar

    g.g. Extraiga la propiedad appRoles del objeto de entidad de servicio.Extract the appRoles property from the service principal object.

    Detalles de la propiedad appRoles

    Nota

    Si usa la aplicación personalizada (no la aplicación de Azure Marketplace), verá dos roles predeterminados: user y msiam_access.If you're using the custom app (not the Azure Marketplace app), you see two default roles: user and msiam_access. En el caso de la aplicación Marketplace, msiam_access es el único rol predeterminado.For the Marketplace app, msiam_access is the only default role. No es necesario realizar ningún cambio en los roles predeterminados.You don't need to make any changes in the default roles.

    h.h. Genere roles nuevos para la aplicación.Generate new roles for your application.

    El siguiente JSON siguiente es un ejemplo del objeto appRoles.The following JSON is an example of the appRoles object. Cree un objeto similar para agregar los roles que desee para la aplicación.Create a similar object to add the roles that you want for your application.

    {
       "appRoles": [
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "msiam_access",
            "displayName": "msiam_access",
            "id": "b9632174-c057-4f7e-951b-be3adc52bfe6",
            "isEnabled": true,
            "origin": "Application",
            "value": null
        },
        {
            "allowedMemberTypes": [
                "User"
            ],
            "description": "Administrators Only",
            "displayName": "Admin",
            "id": "4f8f8640-f081-492d-97a0-caf24e9bc134",
            "isEnabled": true,
            "origin": "ServicePrincipal",
            "value": "Administrator"
        }
    ]
    }
    

    Nota

    Solo puede agregar nuevos roles, además de msiam_access, para la operación de revisión.You can only add new roles after msiam_access for the patch operation. Además, puede agregar tantos roles como su organización necesite.Also, you can add as many roles as your organization needs. Azure AD enviará el valor de estos roles como valor de notificación en la respuesta de SAML.Azure AD will send the value of these roles as the claim value in the SAML response. Para generar los valores del GUID del identificador de los nuevos roles use herramientas web como estaTo generate the GUID values for the ID of new roles use the web tools like this

    i.i. Vuelva al Probador de Graph y cambie el método de GET a PATCH.Go back to Graph Explorer and change the method from GET to PATCH. Aplique la revisión al objeto de entidad de servicio para obtener los roles deseados mediante la actualización de la propiedad appRoles para que sea similar a la del ejemplo anterior.Patch the service principal object to have the desired roles by updating the appRoles property like the one shown in the preceding example. Seleccione Ejecutar consulta para ejecutar la operación de aplicación de revisión.Select Run Query to execute the patch operation. Un mensaje confirma la creación del rol.A success message confirms the creation of the role.

    Operación de aplicación de revisión con mensaje de resultado correcto

  7. Una vez que haya revisado la entidad de servicio con más roles, podrá asignar usuarios a los roles correspondientes.After the service principal is patched with more roles, you can assign users to the respective roles. Para asignar los usuarios, vaya al portal y, después, a la aplicación.You can assign the users by going to portal and browsing to the application. Seleccione la pestaña Usuarios y grupos. Esta pestaña enumera todos los usuarios y grupos que ya están asignados a la aplicación.Select the Users and groups tab. This tab lists all the users and groups that are already assigned to the app. Puede agregar nuevos usuarios a los nuevos roles.You can add new users on the new roles. También puede seleccionar un usuario existente y seleccionar Editar para cambiar el rol.You can also select an existing user and select Edit to change the role.

    Pestaña "Usuarios y grupos"

    Para asignar el rol a cualquier usuario, seleccione el rol nuevo y seleccione el botón Asignar de la parte inferior de la página.To assign the role to any user, select the new role and select the Assign button on the bottom of the page.

    Paneles "Editar asignación" y "Seleccionar rol"

    Nota

    Para ver los nuevos roles es preciso actualizar la sesión en Azure Portal.You need to refresh your session in the Azure portal to see new roles.

  8. Actualice la tabla Atributos para definir una asignación personalizada de la notificación de rol.Update the Attributes table to define a customized mapping of the role claim.

  9. En la sección Notificaciones del usuario del cuadro de diálogo Atributos de usuario, realice los siguientes pasos para agregar el atributo Token SAML como se muestra en la tabla siguientes:In the User Claims section on the User Attributes dialog, perform the following steps to add SAML token attribute as shown in the below table:

    Nombre del atributoAttribute name Valor del atributoAttribute value
    Nombre de rolRole name user.assignedrolesuser.assignedroles

    Nota

    Si el valor de notificación del rol es null, Azure AD no envía este valor en el token y es el predeterminado por diseño.If the role claim value is null, then Azure AD will not send this value in the token and this is default as per design.

    a.a. Haga clic en el icono Editar para abrir el cuadro de diálogo Atributos y notificaciones de usuario.click Edit icon to open User Attributes & Claims dialog.

    Botón "Agregar atributo"

    b.b. En el cuadro de diálogo Administrar las notificaciones del usuario, agregue el atributo de token SAML al hacer clic en Agregar nueva notificación.In the Manage user claims dialog, add the SAML token attribute by clicking on Add new claim.

    Botón "Agregar atributo"

    Panel "Agregar atributo"

    c.c. En el cuadro Nombre, escriba el nombre de atributo según sea necesario.In the Name box, type the attribute name as needed. En este ejemplo se utiliza Role Name como nombre de la notificación.This example uses Role Name as the claim name.

    d.d. Deje el cuadro Espacio de nombres en blanco.Leave the Namespace box blank.

    e.e. En la lista Atributo de origen, escriba el valor de atributo que se muestra para esa fila.From the Source attribute list, type the attribute value shown for that row.

    f.f. Seleccione Guardar.Select Save.

  10. Para probar la aplicación en un inicio de sesión único iniciado por un proveedor de identidades, inicie sesión en el Panel de acceso y seleccione el icono de la aplicación.To test your application in a single sign-on that's initiated by an identity provider, sign in to the Access Panel and select your application tile. En el token SAML, debería ver todos los roles asignados al usuario con el nombre de notificación que les ha dado.In the SAML token, you should see all the assigned roles for the user with the claim name that you have given.

Actualización de un rol existenteUpdate an existing role

Para actualizar un rol existente, siga estos pasos:To update an existing role, perform the following steps:

  1. Abra el Explorador de Microsoft Graph.Open Microsoft Graph Explorer.

  2. Inicie sesión en el sitio del Probador de Graph con las credenciales de administrador o coadministrador global del inquilino.Sign in to the Graph Explorer site by using the global admin or coadmin credentials for your tenant.

  3. Cambie la versión a beta y recupere la lista de entidades de servicio del inquilino con la siguiente consulta:Change the version to beta, and fetch the list of service principals from your tenant by using the following query:

    https://graph.microsoft.com/beta/servicePrincipals

    Si usa varios directorios, siga este patrón: https://graph.microsoft.com/beta/contoso.com/servicePrincipalsIf you're using multiple directories, follow this pattern: https://graph.microsoft.com/beta/contoso.com/servicePrincipals

    Cuadro de diálogo del Probador de Graph, con la consulta para capturar entidades de servicio

  4. En la lista de entidades de servicio capturadas, seleccione la que necesita modificar.From the list of fetched service principals, get the one that you need to modify. También puede usar Ctrl + F para buscar la aplicación en todas las entidades de servicio enumeradas.You can also use Ctrl+F to search the application from all the listed service principals. Busque el identificador de objeto que copió de la página Propiedades y use la consulta siguiente para acceder a la entidad de servicio:Search for the object ID that you copied from the Properties page, and use the following query to get to the service principal:

    https://graph.microsoft.com/beta/servicePrincipals/<objectID>

    Consulta para obtener la entidad de servicio que necesita modificar

  5. Extraiga la propiedad appRoles del objeto de entidad de servicio.Extract the appRoles property from the service principal object.

    Detalles de la propiedad appRoles

  6. Para actualizar el rol existente, siga estos pasos.To update the existing role, use the following steps.

    Cuerpo de la solicitud para "PATCH," con "description" y "displayname" resaltados

    a.a. Cambie el método de GET a PATCH.Change the method from GET to PATCH.

    b.b. Copie los roles existentes y péguelos en Cuerpo de la solicitud.Copy the existing roles and paste them under Request Body.

    c.c. Actualice el valor de un rol mediante la actualización de la descripción del rol, el valor del rol o el nombre para mostrar del rol, lo que sea necesario.Update the value of a role by updating the role description, role value, or role display name as needed.

    d.d. Después de actualizar todos los roles necesarios, seleccione Ejecutar consulta.After you update all the required roles, select Run Query.

Eliminación de un rol existenteDelete an existing role

Para eliminar un rol existente, siga estos pasos:To delete an existing role, perform the following steps:

  1. Abra el Explorador de Microsoft Graph en otra ventana.Open Microsoft Graph Explorer in another window.

  2. Inicie sesión en el sitio del Probador de Graph con las credenciales de administrador o coadministrador global del inquilino.Sign in to the Graph Explorer site by using the global admin or coadmin credentials for your tenant.

  3. Cambie la versión a beta y recupere la lista de entidades de servicio del inquilino con la siguiente consulta:Change the version to beta, and fetch the list of service principals from your tenant by using the following query:

    https://graph.microsoft.com/beta/servicePrincipals

    Si usa varios directorios, siga este patrón: https://graph.microsoft.com/beta/contoso.com/servicePrincipalsIf you're using multiple directories, follow this pattern: https://graph.microsoft.com/beta/contoso.com/servicePrincipals

    Cuadro de diálogo del Probador de Graph, con la consulta para capturar la lista de entidades de servicio

  4. En la lista de entidades de servicio capturadas, seleccione la que necesita modificar.From the list of fetched service principals, get the one that you need to modify. También puede usar Ctrl + F para buscar la aplicación en todas las entidades de servicio enumeradas.You can also use Ctrl+F to search the application from all the listed service principals. Busque el identificador de objeto que copió de la página Propiedades y use la consulta siguiente para acceder a la entidad de servicio:Search for the object ID that you copied from the Properties page, and use the following query to get to the service principal:

    https://graph.microsoft.com/beta/servicePrincipals/<objectID>

    Consulta para obtener la entidad de servicio que necesita modificar

  5. Extraiga la propiedad appRoles del objeto de entidad de servicio.Extract the appRoles property from the service principal object.

    Detalles de la propiedad appRoles del objeto de entidad de servicio

  6. Para eliminar el rol existente, siga estos pasos.To delete the existing role, use the following steps.

    Cuerpo de la solicitud de "PATCH" con IsEnabled establecido en false

    a.a. Cambie el método de GET a PATCH.Change the method from GET to PATCH.

    b.b. Copie los roles existentes de la aplicación y péguelos en Cuerpo de la solicitud.Copy the existing roles from the application and paste them under Request Body.

    c.c. Establezca el valor de IsEnabled en false en el rol que desee eliminar.Set the IsEnabled value to false for the role that you want to delete.

    d.d. Seleccione Ejecutar consulta.Select Run Query.

    Nota

    Asegúrese de que dispone del rol msiam_access y de que el identificador coincide en el rol generado.Make sure that you have the msiam_access role, and the ID is matching in the generated role.

  7. Una vez que el rol esté deshabilitado, elimine el bloque del rol de la sección appRoles.After the role is disabled, delete that role block from the appRoles section. Mantenga el método PATCH y seleccione Ejecutar consulta.Keep the method as PATCH, and select Run Query.

  8. Después de ejecutar la consulta el rol se elimina.After you run the query, the role is deleted.

    Nota

    Para poder quitar el rol es preciso deshabilitar el rol.The role needs to be disabled before it can be removed.

Pasos siguientesNext steps

Para conocer los pasos adicionales, consulte la documentación de la aplicación.For additional steps, see the app documentation.