Partilhar via

Recuperar e retornar dados de um evento OnAttributeCollectionSubmit

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

Para modificar a experiência de inscrição para seus fluxos de usuário de inscrição de autoatendimento do cliente, você pode criar uma extensão de autenticação personalizada e invocá-la em pontos específicos do fluxo de usuário. O evento OnAttributeCollectionSubmit ocorre depois que o usuário insere e envia atributos e pode ser usado para validar as informações fornecidas pelo usuário. Por exemplo, você pode validar um código de convite ou número de parceiro, modificar um formato de endereço, permitir que o usuário continue ou mostrar uma página de validação ou bloqueio. As seguintes ações podem ser configuradas:

  • continueWithDefaultBehavior - Continue com o processo de inscrição.
  • modifyAttributeValues - Substitua os valores enviados pelo usuário no formulário de inscrição.
  • showValidationError - Retorna um erro com base nos valores enviados.
  • showBlockPage - Mostrar uma mensagem de erro e bloquear o usuário de se inscrever.

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

Esquema da API REST

Para desenvolver sua própria API REST para o evento de envio 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.

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

Solicitação à API REST externa

A solicitação para sua API REST está no formato mostrado no exemplo a seguir. 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. Estão incluídos atributos internos (por exemplo, givenName e companyName) e atributos personalizados já 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 e-mail do usuário se ele foi usado como uma credencial verificada para se inscrever. A palavra-passe não é enviada. Para atributos com vários valores, os valores são enviados como uma cadeia de caracteres delimitada por vírgula. 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 uma carga útil de solicitação:

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

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 delimitada por vírgula.

O Microsoft Entra ID espera uma resposta da API REST no seguinte formato.

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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.continueWithDefaultBehavior"
      }
    ]
  }
}

A ação modifyAttributeValues especifica que sua API REST externa retorna uma resposta para modificar e substituir atributos por valores padrão depois que os atributos são coletados. 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.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "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.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."
      }
    ]
  }
}

A ação showValidationError especifica que sua API REST está retornando um erro de validação e uma mensagem e um código de status apropriados.

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