Solucionar problemas de la extensión de autenticación personalizada

Los eventos de autenticación y los proveedores de notificaciones personalizados permiten personalizar la experiencia de autenticación de Microsoft Entra mediante la integración con sistemas externos. Por ejemplo, puede crear una API del proveedor de notificaciones personalizado y configurar una aplicación OpenID Connect o una aplicación SAML para recibir tokens con notificaciones de un almacén externo.

Comportamiento de error

Cuando se produce un error en una llamada API, el comportamiento del error es el siguiente:

• En el caso de las aplicaciones de OpenId Connect: Microsoft Entra ID redirige al usuario a la aplicación cliente con un error. No se acuña ningún token.
• En el caso de las aplicaciones SAML: Microsoft Entra ID muestra al usuario una pantalla de error en la experiencia de autenticación. El usuario no se redirige de nuevo a la aplicación cliente.

El código de error que se devuelve a la aplicación o al usuario es genérico. Para solucionar problemas, compruebe los registros de inicio de sesión de los códigos de error.

Registro

Para solucionar problemas con el punto de conexión de la API de REST del proveedor de notificaciones personalizado, la API de REST debe controlar el registro. Azure Functions y otras plataformas de desarrollo de API proporcionan soluciones de registro detalladas. Use esas soluciones para obtener información detallada sobre el comportamiento de las API y solucionar problemas con la lógica de la API.

Registros de inicio de sesión de Microsoft Entra

Sugerencia

Los pasos de este artículo pueden variar ligeramente en función del portal desde donde comienza.

También puede usar los registros de inicio de sesión de Microsoft Entra además de los registros de la API de REST y las soluciones de diagnóstico del entorno de hospedaje. Al usar los registros de inicio de sesión de Microsoft Entra podría encontrar errores, lo que puede afectar al inicio de sesión de los usuarios. Los registros de inicio de sesión de Microsoft Entra proporcionan información sobre el estado HTTP, el código de error, la duración de la ejecución y el número de reintentos a los que Microsoft Entra ID llamó a la API.

Los registros de inicio de sesión de Microsoft Entra también se integran con Azure Monitor. Puede configurar las alertas y la supervisión, visualizar los datos e integrarlos con las herramientas de administración de eventos e información de seguridad (SIEM). Por ejemplo, puede configurar notificaciones si el número de errores supera un umbral determinado que elija.

Para acceder a los registros de inicio de sesión de Microsoft Entra:

1. Inicie sesión en el Centro de administración de Microsoft Entra como Administrador de aplicaciones en la nube.

2. Vaya a Aplicaciones de identidad>Aplicaciones>Empresariales.

3. Seleccione Registros de inicio de sesión y, a continuación, seleccione el registro de inicio de sesión más reciente.

4. Para obtener más información, seleccione la pestaña Eventos de autenticación. Se muestra información relacionada con la llamada a la API de REST de la extensión de autenticación personalizada, incluidos los códigos de error.

   

Referencia de los códigos de error

Use la tabla siguiente para diagnosticar un código de error.

