Przepływ kodu autoryzacji OAuth 2.0 w usłudze Azure Active Directory B2C

Artykuł
11/06/2023

Możesz użyć przyznawania kodu autoryzacji OAuth 2.0 w aplikacjach zainstalowanych na urządzeniu, aby uzyskać dostęp do chronionych zasobów, takich jak internetowe interfejsy API. Korzystając z implementacji protokołu OAuth 2.0 usługi Azure Active Directory B2C (Azure AD B2C), można dodawać zadania rejestracji, logowania i zarządzania tożsamościami do jednostronicowych, mobilnych i klasycznych aplikacji. Ten artykuł jest niezależny od języka. W tym artykule opisano sposób wysyłania i odbierania komunikatów HTTP bez używania bibliotek typu open source. Jeśli to możliwe, zalecamy użycie obsługiwanych bibliotek uwierzytelniania firmy Microsoft (MSAL). Przyjrzyj się przykładowym aplikacjom korzystającym z biblioteki MSAL.

Przepływ kodu autoryzacji OAuth 2.0 został opisany w sekcji 4.1 specyfikacji OAuth 2.0. Można jej używać do uwierzytelniania i autoryzacji w większości typów aplikacji, w tym aplikacji internetowych, aplikacji jednostronicowych i natywnie zainstalowanych aplikacji. Możesz użyć przepływu kodu autoryzacji OAuth 2.0, aby bezpiecznie uzyskać tokeny dostępu i tokeny odświeżania dla aplikacji, które mogą służyć do uzyskiwania dostępu do zasobów zabezpieczonych przez serwer autoryzacji. Token odświeżania umożliwia klientowi uzyskanie nowych tokenów dostępu (i odświeżanie) po wygaśnięciu tokenu dostępu, zazwyczaj po upływie jednej godziny.

Ten artykuł koncentruje się na przepływie kodu autoryzacji OAuth 2.0 dla klientów publicznych . Klient publiczny to każda aplikacja kliencka, której nie można ufać, aby bezpiecznie zachować integralność tajnego hasła. Dotyczy to aplikacji jednostronicowych, aplikacji mobilnych, aplikacji klasycznych i zasadniczo wszystkich aplikacji, które nie są uruchamiane na serwerze.

Uwaga

Aby dodać zarządzanie tożsamościami do aplikacji internetowej przy użyciu Azure AD B2C, użyj protokołu OpenID Connect zamiast protokołu OAuth 2.0.

Azure AD B2C rozszerza standardowe przepływy OAuth 2.0, aby wykonywać więcej niż proste uwierzytelnianie i autoryzację. Wprowadza on przepływ użytkownika. Za pomocą przepływów użytkowników możesz użyć protokołu OAuth 2.0, aby dodać środowiska użytkownika do aplikacji, takie jak rejestrowanie, logowanie i zarządzanie profilami. Dostawcy tożsamości korzystający z protokołu OAuth 2.0 to Amazon, Microsoft Entra ID, Facebook, GitHub, Google i LinkedIn.

Aby wypróbować żądania HTTP w tym artykule:

Zastąp {tenant} ciąg nazwą dzierżawy usługi Azure AD B2C.
Zastąp 90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 element identyfikatorem aplikacji, która została wcześniej zarejestrowana w dzierżawie usługi Azure AD B2C.
Zastąp {policy} ciąg nazwą zasad utworzonych w dzierżawie, na przykład b2c_1_sign_in.

Konfiguracja identyfikatora URI przekierowania wymagana dla aplikacji jednostronicowych

Przepływ kodu autoryzacji dla aplikacji jednostronicowych wymaga dodatkowej konfiguracji. Postępuj zgodnie z instrukcjami dotyczącymi tworzenia aplikacji jednostronicowej , aby poprawnie oznaczyć identyfikator URI przekierowania jako włączony dla mechanizmu CORS. Aby zaktualizować istniejący identyfikator URI przekierowania w celu włączenia mechanizmu CORS, możesz kliknąć monit migracji w sekcji "Internet" na karcie Uwierzytelnianierejestracji aplikacji. Alternatywnie możesz otworzyć edytor manifestu Rejestracje aplikacji i ustawić type pole identyfikatora URI przekierowania na spa w replyUrlsWithType sekcji .

