Compartilhar via

Recuperar e retornar dados de um evento OnAttributeCollectionStart

Aplica-se a: Círculo verde com um símbolo de marca de seleção branca que indica que o conteúdo a seguir se aplica a locatários externos. Locatários externos (saiba mais)

Para modificar a experiência de cadastro para os fluxos de cadastramento de autoatendimento para clientes, você pode criar uma extensão de autenticação personalizada e integrá-la em pontos específicos do fluxo de usuários. O evento OnAttributeCollectionStart ocorre no início da etapa de coleção de atributos, antes que a página da coleção de atributos seja renderizada. Esse evento permite que você defina ações antes que os atributos sejam coletados do usuário. Por exemplo, você pode impedir que um usuário continue o fluxo de inscrição com base em sua identidade federada, email ou atributos de pré-preenchimento com valores especificados. As seguintes ações podem ser configuradas:

  • continueWithDefaultBehavior – Renderiza a página de coleção de atributos como de costume.
  • setPreFillValues – Preenche previamente atributos no formulário de inscrição.
  • showBlockPage – Mostra uma mensagem de erro e impedir que o usuário se inscreva.

Este artigo descreve o esquema da API REST para o evento OnAttributeCollectionStart. (Consulte também o artigo relacionado sobre a Extensão Personalizada para o evento OnAttributeCollectionSubmit.)

Esquema da API REST

Para desenvolver sua própria API REST para o evento de início da coleção de atributos, use o seguinte contrato de dados da API REST. O esquema descreve o contrato para projetar o manipulador de solicitação e resposta.

Sua extensão de autenticação personalizada no Microsoft Entra ID realiza uma chamada HTTP para sua API REST com um payload JSON. O conteúdo JSON contém dados de perfil do usuário, atributos de contexto de autenticação e informações sobre o aplicativo ao qual o usuário deseja entrar. Os atributos JSON podem ser usados para executar lógica extra por sua API.

Solicitação para a API REST externa

A solicitação para sua API REST está no formato mostrado abaixo. Neste exemplo, a solicitação inclui informações de identidades de usuário, juntamente com atributos internos (givenName e companyName) e atributos personalizados (universityGroups, graduationYear e onMailingList).

A solicitação contém os atributos de usuário selecionados no fluxo de usuário para coleta durante a inscrição de autoatendimento, incluindo atributos internos (por exemplo, givenName e companyName) e atributos personalizados que já foram definidos (por exemplo, universityGroups, graduationYear e onMailingList). Sua API REST não pode adicionar novos atributos.

A solicitação também contém identidades de usuário, incluindo o email do usuário se ele foi usado como uma credencial verificada para se inscrever. A senha não é enviada.

Os atributos na solicitação inicial contêm seus valores padrão. Para atributos com vários valores, os valores são enviados como uma cadeia de caracteres delimitada por vírgulas. Como os atributos ainda não foram coletados do usuário, a maioria dos atributos não terá valores atribuídos. A solicitação HTTP a seguir demonstra como o Microsoft Entra invoca sua API REST.

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

Content-Type: application/json

[Request payload]

O documento JSON a seguir fornece um exemplo de conteúdo de solicitação:

{
  "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"
        }
      ]
    }
  }
}

Resposta da API REST externa

Os tipos de valor de resposta correspondem aos tipos de valor de solicitação, por exemplo:

  • Se a solicitação contiver um atributo graduationYear com um @odata.type de int64DirectoryAttributeValue, a resposta deverá incluir um graduationYear atributo com um valor inteiro, como 2010.
  • Se a solicitação contiver um atributo com vários valores especificados como uma cadeia de caracteres delimitada por vírgula, a resposta deverá conter os valores em uma cadeia de caracteres delimitada por vírgulas.

A ID do Microsoft Entra espera uma resposta da API REST no formato a seguir.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

Na resposta HTTP, forneça um dos seguintes documentos JSON. A ação continueWithDefaultBehavior especifica que sua API REST externa está retornando uma resposta de continuação.

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

A ação setPrefillValues especifica que a API REST externa está retornando uma resposta aos atributos de pré-preenchimento com valores padrão. Sua API REST não pode adicionar novos atributos. Todos os atributos extras retornados, mas que não fazem parte da coleção de atributos, são ignorados.

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

A ação showBlockPage especifica que sua API REST externa está retornando uma resposta de bloqueio.

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