Recuperar y devolver datos de un evento OnAttributeCollectionStart

Se aplica a: Inquilinos externos (más información)

Para modificar la experiencia de inscripción para los flujos de usuario de autoservicio para clientes, puede crear una extensión de autenticación personalizada e invocarla en puntos específicos del proceso. El evento OnAttributeCollectionStart se produce al principio del paso de colección de atributos, antes de que se represente la página de colección de atributos. Este evento permite definir acciones antes de recopilar atributos del usuario. Por ejemplo, puede impedir que un usuario continúe con el flujo de registro en función de su identidad federada o correo electrónico, o bien rellenar previamente atributos con valores especificados. Se pueden configurar las siguientes acciones:

• continueWithDefaultBehavior : represente la página de la colección de atributos como de costumbre.
• setPreFillValues : atributos de prerrellenar en el formulario de registro.
• showBlockPage : muestra un mensaje de error y impide que el usuario se registre.

En este artículo se describe el esquema de la API REST para el evento OnAttributeCollectionStart. (Vea también el artículo relacionado Extensión personalizada para el evento OnAttributeCollectionSubmit).

Esquema de la API REST

Para desarrollar su propia API REST para el evento de inicio de la recopilación de atributos, 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 de autenticación personalizada en microsoft Entra ID realiza una llamada HTTP a la API 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 a la que el usuario quiere iniciar sesión. La API puede usar los atributos JSON para realizar lógica adicional.

Solicitud a la API REST externa

La solicitud a la API REST tiene el formato que se muestra a continuación. En este ejemplo, la solicitud incluye información de identidades de usuario junto con atributos integrados (givenName y companyName) y atributos personalizados (universityGroups, graduaciónYear y onMailingList).

La solicitud contiene los atributos de usuario seleccionados en el flujo de usuario para la recopilación durante el registro de autoservicio, incluidos los atributos integrados (por ejemplo, givenName y companyName) y los atributos personalizados que ya se han definido (por ejemplo, universityGroups, graduaciónYear y onMailingList). La API REST no puede agregar nuevos atributos.

La solicitud también contiene identidades de usuario, incluido el correo electrónico del usuario si se usó como credencial comprobada para registrarse. No se envía la contraseña.

Los atributos de la solicitud de inicio contienen sus valores predeterminados. En el caso de los atributos con varios valores, los valores se envían como una cadena delimitada por comas. Dado que los atributos aún no se han recopilado del usuario, la mayoría de los atributos no tendrán valores asignados. La siguiente solicitud HTTP muestra cómo Microsoft Entra invoca la API REST.

POST https://example.azureWebsites.net/api/functionName

Content-Type: application/json

[Request payload]

En el siguiente documento JSON se proporciona un ejemplo de una carga de solicitud:

{
  "type": "microsoft.graph.authenticationEvent.attributeCollectionStart",
  "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartCalloutData",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "authenticationEventListenerId": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "customAuthenticationExtensionId": "11112222-bbbb-3333-cccc-4444dddd5555",
    "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"
        }
    },
    "userSignUpInfo": {
      "attributes": {
        "givenName": {
          "@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Larissa Price",
          "attributeType": "builtIn"
        },
        "companyName": {
          "@odata.type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Contoso University",
          "attributeType": "builtIn"
        },
        "extension_<appid>_universityGroups": {
          "@odata.Type": "microsoft.graph.stringDirectoryAttributeValue",
          "value": "Alumni,Faculty",
          "attributeType": "directorySchemaExtension"
        },
        "extension_<appid>_graduationYear": {
          "@odata.type": "microsoft.graph.int64DirectoryAttributeValue",
          "value": 2010,
          "attributeType": "directorySchemaExtension"
        },
        "extension_<appid>_onMailingList": {
          "@odata.type": "microsoft.graph.booleanDirectoryAttributeValue",
          "value": false,
          "attributeType": "directorySchemaExtension"
        }
      },
      "identities": [
        {
          "signInType": "email",
          "issuer": "contoso.onmicrosoft.com",
          "issuerAssignedId": "larissa.price@contoso.onmicrosoft.com"
        }
      ]
    }
  }
}

Respuesta de la API REST externa

Los tipos de valor de respuesta coinciden con los tipos de valor de solicitud, por ejemplo:

• Si la solicitud contiene un atributo graduationYear con un @odata.type de int64DirectoryAttributeValue, la respuesta debe incluir un atributo con un graduationYear valor entero, como 2010.
• Si la solicitud contiene un atributo con varios valores especificados como una cadena delimitada por comas, la respuesta debe contener los valores de una cadena delimitada por comas.

Microsoft Entra ID espera una respuesta de la API REST en el formato siguiente.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

En la respuesta HTTP, proporcione uno de los siguientes documentos JSON. La acción continueWithDefaultBehavior especifica que la API REST externa devuelve una respuesta de continuación.

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.continueWithDefaultBehavior"
      }
    ]
  }
}

La acción setPrefillValues especifica que la API REST externa devuelve una respuesta a los atributos de prerrellenar con valores predeterminados. La API REST no puede agregar nuevos atributos. Se omiten los atributos adicionales que se devuelven, pero que no forman parte de la colección de atributos.

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "key1": "value1,value2,value3",
          "key2": true
        }
      }
    ]
  }
}

La acción showBlockPage especifica que la API REST externa devuelve una respuesta de bloqueo.

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.showBlockPage",
        "title": "Hold tight...",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}