Tutorial: asignación de roles personalizados con una función y Microsoft Graph

En este artículo se muestra cómo usar una función para consultar Microsoft Graph y asignar roles personalizados a un usuario en función de su pertenencia a grupos Active Directory.

En este tutorial, aprenderá a:

• Implementación de una aplicación web estática.
• Cree un registro de aplicaciones de Microsoft Entra.
• Configure la autenticación personalizada con Microsoft Entra ID.
• Configure una función sin servidor que consulte la pertenencia a grupos Active Directory del usuario y devuelva una lista de roles personalizados.

Nota

En este tutorial es necesario usar una función para asignar roles. La administración de roles basada en funciones está actualmente en versión preliminar. El nivel de permiso necesario para completar este tutorial es "User.Read.All".

Hay una función denominada GetRoles en la API de la aplicación. Esta función usa el token de acceso del usuario para realizar consultas en Active Directory desde Microsoft Graph. Si el usuario es miembro de cualquier grupo definido en la aplicación, se asignan al usuario los roles personalizados correspondientes.

Requisitos previos

Requisito	Comentarios
Una cuenta activa de Azure	En caso de no tener una, puede crear una cuenta gratuita.
Permisos de Microsoft Entra	Debe tener permisos suficientes para crear una aplicación de Microsoft Entra.

Crear un repositorio de GitHub

1. Generación de un repositorio basado en la plantilla de función de roles. Vaya a la siguiente ubicación para crear un nuevo repositorio.

   https://github.com/staticwebdev/roles-function/generate

2. Asigne el nombre my-custom-roles-app al repositorio.

3. Seleccione Create repository from template (Crear repositorio a partir de plantilla).

Implementación de la aplicación web estática en Azure

1. En una nueva ventana del explorador, abra Azure Portal.

2. En la esquina superior izquierda, haga clic en Crear un recurso.

3. Escriba static web apps en el cuadro de búsqueda.

4. Seleccione Static Web Apps.

5. Seleccione Crear.

6. Configure la aplicación web estática con la siguiente información:

   Configuración	Value	Notas
   Subscription	Seleccione su suscripción a Azure.
   Resource group	Cree un grupo nuevo denominado my-custom-roles-app-group.
   Nombre	my-custom-roles-app
   Tipo de plan	Estándar	La personalización de la autenticación y la asignación de roles mediante una función requieren el plan Estándar.
   Región de la API	Seleccione la región más cercana a la suya.

7. En la sección Detalles de la implementación:

   Configuración	Valor
   Source	Seleccione GitHub.
   Organización	Seleccione la organización en la que ha generado el repositorio.
   Repositorio	Seleccione my-custom-roles-app.
   Rama	Seleccione main (principal).

8. En la sección Detalles de la compilación, agregue los detalles de configuración de esta aplicación.

   Configuración	Value	Notas
   Valores preestablecidos de compilación	seleccione Personalizada.
   Ubicación de la aplicación	Escriba /frontend.	Esta carpeta contiene la aplicación de front-end.
   Ubicación de la API	/api	Carpeta del repositorio que contiene las funciones de la API.
   Ubicación del resultado	déjelo en blanco.	Esta aplicación no tiene salida de compilación.

9. Seleccione Revisar + crear.

10. Seleccione Crear para iniciar la primera implementación.

11. Una vez completado el proceso, seleccione Ir al recurso para abrir la nueva aplicación web estática.

12. En la sección de información general, busque la dirección URL de la aplicación. Copie este valor en un editor de texto para usarlo en los próximos pasos para configurar la autenticación de Active Directory.

Creación de una aplicación de Microsoft Entra

1. En Azure Portal, busque y vaya a Microsoft Entra ID.

2. En el menú Administrar, seleccione Registros de aplicaciones.

