Referencia del proveedor de notificaciones personalizado

Artículo
03/19/2024

En este artículo de referencia, puede obtener información sobre el esquema de la API REST y la estructura de las directivas de asignación de notificaciones para eventos del proveedor de notificaciones personalizadas.

Evento de inicio de emisión de tokens

El evento de emisión de tokens del proveedor de notificaciones personalizadas permite enriquecer o personalizar tokens de aplicación con información de sistemas externos. Esta es información que no se puede almacenar como parte del perfil de usuario en el directorio de Microsoft Entra.

Información general sobre los componentes

Para configurar e integrar una extensión personalizada con la aplicación, es necesario conectar varios componentes. En el diagrama siguiente se muestra una vista general de los puntos de configuración y las relaciones que se crean para implementar una extensión personalizada.

Debe tener un punto de conexión de API REST disponible públicamente. En este diagrama, se representa mediante la función de Azure. La API REST genera y devuelve notificaciones personalizadas a la extensión personalizada. Está asociado a un registro de aplicación de Microsoft Entra.
Debe configurar una extensión personalizada en Microsoft Entra ID, que está configurada para conectarse a la API.
Necesita una aplicación que reciba los tokens personalizados. Por ejemplo, https://jwt.ms, una aplicación web propiedad de Microsoft que muestra el contenido descodificado de un token.
La aplicación, como https://jwt.ms, debe registrarse en Microsoft Entra ID mediante el registro de aplicaciones.
Debe crear una asociación entre la aplicación y la extensión personalizada.
De manera opcional, puede proteger la función de Azure con un proveedor de autenticación; en este artículo se usa Microsoft Entra ID.

REST API

El punto de conexión de la API REST es responsable de interactuar con los servicios de bajada. Por ejemplo, bases de datos, otras API REST, directorios LDAP o cualquier otro almacén que contenga los atributos que quiera agregar a la configuración del token.

La API de REST devuelve una respuesta HTTP a Microsoft Entra ID que contiene los atributos. Los atributos que devuelve la API REST no se agregan automáticamente a un token. En su lugar, la directiva de asignación de notificaciones de una aplicación debe configurarse para que cualquier atributo se incluya en el token. En Microsoft Entra ID, una directiva de asignación de notificaciones modifica las notificaciones enviadas en tokens emitidos para aplicaciones específicas.

Esquema de API REST

Para desarrollar su propia API REST para el evento de inicio de emisión de tokens, use el siguiente contrato de datos de la API REST. El esquema describe el contrato para diseñar el controlador de solicitud y respuesta.

La extensión personalizada en Microsoft Entra ID hace una llamada HTTP a la API de REST con una carga JSON. La carga JSON contiene datos de perfil de usuario, atributos de contexto de autenticación e información sobre la aplicación en la que el usuario quiere iniciar sesión. El valor id en el JSON siguiente es una aplicación de Microsoft que representa el servicio de eventos de autenticación de Microsoft Entra. La API puede usar los atributos JSON para realizar lógica adicional. La solicitud a la API tiene el formato siguiente:

POST https://your-api.com/endpoint

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom extension ID>",
        "authenticationContext": {
            "correlationId": "<GUID>",
            "client": {
                "ip": "30.51.176.110",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2016-03-01T15:23:40Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "caseyjensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

La respuesta de la API REST que Azure espera tiene el siguiente formato, donde las notificaciones DateOfBirth y CustomRoles se devuelven a Azure:

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "DateOfBirth": "01/01/2000",
                    "CustomRoles": [
                        "Writer",
                        "Editor"
                    ]
                }
            }
        ]
    }
}

Cuando un usuario B2B de la organización Fabrikam se autentica en la organización Contoso, la carga de la solicitud enviada a la API REST tiene el elemento user en el siguiente formato:

"user": {
    "companyName": "Fabrikam",
    "createdDateTime": "2022-07-15T00:00:00Z",
    "displayName": "John Wright",
    "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "mail": "johnwright@fabrikam.com",
    "preferredDataLocation": "EUR",
    "userPrincipalName": "johnwright_fabrikam.com#EXT#@contoso.onmicrosoft.com",
    "userType": "Guest"
}

Tipos de datos admitidos

En la tabla siguiente se muestran los tipos de datos admitidos por los proveedores de notificaciones personalizadas para el evento de inicio de emisión de tokens:

Tipo de datos	Compatible
String	True
Matriz de cadena	True
Boolean	False
JSON	False

Limitaciones de tamaño de notificación

El tamaño máximo de notificación que un proveedor de notificaciones puede devolver está limitado a 3KB. Esta es la suma de todos los pares clave y valor devueltos por la API de REST.

Directiva de asignación de notificaciones

En Microsoft Entra ID, una directiva de asignación de notificaciones modifica las notificaciones enviadas en tokens emitidos para aplicaciones específicas. Incluye notificaciones del proveedor de notificaciones personalizadas y las emite en el token.

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "true",
        "ClaimsSchema": [{
            "Source": "CustomClaimsProvider",
            "ID": "dateOfBirth",
            "JwtClaimType": "birthdate"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "customRoles",
            "JwtClaimType": "my_roles"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "correlationId",
            "JwtClaimType": "correlation_Id"
        },
        {
            "Source": "CustomClaimsProvider",
            "ID": "apiVersion",
            "JwtClaimType": "apiVersion"
        },
        {
            "Value": "tokenaug_V2",
            "JwtClaimType": "policy_version"
        }]
    }
}

El elemento ClaimsSchema contiene la lista de notificaciones que se van a asignar con los siguientes atributos:

Source describe el origen del atributo, CustomClaimsProvider. Tenga en cuenta que el último elemento contiene un valor fijo con la versión de la directiva, con fines de prueba. Por lo tanto, se omite el atributo source.
ID es el nombre de las notificaciones según se devuelve de la función de Azure que ha creado.

Importante

El valor del atributo ID distingue mayúsculas de minúsculas. Asegúrese de escribir el nombre de la notificación exactamente como se devolvió en la función de Azure.
JwtClaimType es un nombre opcional de notificación en el token emitido para la aplicación OpenID Connect. Permite proporcionar un nombre diferente que se devuelva en el token de JWT. Por ejemplo, si la respuesta de la API tiene un valor ID de dateOfBirth, se puede emitir como birthdate en el token.

Una vez creada la directiva de asignación de notificaciones, el siguiente paso consiste en cargarla en el inquilino de Microsoft Entra. Use la Graph API claimsMappingPolicy siguiente en el inquilino.

Importante

El elemento definition debe ser una matriz con un único valor de cadena. La cadena debe ser la versión con caracteres de escape y convertida a cadena JSON de la directiva de asignación de notificaciones. Puede usar herramientas como https://jsontostring.com/ para convertir a cadena JSON la directiva de asignación de notificaciones.

Compartir vía