Extensión personalizada para la referencia de eventos OnAttributeCollectionStart (versión preliminar)

Se aplica a: inquilinos de personal inquilinos externos (más información)

Para modificar la experiencia de registro para los flujos de usuario de registro de autoservicio del cliente, puede crear una extensión de autenticación personalizada e invocarla en puntos específicos del flujo de usuario. 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: representar la página de la colección de atributos como de costumbre.
• setPreFillValues: rellena previamente atributos en el formulario de registro.
• showBlockPage: mostrar un mensaje de error e impedir que el usuario se registre.

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

Sugerencia

Para probar esta característica, vaya a la demostración de Woodgrove Groceries e inicie el caso de uso "Relleno previo de atributos de registro".

Esquema de API REST

Para desarrollar su propia API de REST para el evento de inicio de recopilación de atributos, use el siguiente contrato de datos de la API de 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 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. La API puede usar los atributos JSON para realizar lógica adicional.

Solicitud a la API de REST externa

La solicitud a la API de REST tiene el formato que se muestra a continuación. En este ejemplo, la solicitud incluye información de las identidades de usuarios 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 de 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.

JSON

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

{
  "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 de REST externa

Microsoft Entra ID espera una respuesta de la API de REST en el formato siguiente. Los tipos de valor de la respuesta coinciden con los tipos de valor de la solicitud, por ejemplo:

• Si la solicitud contiene un atributo graduationYear con un @odata.type de int64DirectoryAttributeValue, la respuesta debe incluir un atributo graduationYear con un 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.

La acción continueWithDefaultBehavior especifica que la API de REST externa devuelve una respuesta de continuación.

HTTP/1.1 200 OK

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

La acción setPrefillValues especifica que la API de REST externa devuelve una respuesta para prerrellenar los atributos con valores predeterminados. La API de 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.

HTTP/1.1 200 OK

{
  "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 de REST externa devuelve una respuesta de bloqueo.

HTTP/1.1 200 OK

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