Código de error	Nombre del error	Descripción
1003000	EventHandlerUnexpectedError	Error inesperado al procesar un controlador de eventos.
1003001	CustomExtenstionUnexpectedError	Error inesperado al llamar a una API de extensión personalizada.
1003002	CustomExtensionInvalidHTTPStatus	La API de extensión personalizada devolvió un código de estado HTTP no válido. Compruebe que la API devuelva un código de estado aceptado definido para ese tipo de extensión personalizado.
1003003	CustomExtensionInvalidResponseBody	Hubo un problema al analizar el cuerpo de respuesta de la extensión personalizada. Compruebe que el cuerpo de respuesta de la API esté en un esquema aceptable para ese tipo de extensión personalizada.
1003004	CustomExtensionThrottlingError	Hay demasiadas solicitudes de extensión personalizadas. Esta excepción se produce para las llamadas API de la extensión personalizada cuando se alcanzan los límites.
1003005	CustomExtensionTimedOut	La extensión personalizada no respondió dentro del tiempo de espera permitido. Compruebe que la API responde dentro del tiempo de espera configurado para la extensión personalizada. También podría indicar que el token de acceso no es válido. Siga los pasos para llamar directamente a la API de REST.
1003006	CustomExtensionInvalidResponseContentType	El tipo de contenido de respuesta de la extensión personalizada no es "application/json".
1003007	CustomExtensionNullClaimsResponse	La API de extensión personalizada respondió con un contenedor de notificaciones null.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	La API de extensión personalizada no respondió con la misma apiSchemaVersion a la que se llamó.
1003009	CustomExtensionEmptyResponse	El cuerpo de respuesta de la API de extensión personalizada era null cuando no se esperaba.
1003010	CustomExtensionInvalidNumberOfActions	La respuesta de la API de extensión personalizada incluía un número diferente de acciones que las admitidas para ese tipo de extensión personalizada.
1003011	CustomExtensionNotFound	No se encontró la extensión personalizada asociada a un agente de escucha de eventos.
1003012	CustomExtensionInvalidActionType	La extensión personalizada devolvió un tipo de acción no válido definido para ese tipo de extensión personalizada.
1003014	CustomExtensionIncorrectResourceIdFormat	La propiedad identifierUris del manifiesto para el registro de aplicación para la extensión personalizada debe tener el formato "api://{nombre de dominio completo}/{appid}.
1003015	CustomExtensionDomainNameDoesNotMatch	TargetUrl y resourceId de la extensión personalizada deben tener el mismo nombre de dominio completo.
1003016	CustomExtensionResourceServicePrincipalNotFound	El valor appId de la extensión personalizada resourceId debe corresponder a una entidad de servicio real del inquilino.
1003017	CustomExtensionClientServicePrincipalNotFound	La entidad de servicio del recurso de extensión personalizada no se encuentra en el inquilino.
1003018	CustomExtensionClientServiceDisabled	La entidad de servicio de recursos de la extensión personalizada está deshabilitada en este inquilino.
1003019	CustomExtensionResourceServicePrincipalDisabled	La entidad de servicio de recursos de la extensión personalizada está deshabilitada en este inquilino.
1003020	CustomExtensionIncorrectTargetUrlFormat	La dirección URL de destino tiene un formato incorrecto. Debe ser una dirección URL válida que empiece por https.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	La entidad de servicio no tiene el consentimiento del administrador para el rol de aplicación de Microsoft Graph CustomAuthenticationExtensions.Receive.Payload (también conocido como permiso de aplicación), que es necesario para que la aplicación reciba solicitudes HTTP de extensión de autenticación personalizadas.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	La entidad de servicio de MS Graph está deshabilitada o no se encuentra en este inquilino.
1003023	CustomExtensionBlocked	El servicio bloquea el punto de conexión utilizado para la extensión personalizada.
1003024	CustomExtensionResponseSizeExceeded	El tamaño de respuesta de la extensión personalizada superó el límite máximo.
1003025	CustomExtensionResponseClaimsSizeExceeded	El tamaño total de las notificaciones en la respuesta de la extensión personalizada superó el límite máximo.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	La API de extensión personalizada respondió con notificaciones que contienen una clave null o vacía.
1003027	CustomExtensionConnectionError	Error al conectarse a la API de la extensión personalizada.

Llamar directamente a la API de REST

La API de REST está protegida por el token de acceso de Microsoft Entra. Puede probar la API mediante:

• La obtención de un token de acceso con el registro de aplicación asociado a las extensiones de autenticación personalizadas
• Prueba la API localmente mediante una herramienta de prueba de API.

Herramientas para pruebas de API

1. Para fines de desarrollo y pruebas, abra local.settings.json y reemplace el código por el siguiente JSON:

   {
     "IsEncrypted": false,
     "Values": {
       "AzureWebJobsStorage": "",
       "AzureWebJobsSecretStorageType": "files",
       "FUNCTIONS_WORKER_RUNTIME": "dotnet",
       "AuthenticationEvents__BypassTokenValidation" : false
     }
   }
   

   Nota:

   Si usó el paquete NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents, asegúrese de establecer "AuthenticationEvents__BypassTokenValidation" : true con fines de prueba.

2. Con la herramienta de prueba de API preferida, cree una nueva solicitud HTTP y establezca el método HTTP en POST.

