Pobieranie i zwracanie danych ze zdarzenia OnAttributeCollectionSubmit

Dotyczy: Najemcy zewnętrzni (dowiedz się więcej)

Aby zmodyfikować proces rejestracji dla samoobsługowych ścieżek rejestracji klientów, możesz utworzyć niestandardowe rozszerzenie uwierzytelniania i wywołać je w określonych punktach ścieżki użytkownika. Zdarzenie OnAttributeCollectionSubmit występuje po wprowadzeniu i przesłaniu atrybutów przez użytkownika i może służyć do weryfikowania informacji dostarczonych przez użytkownika. Możesz na przykład zweryfikować kod zaproszenia lub numer partnera, zmodyfikować format adresu, zezwolić użytkownikowi na kontynuowanie lub pokazać stronę sprawdzania poprawności lub blokowania. Można skonfigurować następujące akcje:

• continueWithDefaultBehavior: kontynuuj przebieg procesu rejestracji.
• modifyAttributeValues — zastępowanie wartości przesłanych przez użytkownika w formularzu rejestracji.
• showValidationError — zwraca błąd na podstawie przesłanych wartości.
• showBlockPage — umożliwia wyświetlenie komunikatu o błędzie i zablokowanie rejestracji użytkownika.

W tym artykule opisano schemat interfejsu API REST dla zdarzenia OnAttributeCollectionSubmit. (Zobacz również powiązany artykuł Custom Extension for OnAttributeCollectionStart event(Rozszerzenie niestandardowe dla zdarzenia OnAttributeCollectionStart).

Schemat API REST

Aby opracować własny interfejs API REST dla zdarzenia przesyłania kolekcji atrybutów, użyj następującego kontraktu danych interfejsu API REST. Schemat opisuje kontrakt do projektowania procedury obsługi żądań i odpowiedzi.

Niestandardowe rozszerzenie uwierzytelniania w identyfikatorze Entra firmy Microsoft wykonuje wywołanie HTTP do interfejsu API REST za pomocą ładunku JSON. Ładunek JSON zawiera dane profilu użytkownika, atrybuty kontekstu uwierzytelniania i informacje o aplikacji, do której użytkownik chce się zalogować. Atrybuty JSON mogą służyć do wykonywania dodatkowej logiki przez interfejs API.

Żądanie do zewnętrznego interfejsu API REST

Żądanie do interfejsu API REST jest w formacie pokazanym w poniższym przykładzie. W tym przykładzie żądanie zawiera informacje o tożsamościach użytkowników wraz z wbudowanymi atrybutami (givenName i companyName) oraz atrybutami niestandardowymi (universityGroups, graduationYear i onMailingList).

Żądanie zawiera atrybuty użytkownika wybrane w przepływie użytkownika do zbierania podczas rejestracji samoobsługowej. Uwzględnione są wbudowane atrybuty (na przykład givenName i companyName) oraz atrybuty niestandardowe już zdefiniowane (na przykład universityGroups, graduationYear i onMailingList). Interfejs API REST nie może dodawać nowych atrybutów.

Żądanie zawiera również tożsamości użytkowników, w tym adres e-mail użytkownika, jeśli został użyty jako zweryfikowane poświadczenie do zarejestrowania się. Hasło nie jest wysyłane. W przypadku atrybutów z wieloma wartościami wartości są wysyłane jako ciąg rozdzielany przecinkami. Następujące żądanie HTTP pokazuje, jak Microsoft Entra wywołuje interfejs API REST.

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

Content-Type: application/json

[Request payload]

Poniższy dokument JSON zawiera przykład ładunku żądania:

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

Odpowiedź z zewnętrznego interfejsu API REST

Typy wartości odpowiedzi są zgodne z typami wartości żądania, na przykład:

• Jeśli żądanie zawiera atrybut graduationYear o @odata.typeint64DirectoryAttributeValue, odpowiedź powinna zawierać atrybut graduationYear z wartością całkowitą, taką jak 2010.
• Jeśli żądanie zawiera atrybut z wieloma wartościami określonymi jako ciąg rozdzielany przecinkami, odpowiedź powinna zawierać wartości w ciągu rozdzielanym przecinkami.

Identyfikator Entra firmy Microsoft oczekuje odpowiedzi interfejsu API REST w następującym formacie.

HTTP/1.1 200 OK

Content-Type: application/json

[JSON document]

W odpowiedzi HTTP podaj jeden z następujących dokumentów JSON. Akcja continueWithDefaultBehavior określa, że zewnętrzny interfejs API REST zwraca odpowiedź kontynuacji.

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

Akcja modifyAttributeValues określa, że zewnętrzny interfejs API REST zwraca odpowiedź na modyfikowanie i zastępowanie atrybutów wartościami domyślnymi po zebraniu atrybutów. Interfejs API REST nie może dodawać nowych atrybutów. Wszystkie dodatkowe atrybuty, które są zwracane, ale nie są częścią kolekcji atrybutów, są ignorowane.

{
  "data": {
    "@odata.type": "microsoft.graph.onAttributeCollectionSubmitResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionSubmit.modifyAttributeValues",
        "attributes": {
          "key1": "value1,value2,value3",
          "key2": true
        }
      }
    ]
  }
}

Akcja showBlockPage określa, że zewnętrzny interfejs API REST zwraca odpowiedź blokującą.

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

Akcja showValidationError określa, że interfejs API REST zwraca błąd weryfikacji oraz odpowiedni komunikat i kod stanu.

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