Extensión personalizada para la referencia de eventos OnAttributeCollectionSubmit (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 OnAttributeCollectionSubmit se produce después de que el usuario escriba y envíe atributos y puede usarse para validar la información que proporciona el usuario. Por ejemplo, puede validar un código de invitación o un número de asociado, modificar un formato de dirección, permitir que el usuario continúe o mostrar una página de validación o bloqueo. Se pueden configurar las siguientes acciones:

• continueWithDefaultBehavior: continúa con el flujo de registro.
• modifyAttributeValues: sobrescribe los valores que el usuario envió en el formulario de registro.
• showValidationError: devuelve un error basado en los valores enviados.
• showBlockPage: muestra un mensaje de error e impide que el usuario se registre.

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

Sugerencia

Para probar esta característica, vaya a la demostración de Woodgrove Groceries e inicie el caso de uso "Validar atributos de registro" o "Impedir que un usuario continúe con el proceso de registro".

Esquema de API REST

Para desarrollar su propia API de REST para el evento de envío 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. En el caso de los atributos con varios valores, los valores se envían como una cadena delimitada por comas.

JSON

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

{
  "type": "microsoft.graph.authenticationEvent.attributeCollectionSubmit",
  "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/<resourceAppguid>",
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitCalloutData",
    "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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
      }
    ]
  }
}

La acción modifyAttributeValues especifica que la API de REST externa devuelve una respuesta para modificar e invalidar atributos con valores predeterminados después de recopilar los atributos. 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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showBlockPage",
        "title": "Hold tight...",
        "message": "Your access request is already processing. You'll be notified when your request has been approved."
      }
    ]
  }
}

La acción showValidationError especifica que la API de REST devuelve un error de validación y un mensaje y código de estado adecuados.

HTTP/1.1 200 OK

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.showValidationError",
        "message": "Please fix the below errors to proceed.",
        "attributeErrors": {
          "city": "City cannot contain any numbers",
          "extension_<appid>_graduationYear": "Graduation year must be at least 4 digits"
        }
      }
    ]
  }
}