3. Seleccione Nuevo registro para abrir la ventana Registrar una aplicación. Escriba los siguientes valores:

   Configuración	Value	Notas
   Nombre	Escriba MyStaticWebApp.
   Tipos de cuenta admitidos	Seleccione Solo las cuentas de este directorio organizativo.
   URI de redireccionamiento	Seleccione Web y escriba la URL de devolución de llamadas de autenticación de Microsoft Entra de la aplicación web estática. Reemplace <YOUR_SITE_URL> en <YOUR_SITE_URL>/.auth/login/aad/callback por la dirección URL de la aplicación web estática.	Esta dirección URL es lo que copió en un editor de texto en un paso anterior.

   

4. Seleccione Registrar.

5. Una vez creado el registro de la aplicación, copie el Id. de aplicación (cliente) y el Id. de directorio (inquilino) en la sección Essentials de un editor de texto.

   Necesita estos valores para configurar la autenticación de Active Directory en la aplicación web estática.

Habilitación de tokens de identificador

1. En la configuración del registro de aplicaciones, seleccione Autenticación en Administrar.

2. En la sección Flujos de concesión implícita e híbridos, seleccione Tokens de id. (utilizados para flujos implícitos e híbridos) .

   El entorno de ejecución de Static Web Apps requiere esta configuración para autenticar a los usuarios.

3. Seleccione Guardar.

Creación de un secreto de cliente

1. En la configuración del registro de aplicaciones, seleccione Certificados y secretos en Administrar.

2. En la sección Secretos de cliente, seleccione Nuevo secreto de cliente.

3. En el campo Descripción, escriba MyStaticWebApp.

4. En el campo Expiración, deje el valor predeterminado de 6 meses.

   Nota

   Debe rotar el secreto antes de la fecha de expiración generando un nuevo secreto y actualizando la aplicación con su valor.

5. Seleccione Agregar.

6. Copie el valor del secreto de cliente que creó en un editor de texto.

   Necesita este valor para configurar la autenticación de Active Directory en la aplicación web estática.

   

Configuración de la autenticación de Active Directory

1. En un explorador, abra el repositorio GitHub que contiene la aplicación web estática que implementó.

   Vaya al archivo de configuración de la aplicación en frontend/staticwebapp.config.json. Este archivo contiene las secciones siguientes:

   "auth": {
     "rolesSource": "/api/GetRoles",
     "identityProviders": {
       "azureActiveDirectory": {
         "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
         "registration": {
           "openIdIssuer": "https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID>",
           "clientIdSettingName": "AAD_CLIENT_ID",
           "clientSecretSettingName": "AAD_CLIENT_SECRET"
         },
         "login": {
           "loginParameters": [
             "resource=https://graph.microsoft.com"
           ]
         }
       }
     }
   },
   

   Esta configuración consta de las siguientes opciones de configuración:

   Propiedades	Descripción
   rolesSource	Dirección URL en la que el proceso de inicio de sesión obtiene una lista de roles disponibles. Para la aplicación de ejemplo, la dirección URL es /api/GetRoles.
   userDetailsClaim	La dirección URL del esquema utilizado para validar la solicitud de inicio de sesión.
   openIdIssuer	La ruta de inicio de sesión de Microsoft Entra, anexada con el identificador de inquilino.
   clientIdSettingName	Identificador del cliente de Microsoft Entra.
   clientSecretSettingName	Valor del secreto de cliente de Microsoft Entra.
   loginParameters	Para obtener un token de acceso para Microsoft Graph, el campo loginParameters debe configurarse con resource=https://graph.microsoft.com.

2. Seleccione Editar para actualizar el archivo.

3. Actualice el valor openIdIssuer de https://login.microsoftonline.com/<YOUR_AAD_TENANT_ID> reemplazando <YOUR_AAD_TENANT_ID> por el id. de directorio (inquilino) de Microsoft Entra ID.

4. Seleccione Confirmar cambios....

5. Escriba un mensaje de confirmación y seleccione Confirmar cambios.

   Al confirmar estos cambios, se inicia una ejecución de Acciones de GitHub para actualizar la aplicación web estática.

6. Vaya al recurso de la aplicación web estática en Azure Portal.

7. En la barra del menú, seleccione Configuración.

