Compartir a través de

Solución de problemas de la API del proveedor de notificaciones personalizado

  • Artículo

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.

    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.

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.

  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" 
                    ]
                }
            }

        ]
    }
}

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