Cree una extensión de autenticación personalizada para la validación de afirmaciones de recuperación de cuentas

En este artículo se describe cómo configurar una extensión de autenticación personalizada que valida las afirmaciones de ID verificadas durante la recuperación de la cuenta de Microsoft Entra. En el flujo de recuperación de la cuenta, los listeners de eventos se pueden utilizar para ampliar el proceso de validación de solicitudes:

• El evento OnVerifiedIdClaimValidation se produce cuando un usuario inicia la recuperación de la cuenta y presenta reclamaciones de identidad verificada. Puede agregar acciones como validar reclamaciones en un origen de datos autoritativo (como un sistema de RR. HH., una base de datos de aplicaciones o cualquier sistema de registros de empleados) y devolver una decisión de aprobar o reprobar.

Además de crear una extensión de autenticación personalizada, debe crear una API REST que defina las acciones de flujo de trabajo que se deben realizar para el evento. En este artículo se muestra una manera rápida de empezar a usar una función de Azure de C# implementada desde un repositorio de ejemplo. Con Azure Functions, ejecute el código en un entorno sin servidor sin tener que crear primero una máquina virtual o publicar una aplicación web.

Prerequisites

• Una suscripción a Azure. Si no tiene una cuenta de Azure existente, regístrese para obtener una prueba free.
• Un inquilino de Microsoft Entra ID con recuperación de cuenta habilitada.
• Al menos los roles Administrador de aplicaciones y Administrador de autenticación .

Cómo funciona

Durante la recuperación de la cuenta, un usuario que ha perdido todos los métodos de autenticación debe restablecer su identidad. La extensión de autenticación personalizada agrega un paso de validación de declaraciones a este flujo:

diagrama de

El OnVerifiedIdClaimValidation evento es el enlace de corrección previa en la canalización de recuperación. Permite conectar lógica de validación personalizada (búsquedas de RR. HH., comprobaciones de bases de datos externas o comprobación de confianza de asociados) antes de que Microsoft Entra ID continúe con la recuperación.

Paso 1: Creación de una API REST de extensiones de autenticación personalizadas (Aplicación de Funciones de Azure)

En este paso, implementará una aplicación de función de Azure que actúa como API REST para la extensión de autenticación personalizada. La función recibe afirmaciones de identificador verificado de Microsoft Entra ID durante la recuperación de cuentas y las valida contra una fuente de datos de referencia.

La función de ejemplo está disponible como una implementación con un solo clic. Implementa una aplicación de funciones de Azure (.NET 10, modelo de trabajo aislado) en el plan de consumo con Application Insights y una cuenta de almacenamiento.

1.1 Implementación de la función Azure

1. Seleccione el botón Deploy para Azure:

   

2. Rellene los parámetros de implementación:

   Parámetro	Description
   Nombre de la aplicación de funciones	Un nombre único global para function App (por ejemplo, contoso-recovery-claims).
   URL del repositorio	Rellenado previamente con la dirección URL del repositorio de GitHub.
   Rama	main
   Tipo de cuenta de almacenamiento	Standard_LRS (valor predeterminado).
   Location	Seleccione una región Azure cerca de los usuarios.

   Deje los parámetros opcionales en blanco por ahora, configúrelos en los pasos siguientes.

3. Seleccione Revisar y crear y, a continuación, Crear.

4. Espere a que finalice la implementación (normalmente de 2 a 3 minutos).

1.2 Obtención de la dirección URL de la función

1. Una vez implementado, vaya al recurso Function App.
2. Seleccione Functions>CustomClaimMatching>Get Function URL (Obtener dirección URL de función).
3. Copie la dirección URL. Su aspecto es similar a https://<your-function-app>.azurewebsites.net/api/CustomClaimMatching.

1.3 Configuración del origen de datos de prueba

Para las pruebas, la función admite un archivo Excel hospedado en cualquier servidor web con acceso de lectura como origen de datos. En producción, puede cambiar al proveedor de API de RR. HH. (consulte Cambiar a producción: usar el proveedor de API de RR. HH.).