spa Typ przekierowania jest do tyłu zgodny z niejawnym przepływem. Aplikacje korzystające obecnie z niejawnego przepływu do uzyskiwania tokenów mogą przechodzić do spa typu identyfikatora URI przekierowania bez problemów i nadal korzystać z niejawnego przepływu.

1. Pobieranie kodu autoryzacji

Przepływ kodu autoryzacji rozpoczyna się od klienta kierującego użytkownika do punktu końcowego /authorize . Jest to interaktywna część przepływu, w której użytkownik podejmuje działania. W tym żądaniu klient wskazuje w parametrze scope uprawnienia, które musi uzyskać od użytkownika. W poniższych przykładach (z podziałami wierszy dla czytelności) pokazano, jak uzyskać kod autoryzacji. Jeśli testujesz to żądanie HTTP GET, użyj przeglądarki.

GET https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/authorize?
client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&response_type=code
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&response_mode=query
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6%20offline_access%20https://{tenant-name}/{app-id-uri}/{scope}
&state=arbitrary_data_you_can_receive_in_the_response
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Parametr	Wymagane?	Opis
{tenant}	Wymagane	Nazwa dzierżawy usługi Azure AD B2C
{policy}	Wymagane	Przepływ użytkownika do uruchomienia. Określ nazwę przepływu użytkownika utworzonego w dzierżawie usługi Azure AD B2C. Na przykład: `b2c_1_sign_in`, `b2c_1_sign_up`lub `b2c_1_edit_profile`.
client_id	Wymagane	Identyfikator aplikacji przypisany do aplikacji w Azure Portal.
response_type	Wymagane	Typ odpowiedzi, który musi zawierać `code` przepływ kodu autoryzacji. Jeśli uwzględnisz go w typie odpowiedzi, takim jak `code+id_token`, możesz otrzymać token identyfikatora, a w tym przypadku zakres musi zawierać wartość `openid`.
redirect_uri	Wymagane	Identyfikator URI przekierowania aplikacji, w którym odpowiedzi uwierzytelniania są wysyłane i odbierane przez aplikację. Musi dokładnie odpowiadać jednemu z identyfikatorów URI przekierowania zarejestrowanych w portalu, z tą różnicą, że musi być zakodowana w adresie URL.
scope	Wymagane	Rozdzielona spacjami lista zakresów. Zakres `openid` wskazuje uprawnienia do logowania użytkownika i pobierania danych o użytkowniku w postaci tokenów identyfikatorów. Zakres `offline_access` jest opcjonalny dla aplikacji internetowych. Wskazuje, że aplikacja będzie potrzebować tokenu odświeżania w celu uzyskania rozszerzonego dostępu do zasobów. Identyfikator klienta wskazuje, że wystawiony token jest przeznaczony do użycia przez Azure AD zarejestrowanego klienta B2C. Element `https://{tenant-name}/{app-id-uri}/{scope}` wskazuje uprawnienia do chronionych zasobów, takich jak internetowy interfejs API. Aby uzyskać więcej informacji, zobacz Żądanie tokenu dostępu.
response_mode	Zalecane	Metoda używana do wysyłania wynikowego kodu autoryzacji z powrotem do aplikacji. Może to być `query`, `form_post`lub `fragment`.
stan	Zalecane	Wartość uwzględniona w żądaniu, która może być ciągiem dowolnej zawartości, której chcesz użyć. Zazwyczaj jest używana losowo wygenerowana unikatowa wartość, aby zapobiec atakom fałszowania żądań między witrynami. Stan jest również używany do kodowania informacji o stanie użytkownika w aplikacji przed wystąpieniem żądania uwierzytelnienia. Na przykład strona, na którą znajdował się użytkownik, lub przepływ użytkownika, który był wykonywany.
Wierszu	Opcjonalne	Wymagany typ interakcji użytkownika. Obecnie jedyną prawidłową wartością jest `login`, która wymusza na użytkowniku wprowadzenie poświadczeń w ramach tego żądania. Logowanie jednokrotne nie zacznie obowiązywać.
code_challenge	zalecane/wymagane	Służy do zabezpieczania udzielania kodu autoryzacji za pośrednictwem klucza dowodowego dla wymiany kodu (PKCE). Wymagane, jeśli `code_challenge_method` jest uwzględniona. Aby wygenerować elementy `code_verifier` i , `code_challenge`należy dodać logikę w aplikacji. Jest `code_challenge` to skrót SHA256 zakodowany w formacie Base64 w formacie URL .`code_verifier` Przechowujesz element `code_verifier` w aplikacji do późniejszego użycia i wysyłasz `code_challenge` element wraz z żądaniem autoryzacji. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE. Jest to teraz zalecane dla wszystkich typów aplikacji — natywnych aplikacji, spA i poufnych klientów, takich jak aplikacje internetowe.
`code_challenge_method`	zalecane/wymagane	Metoda używana do kodowania `code_verifier` parametru `code_challenge` . Powinna to być `S256`wartość , ale specyfikację można używać`plain`, jeśli z jakiegoś powodu klient nie może obsługiwać algorytmu SHA256. Jeśli wykluczysz element `code_challenge_method`, ale nadal zawiera `code_challenge`wartość , przyjmuje się, `code_challenge` że jest to zwykły tekst. Platforma tożsamości Microsoft obsługuje zarówno elementy , jak `plain` i `S256`. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE. Jest to wymagane w przypadku aplikacji jednostronicowych korzystających z przepływu kodu autoryzacji.
login_hint	Nie	Może służyć do wstępnego wypełniania pola nazwy logowania na stronie logowania. Aby uzyskać więcej informacji, zobacz Wstępne wypełnianie nazwy logowania.
domain_hint	Nie	Zawiera wskazówkę dotyczącą Azure AD B2C o dostawcy tożsamości społecznościowych, który powinien być używany do logowania. Jeśli zostanie dołączona prawidłowa wartość, użytkownik przejdzie bezpośrednio do strony logowania dostawcy tożsamości. Aby uzyskać więcej informacji, zobacz Przekierowywanie logowania do dostawcy społecznościowego.
Parametry niestandardowe	Nie	Parametry niestandardowe, których można używać z zasadami niestandardowymi. Na przykład dynamiczne identyfikatory URI zawartości niestandardowej strony lub rozpoznawanie oświadczeń klucz-wartość.

