Udostępnij za pośrednictwem

Zakresy i uprawnienia w platformie tożsamości Microsoft

  • Artykuł

Platforma tożsamości Microsoft implementuje protokół autoryzacji OAuth 2.0. OAuth 2.0 to metoda, za pomocą której aplikacja innej firmy może uzyskiwać dostęp do zasobów hostowanych w Internecie w imieniu użytkownika. Każdy zasób hostowany w internecie, który integruje się z Platformą Tożsamości Microsoft, ma identyfikator zasobu lub URI identyfikatora aplikacji.

Z tego artykułu dowiesz się więcej o zakresach i uprawnieniach na platformie tożsamości.

Na poniższej liście przedstawiono kilka przykładów zasobów hostowanych przez internet firmy Microsoft:

  • Microsoft Graph: https://graph.microsoft.com
  • Interfejs API poczty platformy Microsoft 365: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

To samo dotyczy wszystkich zasobów innych firm, które integrują się z platformą tożsamości firmy Microsoft. Każdy z tych zasobów może również zdefiniować zestaw uprawnień, które dzielą funkcjonalność tego zasobu na mniejsze fragmenty. Na przykład Microsoft Graph definiuje uprawnienia do wykonywania następujących zadań, między innymi:

  • Odczytywanie kalendarza użytkownika
  • Zapisywanie w kalendarzu użytkownika
  • Wysyłanie wiadomości e-mail jako użytkownik

Ze względu na te typy definicji uprawnień zasób ma szczegółową kontrolę nad danymi i sposobem uwidocznienia funkcji interfejsu API. Aplikacja innej firmy może zażądać tych uprawnień od użytkowników i administratorów, którzy muszą zatwierdzić żądanie, zanim aplikacja będzie mogła uzyskać dostęp do danych lub działać w imieniu użytkownika.

Gdy funkcjonalność zasobu jest podzielona na małe zestawy uprawnień, aplikacje innych firm można tworzyć tak, aby żądały tylko tych uprawnień, które są im potrzebne do wykonywania swoich zadań. Użytkownicy i administratorzy mogą wiedzieć, do jakich danych może uzyskiwać dostęp aplikacja. I mogą być bardziej pewni, że aplikacja nie działa ze złośliwymi intencjami. Deweloperzy powinni zawsze przestrzegać zasady najniższych uprawnień, prosząc o uprawnienia, których potrzebują, aby aplikacje działały.

W usłudze OAuth 2.0 te typy zestawów uprawnień są nazywane zakresami. Są one również często określane jako uprawnienia. Na platformie tożsamości Microsoft uprawnienie jest reprezentowane jako wartość ciągu. Aplikacja żąda wymaganych uprawnień, określając uprawnienie w parametrze scope zapytania. Platforma tożsamości obsługuje kilka dobrze zdefiniowanych zakresów programu OpenID Connect i uprawnień opartych na zasobach (każde uprawnienie jest wskazywane przez dołączenie wartości uprawnień do identyfikatora zasobu lub identyfikatora URI identyfikatora aplikacji). Na przykład ciąg https://graph.microsoft.com/Calendars.Read uprawnień jest używany do żądania uprawnień do odczytywania kalendarzy użytkowników w programie Microsoft Graph.

W żądaniach do serwera autoryzacji, dla platformy tożsamości Microsoft, jeśli identyfikator zasobu zostanie pominięty w parametrze zakresu, przyjmuje się, że zasób to Microsoft Graph. Na przykład instrukcja scope=User.Read jest równoważna instrukcji https://graph.microsoft.com/User.Read.

Uprawnienia ograniczone przez administratora

Uprawnienia na platformie tożsamości Microsoft można ustawić jako ograniczone przez administratora. Na przykład wiele uprawnień wyższego poziomu uprawnień programu Microsoft Graph wymaga zatwierdzenia przez administratora. Jeśli aplikacja wymaga uprawnień ograniczonych przez administratora, administrator organizacji musi wyrazić zgodę na te zakresy w imieniu użytkowników organizacji. W poniższej sekcji przedstawiono przykłady tego rodzaju uprawnień:

  • User.Read.All: Odczytywanie pełnych profilów wszystkich użytkowników
  • Directory.ReadWrite.All: Zapisywanie danych w katalogu organizacji
  • Groups.Read.All: Odczytaj wszystkie grupy w katalogu organizacji