1. Descargue el archivo Excel de ejemplo de la carpeta SampleData en el repositorio o cree su propio con estas columnas:

   Identificación de empleado	UPN	firstName	lastName	nombreCompleto	dateOfBirth	tipo de documento	documentId	fechaDeExpiracionDelDocumento
   E001	user@contoso.com	Juan	Cierva	John Doe	1990-01-15	Pasaporte	AB123456	15/01/2028

   Sugerencia

   Para agregar una nueva notificación, agregue una columna con el nombre de la notificación como encabezado. La función empareja dinámicamente las claves de atributos de la solicitud con los encabezados de columna, sin necesidad de cambios de código.

   Note

   De forma predeterminada, la aplicación de funciones solo valida la reclamación del número de documento (documentId). Para que coincidan reclamaciones adicionales, como firstName, dateOfBirth o employeeId, actualice la lógica de validación en el código de Azure Function.

2. Cargue el archivo en un servidor web, un recurso compartido de archivos o un servicio de almacenamiento en la nube (por ejemplo, Azure Blob Storage, SharePoint o cualquier ubicación accesible para HTTP).

3. Obtenga una dirección URL de descarga directa para el archivo. La dirección URL debe ser accesible sin inicio de sesión interactivo.

4. En el portal de Azure, vaya a la aplicación de funciones >Ajustes>Variables de entorno. La plantilla de implementación crea previamente estas variables con valores predeterminados. Compruebe y actualice lo siguiente:

   Nombre	Acción	Value
   ClaimsValidator__Provider	Compruebe (creado previamente como excel)	excel
   Excel__ShareUrl	Actualización (creada previamente pero vacía)	Dirección URL de descarga directa del archivo Excel.
   Excel__SheetName	Compruebe (creado previamente como Sheet1)	Sheet1 (o el nombre de la hoja de cálculo).

5. Seleccione Aplicar y, después, Confirmar.

Paso 2: Crear y registrar una extensión de autenticación personalizada

En este paso, registrará una extensión de autenticación personalizada que Microsoft Entra ID utiliza para invocar su Función de Azure. La extensión de autenticación personalizada contiene información sobre el punto de conexión de la API REST, la acción de validación de declaraciones que analiza de su API REST y cómo autenticarse con su API REST.

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
    "appId": "{authenticationeventsAPI_AppId}"
}

PATCH https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}
Content-type: application/json

{
    "identifierUris": [
        "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
    ],
    "api": {
        "requestedAccessTokenVersion": 2,
        "acceptMappedClaims": null,
        "knownClientApplications": [],
        "oauth2PermissionScopes": [],
        "preAuthorizedApplications": []
    },
    "requiredResourceAccess": [
        {
            "resourceAppId": "00000003-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "214e810f-fda8-4fd7-a475-29461495eb00",
                    "type": "Role"
                }
            ]
        }
    ]
}

2.1 Conceder consentimiento del administrador

Una vez creada la extensión de autenticación personalizada, conceda el consentimiento de la aplicación registrada, lo que permite que la extensión de autenticación personalizada se autentique en la API.

1. Vaya a Entra ID>Aplicaciones empresariales>Extensiones de autenticación personalizadas.
2. Seleccione la extensión de autenticación personalizada en la lista.
3. En la pestaña Información general, seleccione el botón Conceder permiso para dar consentimiento del administrador a la aplicación registrada. La extensión de autenticación personalizada usa client_credentials para autenticarse en la Azure Function App mediante el permiso Receive custom authentication extension HTTP requests. Seleccione Aceptar.

Paso 3: Agregar la extensión de autenticación personalizada a la directiva de recuperación de la cuenta

Ahora asocias la extensión personalizada de autenticación con las configuraciones de validación de cuentas del perfil de verificación de identidad para que se active durante el flujo de recuperación.

Paso 4: Probar la función (antes de agregar la autenticación)

Antes de configurar la autenticación (paso 5), compruebe que la lógica de coincidencia de declaraciones de la función funciona llamándola directamente. En este punto, la función no debe tener ninguna autenticación configurada: ningún proveedor de identidades de EasyAuth y las variables de entorno EntraId__TenantId / EntraId__ClientId deben estar vacías.

