Compartir a través de

Recuperar y devolver datos de un evento OnAttributeCollectionSubmit

Se aplica a: Círculo verde con un símbolo de marca de verificación blanca que indica que el siguiente contenido se aplica a los inquilinos externos. Inquilinos externos (más información)

Para modificar la experiencia de registro en los flujos de usuario 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 se pueda usar para validar la información proporcionada por 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úe con el proceso 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 y impide que el usuario se registre.

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

Esquema de la API REST

Para desarrollar su propia API REST para el evento de envío de 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 hace una llamada HTTP a tu 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 en el ejemplo siguiente. 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. Se incluyen atributos integrados (por ejemplo, givenName y companyName) y atributos personalizados ya definidos (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. En el caso de los atributos con varios valores, los valores se envían como una cadena delimitada por comas. 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.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 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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
      }
    ]
  }
}

La acción modifyAttributeValues especifica que la API REST externa devuelve una respuesta para modificar e invalidar atributos con valores predeterminados después de recopilar los atributos. 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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "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.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 REST devuelve un error de validación y un mensaje y código de estado adecuados.

{
  "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"
        }
      }
    ]
  }
}
  • Last updated on