Solución de 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 de proveedor de declaraciones personalizada y configurar una aplicación OpenID Connect para recibir tokens con declaraciones de un almacén externo.

Error behavior

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. To troubleshoot, check the sign-in logs for the error codes.

Logging

Para solucionar problemas con el endpoint de la API REST del proveedor de reclamaciones personalizado, la API REST debe gestionar el registro de eventos. 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

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, puedes encontrar errores que podrían afectar los inicios 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 que ocurrieron cuando la API fue llamada por Microsoft Entra ID.

Microsoft Entra sign-in logs also integrate with 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 al menos Administrador de aplicaciones en la nube.

  2. Browse to Entra ID>Enterprise apps.

  3. Select Sign-in logs, and then select the latest sign-in log.

  4. For more details, select the Authentication Events tab. Information related to the custom authentication extension REST API call is displayed, including any error codes.

    Captura de pantalla que muestra la información de eventos de autenticación.

Referencia de los códigos de error

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

Error code Error name Description
1003000 EventHandlerUnexpectedError Error inesperado al procesar un controlador de eventos.
1003001 CustomExtensionUnexpectedError 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 The identifierUris property in the manifest for the application registration for the custom extension, should be in the format of "api://{fully qualified domain name}/{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 reclamaciones en la respuesta de la extensión personalizada superó el límite máximo.
1003026 CustomExtensionNullOrEmptyClaimKeyNotSupported La API de extensión personalizada respondió con reclamaciones 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:

  • Obtaining an access token with an application registration associated with the custom authentication extensions
  • Prueba la API localmente mediante una herramienta de prueba de API.
  1. For local development and testing purposes, open local.settings.json and replace the code with the following JSON:

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

    Note

    If you used the Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet package, be sure to set "AuthenticationEvents__BypassTokenValidation" : true for local testing purposes.

  2. Using your preferred API testing tool, create a new HTTP request and set the HTTP method to 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": "[email protected]",
                    "onPremisesSamAccountName": "Casey Jensen",
                    "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                    "onPremisesUserPrincipalName": "Casey Jensen",
                    "preferredLanguage": "en-us",
                    "surname": "Jensen",
                    "userPrincipalName": "[email protected]",
                    "userType": "Member"
                }
            }
        }
    }
    

    Tip

    If you're using an access token obtained from Microsoft Entra ID, select Authorization and then select Bearer token, then paste the access token you received from Microsoft Entra ID.

  4. Select Send, and you should receive a JSON response similar to the following:

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

Mejoras importantes del rendimiento

Uno de los problemas más comunes es que la API del proveedor de declaraciones 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.

See also