Udostępnij za pośrednictwem

Rozszerzenie niestandardowe dla dokumentacji zdarzeń OnAttributeCollectionStart (wersja zapoznawcza)

  • Artykuł

Dotyczy:Biały okrąg z szarym symbolem X. Dzierżawcy siły roboczej — dzierżawcy zewnętrzni Zielony okrąg z białym symbolem znacznika wyboru. (dowiedz się więcej)

Aby zmodyfikować środowisko rejestracji dla przepływów użytkownika samoobsługowego rejestracji klienta, możesz utworzyć niestandardowe rozszerzenie uwierzytelniania i wywołać je w określonych punktach przepływu 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 przepływu rejestracji na podstawie tożsamości federacyjnej lub poczty e-mail albo wstępnie wypełnić atrybuty z określonymi wartościami. Można skonfigurować następujące akcje:

  • continueWithDefaultBehavior — renderuj stronę kolekcji atrybutów w zwykły sposób.
  • setPreFillValues — atrybuty wstępnego wypełniania 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ł Rozszerzenie niestandardowe dla zdarzenia OnAttributeCollectionSubmit.

Napiwek

Wypróbuj teraz

Aby wypróbować tę funkcję, przejdź do pokazu Woodgrove Groceries i uruchom przypadek użycia "Atrybuty rejestracji wstępnej".

Schemat interfejsu 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 dla kolekcji podczas rejestracji samoobsługowej, w tym wbudowane atrybuty (na przykład givenName i companyName) oraz atrybuty niestandardowe, 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.

JSON

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

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

Identyfikator Entra firmy Microsoft oczekuje odpowiedzi interfejsu API REST w następującym formacie. Typy wartości odpowiedzi są zgodne z typami wartości żądania, na przykład:

  • Jeśli żądanie zawiera atrybut graduationYear z int64DirectoryAttributeValue@odata.type wartością , odpowiedź powinna zawierać atrybut z wartością graduationYear 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.

Akcja continueWithDefaultBehavior określa, że zewnętrzny interfejs API REST zwraca odpowiedź kontynuacji.

HTTP/1.1 200 OK

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

HTTP/1.1 200 OK

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

HTTP/1.1 200 OK

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