3. Use el siguiente cuerpo JSON que imita la solicitud que Microsoft Entra ID envía a la API de REST.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
           "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
           "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
           "authenticationContext": {
               "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                   "mail": "casey@contoso.com",
                   "onPremisesSamAccountName": "Casey Jensen",
                   "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                   "onPremisesUserPrincipalName": "Casey Jensen",
                   "preferredLanguage": "en-us",
                   "surname": "Jensen",
                   "userPrincipalName": "casey@contoso.com",
                   "userType": "Member"
               }
           }
       }
   }
   

   Sugerencia

   Si usa un token de acceso obtenido de Microsoft Entra ID, seleccione Autorización y, a continuación, seleccione Token de portadory pegue el token de acceso que recibió de Microsoft Entra ID.

4. Seleccione Enviar y debería recibir una respuesta JSON similar a la siguiente:

   {
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                   "claims": {
                       "customClaim1": "customClaimValue1",
                       "customClaim2": [
                           "customClaimString1",
                           "customClaimString2" 
                       ]
                   }
               }
   
           ]
       }
   }
   

Obtención de un token de acceso

Después de adquirir un token de acceso, pase el encabezado HTTP Authorization. Para obtener un token de acceso, siga estos pasos:

1. Inicie sesión en el Centro de administración de Microsoft Entra como Administrador de aplicaciones en la nube.

2. Vaya aIdentidad>Aplicaciones>Registros de aplicaciones.

3. Seleccione el registro de la aplicación de la API de eventos de autenticación de Azure Functions, configurado previamente en configuración de un proveedor de notificaciones personalizado para un evento de emisión de tokens.

4. Copie el id. de la aplicación.

5. Si no ha creado un secreto de aplicación, siga estos pasos:

   1. Seleccione Certificates & secrets>Client secrets>New client secret (Certificados y secretos > Secretos de cliente > Nuevo secreto de cliente).
   2. Agregue una descripción para el secreto de cliente.
   3. Seleccione una expiración para el secreto o especifique una duración personalizada.
   4. Seleccione Agregar.
   5. Registre el valor del secreto para usarlo en el código de la aplicación cliente. Este valor secreto no se volverá a mostrar una vez que abandone esta página.

6. En el menú, seleccione Exponer una API y copie el valor del identificador URI de la aplicación. Por ejemplo, api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444.

7. Abre la herramienta de prueba de API preferida y crea una consulta HTTP.

8. Cambie el método HTTP a POST.

9. Escriba la siguiente dirección URL. Reemplace {tenantID} con su identificador de inquilino.

   https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
   

10. En Cuerpo, seleccione formulario de datos y agregue las siguientes claves:

    Clave	Valor
    grant_type	client_credentials
    client_id	El Id. de cliente de la aplicación.
    client_secret	El secreto de cliente de la aplicación.
    scope	El identificador URI de la aplicación y, a continuación, agregue .default. Por ejemplo: api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default

11. Ejecute la consulta HTTP y copie el access_token en la aplicación web https://jwt.ms.

12. Compare el iss con el nombre del emisor que configuró en la API.

13. Compare el aud con el Id. de cliente que configuró en la API.

Mejoras importantes del rendimiento

Uno de los problemas más comunes es que la API del proveedor de notificaciones personalizado no responde dentro del tiempo de espera de dos segundos. Si la API de REST no responde en reintentos posteriores, se produce un error en la autenticación. Para mejorar el rendimiento de la API de REST, siga estas sugerencias:

1. Si la API accede a cualquier API de bajada, almacene en caché el token de acceso usado para llamar a estas API para que no sea necesario tener que adquirir un nuevo token en cada ejecución.
2. Los problemas de rendimiento suelen estar relacionados con los servicios de bajada. Agregue el registro, que registrará el tiempo del proceso para llamar a cualquier servicio de bajada.
3. Si usa un proveedor de nube para hospedar la API, use un plan de hospedaje que mantenga la API siempre "activa". Para Azure Functions, puede ser el plan Premium o el plan Dedicado.
4. Ejecute pruebas de integración automatizadas para las autenticaciones. También puedes usar las herramientas de prueba de API para probar solo el rendimiento de la API.

Consulte también

• Creación de una API de REST con un evento de inicio de emisión de tokens
• Configuración de una aplicación SAML para recibir tokens con notificaciones de un almacén externo
• Artículo de referencia del proveedor de notificaciones personalizado.