Uwaga

W żądaniach do punktów końcowych autoryzacji, tokenu lub zgody dla platformy tożsamości Microsoft, jeśli identyfikator zasobu zostanie pominięty w parametrze zakresu, zakłada się, że zasobem jest Microsoft Graph. Na przykład instrukcja scope=User.Read jest równoważna instrukcji https://graph.microsoft.com/User.Read.

Mimo że użytkownik konsumenta może udzielić aplikacji dostępu do tego rodzaju danych, użytkownicy organizacji nie mogą udzielać dostępu do tego samego zestawu poufnych danych firmy. Jeśli aplikacja żąda dostępu do jednego z tych uprawnień od użytkownika organizacyjnego, użytkownik otrzymuje komunikat o błędzie informujący, że nie ma autoryzacji do wyrażania zgody na uprawnienia aplikacji.

Jeśli aplikacja żąda uprawnień aplikacji, a administrator przyznaje te uprawnienia, to przyznanie nie jest wykonywane w imieniu żadnego określonego użytkownika. Zamiast tego aplikacja kliencka ma bezpośrednio przyznane uprawnienia. Tego typu uprawnienia powinny być używane tylko przez usługi demona i inne aplikacje nieinterakcyjne, które działają w tle. Aby uzyskać więcej informacji na temat scenariusza bezpośredniego dostępu, zobacz Scenariusze dostępu w Platforma tożsamości Microsoft.

Aby uzyskać szczegółowy przewodnik dotyczący uwidaczniania zakresów w internetowym interfejsie API, zobacz Konfigurowanie aplikacji w celu uwidocznienia internetowego interfejsu API.

Zakresy OpenID Connect

Implementacja platformy tożsamości firmy Microsoft OpenID Connect ma kilka dobrze zdefiniowanych zakresów, które są również hostowane w programie Microsoft Graph: openid, email, profile i offline_access. address i phone zakresy OpenID Connect nie są obsługiwane. Te zakresy są czasami opcjonalne i uznawane za wzbogacanie tokenu identyfikatora. Te zakresy nie zawsze będą wyświetlane w osobnych wierszach w monicie zgody dla użytkownika.

Jeśli zażądasz zakresów OpenID Connect i tokenu, otrzymasz token w celu wywołania punktu końcowego UserInfo.

Zakres openid

Jeśli aplikacja loguje się używając OpenID Connect, musi zażądać zakresu openid. Zakres openid jest wyświetlany na stronie zgody konta służbowego jako uprawnienie Zaloguj się .

Aplikacja używa tego uprawnienia do odbierania unikatowego identyfikatora użytkownika w postaci oświadczenia sub. Uprawnienie daje również aplikacji dostęp do punktu końcowego UserInfo. Zakres openid może być używany w punkcie końcowym tokenu platformy tożsamości Microsoft do uzyskiwania tokenów ID. Aplikacja może używać tych tokenów do uwierzytelniania.

Zakres email

Zakres email może być używany z zakresem openid i innymi zakresami. Zapewnia ona aplikacji dostęp do podstawowego adresu e-mail użytkownika w postaci email oświadczenia.

Oświadczenie email jest uwzględniane w tokenie tylko wtedy, gdy adres e-mail jest skojarzony z kontem użytkownika, co nie zawsze ma miejsce. Jeśli aplikacja używa email zakresu, musi umieć obsłużyć sytuację, w której w tokenie nie ma email oświadczenia.

Zakres profile

Zakres profile może być używany z zakresem openid oraz z dowolnym innym zakresem. Zapewnia ona aplikacji dostęp do dużej ilości informacji o użytkowniku. Informacje, do których może uzyskać dostęp, obejmują, ale nie tylko imię, nazwisko użytkownika, preferowaną nazwę użytkownika i identyfikator obiektu.