Na tym etapie użytkownik jest proszony o ukończenie przepływu pracy przepływu użytkownika. Może to obejmować wprowadzenie nazwy użytkownika i hasła, zalogowanie się przy użyciu tożsamości społecznościowej, zarejestrowanie się w katalogu lub dowolną inną liczbę kroków. Akcje użytkownika zależą od sposobu definiowania przepływu użytkownika.

Po zakończeniu przepływu użytkownika Microsoft Entra identyfikator zwraca odpowiedź do aplikacji z wartością użytą dla redirect_urielementu . Używa metody określonej w parametrze response_mode . Odpowiedź jest dokładnie taka sama dla każdego scenariusza akcji użytkownika niezależnie od wykonanego przepływu użytkownika.

Pomyślna odpowiedź, która używa response_mode=query , wygląda następująco:

GET urn:ietf:wg:oauth:2.0:oob?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...        // the authorization_code, truncated
&state=arbitrary_data_you_can_receive_in_the_response                // the value provided in the request

Parametr	Opis
kod	Kod autoryzacji żądany przez aplikację. Aplikacja może użyć kodu autoryzacji, aby zażądać tokenu dostępu dla zasobu docelowego. Kody autoryzacji są bardzo krótkotrwałe. Zazwyczaj wygasają po około 10 minutach.
stan	Zobacz pełny opis w tabeli w poprzedniej sekcji. `state` Jeśli parametr jest uwzględniony w żądaniu, ta sama wartość powinna pojawić się w odpowiedzi. Aplikacja powinna sprawdzić, czy `state` wartości w żądaniu i odpowiedzi są identyczne.

Odpowiedzi na błędy można również wysłać do identyfikatora URI przekierowania, aby aplikacja mogła je odpowiednio obsłużyć:

GET urn:ietf:wg:oauth:2.0:oob?
error=access_denied
&error_description=The+user+has+cancelled+entering+self-asserted+information
&state=arbitrary_data_you_can_receive_in_the_response

