Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Dotyczy:
Dzierżawy zewnętrzne (dowiedz się więcej)
Metoda uwierzytelniania: Osadzone uwierzytelnianie natywne.
W tej dokumentacji opisano rejestrację za pośrednictwem kolekcji atrybutów opartych na serwerze. Rejestracja jednorazowego kodu dostępu pocztą e-mail z hasłem i wiadomościami e-mail używa tych samych operacji i kształtów wiadomości. W przypadku tych metod poczty e-mail przepływ użytkownika skojarzony z aplikacją wybiera metodę rejestracji; klient nie wybiera go w żądaniu uruchamiania.
W przykładach pokazano rejestrację opartą na wiadomościach e-mail. W przypadku istniejących integracji w wersji 1 użyj dokumentacji interfejsu API w wersji 1.
W przykładach użyto zweryfikowanego przez dzierżawę urzędu niestandardowej domeny.
custom_domain jest domeną uwierzytelniania i tenant jest identyfikatorem GUID dzierżawy.
Rozpoczynanie rejestracji
Important
Interfejs API uwierzytelniania natywnego w wersji 2 jest w wersji zapoznawczej. Interfejs API uwierzytelniania natywnego w wersji 1 pozostaje ogólnie dostępny. Zapoznaj się z dodatkowymi warunkami użytkowania dotyczącymi wersji zapoznawczej Microsoft Azure, aby uzyskać postanowienia prawne dotyczące funkcji w wersji zapoznawczej.
Na diagramie przedstawiono sekwencję rejestracji opartą na odpowiedziach. Przepływ użytkownika określa metodę rejestracji, a bieżąca odpowiedź określa, które atrybuty i interakcje są wymagane.
Rozpocznij autoryzację, a następnie postępuj zgodnie z linkiem sign_up z zwróconym tokenem:
POST https://{custom_domain}/{tenant}/api/v2.0/signup/start
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
continuationToken jest wymaganym ciągiem. Odpowiedź początkowa może zażądać wiadomości e-mail:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "collectAttributes",
"attributes": [
{
"attributeId": "email",
"inputType": "text",
"hidden": false,
"required": true,
"canChange": true,
"label": "Email"
}
],
"_links": {
"submitAttributes": {
"href": "/{tenant}/api/v2.0/signup/submitattributes"
}
}
}
Etykiety, wymaganość i metadane weryfikacji pochodzą z zasad. Użyj tych wymagań w obrębie interfejsu aplikacji i logiki kolekcji.
Przesyłanie atrybutów
Postępuj zgodnie z instrukcjami _links.submitAttributes.href. Kolekcja może wystąpić więcej niż raz:
POST https://{custom_domain}/{tenant}/api/v2.0/signup/submitattributes
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"attributes": {
"email": "user@contoso.com"
}
}
| Property | Typ | Required | Description |
|---|---|---|---|
continuationToken |
Struna. | Yes. | Najnowszy token rejestracji. |
attributes |
Obiekt wartości ciągu. | Yes. | Wartości kluczowane przez dokładne zwrócone attributeId wartości. |
Przed ukończeniem rejestracji należy podać wszystkie wymagane wartości. Wartości opcjonalne można pominąć. Brakujące wymagane wartości mogą spowodować błąd weryfikacji lub inną collectAttributes odpowiedź.
W przypadku rejestracji w wiadomości e-mail z hasłem prześlij hasło po zażądaniu. Na przykład kolekcja zaokrąglana, która żąda pól hasła i profilu, może zaakceptować następujące elementy:
{
"continuationToken": "******",
"attributes": {
"email": "user@contoso.com",
"password": "******",
"givenName": "Example",
"surname": "User"
}
}
Prześlij pola zgodnie ze zwracanych deskryptorami przepływu użytkownika. Rejestracja jednorazowego kodu dostępu w wiadomości e-mail tworzy konto bez hasła, które loguje się przy użyciu kodu dostępu poczty e-mail.
Kolejność kolekcji
Usługa może najpierw zażądać wiadomości e-mail, zebrać kilka atrybutów lub powrócić do kolekcji atrybutów po weryfikacji. Prześlij atrybuty żądane przez najnowszą odpowiedź, a nie przewidywanie sekwencji z przesłanych wartości.
Aplikacja może organizować kolekcję zgodnie z logiką przepływu i dostępnymi deskryptorami. Zobacz Kolejność kolekcji i weryfikacja poczty e-mail. Każda odpowiedź określa dostępne następne operacje.
Interpretowanie deskryptorów atrybutów i stron
Każda odpowiedź opisuje bieżący formularz. Następujące pola definiują atrybut:
| Pole | Meaning |
|---|---|
attributeId |
Klucz przesyłania. |
inputType |
Typ kontrolki wejściowej, taki jak text, password, boolean, datelub checkboxMultiSelect. |
required |
Określa, czy należy podać wartość. |
hidden |
Czy pole jest ukryte. |
canChange |
Informacje o możliwości edycji, jeśli są uwzględnione. |
label |
Opcjonalna etykieta wyświetlania. |
initialValue |
Opcjonalna wstępnie wypełniona wartość. |
validation.validationRegEx |
Opcjonalny wzorzec weryfikacji. |
options |
Opcjonalne opcje z właściwościami label i value . |
confirmationInput |
Opcjonalne zachowanie potwierdzenia, takie jak retype, reveallub none. |
Nie wymagaj członka pages . Bieżąca attributes tablica definiuje pola i wymagania; metadane grupowania stron, jeśli są zwracane, są dodatkowymi informacjami o prezentacji. Typy kontrolek wejściowych nie zmieniają obiektu przesyłania wartości ciągu. Zobacz Pojęcia dotyczące atrybutów użytkownika.
Weryfikowanie poczty e-mail
Gdy przesyłanie atrybutu wymaga weryfikacji wiadomości e-mail, wysyła kod dostępu i zwraca:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "verify",
"id": "{email_method_id}",
"type": "email",
"hint": "u***@contoso.com",
"codeLength": 8,
"_links": {
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
},
"resend": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
}
}
}
Usługa wysłała już kod dostępu; przejdź bezpośrednio do weryfikacji. Użyj zwróconej długości i zamaskowanej wskazówki. Opublikuj w :verify
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"otp": "{one_time_passcode}"
}
Aby zażądać innego kodu, opublikuj tylko najnowszą wersję continuationToken bieżącego resend linku, z zastrzeżeniem limitów usługi.
Weryfikacja może zwrócić więcej kolekcji atrybutów:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "collectAttributes",
"attributes": [
{
"attributeId": "givenName",
"inputType": "text",
"hidden": false,
"required": true,
"canChange": true,
"label": "First name"
}
],
"_links": {
"submitAttributes": {
"href": "/{tenant}/api/v2.0/signup/submitattributes"
}
}
}
Prześlij żądane wartości i kontynuuj obsługę następnej odpowiedzi.
Pełne wymagania dotyczące zasad i autoryzacja
Po utworzeniu konta i wymaganej weryfikacji przed wznowieniem autoryzacji ukończ wszystkie wymagania dotyczące uwierzytelniania wieloskładnikowego (MFA) i dostępu warunkowego.
Jeśli odpowiedź anonsuje inne wyzwanie metody, użyj wspólnego wyzwania i operacji weryfikacji. Rejestracja metody różni się od weryfikowania wiadomości e-mail z rejestracją. Zobacz Odnajdywanie metod i rejestracja dla kontraktu rejestracji.
Gdy usługa zwróci state: continuewartość , postępuj zgodnie z instrukcjami _links.continue, wznów autoryzację i wymieniaj kod. Uzyskuje to tokeny bez uruchamiania niepowiązanej transakcji logowania.
Błędy i cykl życia
Użyj koperty błędu udostępnionego. Wpisy weryfikacji strukturalnej mogą zawierać codepozycje , message, attributeIds, suggestionsi opcjonalne recovery.
| Warunek | Stan lub zachowanie | Obsługa |
|---|---|---|
| Nieprawidłowy token kontynuacji | 400 |
Uruchom ponownie przepływ. |
| Brak lub nieprawidłowy atrybut |
400 lub inna collectAttributes odpowiedź |
Prezentowanie opinii na poziomie pola i przesyłanie poprawionych wartości. |
| Użytkownik już istnieje | 400 invalidRequest |
Oferowanie ogólnych wskazówek dotyczących logowania lub odzyskiwania bez niepotrzebnego ujawniania istnienia konta. |
| Naruszenie zasad haseł | 400 |
Zbierz zgodne hasło. |
| Niepoprawny kod dostępu poczty e-mail |
400 invalidGrant z innerError.code: invalidOneTimeCode |
Pozwól użytkownikowi poprawić kod przy użyciu bieżącego stanu użytecznego lub anonsowanego ponownego wysłanie. |
| Brak kodu dostępu | 400 invalidRequest |
Popraw brakujące dane wejściowe. |
| Ograniczanie przepustowości | 429 |
Honor server retry guidance (Wskazówki dotyczące ponawiania prób serwera honorowego). |
| Nieobsługiwana interakcja natywna | state: redirect |
Zatrzymaj żądania natywne i zaoferuj skonfigurowaną ścieżkę przeglądarki lub wyraźną awarię. |
Obsługa innych niepowodzeń za pomocą rzeczywistych stanów i stabilnych kodów błędów. Nie traktuj wygasłej transakcji jako możliwego do odzyskania nieprawidłowego wpisu kodu.
Przesyłanie atrybutów nie jest idempotentne po utworzeniu użytkownika. Nie powtarzaj pomyślnych przesłanych danych, rejestruj poufne wartości atrybutów ani nie traktuj weryfikacji po stronie klienta jako autorytatywne.