Aby uzyskać pełną listę profile oświadczeń dostępnych w parametrze id_tokens dla określonego użytkownika, zobacz id_tokens dokumentację.

Zakres offline_access

Zakres offline_access zapewnia aplikacji dostęp do zasobów w imieniu użytkownika przez dłuższy czas. Na stronie zgody ten zakres jest wyświetlany jako Zachowaj dostęp do danych, do których udzielono mu dostępu.

Jeśli którekolwiek z żądanych uprawnień delegowanych z parametru scope (z wyłączeniem openid, profile, email) zostanie przyznane, to jest wystarczające, aby aplikacja mogła zażądać tokenu odświeżania przy użyciu offline_access. Jeśli na przykład User.Read dla firmy Microsoft zostanie udzielona, aplikacja otrzyma tylko token dostępu. Oznacza to, że jeśli aplikacja miałaby następnie zażądać tokenu odświeżania, udzielenie User.Read jest wystarczające do dostarczenia takiego tokenu. Tokeny odświeżania są długoterminowe. Twoja aplikacja może uzyskać nowe tokeny dostępu w miarę wygasania starszych.

Uwaga

To uprawnienie jest wyświetlane obecnie na wszystkich stronach zgody, nawet w przypadku przepływów, które nie udostępniają tokenu odświeżania, takich jak niejawny przepływ. Ta konfiguracja dotyczy scenariuszy, w których klient może rozpocząć pracę w przepływie niejawnym, a następnie przejść do przepływu kodu, w którym oczekiwano tokenu odświeżania.

Na platformie tożsamości Microsoft (żądania wysyłane do punktu końcowego w wersji 2.0) Twoja aplikacja musi jawnie zażądać zakresu offline_access, aby otrzymać tokeny odświeżania. Dlatego w przypadku realizacji kodu autoryzacji w przepływie kodu autoryzacji OAuth 2.0otrzymujesz token dostępu z punktu końcowego .

Token dostępu jest ważny przez około godzinę. W tym momencie aplikacja musi przekierować użytkownika z powrotem do punktu końcowego /authorize , aby zażądać nowego kodu autoryzacji. Podczas tego przekierowania i w zależności od typu aplikacji może być konieczne ponowne wprowadzenie poświadczeń lub ponowne wyrażenie zgody na uprawnienia.

Token odświeżania ma dłuższy czas wygaśnięcia niż token dostępu i jest zwykle ważny przez 90 dni. Aby uzyskać więcej informacji na temat uzyskiwania i używania tokenów odświeżania, zobacz dokumentację protokołu platformy tożsamości Microsoft.

Dołączenie tokenu odświeżania w odpowiedzi może zależeć od kilku czynników, w tym od określonej konfiguracji aplikacji i zakresów żądanych podczas procesu autoryzacji. Jeśli oczekujesz otrzymać token odświeżenia w odpowiedzi, ale go nie otrzymujesz, rozważ następujące czynniki:

  • Wymagania dotyczące zakresu: Upewnij się, że żądasz zakresów offline_access wraz z innymi wymaganymi zakresami.
  • typ udzielania autoryzacji: token odświeżania jest udostępniany podczas korzystania z typu udzielania kodu autoryzacji. Jeśli przepływ się różni, może to mieć wpływ na odpowiedź.
  • Konfiguracja klienta: sprawdź ustawienia aplikacji na platformie tożsamości. Niektóre konfiguracje mogą ograniczać wystawianie refresh_tokens.

Zakres .default

Zakres .default służy do ogólnego odwoływania się do usługi zasobowej (API) w żądaniu, bez wskazywania na specyficzne uprawnienia. W razie potrzeby korzystanie z .default sygnalizuje, że należy uzyskać zgodę na wszystkie wymagane uprawnienia wymienione w rejestracji aplikacji (dla wszystkich wymienionych interfejsów API).