Parametr	Opis
error	Ciąg kodu błędu, którego można użyć do klasyfikowania typów błędów, które występują. Możesz również użyć ciągu, aby reagować na błędy.
error_description	Określony komunikat o błędzie, który może pomóc zidentyfikować główną przyczynę błędu uwierzytelniania.
stan	Zobacz pełny opis w poprzedniej tabeli. `state` Jeśli parametr jest uwzględniony w żądaniu, ta sama wartość powinna pojawić się w odpowiedzi. Aplikacja powinna sprawdzić, czy `state` wartości w żądaniu i odpowiedzi są identyczne.

2. Uzyskiwanie tokenu dostępu

Teraz, po uzyskaniu kodu autoryzacji, możesz wymienić code token na zamierzony zasób, wysyłając żądanie POST do punktu końcowego /token . W Azure AD B2C można żądać tokenów dostępu dla innych interfejsów API w zwykły sposób, określając ich zakresy w żądaniu.

Możesz również zażądać tokenu dostępu dla własnego internetowego interfejsu API zaplecza aplikacji zgodnie z konwencją użycia identyfikatora klienta aplikacji jako żądanego zakresu (co spowoduje token dostępu z tym identyfikatorem klienta jako "odbiorcy"):

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong

Parametr	Wymagane?	Opis
{tenant}	Wymagane	Nazwa dzierżawy usługi Azure AD B2C
{policy}	Wymagane	Przepływ użytkownika, który został użyty do uzyskania kodu autoryzacji. W tym żądaniu nie można użyć innego przepływu użytkownika.
client_id	Wymagane	Identyfikator aplikacji przypisany do aplikacji w Azure Portal.
client_secret	Tak, w Web Apps	Wpis tajny aplikacji wygenerowany w Azure Portal. Wpisy tajne klienta są używane w tym przepływie w scenariuszach aplikacji internetowej, w których klient może bezpiecznie przechowywać klucz tajny klienta. W przypadku scenariuszy aplikacji natywnej (klienta publicznego) wpisy tajne klienta nie mogą być bezpiecznie przechowywane i dlatego nie są używane w tym wywołaniu. Jeśli używasz klucza tajnego klienta, zmień go okresowo.
grant_type	Wymagane	Typ udzielenia. W przypadku przepływu kodu autoryzacji typ udzielenia musi mieć wartość `authorization_code`.
scope	Zalecane	Rozdzielona spacjami lista zakresów. Pojedyncza wartość zakresu wskazuje Microsoft Entra identyfikatora obu żądanych uprawnień. Użycie identyfikatora klienta jako zakresu wskazuje, że aplikacja potrzebuje tokenu dostępu, który może być używany względem własnej usługi lub internetowego interfejsu API reprezentowanego przez ten sam identyfikator klienta. Zakres `offline_access` wskazuje, że aplikacja potrzebuje tokenu odświeżania na potrzeby długotrwałego dostępu do zasobów. Możesz również użyć `openid` zakresu, aby zażądać tokenu identyfikatora z Azure AD B2C.
kod	Wymagane	Kod autoryzacji uzyskany z punktu końcowego `/authorize` .
redirect_uri	Wymagane	Identyfikator URI przekierowania aplikacji, w której odebrano kod autoryzacji.
code_verifier	zalecane	To samo `code_verifier` , które zostało użyte do uzyskania kodu autoryzacji. Wymagane, jeśli klucz PKCE został użyty w żądaniu udzielenia kodu autoryzacji. Aby uzyskać więcej informacji, zobacz dokument RFC PKCE.

Jeśli testujesz to żądanie HTTP POST, możesz użyć dowolnego klienta HTTP, takiego jak Microsoft PowerShell lub Postman.

Pomyślna odpowiedź tokenu wygląda następująco:

{
    "not_before": "1442340812",
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "scope": "90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access",
    "expires_in": "3600",
    "refresh_token": "AAQfQmvuDy8WtUv-sd0TBwWVQs1rC-Lfxa_NDkLqpg50Cxp5Dxj0VPF1mx2Z...",
}

