Dodawanie niestandardowego przepływu pracy zatwierdzania do samoobsługowej rejestracji

Dotyczy: Dzierżawcy siły roboczej — dzierżawcy zewnętrzni (dowiedz się więcej)

Łączniki interfejsu API umożliwiają integrację z własnymi niestandardowymi przepływami pracy zatwierdzania z rejestracją samoobsługową, dzięki czemu możesz zarządzać kontami użytkowników-gości utworzonymi w dzierżawie.

W tym artykule przedstawiono przykład integracji z systemem zatwierdzania. W tym przykładzie przepływ samoobsługowego tworzenia konta użytkownika zbiera dane użytkownika podczas procesu rejestracji i przekazuje go do systemu zatwierdzania. Następnie system zatwierdzania może:

• Automatycznie zatwierdź użytkownika i zezwól usłudze Microsoft Entra ID na utworzenie konta użytkownika.
• Wyzwalanie ręcznego przeglądu. Jeśli żądanie zostanie zatwierdzone, system zatwierdzania używa programu Microsoft Graph do aprowizowania konta użytkownika. System zatwierdzania może również powiadomić użytkownika o utworzeniu konta.

Ważne

• Od 12 lipca 2021 r., jeśli klienci firmy Microsoft Entra B2B skonfigurowali nowe integracje Google do użycia z rejestracją samoobsługową dla swoich niestandardowych lub biznesowych aplikacji, uwierzytelnianie przy użyciu tożsamości Google nie będzie działać, dopóki uwierzytelnianie nie zostanie przeniesione do systemowych widoków internetowych. Dowiedz się więcej.
• Od 30 września 2021 r. firma Google wycofa obsługę logowania osadzonego widoku internetowego. Jeśli aplikacje uwierzytelniają użytkowników za pomocą osadzonego widoku internetowego i korzystasz z federacji Google z usługą Azure AD B2C lub Microsoft Entra B2B w przypadku zaproszeń użytkowników zewnętrznych lub rejestracji samoobsługowej, użytkownicy usługi Google Gmail nie będą mogli się uwierzytelniać. Dowiedz się więcej.

Rejestrowanie aplikacji dla systemu zatwierdzania

Napiwek

Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.

Musisz zarejestrować system zatwierdzania jako aplikację w dzierżawie firmy Microsoft Entra, aby mógł uwierzytelniać się przy użyciu identyfikatora Entra firmy Microsoft i mieć uprawnienia do tworzenia użytkowników. Dowiedz się więcej o podstawach uwierzytelniania i autoryzacji dla programu Microsoft Graph.

1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator użytkowników.
2. Przejdź do pozycji Aplikacje> tożsamości>Rejestracje aplikacji, a następnie wybierz pozycję Nowa rejestracja.
3. Wprowadź nazwę aplikacji, na przykład Zatwierdzenia rejestracji.
4. Wybierz pozycję Zarejestruj. Możesz pozostawić inne pola w domyślnych polach.

1. W obszarze Zarządzaj w menu po lewej stronie wybierz pozycję Uprawnienia interfejsu API, a następnie wybierz pozycję Dodaj uprawnienie.
2. Na stronie Żądanie uprawnień interfejsu API wybierz pozycję Microsoft Graph, a następnie wybierz pozycję Uprawnienia aplikacji.
3. W obszarze Wybierz uprawnienia rozwiń węzeł Użytkownik, a następnie zaznacz pole wyboru User.ReadWrite.All . To uprawnienie umożliwia systemowi zatwierdzania utworzenie użytkownika po zatwierdzeniu. Wybierz opcję Dodaj uprawnienia.

9. Na stronie Uprawnienia interfejsu API wybierz pozycję Udziel zgody administratora (nazwa dzierżawy), a następnie wybierz pozycję Tak.
10. W obszarze Zarządzaj w menu po lewej stronie wybierz pozycję Certyfikaty i wpisy tajne, a następnie wybierz pozycję Nowy klucz tajny klienta.
11. Wprowadź opis wpisu tajnego, na przykład wpis tajny klienta Zatwierdzenia, a następnie wybierz czas trwania wygaśnięcia wpisu tajnego klienta. Następnie wybierz pozycję Dodaj.
12. Skopiuj wartość klucza tajnego klienta. Wartości wpisów tajnych klienta można wyświetlać tylko natychmiast po utworzeniu. Pamiętaj, aby zapisać wpis tajny podczas tworzenia przed opuszczeniem strony.

13. Skonfiguruj system zatwierdzania, aby używał identyfikatora aplikacji jako identyfikatora klienta i klucza tajnego klienta wygenerowanego do uwierzytelniania za pomocą identyfikatora Entra firmy Microsoft.

Tworzenie łączników interfejsu API

Następnie utworzysz łączniki interfejsu API dla przepływu użytkownika rejestracji samoobsługowej. Interfejs API systemu zatwierdzania wymaga dwóch łączników i odpowiednich punktów końcowych, takich jak przykłady przedstawione poniżej. Te łączniki interfejsu API wykonują następujące czynności:

