Rozszerzenie niestandardowe dla dokumentacji zdarzeń OnAttributeCollectionSubmit (wersja zapoznawcza)

Artykuł
11/23/2024

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 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 przepływ 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ł Rozszerzenie niestandardowe dla zdarzenia OnAttributeCollectionStart).

Napiwek

Aby wypróbować tę funkcję, przejdź do pokazu Woodgrove Groceries i uruchom przypadek użycia "Zweryfikuj atrybuty rejestracji" lub "Blokuj użytkownikowi kontynuowanie procesu rejestracji".

Schemat interfejsu 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 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. W przypadku atrybutów z wieloma wartościami wartości są wysyłane jako ciąg rozdzielany przecinkami.

JSON

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

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

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

HTTP/1.1 200 OK

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

HTTP/1.1 200 OK

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

HTTP/1.1 200 OK

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

Udostępnij za pośrednictwem

Rozszerzenie niestandardowe dla dokumentacji zdarzeń OnAttributeCollectionSubmit (wersja zapoznawcza)

Schemat interfejsu API REST

Żądanie do zewnętrznego interfejsu API REST

JSON

Odpowiedź z zewnętrznego interfejsu API REST

Opinia

Dodatkowe zasoby