4.1 Probar directamente la función

1. Abra un terminal y ejecute:

   $body = @'
   {
       "type": "microsoft.graph.authenticationEvent.verifiedIdClaimValidation",
       "source": "/tenants/<tenant-guid>/applications/<app-id>",
       "data": {
           "@odata.type": "microsoft.graph.onVerifiedIdClaimValidationCalloutData",
           "tenantId": "<tenant-guid>",
           "authenticationContext": {
               "correlationId": "00000000-0000-0000-0000-000000000001",
               "user": {
                   "userPrincipalName": "user@contoso.com"
               }
           },
           "verifiedIdClaimsContext": {
               "additionalInfo": {
                   "employeeId": "E001"
               },
               "claims": {
                   "firstName": "John",
                   "lastName": "Doe",
                   "dateOfBirth": "1990-01-15"
               }
           }
       }
   }
   '@
   
   (Invoke-WebRequest -Method Post `
     -Uri "https://<your-function-app>.azurewebsites.net/api/CustomClaimMatching" `
     -ContentType "application/json" `
     -Headers @{ Authorization = "Bearer test" } `
     -Body $body).Content
   

2. Compruebe la respuesta:

   Coincidencia exitosa:

   {
       "data": {
           "@odata.type": "microsoft.graph.onVerifiedIdClaimValidationResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.verifiedIdClaimValidation.pass"
               }
           ]
       }
   }
   

   Coincidencia fallida (muestra las afirmaciones que no coinciden):

   {
       "data": {
           "@odata.type": "microsoft.graph.onVerifiedIdClaimValidationResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.verifiedIdClaimValidation.failed",
                   "failedClaims": ["dateOfBirth"]
               }
           ]
       }
   }
   

Paso 5: Proteger la función de Azure

Microsoft Entra extensiones personalizadas de autenticación utilizan el flujo de servidor a servidor para obtener un token de acceso que se envía en el encabezado HTTP Authorization a tu función de Azure. Al publicar la función en Azure, especialmente en un entorno de producción, debe validar el token enviado en el encabezado de autorización.

Para proteger tus Azure Functions, sigue estos pasos para integrar la autenticación de Microsoft Entra para validar los tokens entrantes con la API de eventos de autenticación de Azure Functions en el registro de aplicaciones.

5.1 Agregar un proveedor de identidades a la función de Azure

1. Inicie sesión en Azure Portal.
2. Vaya a y seleccione la aplicación de funciones que implementó anteriormente.
3. Seleccione Autenticación en el menú de la izquierda.
4. Seleccione Agregar proveedor de identidades.
5. Seleccione Microsoft como proveedor de identidades.
6. En Elegir un inquilino, seleccione Configuración de workforce (inquilino actual).
7. En Registro de aplicaciones, seleccione Pick un registro de aplicación existente en este directorio y seleccione el Azure Functions api de eventos de autenticación registro de aplicaciones creado en el paso 2.
8. En Expiración del secreto de cliente, seleccione un período de expiración.
9. En Tipos de cuenta admitidos, seleccione Inquilino actual: inquilino único.
10. En Comprobaciones adicionales:
    • Requisito de la aplicación cliente: Seleccione Permitir solicitudes de aplicaciones cliente específicas y agregue 99045fe1-7639-4a75-9d4a-577b6ca3810f (este es el ID de la aplicación de primer nivel de las extensiones de autenticación personalizadas de Microsoft Entra).
    • Requisito de identidad: Seleccione Permitir solicitudes de cualquier identidad.
    • Requisito de inquilino: Seleccione Permitir solicitudes de inquilinos específicos y escriba el identificador de inquilino del personal.
11. En Solicitudes no autenticadas, seleccione HTTP 401 No autorizado: recomendado para las API.
12. Para la URL de Issuer, ingrese https://login.microsoftonline.com/{tenantId}/v2.0, donde {tenantId} es el identificador de cliente de su cliente de Microsoft Entra.
13. Anule la selección de la opción Almacén de tokens.
14. Seleccione Agregar para agregar autenticación a la función de Azure.