• Sprawdź stan zatwierdzenia. Wyślij wywołanie do systemu zatwierdzania bezpośrednio po zalogowaniu się użytkownika za pomocą dostawcy tożsamości, aby sprawdzić, czy użytkownik ma istniejące żądanie zatwierdzenia lub został już odrzucony. Jeśli system zatwierdzania podejmuje tylko decyzje dotyczące automatycznego zatwierdzania, ten łącznik interfejsu API może nie być potrzebny. Przykład łącznika interfejsu API "Sprawdzanie stanu zatwierdzenia".

• Żądanie zatwierdzenia — wyślij wywołanie do systemu zatwierdzania po zakończeniu strony kolekcji atrybutów przez użytkownika, ale przed utworzeniem konta użytkownika w celu żądania zatwierdzenia. Żądanie zatwierdzenia można automatycznie udzielić lub ręcznie przejrzeć. Przykład łącznika interfejsu API "Żądanie zatwierdzenia".

Aby utworzyć te łączniki, wykonaj kroki opisane w artykule Tworzenie łącznika interfejsu API.

Włączanie łączników interfejsu API w przepływie użytkownika

Teraz dodasz łączniki interfejsu API do przepływu użytkownika rejestracji samoobsługowej, wykonując następujące kroki:

1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator użytkowników.

2. Przejdź do pozycji Tożsamości>Zewnętrzne tożsamości>Przepływy użytkownika, a następnie wybierz przepływ użytkownika, dla którego chcesz włączyć łącznik interfejsu API.

3. Wybierz pozycję Łączniki interfejsu API, a następnie wybierz punkty końcowe interfejsu API, które chcesz wywołać, wykonując następujące kroki w przepływie użytkownika:

   • Po sfederowaniu z dostawcą tożsamości podczas rejestracji: wybierz łącznik interfejsu API stanu zatwierdzenia, na przykład Sprawdź stan zatwierdzenia.
   • Przed utworzeniem użytkownika: wybierz łącznik interfejsu API żądania zatwierdzenia, na przykład Żądanie zatwierdzenia.

1. Wybierz pozycję Zapisz.

Kontrolowanie przepływu rejestracji przy użyciu odpowiedzi interfejsu API

System zatwierdzania może używać odpowiedzi po wywołaniu w celu kontrolowania przepływu rejestracji.

Żądania i odpowiedzi dotyczące łącznika interfejsu API "Sprawdzanie stanu zatwierdzenia"

Przykład żądania odebranego przez interfejs API z łącznika interfejsu API "Sprawdź stan zatwierdzenia":

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ //Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Dokładne oświadczenia wysyłane do interfejsu API zależą od tego, które informacje są dostarczane przez dostawcę tożsamości. Wiadomość e-mail jest zawsze wysyłana.

Odpowiedź kontynuacji dla komunikatu "Sprawdź stan zatwierdzenia"

Punkt końcowy interfejsu API sprawdzania stanu zatwierdzenia powinien zwrócić odpowiedź kontynuacji, jeśli:

• Użytkownik nie zażądał wcześniej zatwierdzenia.

Przykład odpowiedzi kontynuacji:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

Odpowiedź blokująca dla komunikatu "Sprawdź stan zatwierdzenia"

Punkt końcowy interfejsu API sprawdzania stanu zatwierdzenia powinien zwrócić odpowiedź blokującą, jeśli:

• Trwa oczekiwanie na zatwierdzenie przez użytkownika.
• Użytkownik został odrzucony i nie powinien mieć zezwolenia na ponowne żądanie zatwierdzenia.

Poniżej przedstawiono przykłady blokowania odpowiedzi:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your access request is already processing. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

Żądania i odpowiedzi dotyczące łącznika interfejsu API "Żądanie zatwierdzenia"

Przykład żądania HTTP odebranego przez interfejs API z łącznika interfejsu API "Żądanie zatwierdzenia":

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Dokładne oświadczenia wysyłane do interfejsu API zależą od tego, które informacje są zbierane od użytkownika lub są dostarczane przez dostawcę tożsamości.

Odpowiedź kontynuacji dla żądania zatwierdzenia

Punkt końcowy interfejsu API zatwierdzania żądania powinien zwrócić odpowiedź kontynuacji, jeśli:

• Użytkownik może zostać automatycznie zatwierdzony.

Przykład odpowiedzi kontynuacji:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue"
}

Ważne

Jeśli zostanie odebrana odpowiedź kontynuacji, identyfikator Entra firmy Microsoft tworzy konto użytkownika i kieruje użytkownika do aplikacji.

Odpowiedź blokująca dla żądania zatwierdzenia

Punkt końcowy interfejsu API zatwierdzania żądań powinien zwrócić odpowiedź blokującą, jeśli:

