Przepływy OpenID Connect/OAuth dla usług AD FS i scenariusze aplikacji
Dotyczy usług AD FS 2019 i nowszych
| Scenariusz | Przewodnik po scenariuszu przy użyciu przykładów | Przepływ/udzielanie protokołu OAuth 2.0 | Typ klienta |
|---|---|---|---|
| Aplikacja jednostronicowa | Przykład przy użyciu biblioteki MSAL | niejawna | Publiczność |
| Aplikacja internetowa, która loguje użytkowników | Przykład przy użyciu OWIN | Kod autoryzacji | Publiczne, poufne |
| Aplikacja natywna wywołuje internetowy interfejs API | Przykład przy użyciu biblioteki MSAL | Kod autoryzacji | Publiczność |
| Aplikacja webowa wywołuje Web API | Przykład przy użyciu biblioteki MSAL | Kod autoryzacji | Poufne |
| Implementacja PKCE | Kod autoryzacji | Publiczność | |
| Internetowy interfejs API wywołuje inny internetowy interfejs API w imieniu użytkownika (OBO) | Przykład przy użyciu biblioteki MSAL | W imieniu | Aplikacja internetowa działa jako poufny komponent |
| Aplikacja daemon wywołuje interfejs API webowy | Poświadczenia klienta | Poufne | |
| Aplikacja internetowa wywołuje internetowy interfejs API przy użyciu poświadczeń użytkownika | Dane uwierzytelniające właściciela zasobu | Publiczne, poufne | |
| Aplikacja bez przeglądarki wywołuje internetowy interfejs API | Kod urządzenia | Publiczne, poufne |
Niejawny przepływ udzielania
Uwaga
Firma Microsoft zdecydowanie zaleca migrację do identyfikatora Entra firmy Microsoft zamiast uaktualniania do nowszej wersji usług AD FS. Aby uzyskać więcej informacji na temat niejawnego przepływu przyznawania w Microsoft Entra ID, zobacz Niejawny przepływ przyznawania na platformie tożsamości Microsoft.
W przypadku aplikacji jednostronicowych (AngularJS, Ember.js, React.jsitd.) AD FS obsługuje przepływ autoryzacji implicit OAuth 2.0. Niejawny przepływ jest opisany w specyfikacji OAuth 2.0. Jego główną zaletą jest to, że umożliwia aplikacji pobieranie tokenów z usług AD FS bez przeprowadzania wymiany poświadczeń serwera zaplecza. Ten przepływ umożliwia aplikacji logowanie użytkownika, utrzymywanie sesji i uzyskiwanie tokenów do innych internetowych interfejsów API w kodzie JavaScript klienta. Istnieje kilka ważnych zagadnień dotyczących zabezpieczeń, które należy wziąć pod uwagę podczas korzystania z przepływu pośredniego, w szczególności wokół klienta.
Jeśli chcesz użyć niejawnego przepływu i usług AD FS, aby dodać uwierzytelnianie do aplikacji JavaScript, wykonaj ogólne kroki opisane w poniższej sekcji.
Diagram protokołu
Na poniższym diagramie przedstawiono cały przebieg niejawnego logowania, a w dalszych sekcjach opisano każdy krok bardziej szczegółowo.
Token identyfikatora żądania i token dostępu
Aby początkowo zalogować użytkownika do aplikacji, możesz wysłać żądanie uwierzytelniania OpenID Connect i uzyskać id_token i token dostępu z punktu końcowego usług AD FS.
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
| Parametr | Wymagane/opcjonalne | Opis |
|---|---|---|
| identyfikator_klienta | wymagane | Identyfikator aplikacji (klienta) przypisany do aplikacji przez usługi AD FS. |
| typ_odpowiedzi | wymagane | Musi zawierać id_token w celu logowania za pomocą OpenID Connect. Może również zawierać response_type token. Użycie tokenu umożliwia aplikacji natychmiastowe odbieranie tokenu dostępu z autoryzowanego punktu końcowego bez konieczności przesyłania drugiego żądania do punktu końcowego tokenu. |
| adres_przekierowania | wymagane | Adres URL przekierowania w Twojej aplikacji, za pomocą którego można wysyłać i odbierać odpowiedzi dotyczące uwierzytelnienia przez aplikację. Musi dokładnie odpowiadać jednemu z redirect_uris skonfigurowanych w AD FS. |
| nonce | wymagane | Wartość zawarta w żądaniu, wygenerowana przez aplikację, która ma zostać uwzględniona w wynikowym "id_token" jako twierdzenie. Następnie aplikacja może zweryfikować tę wartość, aby wyeliminować ataki ponownego odtwarzania tokenu. Wartość jest zazwyczaj losowym, unikatowym ciągiem, który może służyć do identyfikowania źródła żądania. Wymagane tylko wtedy, gdy zażądano id_token. |
| zakres | opcjonalny | Rozdzielona spacjami lista zakresów. W przypadku OpenID Connect musi zawierać zakres openid. |
| zasób | opcjonalny | Adres URL Twojego internetowego interfejsu API. Uwaga — w przypadku korzystania z biblioteki klienta MSAL parametr zasobu nie jest wysyłany. Zamiast tego URL zasobu jest wysyłany jako część parametru zakresu: scope = [resource url]//[scope values e.g., openid]jeśli zasób nie jest przekazywany tutaj ani w zakresie, usługa AD FS używa domyślnego zasobu urn:microsoft:userinfo. Nie można dostosować polityk zasobów userinfo, takich jak MFA, polityka wystawiania lub autoryzacji. |
| Tryb_odpowiedzi | opcjonalny | Określa metodę, która powinna służyć do wysyłania wynikowego tokenu z powrotem do aplikacji. Wartość domyślna to fragment. |
| stan | opcjonalny | Wartość uwzględniona w żądaniu, która ma być również zwrócona w odpowiedzi tokenu. Może to być ciąg dowolnej zawartości. Losowo wygenerowana unikatowa wartość jest zwykle używana do zapobiegania atakom fałszerzowanym żą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 strony lub widoku, na której się znajdowały. |
| zachęta | opcjonalny | Wskazuje wymagany typ interakcji użytkownika. Jedynymi prawidłowymi wartościami w tej chwili są logowanie i żadne. - prompt=login wymusza, aby użytkownik wprowadzał swoje poświadczenia na tym żądaniu, negując logowanie jednokrotne.
- prompt=none jest przeciwieństwem — gwarantuje, że nie zostanie wyświetlony żaden interaktywny monit. Jeśli nie można ukończyć żądania w trybie dyskretnym za pośrednictwem logowania jednokrotnego, usługi AD FS zwracają błąd interaction_required. |
| podpowiedź do logowania | opcjonalny | Może służyć do wstępnego wypełniania pola nazwy użytkownika/adresu e-mail na stronie logowania użytkownika, jeśli znasz nazwę użytkownika z wyprzedzeniem. Często aplikacje używają tego parametru podczas ponownego uwierzytelniania, po wyodrębnieniu nazwy użytkownika z poprzedniego upn logowania przy użyciu oświadczenia z id_token. |
| wskazówka dotycząca domeny | opcjonalny | Jeśli zostanie to uwzględnione, pomija proces wykrywania opartego na domenie, który użytkownik przechodzi na stronie logowania, co prowadzi do nieco bardziej usprawnionego doświadczenia użytkownika. |
Na tym etapie użytkownik zostanie poproszony o wprowadzenie poświadczeń i ukończenie uwierzytelniania. Po uwierzytelnieniu użytkownika, punkt końcowy autoryzacji AD FS zwraca odpowiedź do twojej aplikacji we wskazanym redirect_uri, przy użyciu metody określonej w parametrze response_mode.
Odpowiedź pomyślna
Pomyślna odpowiedź przy użyciu response_mode=fragment and response_type=id_token+token wygląda następująco
// Line breaks for legibility only
GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZEstZnl0aEV...
&token_type=Bearer
&expires_in=3599
&scope=openid
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZstZnl0aEV1Q...
&state=12345
| Parametr | Opis |
|---|---|
| token dostępu | Uwzględnione, jeśli response_type zawiera token. |
| typ tokena | Uwzględnione, jeśli response_type zawiera token. jest zawsze "Bearer". |
| wygasa_za | Uwzględnione, jeśli response_type zawiera token element. Wskazuje liczbę sekund, przez które token jest prawidłowy dla celów buforowania. |
| zakres | Wskazuje zakresy, dla których token dostępu jest prawidłowy. |
| token identyfikacyjny | Uwzględnione, jeśli response_type zawiera id_tokenelement . Podpisany token internetowy JSON (JWT). Aplikacja może dekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował. Aplikacja może buforować wartości i wyświetlać je, ale nie powinna polegać na nich dla żadnych granic autoryzacji ani zabezpieczeń. |
| stan | Jeśli parametr stanu jest uwzględniony w żądaniu, ta sama wartość powinna pojawić się w odpowiedzi. Aplikacja powinna sprawdzić, czy wartości stanu w żądaniu i odpowiedzi są identyczne. |
Odświeżanie tokenów
Niejawne przyznanie nie zapewnia tokenów odświeżania. Zarówno, id_tokens jak i access_tokens wygaśnie po krótkim czasie, więc aplikacja musi być przygotowana do okresowego odświeżania tych tokenów. Aby odświeżyć dowolny typ tokenu, możesz wykonać to samo ukryte żądanie iframe w poprzedniej części przy użyciu parametru prompt=none w celu kontrolowania zachowania platformy tożsamości. Jeśli chcesz otrzymać new id_token, pamiętaj, aby użyć response_type=id_token.
Przepływ nadawania kodu autoryzacyjnego
Uwaga
Firma Microsoft zdecydowanie zaleca migrację do identyfikatora Entra firmy Microsoft zamiast uaktualniania do nowszej wersji usług AD FS. Aby uzyskać więcej informacji na temat przepływu udzielania kodu autoryzacji w usłudze Microsoft Entra ID, zobacz Przepływ udzielania kodu autoryzacji na platformie tożsamości firmy Microsoft.
Udzielenie kodu autoryzacji OAuth 2.0 może być używane w aplikacjach internetowych w celu uzyskania dostępu do chronionych zasobów, takich jak internetowe interfejsy API. Przepływ kodu autoryzacji OAuth 2.0 został opisany w sekcji 4.1 specyfikacji OAuth 2.0. Służy do przeprowadzania uwierzytelniania i autoryzacji w większości typów aplikacji, w tym aplikacji internetowych i aplikacji zainstalowanych natywnie. Przepływ umożliwia aplikacjom bezpieczne uzyskiwanie access_tokens, których można użyć do uzyskiwania dostępu do zasobów, które ufają usługom AD FS.
Schemat protokołu
Na wysokim poziomie przepływ uwierzytelniania dla aplikacji natywnej wygląda nieco następująco:
Żądanie kodu autoryzacji
Przepływ kodu autoryzacji rozpoczyna się od klienta kierującego użytkownika do punktu końcowego /authorize. W tym żądaniu klient wskazuje uprawnienia, które musi uzyskać od użytkownika:
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&resource=https://webapi.com/
&scope=openid
&state=12345
| Parametr | Wymagane/opcjonalne | Opis |
|---|---|---|
| identyfikator_klienta | wymagane | Identyfikator aplikacji (klienta) przypisany do Twojej aplikacji przez AD FS. |
| typ_odpowiedzi | wymagane | Musi zawierać kod przepływu kodu autoryzacji. |
| adres_przekierowania | wymagane | Miejsce redirect_uri Twojej aplikacji, w którym można wysyłać i odbierać odpowiedzi uwierzytelniania. Musi dokładnie odpowiadać jednemu z „redirect_uris” zarejestrowanych w AD FS dla klienta. |
| zasób | opcjonalny | Adres URL internetowego interfejsu API. Uwaga — w przypadku korzystania z biblioteki klienta biblioteki MSAL parametr zasobu nie jest wysyłany. Zamiast tego adres URL zasobu jest wysyłany jako część parametru zakresu: scope = [resource url]//[scope values e.g., openid]jeśli zasób nie został przekazany tutaj lub w zakresie, usługi AD FS używają domyślnego adresu URL zasobu:microsoft:userinfo. Nie można dostosować zasad dotyczących zasobu userinfo, takich jak uwierzytelnianie wieloskładnikowe, polityka wystawiania lub autoryzacji. |
| zakres | opcjonalny | Rozdzielona spacjami lista zakresów. |
| Tryb_odpowiedzi | opcjonalny | Określa metodę, która powinna służyć do wysyłania wynikowego tokenu z powrotem do aplikacji. Może być jedną z następujących metod: - query - fragment - form_post query dostarcza kod jako parametr zapytania na adresie URL przekierowania. Jeśli żądasz kodu, możesz użyć zapytania, fragmentu lub form_post.
form_post Wykonuje post zawierający kod do identyfikatora URI przekierowania. |
| stan | opcjonalny | Wartość uwzględniona w żądaniu, która ma być również zwracana w odpowiedzi tokena. Może to być ciąg dowolnej zawartości. Losowo wygenerowana unikatowa wartość jest zwykle używana do zapobiegania atakom fałszerstwa żądań między stronami. Wartość może również zakodować informacje o stanie użytkownika w aplikacji przed wystąpieniem żądania uwierzytelnienia, takie jak strona lub widok, na której się znajdowały. |
| zachęta | opcjonalny | Wskazuje wymagany typ interakcji użytkownika. Jedynymi prawidłowymi wartościami w tej chwili są logowanie i żadne. - prompt=login wymusza, aby użytkownik wprowadzał swoje poświadczenia na tym żądaniu, negując logowanie jednokrotne.
- prompt=none jest przeciwieństwem — gwarantuje, że użytkownik nie będzie prezentowany z żadnymi interaktywnymi monitami. Jeśli nie można ukończyć żądania w trybie dyskretnym za pośrednictwem logowania jednokrotnego, usługi AD FS zwracają błąd interaction_required. |
| podpowiedź do logowania | opcjonalny | Może służyć do wstępnego wypełniania pola nazwy użytkownika/adresu e-mail na stronie logowania użytkownika, jeśli znasz nazwę użytkownika z wyprzedzeniem. Często aplikacje używają tego parametru podczas ponownego uwierzytelniania, po wyodrębnieniu nazwy użytkownika z poprzedniego upnlogowania przy użyciu oświadczenia z id_token. |
| wskazówka dotycząca domeny | opcjonalny | Jeśli zostanie to uwzględnione, pomija proces odnajdywania opartego na domenie, który użytkownik przechodzi na stronie logowania, co prowadzi do nieco bardziej usprawnionego środowiska użytkownika. |
| code_challenge_method | opcjonalny | Metoda używana do kodowania code_verifier dla parametru code_challenge. Może być jedną z następujących wartości: — zwykły — S256 Jeśli jest wykluczony, przyjmuje się, że code_challenge jest zwykły tekst, jeśli code_challenge jest uwzględniony. Usługi AD FS obsługują zarówno czysty, jak i S256. Aby uzyskać więcej informacji, zobacz PKCE RFC. |
| code_challenge | opcjonalny | Służy do zabezpieczania udzielania kodu autoryzacji za pośrednictwem klucza dowodowego dla wymiany kodu (PKCE) z klienta natywnego. Wymagane, jeśli code_challenge_method jest uwzględnione. Aby uzyskać więcej informacji, zobacz PKCE RFC |
Na tym etapie użytkownik zostanie poproszony o wprowadzenie poświadczeń i ukończenie uwierzytelniania. Gdy użytkownik się uwierzytelni, usługi AD FS zwracają odpowiedź do aplikacji pod wskazanym redirect_uriadresem, przy użyciu metody określonej w parametrze response_mode.
Odpowiedź pomyślna
Pomyślna odpowiedź przy użyciu response_mode=query wygląda następująco:
GET https://adfs.contoso.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Parametr | Opis |
|---|---|
| kod |
authorization_code żądane przez aplikację. Aplikacja może użyć kodu autoryzacji, aby zażądać tokenu dostępu dla zasobu docelowego. Kody autoryzacyjne są krótkotrwałe, na ogół wygasają po około 10 minutach. |
| stan |
state Jeśli parametr jest uwzględniony w żądaniu, ta sama wartość powinna pojawić się w odpowiedzi. Aplikacja powinna sprawdzić, czy wartości stanu w żądaniu i odpowiedzi są identyczne. |
Żądanie tokenu dostępu
Teraz, po uzyskaniu authorization_code i uzyskaniu zgody od użytkownika, możesz wykorzystać kod dla access_token na żądany zasób. Zrealizuj kod, wysyłając żądanie POST do punktu końcowego /token:
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com/
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Parametr | Wymagane/opcjonalne | Opis |
|---|---|---|
| identyfikator_klienta | wymagane | Identyfikator aplikacji (klienta) przypisany do aplikacji przez usługi AD FS. |
| typ_grantu | wymagane | Musi być authorization_code dla przepływu kodu autoryzacji. |
| kod | wymagane | Element authorization_code uzyskany w pierwszej części procesu. |
| adres_przekierowania | wymagane | Ta sama redirect_uri wartość, która została użyta do uzyskania elementu authorization_code. |
| tajemnica klienta | wymagane dla aplikacji internetowych | Sekret aplikacji utworzony podczas rejestracji aplikacji w AD FS. Nie należy używać tajnego klucza aplikacji w aplikacji natywnej, ponieważ tajne dane klienta nie mogą być niezawodnie przechowywane na urządzeniach. Jest to wymagane w przypadku aplikacji internetowych i internetowych interfejsów API, które mają możliwość bezpiecznego przechowywania client_secret po stronie serwera. Klucz tajny klienta musi być zakodowany w adresie URL przed wysłaniem. Te aplikacje mogą również używać uwierzytelniania opartego na kluczu, podpisując token JWT i dodając go jako parametr client_assertion. |
| weryfikator_kodu | opcjonalny | 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 PKCE RFC. Ta opcja dotyczy usług AD FS 2019 i nowszych |
Odpowiedź pomyślna
Pomyślna odpowiedź tokenu wygląda następująco:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parametr | Opis |
|---|---|
| token dostępu | Żądany token dostępu. Aplikacja może wykorzystać ten token do uwierzytelniania w zabezpieczonym zasobie (web API). |
| typ tokena | Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje AD FS, jest Bearer. |
| wygasa_za | Jak długo token dostępu jest prawidłowy (w sekundach). |
| token odświeżania | Token odświeżania OAuth 2.0. Aplikacja może użyć tego tokenu, aby uzyskać więcej tokenów dostępu po wygaśnięciu bieżącego tokenu dostępu. Refresh_tokens są długotrwałe i mogą być używane do zachowania dostępu do zasobów przez dłuższy czas. |
| czas_wygasania_refresh_token | Jak długo token odświeżania jest ważny (w sekundach). |
| token identyfikacyjny | Token sieciowy JSON (JWT). Aplikacja może dekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował. Aplikacja może buforować wartości i wyświetlać je, ale nie powinna polegać na nich dla żadnych granic autoryzacji ani zabezpieczeń. |
Korzystanie z tokenu dostępu
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Proces przyznawania tokenu odświeżającego
Access_tokens są krótkotrwałe i należy je odświeżyć po wygaśnięciu, aby nadal uzyskiwać dostęp do zasobów. Możesz to zrobić, przesyłając kolejne żądanie POST do punktu końcowego /token , tym razem podając refresh_token zamiast kodu. Tokeny odświeżania są ważne dla wszystkich uprawnień, dla których klient otrzymał już token dostępu.
Tokeny odświeżania nie mają określonych okresów istnienia. Zazwyczaj okresy istnienia tokenów odświeżania są stosunkowo długie. Jednak w niektórych przypadkach tokeny odświeżania wygasają, są odwoływały lub nie mają wystarczających uprawnień dla żądanej akcji. Aplikacja musi oczekiwać błędów zwracanych przez punkt końcowy wystawiania tokenu i obsługiwać je prawidłowo.
Chociaż tokeny odświeżania nie są unieważniane, gdy używa się ich do uzyskania nowych tokenów dostępu, powinieneś odrzucić stary token odświeżania. Zgodnie ze specyfikacją OAuth 2.0 mówi: "Serwer autoryzacji MOŻE wydać nowy token odświeżania, w tym przypadku klient MUSI odrzucić stary token odświeżania i zastąpić go nowym tokenem odświeżania. Serwer autoryzujący MOŻE unieważnić stary token odświeżania po wystawieniu nowego tokenu do klienta. Usługi AD FS wystawiają nowy token odświeżania, gdy jego okres istnienia jest dłuższy niż poprzedniego tokenu. Aby wyświetlić dodatkowe informacje na temat okresów istnienia tokenu odświeżania usług AD FS, odwiedź stronę Ad FS Single Sign On Settings (Ustawienia logowania jednokrotnego usług AD FS).
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Parametr | Wymagane/opcjonalne | Opis |
|---|---|---|
| identyfikator_klienta | wymagane | Identyfikator aplikacji (klient) przypisany do aplikacji przez AD FS. |
| typ_grantu | wymagane | Musi być refresh_token dla tej części przepływu kodu autoryzacji. |
| zasób | opcjonalny | Adres URL interfejsu API Web. Uwaga — w przypadku korzystania z biblioteki klienta MSAL parametr zasobu nie jest wysyłany. Zamiast tego adres URL zasobu jest wysyłany jako część parametru zakresu: scope = [resource url]//[scope values e.g., openid]jeśli zasób nie został przekazany tutaj lub w zakresie, AD FS używa domyślnego zasobu urn:microsoft:userinfo. Nie można dostosować zasad zasobów userinfo, takich jak uwierzytelnianie wieloskładnikowe, wystawianie lub autoryzacja. |
| zakres | opcjonalny | Rozdzielona spacjami lista zakresów. |
| token odświeżający | wymagane | Refresh_token uzyskany w drugim etapie przepływu. |
| tajemnica klienta | wymagane dla aplikacji internetowych | Sekret aplikacji utworzony w portalu rejestracji aplikacji. Nie należy jej używać w aplikacji natywnej, ponieważ client_secrets nie może być niezawodnie przechowywana na urządzeniach. Jest to wymagane w przypadku aplikacji internetowych i internetowych interfejsów API, które mają możliwość bezpiecznego przechowywania client_secret po stronie serwera. Te aplikacje mogą również używać uwierzytelniania opartego na kluczu, podpisując token JWT i dodając go jako parametr client_assertion. |
Odpowiedź pomyślna
Pomyślna odpowiedź tokenu wygląda następująco:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parametr | Opis |
|---|---|
| token dostępu | Żądany token dostępu. Aplikacja może używać tego tokenu do uwierzytelniania w zabezpieczonym zasobie, takim jak internetowy interfejs API. |
| typ tokena | Wskazuje wartość typu tokenu. Jedynym typem, który obsługuje AD FS, jest Bearer |
| wygasa_za | Jak długo token dostępu jest prawidłowy (w sekundach). |
| zakres | Zakresy, dla których access_token jest prawidłowy. |
| token odświeżania | Token odświeżania OAuth 2.0. Aplikacja może użyć tego tokenu, aby uzyskać więcej tokenów dostępu po wygaśnięciu bieżącego tokenu dostępu. Refresh_tokens są długotrwałe i mogą być używane do zachowania dostępu do zasobów przez dłuższy czas. |
| czas_wygasania_refresh_token | Jak długo token odświeżania jest ważny (w sekundach). |
| token identyfikacyjny | Token sieciowy JSON (JWT). Aplikacja może dekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował. Aplikacja może buforować wartości i wyświetlać je, ale nie powinna polegać na nich dla żadnych granic autoryzacji ani zabezpieczeń. |
Obsługa klucza weryfikacyjnego dla wymiany kodu (PKCE) w protokole OAuth
Klienci publiczni OAuth korzystający z udzielania kodu autoryzacji są narażeni na ataki przechwytujące kod autoryzacji, zgodnie z opisem w artykule RFC 7636. Aby wyeliminować te ataki, od systemu Windows Server 2019 usługa AD FS teraz obsługuje Proof Key for Code Exchange (PKCE) dla przepływu udzielania kodu autoryzacji OAuth.
Specyfikacja obsługi PKCE dodaje więcej parametrów do żądań autoryzacji i tokenu dostępu OAuth 2.0. Na poniższym diagramie przedstawiono wizualny zarys procesu PKCE, gdy klient kontaktuje się z usługami AD FS w systemie Windows Server 2019.
W sekcji oznaczonej etykietą A klient tworzy i rejestruje wpis tajny o nazwie code_verifier i uzyskuje przekształconą wersję wpisu tajnego o nazwie t(code_verifier), znaną również jako code_challenge. Następnie klient wysyła tajny klucz w żądaniu autoryzacji OAuth 2.0 razem z metodą przekształcania t_m.
W sekcji oznaczonej etykietą B punkt końcowy autoryzacji działa zgodnie z oczekiwaniami, ale rejestruje t(code_verifier) tajny sekret i metodę transformacji.
W sekcji oznaczonej jako C klient wysyła kod autoryzacji w żądaniu tokenu dostępu w zwykły sposób, ale zawiera sekret code_verifier wygenerowany w sekcji A.
W sekcji oznaczonej jako D usługi AD FS przekształca wpis code_verifiertajny i porównuje go z wpisem tajnym t(code_verifier) z sekcji B. Jeśli ich wartości nie są równe, usługi AD FS odmawia dostępu.
Jak wybrać kilku dostawców uwierzytelniania dla tej samej reguły w systemie Windows Server 2019
Usługi AD FS obsługują już wyzwalanie dodatkowego uwierzytelniania na podstawie zasad reguł oświadczeń (RP). Te zasady można ustawić dla określonego RP lub na poziomie globalnym. Dodatkowe zasady uwierzytelniania dla określonego dostawcy zasobów można ustawić, otwierając program PowerShell jako administrator i uruchamiając polecenie cmdlet Set-AdfsRelyingPartyTrust, przekazując parametr AdditionalAuthenticationRules lub AdditionalAuthenticationRulesFile. Aby ustawić ją globalnie, administrator może użyć polecenia cmdlet Set-AdfsAdditionalAuthenticationRule . Ustawienie dodatkowych zasad umożliwia użycie więcej niż jednego dostawcy uwierzytelniania dla tej samej aplikacji.
Reguły oświadczeń zapewniają opcję wyboru dostawcy uwierzytelniania na potrzeby dodatkowego uwierzytelniania, co okazuje się korzystne w sytuacjach, w których klienci przełączają się między dostawcami lub wymagają odrębnego dostawcy dla niektórych aplikacji. Od systemu Windows Server 2019 można teraz użyć reguł oświadczeń, aby zdecydować, który inny dostawca uwierzytelniania ma być wywoływany w celu dodatkowego uwierzytelniania. Ta funkcja jest przydatna w dwóch scenariuszach:
Użytkownicy przechodzą od innego dostawcy uwierzytelniania do innego. Po dołączeniu użytkowników do nowszego dostawcy uwierzytelniania mogą oni użyć grup do kontrolowania, którego dodatkowego dostawcy uwierzytelniania używa usługa.
Użytkownicy potrzebują określonego dodatkowego dostawcy uwierzytelniania dla niektórych aplikacji, ale także muszą używać innej metody dla innych aplikacji.
Te ustawienia można skonfigurować, uruchamiając następujące polecenie z poziomu innych zasad uwierzytelniania:
Set-AdfsAdditionalAuthenticationRule -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", value = "http://schemas.microsoft.com/claims/multipleauthn" );'
Aby skonfigurować tę regułę, należy wydać oświadczenie http://schemas.microsoft.com/claims/authnmethodsproviders z innych zasad uwierzytelniania. Wartość tego oświadczenia powinna być zmienną Name dostawcy uwierzytelniania.
Tę konfigurację reguły można również zmodyfikować, aby ułatwić użytkownikom przejście od jednego dostawcy uwierzytelniania do innego. Załóżmy na przykład, że chcesz zmodyfikować jedną grupę, którą zarządzasz, aby używać usługi Azure AD MFA, i jedną grupę do używania certyfikatów jako dodatkowego dostawcy uwierzytelniania.
Jeśli chcesz śledzić, ile osób rejestruje się do uwierzytelniania wieloskładnikowego Azure AD i uwierzytelniania certyfikatem, wykonaj polecenie podobne do tego, zamieniając wartości na te odpowiednie dla Twojej organizacji.
'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" );
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-21-608905689-872870963-3921916988-12345"] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication");
not exists([Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value=="S-1-5-21-608905689-872870963-3921916988-12345"]) => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");’
Następnie możesz ustawić pierwszą aplikację o nazwie AppA, aby użyć usługi Azure AD Multi-Factor Authentication jako dodatkowego dostawcy uwierzytelniania, uruchamiając następujące polecenie:
Set-AdfsRelyingPartyTrust -TargetName AppA -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" );
c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "AzureMfaAuthentication");'
Na koniec możesz ustawić drugą aplikację o nazwie AppB, aby użyć certyfikatu jako dodatkowego dostawcy uwierzytelniania, uruchamiając następujące polecenie:
Set-AdfsRelyingPartyTrust -TargetName AppB -AdditionalAuthenticationRules 'c:[type == "http://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] => issue(type = "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", Value = "http://schemas.microsoft.com/claims/multipleauthn" );
c:[] => issue(Type = "http://schemas.microsoft.com/claims/authnmethodsproviders", Value = "CertificateAuthentication");'
Administratorzy mogą również tworzyć reguły zezwalania na więcej niż jednego dodatkowego dostawcę uwierzytelniania. W tym przypadku usługa AD FS pokazuje dostawców metod uwierzytelniania, a użytkownik może wybrać dowolnego z nich. Aby umożliwić wielu dodatkowych dostawców uwierzytelniania, powinni wydać wiele oświadczeń przy użyciu wartości http://schemas.microsoft.com/claims/authnmethodsproviders.
Jeśli ocena oświadczenia nie zwraca żadnego z dostawców uwierzytelniania, AD FS cofa się i wyświetla listę wszystkich dodatkowych dostawców uwierzytelniania skonfigurowanych przez administratora w AD FS. Użytkownik musi następnie ręcznie wybrać odpowiedniego dostawcę uwierzytelniania.
Jeśli preferowany dostawca uwierzytelniania nie znajduje się na liście, możesz uruchomić następujące polecenie cmdlet, aby wyświetlić wszystkich obsługiwanych dostawców:
(Get-AdfsGlobalAuthenticationPolicy).AdditionalAuthenticationProvider
Wartość, której używasz dla http://schemas.microsoft.com/claims/authnmethodsproviders oświadczenia, powinna być jedną z nazw dostawców zwróconych przez listę dostarczoną przez AD FS.
Usługi AD FS nie obsługują wyzwalania określonego dodatkowego dostawcy uwierzytelniania, podczas gdy RP korzysta z zasad kontroli dostępu w usługach AD FS Windows Server 2016. Po przeniesieniu aplikacji z Zasad kontroli dostępu, usługa AD FS kopiuje odpowiednie zasady z Zasad kontroli dostępu do AdditionalAuthenticationRules i IssuanceAuthorizationRules. Jeśli administrator chce użyć określonego dostawcy uwierzytelniania, powinien przestać używać zasad kontroli dostępu, a zamiast tego zmodyfikować dodatkowe uwierzytelnianieRules.
PrzepływBehalf-Of
Uwaga
Firma Microsoft zdecydowanie zaleca migrację do identyfikatora Entra firmy Microsoft zamiast uaktualniania do nowszej wersji usług AD FS. Aby uzyskać więcej informacji na temat przepływu On-Behalf-Of w usłudze Microsoft Entra ID, zobacz Przepływ On-Behalf-Of w platformie tożsamości Microsoft (Microsoft Identity Platform).
Przepływ OAuth 2.0 On-Behalf-Of (OBO) obsługuje przypadek użycia, w którym aplikacja wywołuje interfejs API sieci Web, który z kolei musi wywołać inny interfejs API tej samej usługi lub sieci Web. Chodzi o propagowanie delegowanej tożsamości użytkownika i uprawnień za pośrednictwem łańcucha żądań. Aby usługa warstwy środkowej wysyłała uwierzytelnione żądania do usługi podrzędnej, musi zabezpieczyć token dostępu z usług AD FS w imieniu użytkownika.
Diagram protokołu
Załóżmy, że użytkownik został uwierzytelniony w aplikacji przy użyciu przepływu udzielania kodu autoryzacji OAuth 2.0 opisanego w poprzedniej sekcji. W tym momencie aplikacja ma token dostępu dla interfejsu API A (token A) z oświadczeniami użytkownika i zgodą na dostęp do środkowej warstwy interfejsu sieciowego API (API A). Upewnij się, że klient żąda zakresu: user_impersonation w tokenie. Teraz interfejs API A musi wysłać uwierzytelnione żądanie do podrzędnego internetowego interfejsu API (API B).
Kroki, które należy wykonać, stanowią przepływ OBO i zostały wyjaśnione za pomocą poniższego diagramu.
- Aplikacja kliencka wysyła żądanie do interfejsu API A z tokenem A. Uwaga: podczas konfigurowania przepływu OBO w usługach AD FS upewnij się, że wybrano zakres
user_impersonationi że klient żąda zakresuuser_impersonationw żądaniu. - Interfejs API A uwierzytelnia się w punkcie końcowym wystawiania tokenu usług AD FS i żąda tokenu dostępu do interfejsu API B. Uwaga: podczas konfigurowania tego przepływu w usługach AD FS upewnij się, że interfejs API A jest również zarejestrowany jako aplikacja serwera z identyfikatorem clientID o tej samej wartości co identyfikator zasobu w interfejsie API A.
- Punkt końcowy wystawiania tokenów w usługach AD FS weryfikuje poświadczenia API A za pomocą tokenu A, a następnie wystawia token dostępu dla API B (token B).
- Token B jest ustawiony w nagłówku autoryzacji żądania do API B.
- Dane z zabezpieczonego zasobu są zwracane przez interfejs API B.
Żądanie tokenu dostępu usługa-do-usługi
Aby zażądać tokenu dostępu, wykonaj żądanie HTTP POST do punktu końcowego tokenu AD FS z następującymi parametrami.
Pierwszy przypadek: żądanie tokenu dostępu z współdzielonym sekretem
W przypadku wspólnego sekretu żądanie tokenu dostępu między usługami zawiera następujące parametry.
| Parametr | Wymagane/opcjonalne | Opis |
|---|---|---|
| typ_grantu | wymagane | Typ żądania tokenu. W przypadku żądania używającego JWT wartość musi być urn:ietf:params:oauth:grant-type:jwt-bearer. |
| identyfikator_klienta | wymagane | Identyfikator klienta skonfigurowany podczas rejestrowania pierwszego internetowego interfejsu API jako aplikacji serwera (aplikacji warstwy środkowej). Powinien być taki sam jak identyfikator zasobu używany w pierwszym etapie, czyli adres URL pierwszego internetowego interfejsu API. |
| tajemnica klienta | wymagane | Tajny klucz aplikacji utworzony podczas rejestracji aplikacji serwera w usługach AD FS. |
| twierdzenie | wymagane | Wartość tokenu używanego w żądaniu. |
| żądane_użycie_tokena | wymagane | Określa sposób przetwarzania żądania. W przepływie OBO wartość musi być ustawiona na wartość on_behalf_of |
| zasób | wymagane | Identyfikator zasobu podany podczas rejestrowania pierwszego interfejsu API jako aplikacji serwera (aplikacja środkowej warstwy). Identyfikator zasobu powinien być adresem URL drugiego wywołania aplikacji warstwy środkowej interfejsu API sieci Web w imieniu klienta. |
| zakres | opcjonalny | Rozdzielona spacją lista zakresów dla żądania tokenu. |
Przykład
Następujące HTTP POST żądanie dotyczy tokenu dostępu i tokenu odświeżania
//line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=https://webapi.com/
&client_secret=BYyVnAt56JpLwUcyo47XODd
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope=openid
Drugi przypadek: żądanie tokenu dostępu z certyfikatem
Żądanie tokenu dostępu typu service-to-service z certyfikatem zawiera następujące parametry:
| Parametr | wymagane/opcjonalne | Opis |
|---|---|---|
| typ_grantu | wymagane | Typ żądania tokenu. W przypadku żądania używającego tokena JWT wartość musi być urn:ietf:params:oauth:grant-type:jwt-bearer. |
| identyfikator_klienta | wymagane | Identyfikator klienta skonfigurowany podczas rejestrowania pierwszego internetowego interfejsu API jako aplikacji serwera (aplikacji warstwy środkowej). Powinien być taki sam jak identyfikator zasobu używany w pierwszym etapie, czyli adres URL pierwszego internetowego interfejsu API. |
| typ_potwierdzenia_klienta | wymagane | Wartość musi być typu urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
| oświadczenie_klienta | wymagane | Potwierdzenie (token internetowy JSON), który należy utworzyć i podpisać przy użyciu certyfikatu zarejestrowanego jako poświadczenia aplikacji. |
| twierdzenie | wymagane | Wartość tokenu używanego w żądaniu. |
| żądane_użycie_tokenu | wymagane | Określa sposób przetwarzania żądania. W przepływie OBO wartość musi być ustawiona na on_behalf_of. |
| zasób | wymagane | Identyfikator zasobu podany podczas rejestrowania pierwszego interfejsu API jako aplikacji serwerowej (aplikacja warstwy pośredniej). Identyfikator zasobu powinien być adresem URL drugiego wywołania aplikacji warstwy środkowej interfejsu API sieci Web w imieniu klienta. |
| zakres | opcjonalny | Rozdzielona spacją lista zakresów dla żądania tokenu. |
Zwróć uwagę, że parametry są prawie takie same. Ten przykład jest podobny do żądania udostępnionego wpisu tajnego, z tą różnicą, że parametr client_secret jest zastępowany dwoma parametrami: client_assertion_type i client_assertion.
Przykład
Następujący kod HTTP POST żąda tokenu dostępu dla internetowego interfejsu API z certyfikatem.
// line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id= https://webapi.com/
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNS…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope= openid
Odpowiedź tokenu dostępu do usługi
Odpowiedź na powodzenie to odpowiedź JSON OAuth 2.0 z następującymi parametrami.
| Parametr | Opis |
|---|---|
| typ tokena | Wskazuje wartość typu tokenu. Jedynym typem obsługiwanym przez usługi AD FS jest Bearer. |
| zakres | Zakres dostępu udzielony przez token. |
| wygasa_za | Okres ważności tokenu dostępu, wyrażony w sekundach. |
| token dostępu | Żądany token dostępu. Usługa wywołująca może używać tego tokenu do uwierzytelniania w usłudze odbierającej. |
| token identyfikacyjny | Token sieciowy JSON (JWT) Aplikacja może dekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował. Aplikacja może buforować wartości i wyświetlać je, ale nie powinna polegać na nich dla żadnych granic autoryzacji ani zabezpieczeń. |
| token odświeżania | Token odświeżania dla żądanego tokenu dostępu. Usługa wywołująca może użyć tego tokenu, aby zażądać innego tokenu dostępu po wygaśnięciu bieżącego tokenu dostępu. |
| Refresh_token_expires_in | Czas w sekundach, przez który token odświeżania jest prawidłowy. |
Przykład odpowiedzi na powodzenie
W poniższym przykładzie przedstawiono pomyślną odpowiedź na żądanie tokenu dostępu dla internetowego interfejsu API.
{
"token_type": "Bearer",
"scope": openid,
"expires_in": 3269,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1t"
"id_token": "aWRfdG9rZW49ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOa"
"refresh_token": "OAQABAAAAAABnfiG…"
"refresh_token_expires_in": 28800,
}
Użyj tokenu dostępu, aby uzyskać dostęp do zabezpieczonego zasobu Teraz usługa warstwy środkowej może użyć tokenu uzyskanego w poprzednim przykładzie odpowiedzi, aby wysyłać uwierzytelnione żądania do podrzędnego internetowego interfejsu API, ustawiając token w nagłówku Autoryzacja.
Przykład
GET /v1.0/me HTTP/1.1
Host: https://secondwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQ…
Przepływ udzielania poświadczeń klienta
Uwaga
Firma Microsoft zdecydowanie zaleca migrację do identyfikatora Entra firmy Microsoft zamiast uaktualniania do nowszej wersji usług AD FS. Aby uzyskać więcej informacji na temat przepływu udzielania poświadczeń klienta w identyfikatorze Entra firmy Microsoft, zobacz Przepływ udzielania poświadczeń klienta na platformie tożsamości firmy Microsoft.
Aby uzyskać dostęp do zasobów hostowanych w Internecie przy użyciu tożsamości aplikacji, można użyć udzielenia poświadczeń klienta OAuth 2.0 określonych w specyfikacji RFC 6749. Ten rodzaj grantów jest często używany do interakcji między serwerami, które muszą działać w tle, bez natychmiastowej interakcji z użytkownikiem. Te typy aplikacji są często określane jako demony lub konta serwisowe.
Przepływ przyznawania poświadczeń dla klienta OAuth 2.0 pozwala usłudze internetowej (poufny klient) używać własnych poświadczeń do uwierzytelniania, bez podszywania się pod użytkownika, gdy wywołuje inną usługę sieciową. W tym scenariuszu klient jest zazwyczaj usługą internetową warstwy środkowej, usługą demona lub witryną internetową. W celu zapewnienia wyższego poziomu zabezpieczeń AD FS umożliwia również usłudze wywołującej używanie certyfikatu (zamiast wspólnego sekretu) jako poświadczenia.
Diagram protokołu
Na poniższym diagramie przedstawiono przepływ udzielania poświadczeń klienta.
Żądanie tokenu
Aby uzyskać token przy użyciu udzielenia poświadczeń klienta, wyślij POST żądanie do punktu końcowego usługi AD FS /token:
Pierwszy przypadek: żądanie tokenu dostępu z współdzielonym sekretem
POST /adfs/oauth2/token HTTP/1.1
//Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| Parametr | Wymagane/opcjonalne | Opis |
|---|---|---|
| identyfikator_klienta | wymagane | Identyfikator aplikacji (klienta) przypisany Twojej aplikacji przez AD FS. |
| zakres | opcjonalny | Rozdzielona spacjami lista zakresów, do których użytkownik ma wyrazić zgodę. |
| tajemnica klienta | wymagane | Tajny klucz klienta, który wygenerowałeś dla swojej aplikacji w portalu rejestracji aplikacji. Klucz tajny klienta musi być zakodowany w adresie URL przed wysłaniem. |
| typ_grantu | wymagane | Musi być ustawione na client_credentials. |
Drugi przypadek: żądanie tokenu dostępu z certyfikatem
POST /adfs/oauth2/token HTTP/1.1
// Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| Parametr | Wymagane/opcjonalne | Opis |
|---|---|---|
| client_assertion_type | wymagane | Wartość musi być ustawiona na wartość urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
| oświadczenie_klienta | wymagane | Potwierdzenie (token sieciowy JSON), które trzeba utworzyć i podpisać za pomocą certyfikatu zarejestrowanego jako poświadczenie aplikacji. |
| typ_grantu | wymagane | Musi być ustawione na client_credentials. |
| identyfikator_klienta | opcjonalny | Identyfikator aplikacji (klienta), który usługa AD FS przypisała twojej aplikacji. Jest to część client_assertion, więc nie jest wymagane przekazanie jej tutaj. |
| zakres | opcjonalny | Rozdzielona spacjami lista zakresów, do których użytkownik ma wyrazić zgodę. |
Używanie tokenu
Po uzyskaniu tokenu użyj tokenu, aby wysyłać żądania do zasobu. Po wygaśnięciu tokenu powtórz żądanie do punktu końcowego /token, aby uzyskać nowy token dostępu.
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Proces przyznawania dostępu na podstawie poświadczeń hasła właściciela zasobu (niezalecane)
Uwaga
Firma Microsoft zdecydowanie zaleca migrację do identyfikatora Entra firmy Microsoft zamiast uaktualniania do nowszej wersji usług AD FS. Aby uzyskać więcej informacji na temat przepływu udzielania poświadczeń hasła właściciela zasobu w identyfikatorze Entra firmy Microsoft, zobacz Przepływ udzielania poświadczeń hasła właściciela zasobu na platformie tożsamości firmy Microsoft.
Przyznanie dostępu za pomocą poświadczeń hasła właściciela zasobu (ROPC) umożliwia aplikacji logowanie użytkownika poprzez bezpośrednie przetwarzanie jego hasła. Przepływ ROPC wymaga wysokiego stopnia zaufania i narażenia użytkowników i należy używać tego przepływu tylko wtedy, gdy nie można używać innych, bezpieczniejszych przepływów.
Diagram protokołu
Na poniższym diagramie przedstawiono przepływ ROPC.
Żądanie autoryzacji
Przepływ ROPC jest pojedynczym żądaniem — wysyła identyfikację klienta i poświadczenia użytkownika do dostawcy tożsamości, a następnie otrzymuje tokeny w zamian. Przed wykonaniem tej czynności klient musi zażądać adresu e-mail użytkownika (UPN) i hasła. Natychmiast po pomyślnym żądaniu klient powinien bezpiecznie zwolnić poświadczenia użytkownika z pamięci. Nigdy nie może ich uratować.
// Line breaks and spaces are for legibility only.
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope= openid
&username=myusername@contoso.com
&password=SuperS3cret
&grant_type=password
| Parametr | Wymagane/opcjonalne | Opis |
|---|---|---|
| identyfikator_klienta | wymagane | Identyfikator klienta |
| typ_grantu | wymagane | Musi być ustawiona na hasło. |
| nazwa użytkownika | wymagane | Adres e-mail użytkownika. |
| hasło | wymagane | Hasło użytkownika. |
| zakres | opcjonalny | Rozdzielona spacjami lista zakresów. |
Pomyślna odpowiedź na uwierzytelnianie
W poniższym przykładzie przedstawiono pomyślną odpowiedź tokenu:
{
"token_type": "Bearer",
"scope": "openid",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDR..."
}
| Parametr | Opis |
|---|---|
| typ tokena | Zawsze ustaw na Bearer. |
| zakres | Jeśli zwrócono token dostępu, ten parametr zawiera listę zakresów, dla których token dostępu jest prawidłowy. |
| wygasa_za | Liczba sekund ważności dołączonego tokenu dostępu. |
| token dostępu | Wystawiono dla żądanych zakresów. |
| token identyfikacyjny | Token sieciowy JSON (JWT). Aplikacja może dekodować segmenty tego tokenu, aby zażądać informacji o użytkowniku, który się zalogował. Aplikacja może buforować wartości i wyświetlać je, ale nie powinna polegać na nich dla żadnych granic autoryzacji ani zabezpieczeń. |
| czas_wygasania_refresh_token | Liczba sekund ważności dołączonego tokenu odświeżania. |
| refresh_token | Wystawiono, jeśli oryginalny parametr zakresu zawiera offline_access. |
Token odświeżania służy do uzyskiwania nowych tokenów dostępu i odświeżania tokenów przy użyciu tego samego przepływu opisanego w sekcji przepływu udzielania kodu uwierzytelniania w tym artykule.
Przepływ kodu urządzenia
Uwaga
Firma Microsoft zdecydowanie zaleca migrację do identyfikatora Entra firmy Microsoft zamiast uaktualniania do nowszej wersji usług AD FS. Aby uzyskać więcej informacji na temat przepływu kodu urządzenia w usłudze Microsoft Entra ID, zobacz Przepływ kodu urządzenia na platformie tożsamości firmy Microsoft.
Przyznawanie kodu urządzenia umożliwia użytkownikom logowanie się do urządzeń z ograniczonymi danymi wejściowymi, takich jak smart TV, urządzenie IoT lub drukarka. Aby włączyć ten przepływ, użytkownik odwiedza stronę internetową w przeglądarce na innym urządzeniu, aby się zalogować. Po zalogowaniu się użytkownik będzie mógł uzyskać tokeny dostępu i odświeżyć tokeny zgodnie z potrzebami.
Diagram protokołu
Cały przepływ kodu urządzenia wygląda podobnie do następnego diagramu. W dalszej części tego artykułu opisano poszczególne kroki.
Żądanie autoryzacji urządzenia
Klient musi najpierw sprawdzić u serwera uwierzytelniania kody urządzenia i użytkownika, które są używane do inicjowania uwierzytelniania. Klient zbiera to żądanie z punktu końcowego /devicecode . W tym żądaniu klient powinien również uwzględnić uprawnienia, które musi uzyskać od użytkownika. Od momentu wysłania tego żądania użytkownik ma tylko 15 minut na zalogowanie (zwykłą wartość dla expires_in), więc wyślij to żądanie tylko wtedy, gdy użytkownik poinformował, że jest gotowy do zalogowania.
// Line breaks are for legibility only.
POST https://adfs.contoso.com/adfs/oauth2/devicecode
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
scope=openid
| Parametr | Warunek | Opis |
|---|---|---|
| identyfikator_klienta | wymagane | Identyfikator aplikacji (klienta) przypisany do aplikacji przez usługi AD FS. |
| zakres | opcjonalny | Rozdzielona spacjami lista zakresów. |
Odpowiedź na autoryzację urządzenia
Pomyślna odpowiedź to obiekt JSON zawierający wymagane informacje, aby umożliwić użytkownikowi logowanie się.
| Parametr | Opis |
|---|---|
| device_code | Długi ciąg używany do weryfikowania sesji między klientem a serwerem autoryzacji. Klient używa tego parametru do żądania tokenu dostępu z serwera autoryzacji. |
| user_code | Krótki ciąg wyświetlany użytkownikowi, który jest używany do identyfikowania sesji na urządzeniu pomocniczym. |
| verification_uri | Identyfikator URI, do którego użytkownik powinien przejść przy użyciu kodu użytkownika, aby się zalogować. |
| weryfikacja_uri_zakończona | Identyfikator URI, do którego użytkownik powinien przejść przy użyciu kodu użytkownika, aby się zalogować. Jest z góry wypełniona kodem użytkownika, dzięki czemu użytkownik nie musi go wprowadzać. |
| wygasa_za | Liczba sekund, zanim device_code i user_code wygasną. |
| interwał | Liczba sekund, przez które klient powinien czekać między żądaniami sondowania. |
| Komunikat | Ciąg czytelny dla człowieka z instrukcjami dla użytkownika. Można go lokalizować, dołączając parametr zapytania w żądaniu formularza ?mkt=xx-XX, wypełniając odpowiedni kod kultury języka. |
Uwierzytelnianie użytkownika
Gdy klient otrzyma user_code i verification_uri, wyświetli te szczegóły użytkownikowi, poinstruując ich, aby zalogowali się przy użyciu telefonu komórkowego lub przeglądarki komputera. Ponadto klient może użyć kodu QR lub podobnego mechanizmu, aby wyświetlić verification_uri_complete, który upraszcza krok wprowadzania user_code przez użytkownika.
Podczas gdy użytkownik uwierzytelnia się w verification_uri, klient powinien odpytywać /token punkt końcowy za pomocą device_code w celu uzyskania żądanego tokenu.
POST https://adfs.contoso.com /adfs/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type: urn:ietf:params:oauth:grant-type:device_code
client_id: 00001111-aaaa-2222-bbbb-3333cccc4444
device_code: GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8
| Parametr | wymagane | Opis |
|---|---|---|
| typ_grantu | wymagane | Musi być urn:ietf:params:oauth:grant-type:device_code |
| identyfikator_klienta | wymagane | Musi być zgodna z client_id używanym w początkowym żądaniu. |
| kod | wymagane | Kod_urządzenia zwrócony w żądaniu autoryzacji urządzenia. |
Odpowiedź uwierzytelniania pomyślna
Pomyślna odpowiedź tokenu wygląda następująco:
| Parametr | Opis |
|---|---|
| typ tokena | Zawsze "Bearer". |
| zakres | Jeśli zwrócono token dostępu, wyświetla on zakresy, dla których token dostępu jest prawidłowy. |
| wygasa_za | Liczba sekund przed prawidłowym dołączonym tokenem dostępu. |
| token dostępu | Wystawiono dla żądanych zakresów. |
| token identyfikacyjny | Wystawiono, jeśli oryginalny parametr zakresu zawierał zakres openid. |
| refresh_token | Wystawiono, jeśli oryginalny parametr zakresu zawierał offline_access. |
| czas_wygasania_refresh_token | Liczba sekund, zanim dołączony token odświeżania stanie się ważny. |
Powiązana zawartość
Aby uzyskać pełną listę artykułów z przewodnikami, zobacz Artykuły dotyczące programowania w usługach AD FS , które zawierają instrukcje krok po kroku dotyczące korzystania z powiązanych przepływów.