5.2 Uso del proveedor de identidades de OpenID Connect

Si la función Azure se hospeda en un inquilino diferente al inquilino donde se registra la extensión de autenticación personalizada, siga estos pasos en su lugar:

1. Inicie sesión en el portal Azure y, a continuación, vaya a Function App.
2. Seleccione Autenticación en el menú de la izquierda.
3. Seleccione Agregar proveedor de identidades.
4. Seleccione OpenID Connect como proveedor de identidades.
5. Proporcione un nombre, como Contoso Microsoft Entra ID.
6. En la entrada Metadata, escriba la siguiente dirección URL al Document URL, reemplazando {tenantId} por el identificador de inquilino de Microsoft Entra:

   https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
   

7. En App registration, escriba el identificador de aplicación (id. de cliente) de la API de eventos de autenticación de Azure Functions del registro de aplicaciones creado en el paso 2.
8. En el centro de administración de Microsoft Entra, vaya a la API de eventos de autenticación Azure Functions registro de aplicaciones >Certificados y secretos>Secretos de cliente>Nuevo secreto de cliente. Copie el valor del secreto.
9. De nuevo en la función Azure, escriba el secreto Client.
10. Anule la selección de la opción Almacén de tokens.
11. Seleccione Agregar para agregar el proveedor de identidades de OpenID Connect.

Paso 6: Probar el flujo de recuperación de un extremo a otro

1. Inicie sesión en el Centro de administración Microsoft Entra y confirme que la extensión de autenticación personalizada está activa y asignada al perfil de comprobación de identidad (paso 3).

2. En una ventana del explorador privado, vaya a https://myaccount.microsoft.com e inicie una recuperación de la cuenta.

3. Complete los pasos de corrección de identidad (comprobación facial, presentación de identificador comprobado).

4. El evento OnVerifiedIdClaimValidation se dispara y llama a tu Función de Azure. La función valida las afirmaciones en el origen de datos y devuelve aprobado o rechazado.

5. Compruebe en Application Insights>Registros que se llamó a la función y que los claims se validaron:

   traces
   | where message has "claims" or message has "validation"
   | order by timestamp desc
   | take 20
   

Cambia a producción: usa el proveedor de la API de RR. HH.

Para producción, cambie del proveedor de Excel al proveedor de la API de RR. HH., que llama al endpoint REST de RR. HH. de su organización.

1. En las variables de entorno de Function App, actualice:

   Nombre	Value
   ClaimsValidator__Provider	hrapi
   HrApi__BaseUrl	URL base de la API de RRHH (por ejemplo, https://hr.contoso.com/api).
   HrApi__AuthMode	apikey o oauth.
   HrApi__ApiKey	La clave de API (si usa el apikey modo de autenticación).
   HrApi__OAuthScope	Ámbito de OAuth (si usa el oauth modo de autenticación, por ejemplo, api://hr-api-app-id/.default).

2. Cuando se usa el modo de autenticación oauth, la función utiliza la identidad administrada asignada por el sistema de la Function App. Conceda a la identidad administrada el rol de aplicación adecuado en el registro de aplicaciones de la API de Recursos Humanos.

3. La API de RR. HH. debe implementar este contrato:

   Solicitud:POST {BaseUrl}/validate

   {
       "upn": "user@contoso.com",
       "employeeId": "E001",
       "claims": {
           "firstName": "John",
           "lastName": "Doe",
           "dateOfBirth": "1990-01-15"
       }
   }
   

   Respuesta (aprobado):

   {
       "result": "pass"
   }
   

   Respuesta (error):

   {
       "result": "fail",
       "failedClaims": ["dateOfBirth"]
   }
   

Troubleshoot

Para obtener más instrucciones de solución de problemas, consulte Solución de problemas de la API de extensiones de autenticación personalizadas.

Contenido relacionado

• Introducción a las extensiones de autenticación personalizadas
• Información general de la recuperación de cuentas de Microsoft Entra ID
• Habilitación de la recuperación de cuentas para la organización
• Código de ejemplo: AccountRecoveryClaimsMatchingAPI