Wartość parametru zakresu jest konstruowana przy użyciu identyfikatora URI zasobu i .default, oddzielonego ukośnikiem (/). Na przykład, jeśli identyfikator URI zasobu to https://contoso.com, to żądany zakres to https://contoso.com/.default. Jeśli musisz dodać drugi ukośnik, aby poprawnie zażądać tokenu, zobacz sekcję dotyczącą końcowych ukośników.

Użycie scope={resource-identifier}/.default jest funkcjonalnie takie samo jak resource={resource-identifier} w punkcie końcowym w wersji 1.0 (gdzie {resource-identifier} jest identyfikatorem URI interfejsu API, na przykład https://graph.microsoft.com dla programu Microsoft Graph).

Zakres .default może być używany w dowolnym przepływie OAuth 2.0 i inicjować zgodę administratora. Jego użycie jest wymagane w przepływie On-Behalf-Of i przepływie poświadczeń klienta.

Klienci nie mogą łączyć statycznej zgody (.default) i dynamicznej zgody w jednym żądaniu. Dlatego scope=https://graph.microsoft.com/.default Mail.Read skutkuje błędem, ponieważ wiąże się z typami zakresów.

Parametr zakresu .default wyzwala monit o wyrażenie zgody tylko wtedy, gdy zgoda nie została udzielona dla żadnych delegowanych uprawnień między klientem a zasobem w imieniu zalogowanego użytkownika.

Jeśli istnieje zgoda, zwrócony token zawiera wszystkie zakresy przyznane dla tego zasobu dla zalogowanego użytkownika. Jeśli jednak nie udzielono żadnych uprawnień dla żądanego zasobu (lub jeśli podano parametr prompt=consent), zostanie wyświetlony monit o wyrażenie zgody dla wszystkich wymaganych uprawnień skonfigurowanych podczas rejestracji aplikacji klienckiej dla wszystkich interfejsów API na liście.

Jeśli na przykład zakres https://graph.microsoft.com/.default jest żądany, aplikacja żąda tokenu dostępu dla interfejsu API programu Microsoft Graph. Jeśli co najmniej jedno delegowane uprawnienie zostało przyznane dla programu Microsoft Graph w imieniu zalogowanego użytkownika, logowanie będzie kontynuowane. Wszystkie delegowane uprawnienia programu Microsoft Graph, które zostały przyznane dla tego użytkownika, zostaną uwzględnione w tokenie dostępu. Jeśli dla żądanego zasobu nie udzielono żadnych uprawnień (w tym przykładzie program Microsoft Graph), zostanie wyświetlony monit o wyrażenie zgody dla wszystkich wymaganych uprawnień skonfigurowanych w aplikacji dla wszystkich interfejsów API na liście.

Przykład 1: Użytkownik lub administrator dzierżawy ma przyznane uprawnienia

W tym przykładzie użytkownik lub administrator dzierżawy udzielił klientowi uprawnień Mail.Read i User.Read do korzystania z Microsoft Graph.

Jeśli klient żąda scope=https://graph.microsoft.com/.default, nie jest wyświetlany żaden monit o wyrażenie zgody, niezależnie od zawartości zarejestrowanych uprawnień aplikacji klienckiej dla programu Microsoft Graph. Zwrócony token zawiera zakresy Mail.Read i User.Read.

Przykład 2: Użytkownik nie udzielił uprawnień między klientem a zasobem

W tym przykładzie użytkownik nie udzielił zgody między klientem a programem Microsoft Graph ani nie ma administratora. Klient zarejestrował się do uprawnień User.Read i Contacts.Read oraz zgłosił się do zakresu usługi Azure Key Vault https://vault.azure.net/user_impersonation.

Gdy klient żąda tokenu dla scope=https://graph.microsoft.com/.default, użytkownik zobaczy stronę zgody dla zakresów Microsoft Graph User.Read i Contacts.Read, oraz dla zakresu Azure Key Vault user_impersonation. Zwrócony token zawiera tylko zakresy User.Read i Contacts.Read i może być używany tylko do usługi Microsoft Graph.

Przykład 3: Użytkownik wyraził zgodę, a klient żąda większej liczby zakresów

W tym przykładzie użytkownik już wyraził zgodę na Mail.Read dla klienta. Klient zarejestrował się do zakresu Contacts.Read.

Klient najpierw wykonuje logowanie się przy użyciu scope=https://graph.microsoft.com/.default. Na podstawie parametru odpowiedzi scopes, kod aplikacji wykrywa, że udzielono tylko Mail.Read. Następnie klient inicjuje drugie logowanie przy użyciu polecenia scope=https://graph.microsoft.com/.default, a tym razem wymusza zgodę przy użyciu polecenia prompt=consent. Jeśli użytkownik może wyrazić zgodę na wszystkie uprawnienia zarejestrowane przez aplikację, zostanie wyświetlony monit o wyrażenie zgody. (Jeśli nie, wyświetlany jest im komunikat o błędzie lub formularz żądania zgody administratora.) Zarówno Contacts.Read, jak i Mail.Read są wyświetlane w prośbie o zgodę. Jeśli udzielono zgody, a logowanie jest kontynuowane, zwrócony token dotyczy programu Microsoft Graph i zawiera Mail.Read oraz Contacts.Read.

.default Używanie zakresu z klientem

W niektórych przypadkach klient może zażądać własnego .default zakresu. W poniższym przykładzie pokazano ten scenariusz.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Ten przykładowy kod tworzy stronę zgody dla wszystkich zarejestrowanych uprawnień, jeśli powyższe opisy zgody i .default mają zastosowanie do scenariusza. Następnie kod zwraca id_token, a nie token dostępu.

Nowi klienci korzystający z platformy tożsamości firmy Microsoft nie powinni używać tej konfiguracji. Upewnij się, że przeprowadzasz migrację do biblioteki Microsoft Authentication Library (MSAL) z biblioteki Azure AD Authentication Library (ADAL).

Przepływ uzyskiwania akredytacji klienta i .default

Innym zastosowaniem .default jest żądanie ról aplikacji (nazywanych również uprawnieniami aplikacji) w aplikacji nieinterakcyjnej, takiej jak aplikacja demona, która używa przepływu udzielania poświadczeń klienta w celu wywołania interfejsu API.

Aby zdefiniować role aplikacji (uprawnienia aplikacji) dla internetowego interfejsu API, zobacz Dodawanie ról aplikacji w aplikacji.

Żądania poświadczeń klienta w usłudze klienta muszą zawierać wartość scope={resource}/.default. Interfejs API {resource} to internetowy interfejs, który Twoja aplikacja chce wywołać i uzyskać dla niego token dostępu. Wystawianie żądania poświadczeń klienta przy użyciu indywidualnych uprawnień aplikacyjnych (ról) nie jest obsługiwane. Wszystkie role aplikacji (uprawnienia aplikacji), które zostały przyznane dla tego internetowego interfejsu API, są uwzględnione w zwróconym tokenie dostępu.

Aby udzielić dostępu do zdefiniowanych ról aplikacji, w tym udzielenia zgody administratora dla aplikacji, zobacz Konfigurowanie aplikacji klienckiej w celu uzyskania dostępu do internetowego interfejsu API.

Końcowy ukośnik i .default

Niektóre identyfikatory URI zasobów mają ukośnik na końcu, na przykład https://contoso.com/ w odróżnieniu od https://contoso.com. Końcowy ukośnik może powodować problemy z weryfikacją tokenu. Problemy występują głównie w przypadku żądania tokenu dla usługi Azure Resource Manager (https://management.azure.com/).

W takim przypadku końcowy ukośnik identyfikatora URI zasobu oznacza, że ukośnik musi być obecny podczas żądania tokenu. Dlatego, kiedy żądasz tokenu dla https://management.azure.com/ i używasz .default, musisz zażądać https://management.azure.com//.default (zwróć uwagę na podwójny ukośnik!).

Ogólnie rzecz biorąc, jeśli zweryfikujesz, że token jest wystawiany, a następnie zauważysz, że token jest odrzucany przez interfejs API, który powinien go zaakceptować, rozważ dodanie drugiego ukośnika w prawo i spróbuj ponownie.

Zobacz też