Personalización de notificaciones mediante la directiva de notificaciones personalizadas de Microsoft Graph (versión preliminar)

  • Artículo

Una notificación es información que un proveedor de identidades declara sobre un usuario dentro del token que se emite para dicho usuario. Los administradores de inquilinos usan la personalización de notificaciones para personalizar las notificaciones que se emiten en tokens para una aplicación específica de su inquilino. La personalización de notificaciones admite la configuración de notificaciones para aplicaciones mediante los protocolos SAML, OAuth y OpenID Connect. Puede usar la personalización de notificaciones para lo siguiente:

  • Seleccionar las notificaciones que se incluyen en tokens.
  • Crear tipos de notificación que aún no existen.
  • Elegir o cambiar el origen de los datos emitidos en notificaciones concretas.

En esta guía paso a paso se abordan algunos escenarios comunes que pueden ayudarle a entender cómo usar la directiva de notificaciones personalizadas.

Requisitos previos

Personalización de notificaciones de Microsoft Entra ID

Microsoft Entra ID admite dos maneras de personalizar las notificaciones mediante Microsoft Graph o PowerShell para las aplicaciones:

En los ejemplos siguientes, va a crear, actualizar y reemplazar las directivas de entidades de servicio. Las directivas de notificaciones personalizadas siempre están vinculadas a objetos de una entidad de servicio. Asegúrese de que ha configurado la aplicación empresarial como parte de los requisitos previos antes de crear una directiva de notificaciones personalizadas para la aplicación o la entidad de servicio.

Abra Microsoft Graph Explorer en el explorador, inicie sesión en el explorador de Microsoft Graph Explorer como al menos administrador de aplicaciones y elija uno de los escenarios siguientes.

Después de crear una directiva de notificaciones personalizadas, configure la aplicación para que reconozca que los tokens contienen notificaciones personalizadas. Para obtener más información, consulte las consideraciones sobre seguridad.

Omisión de las notificaciones básicas de los tokens

En este ejemplo se crea una directiva de notificaciones personalizadas que quita el conjunto de notificaciones básicas de los tokens emitidos para entidades de servicio vinculadas.

  1. En Microsoft Graph Explorer, identifique la aplicación para la que desea configurar la directiva de notificaciones personalizadas para usar la API de entidad de servicio.

  2. Cree la directiva de notificaciones personalizadas mediante la ejecución de la siguiente API. Esta directiva, vinculada a una entidad de servicio, omite las notificaciones básicas de los tokens.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Cuerpo de la solicitud:

    {
    "includeBasicClaimSet": false
}

  3. Para ver la nueva directiva, ejecute el siguiente comando

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Respuesta:

    HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222.",
    "includeBasicClaimSet": false,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": []
}

Incorporación de EmployeeID y TenantCountry como reclamaciones en tokens

En este ejemplo, creará una personalización de las notificaciones que agrega EmployeeID y TenantCountry a los tokens. En este ejemplo se incluye también el conjunto de notificaciones básicas en los tokens.

  1. En Microsoft Graph Explorer, identifique la aplicación para la que desea configurar la directiva de notificaciones personalizadas para usar la API de entidad de servicio.

  2. Cree la directiva de notificaciones personalizadas mediante la ejecución de la siguiente API. Esta directiva, que se vincula a una entidad de servicio agrega las notificaciones EmployeeID y TenantCountry a los tokens.

    PUT https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Cuerpo de la solicitud:

    {
    "includeBasicClaimSet": true,
    "claims": [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "employeeId",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " employeeid",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        },
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "country",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": [
                {
                    "condition": null,
                    "attribute": {
                        "@odata.type": "#microsoft.graph.sourcedAttribute",
                        "id": " tenantcountry",
                        "source": "user",
                        "isExtensionAttribute": false
                    },
                    "transformations": []
                }
            ]
        }
    ]
}

  3. Para ver la nueva directiva, ejecute el siguiente comando:

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Respuesta:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Uso de una transformación de notificaciones en los tokens

En este ejemplo se actualiza una directiva para emitir una notificación "JoinedData" personalizada para los tokens JWT emitidos para entidades de servicio vinculadas. Esta notificación contiene un valor creado mediante la combinación de los datos almacenados en el atributo extensionattribute1 en el objeto de usuario que incluye "-ext". En este ejemplo se excluye el conjunto de notificaciones básicas en los tokens.

  1. En Microsoft Graph Explorer, identifique la aplicación para la que desea configurar la directiva de notificaciones personalizadas para usar la API de entidad de servicio.

  2. Cree la directiva de notificaciones personalizadas mediante la ejecución de la siguiente API. Esta directiva emite una notificación personalizada JoinedData a los tokens.

    PATCH https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Cuerpo de la solicitud:

    {
    "includeBasicClaimSet": true,
    "claims": 
    [
        {
            "@odata.type": "#microsoft.graph.customClaim",
            "name": "JoinedData",
            "namespace": null,
            "tokenFormat": [
                "jwt"
            ],
            "samlAttributeNameFormat": null,
            "configurations": 
            [
                {
                    "condition": null,
                    "attribute": null,
                    "transformations": 
                    [
                        {
                            "@odata.type": "#microsoft.graph.joinTransformation",
                            "separator": "-",
                            "input": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type": "#microsoft.graph.sourcedAttribute",
                                    "id": "extensionattribute1",
                                    "source": "user",
                                    "isExtensionAttribute": false
                                }
                            },
                            "input2": 
                            {
                                "treatAsMultiValue": false,
                                "attribute": 
                                {
                                    "@odata.type":"#microsoft.graph.valueBasedAttribute",
                                    "value": "ext"
                                 }
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

    Nota:

    La directiva de notificaciones personalizadas es una directiva tipada fuertemente y cada transformación usa un valor de @odata.type diferente.

  3. Para ver la nueva directiva y obtener su ObjectId, ejecute el siguiente comando:

    GET https://graph.microsoft.com/beta/servicePrincipals/<servicePrincipal-id>/claimsPolicy

    Respuesta:

    {
    "@odata.context": "…",
    "id": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "includeBasicClaimSet": true,
    "includeApplicationIdInIssuer": false,
    "audienceOverride": null,
    "groupFilter": null,
    "claims": [...]
}

Contenido relacionado