• Żądanie zatwierdzenia użytkownika zostało utworzone i jest teraz oczekujące.
• Żądanie zatwierdzenia użytkownika zostało automatycznie odrzucone.

Poniżej przedstawiono przykłady blokowania odpowiedzi:

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your account is now waiting for approval. You'll be notified when your request has been approved.",
}

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "Your sign up request has been denied. Please contact an administrator if you believe this is an error",
}

Element userMessage w odpowiedzi jest wyświetlany użytkownikowi, na przykład:

Tworzenie konta użytkownika po ręcznym zatwierdzeniu

Po ręcznym zatwierdzeniu przez niestandardowy system zatwierdzania tworzy konto użytkownika przy użyciu programu Microsoft Graph. Sposób aprowizowany przez system zatwierdzania konta użytkownika zależy od dostawcy tożsamości, który był używany przez użytkownika.

W przypadku federacyjnego użytkownika Google lub Facebook i jednorazowego kodu dostępu e-mail

Ważne

System zatwierdzania powinien jawnie sprawdzić, czy identitieselement i identities[0] identities[0].issuer jest obecny, i że identities[0].issuer równa się "facebook", "google" lub "mail", aby użyć tej metody.

Jeśli użytkownik zalogował się przy użyciu konta Google lub Facebook lub jednorazowego kodu dostępu e-mail, możesz użyć interfejsu API tworzenia użytkownika.

1. System zatwierdzania odbiera żądanie HTTP z przepływu użytkownika.

POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@outlook.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

2. System zatwierdzania używa programu Microsoft Graph do utworzenia konta użytkownika.

POST https://graph.microsoft.com/v1.0/users
Content-type: application/json

{
 "userPrincipalName": "johnsmith_outlook.com#EXT@contoso.onmicrosoft.com",
 "accountEnabled": true,
 "mail": "johnsmith@outlook.com",
 "userType": "Guest",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value"
}

Parametr	Wymagania	opis
userPrincipalName	Tak	Można wygenerować przez pobranie oświadczenia wysłanego do interfejsu email API, zastąpienie @znaku znakiem _i wstępne oczekiwanie na #EXT@<tenant-name>.onmicrosoft.com.
accountEnabled	Tak	Musi być ustawiona wartość true.
poczta	Tak	Odpowiednik oświadczenia wysłanego email do interfejsu API.
userType	Tak	Musi mieć wartość Guest. Wyznacza tego użytkownika jako użytkownika-gościa.
Tożsamości	Tak	Informacje o tożsamości federacyjnej.
<otherBuiltInAttribute>	Nie.	Inne wbudowane atrybuty, takie jak displayName, cityi inne. Nazwy parametrów są takie same jak parametry wysyłane przez łącznik interfejsu API.
<extension_{extensions-app-id}_CustomAttribute>	Nie.	Atrybuty niestandardowe dotyczące użytkownika. Nazwy parametrów są takie same jak parametry wysyłane przez łącznik interfejsu API.

W przypadku użytkownika federacyjnego microsoft Entra lub użytkownika konta Microsoft

Jeśli użytkownik zaloguje się przy użyciu federacyjnego konta Microsoft Entra lub konta Microsoft, musisz użyć interfejsu API zaproszenia, aby utworzyć użytkownika, a następnie opcjonalnie zaktualizować interfejs API aktualizacji użytkownika, aby przypisać więcej atrybutów do użytkownika.

1. System zatwierdzania odbiera żądanie HTTP z przepływu użytkownika.

POST <Approvals-API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "displayName": "John Smith",
 "city": "Redmond",
 "extension_<extensions-app-id>_CustomAttribute": "custom attribute value",
 "ui_locales":"en-US"
}

2. System zatwierdzania tworzy zaproszenie przy użyciu email łącznika interfejsu API dostarczonego przez program .

POST https://graph.microsoft.com/v1.0/invitations
Content-type: application/json

{
    "invitedUserEmailAddress": "johnsmith@fabrikam.onmicrosoft.com",
    "inviteRedirectUrl" : "https://myapp.com"
}

Przykład odpowiedzi:

HTTP/1.1 201 OK
Content-type: application/json

{
    ...
    "invitedUser": {
        "id": "<generated-user-guid>"
    }
}

3. System zatwierdzania używa identyfikatora zaproszonego użytkownika do zaktualizowania konta użytkownika przy użyciu zebranych atrybutów użytkownika (opcjonalnie).

PATCH https://graph.microsoft.com/v1.0/users/<generated-user-guid>
Content-type: application/json

{
    "displayName": "John Smith",
    "city": "Redmond",
    "extension_<extensions-app-id>_AttributeName": "custom attribute value"
}

Następne kroki

• Dodawanie przepływu użytkownika rejestracji samoobsługowej
• Dodawanie łącznika interfejsu API
• Zabezpieczanie łącznika interfejsu API
• rejestracja samoobsługowa dla użytkowników-gości przy użyciu przykładu ręcznego zatwierdzania.