Compartir a través de

Tutorial: asignación de roles personalizados con una función y Microsoft Graph (versión preliminar)

  • Artículo

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 Entra ID.

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 Entra ID 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 Entra ID 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 Entra.

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.

    Crear un registro de aplicación

  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 Entra ID 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 Entra ID en la aplicación web estática.

    Creación de un secreto de cliente

Configuración de la autenticación de Entra ID

  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_ENTRA_TENANT_ID>",
        "clientIdSettingName": "ENTRA_CLIENT_ID",
        "clientSecretSettingName": "ENTRA_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_ENTRA_TENANT_ID> reemplazando <YOUR_ENTRA_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
    ENTRA_CLIENT_ID Identificador de la aplicación Entra ID (cliente).
    ENTRA_CLIENT_SECRET Valor del secreto de cliente de la aplicación Entra.

  9. Seleccione Guardar.

Crear roles

  1. Abra el registro de la aplicación Entra ID 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 Entra 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 Entra ID 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 Entra ID 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