8. En la sección Configuración de la aplicación, agregue la siguiente configuración:

   Nombre	Valor
   AAD_CLIENT_ID	El id. de cliente de la aplicación de Azure Active Directory.
   AAD_CLIENT_SECRET	El valor del secreto de cliente de la aplicación de Active Directory.

9. Seleccione Guardar.

Crear roles

1. Abra el registro de aplicaciones de Active Directory en Azure Portal.

2. En Administrar, seleccione Roles de aplicación.

3. Seleccione Crear rol de aplicación y escriba los valores siguientes:

   Configuración	Value
   Nombre para mostrar	Escriba admin.
   Tipos de miembros permitido	Seleccione Usuarios o grupos.
   Valor	Escriba admin.
   Descripción	Escriba Administrador.

4. Active la casilla ¿Desea habilitar este rol de aplicación?

5. Seleccione Aplicar.

6. Ahora repita el mismo proceso para un rol denominado lector.

7. Copie los valores de id. de cada rol y resérvelos en un editor de texto.

Verificación de roles personalizados

La aplicación de ejemplo contiene una función de API (api/GetRoles/index.js) que consulta Microsoft Graph para determinar si un usuario está en un grupo definido previamente.

En función de las pertenencias a grupos del usuario, la función asigna roles personalizados al usuario. La aplicación está configurada para restringir determinadas rutas en función de estos roles personalizados.

1. En el repositorio de GitHub, vaya a la función GetRoles que se encuentra en api/GetRoles/index.js.

   Cerca de la parte superior, hay un objeto roleGroupMappings que asigna roles de usuario personalizados a grupos de Microsoft Entra.

2. Seleccione Editar.

3. Actualice el objeto con los id. de grupo del inquilino de Microsoft Entra.

   Por ejemplo, si tiene grupos con los id. 6b0b2fff-53e9-4cff-914f-dd97a13bfbd6 y b6059db5-9cef-4b27-9434-bb793aa31805, actualizaría el objeto a:

   const roleGroupMappings = {
     'admin': '6b0b2fff-53e9-4cff-914f-dd97a13bfbd6',
     'reader': 'b6059db5-9cef-4b27-9434-bb793aa31805'
   };
   

   Se llama a la función GetRoles cada vez que un usuario se autentica correctamente con Microsoft Entra ID. La función usa el token de acceso del usuario para consultar su pertenencia al grupo Active Directory de Microsoft Graph. Si el usuario es miembro de cualquier grupo definido en el objeto roleGroupMappings, se devuelven los roles personalizados correspondientes.

   En el ejemplo anterior, si un usuario es miembro del grupo de Active Directory con el identificador b6059db5-9cef-4b27-9434-bb793aa31805, se le concede el rol reader.

4. Seleccione Confirmar cambios....

5. Agregue un mensaje de confirmación y seleccione Confirmar cambios.

   Al realizar estos cambios, se inicia una compilación para actualizar la aplicación web estática.

6. Una vez completada la implementación, puede verificar los cambios; para ello, vaya a la dirección URL de la aplicación.

7. Inicie sesión en la aplicación web estática mediante Microsoft Entra ID.

8. Cuando haya iniciado sesión, la aplicación de ejemplo muestra la lista de roles que se le asignan en función de la pertenencia a grupos de Active Directory de su identidad.

   En función de estos roles, se le permite o prohíbe acceder a algunas de las rutas de la aplicación.

Nota

Algunas consultas en Microsoft Graph devuelven varias páginas de datos. Cuando se requiere más de una solicitud de consulta, Microsoft Graph devuelve una propiedad @odata.nextLink en la respuesta que contiene una dirección URL a la página siguiente de resultados. Para obtener más información, consulte Paginación de datos de Microsoft Graph en la aplicación

Limpieza de recursos

Limpie los recursos que implementó eliminando el grupo de recursos.

1. En Azure Portal, seleccione Grupos de recursos en el menú de la izquierda.

2. Escriba el nombre del grupo de recursos en el campo Filtrar por nombre.

3. Seleccione el nombre del grupo de recursos que ha utilizado en este tutorial.

4. Seleccione Eliminar grupo de recursos del menú superior.

Pasos siguientes

Autenticación y autorización