Parametr	Opis
not_before	Czas, w którym token jest uznawany za prawidłowy, w czasie epoki.
token_type	Wartość typu tokenu. Jedynym typem obsługującym identyfikator Microsoft Entra jest Bearer.
access_token	Podpisany token internetowy JSON (JWT), którego zażądano.
scope	Zakresy, dla których token jest prawidłowy. Można również użyć zakresów do buforowania tokenów do późniejszego użycia.
expires_in	Czas ważności tokenu (w sekundach).
refresh_token	Token odświeżania OAuth 2.0. Aplikacja może użyć tego tokenu do uzyskania dodatkowych tokenów po wygaśnięciu bieżącego tokenu. Tokeny odświeżania są długotrwałe. Można ich użyć do zachowania dostępu do zasobów przez dłuższy czas. Aby uzyskać więcej informacji, zobacz dokumentację tokenu usługi Azure AD B2C.

Odpowiedzi na błędy wyglądają następująco:

{
    "error": "access_denied",
    "error_description": "The user revoked access to the app.",
}

Parametr	Opis
error	Ciąg kodu błędu, którego można użyć do klasyfikowania typów błędów, które występują. Możesz również użyć ciągu, aby reagować na błędy.
error_description	Określony komunikat o błędzie, który może pomóc zidentyfikować główną przyczynę błędu uwierzytelniania.

3. Użyj tokenu

Po pomyślnym uzyskaniu tokenu dostępu możesz użyć tokenu w żądaniach do internetowych interfejsów API zaplecza, dołączając go do nagłówka Authorization :

GET /tasks
Host: mytaskwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

4. Odśwież token

Tokeny dostępu i tokeny identyfikatorów są krótkotrwałe. Po wygaśnięciu należy je odświeżyć, aby nadal uzyskiwać dostęp do zasobów. Podczas odświeżania tokenu dostępu Azure AD B2C zwraca nowy token. Odświeżony token dostępu zostanie zaktualizowany nbf (nie wcześniej), iat (wystawiony pod adresem) i exp (wygaśnięcie) wartości oświadczeń. Wszystkie inne wartości oświadczeń będą takie same jak pierwotnie wystawiony token dostępu.

Aby odświeżyć token, prześlij kolejne żądanie POST do punktu końcowego /token . Tym razem podaj wartość refresh_token zamiast parametru code:

POST https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}/oauth2/v2.0/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6
&scope=90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6 offline_access
&refresh_token=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&redirect_uri=urn:ietf:wg:oauth:2.0:oob

Parametr	Wymagane?	Opis
{tenant}	Wymagane	Nazwa dzierżawy usługi Azure AD B2C
{policy}	Wymagane	Przepływ użytkownika, który został użyty do uzyskania oryginalnego tokenu odświeżania. W tym żądaniu nie można użyć innego przepływu użytkownika.
client_id	Wymagane	Identyfikator aplikacji przypisany do aplikacji w Azure Portal.
client_secret	Tak, w Web Apps	Wpis tajny aplikacji wygenerowany w Azure Portal. Wpisy tajne klienta są używane w tym przepływie w scenariuszach aplikacji internetowej, w których klient może bezpiecznie przechowywać klucz tajny klienta. W przypadku scenariuszy aplikacji natywnej (klienta publicznego) wpisy tajne klienta nie mogą być bezpiecznie przechowywane i dlatego nie są używane w tym wywołaniu. Jeśli używasz klucza tajnego klienta, zmień go okresowo.
grant_type	Wymagane	Typ udzielenia. W przypadku tego etapu przepływu kodu autoryzacji typ udzielenia musi mieć wartość `refresh_token`.
scope	Zalecane	Rozdzielona spacjami lista zakresów. Pojedyncza wartość zakresu wskazuje Microsoft Entra identyfikatora obu żądanych uprawnień. Użycie identyfikatora klienta jako zakresu wskazuje, że aplikacja potrzebuje tokenu dostępu, który może być używany względem własnej usługi lub internetowego interfejsu API reprezentowanego przez ten sam identyfikator klienta. Zakres `offline_access` wskazuje, że aplikacja będzie potrzebować tokenu odświeżania na potrzeby długotrwałego dostępu do zasobów. Możesz również użyć `openid` zakresu, aby zażądać tokenu identyfikatora z Azure AD B2C.
redirect_uri	Opcjonalne	Identyfikator URI przekierowania aplikacji, w której odebrano kod autoryzacji.
refresh_token	Wymagane	Oryginalny token odświeżania uzyskany w drugim etapie przepływu.