Pobieranie i zwracanie danych ze zdarzenia OnAttributeCollectionStart

Dotyczy: Dzierżawy zewnętrzne (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 OnAttributeCollectionStart występuje na początku kroku kolekcji atrybutów przed renderowaniem strony kolekcji atrybutów. To zdarzenie umożliwia zdefiniowanie akcji przed zebranie atrybutów od użytkownika. Możesz na przykład zablokować użytkownikowi kontynuowanie procesu rejestracji na podstawie jego tożsamości federacyjnej lub adresu e-mail. Możesz także wstępnie wypełnić atrybuty określonymi wartościami. Można skonfigurować następujące akcje:

• continueWithDefaultBehavior — renderuj stronę kolekcji atrybutów w zwykły sposób.
• setPreFillValues — Wprowadź wartości wstępne w formularzu rejestracji.
• showBlockPage — umożliwia wyświetlenie komunikatu o błędzie i zablokowanie rejestracji użytkownika.

W tym artykule opisano schemat interfejsu API REST dla zdarzenia OnAttributeCollectionStart. (Zobacz również powiązany artykuł Niestandardowe rozszerzenie dla zdarzenia OnAttributeCollectionSubmit.)

Schemat API REST

Aby opracować własny interfejs API REST dla zdarzenia rozpoczęcia zbierania 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 poniżej. 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 w trakcie samodzielnej rejestracji, w tym wbudowane atrybuty użytkownika (na przykład givenName i companyName) oraz niestandardowe atrybuty, które zostały 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.

Atrybuty w żądaniu początkowym zawierają ich wartości domyślne. W przypadku atrybutów z wieloma wartościami wartości są wysyłane jako ciąg rozdzielany przecinkami. Ponieważ atrybuty nie zostały jeszcze zebrane od użytkownika, większość atrybutów nie ma przypisanych wartości. Następujące żądanie HTTP pokazuje, jak Microsoft Entra wywołuje Twój 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.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"
        }
      ]
    }
  }
}

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

Akcja setPrefillValues określa, że zewnętrzny interfejs API REST zwraca odpowiedź na wstępnie wypełnione atrybuty z wartościami domyślnymi. 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.onAttributeCollectionStartResponseData",
    "actions": [
      {
        "@odata.type": "microsoft.graph.attributeCollectionStart.setPrefillValues",
        "inputs": {
          "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.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."
      }
    ]
  }
}