Udostępnij za pośrednictwem

Zakresy i uprawnienia w Platforma 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 integrujący się z Platforma tożsamości Microsoft ma identyfikator zasobu lub identyfikator URI identyfikatora aplikacji.

W tym artykule znajdziesz informacje 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 zostały zintegrowane z Platforma tożsamości Microsoft. Każdy z tych zasobów może również zdefiniować zestaw uprawnień, które mogą służyć do dzielenia funkcji tego zasobu na mniejsze fragmenty. Na przykład program Microsoft Graph ma zdefiniowane 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 skompilować, aby zażądać tylko uprawnień potrzebnych do wykonania funkcji. 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. W Platforma 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 Platforma tożsamości Microsoft, jeśli identyfikator zasobu zostanie pominięty w parametrze zakresu, zasób przyjmuje się program 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 w Platforma tożsamości Microsoft można ustawić na uprawnienia administratora z ograniczeniami. 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: Odczytywanie wszystkich grup w katalogu organizacji

Uwaga

W żądaniach autoryzacji, tokenu lub punktu końcowego zgody dla Platforma tożsamości Microsoft, jeśli identyfikator zasobu zostanie pominięty w parametrze zakresu, zakłada się, że zasób jest programem 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 Platforma tożsamości Microsoft openID Connect ma kilka dobrze zdefiniowanych zakresów, które są również hostowane w programie Microsoft Graph: openid, , emailprofilei offline_access. address Zakresy OpenID phone Connect nie są obsługiwane.

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

Zakres openid

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

Korzystając z tego uprawnienia, aplikacja może otrzymać unikatowy identyfikator użytkownika w postaci sub oświadczenia. Uprawnienie daje również aplikacji dostęp do punktu końcowego UserInfo. Zakres openid może być używany w punkcie końcowym tokenu Platforma tożsamości Microsoft do uzyskiwania tokenów identyfikatorów. 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 jest przypadkiem. Jeśli aplikacja używa email zakresu, aplikacja musi być w stanie obsłużyć przypadek, w którym nie email ma oświadczenia w tokenie.

Zakres profile

Zakres profile może być używany z zakresem i dowolnym innym zakresem openid . 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 dokumentacjęid_tokens.

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.

Gdy użytkownik zatwierdzi offline_access zakres, aplikacja może odbierać tokeny odświeżania z punktu końcowego tokenu Platforma tożsamości Microsoft. Tokeny odświeżania są długotrwałe. Twoja aplikacja może uzyskać nowe tokeny dostępu w miarę wygasania starszych.

Uwaga

To uprawnienie jest obecnie wyświetlane na wszystkich stronach zgody, nawet w przypadku przepływów, które nie udostępniają tokenu odświeżania (na przykład niejawnego przepływu). 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.

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

Token dostępu jest zwykle 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 dzień. Aby uzyskać więcej informacji na temat uzyskiwania i używania tokenów odświeżania, zobacz dokumentację protokołu Platforma 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, że token odświeżania w odpowiedzi nie powiedzie się, rozważ następujące czynniki:

  • Wymagania dotyczące zakresu: upewnij się, że żądasz offline_access zakresów wraz z innymi wymaganymi zakresami.
  • Typ udzielania autoryzacji: token odświeżania jest zwykle 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 zasobów (INTERFEJS API) w żądaniu bez identyfikowania określonych uprawnień. W razie potrzeby należy użyć .default sygnałów, że zgoda powinna być monitowana o wszystkie wymagane uprawnienia wymienione w rejestracji aplikacji (dla wszystkich interfejsów API na liście).

Wartość parametru zakresu jest konstruowana przy użyciu identyfikatora URI zasobu i .default, oddzielonego ukośnikiem (/). Jeśli na przykład identyfikator URI identyfikatora zasobu to https://contoso.com, zakres żądania to https://contoso.com/.default. W przypadku, gdy musisz dołączyć 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 poświadczeń klienta.

Klienci nie mogą łączyć statycznej zgody (.default) i dynamicznej zgody w jednym żądaniu. Powoduje to scope=https://graph.microsoft.com/.default Mail.Read błąd, ponieważ łączy typy zakresów.

.default Parametr zakresu wyzwala tylko monit o wyrażenie zgody, jeśli zgoda nie została udzielona dla żadnego delegowanego uprawnienia 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 prompt=consent parametr został podany), 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 i wszystkie delegowane uprawnienia programu Microsoft Graph, które zostały przyznane dla tego użytkownika, zostaną uwzględnione w tokenie dostępu. Jeśli nie udzielono żadnych uprawnień dla żądanego zasobu (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ł Mail.Read klientowi uprawnień i User.Read programu 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ę pod kątem uprawnień User.Read i Contacts.Read. Zarejestrowano go również w zakresie https://vault.azure.net/user_impersonationusługi Azure Key Vault.

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

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

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

Klient najpierw wykonuje logowanie przy użyciu scope=https://graph.microsoft.com/.defaultpolecenia . scopes Na podstawie parametru odpowiedzi kod aplikacji wykrywa, że udzielono tylko Mail.Read tej odpowiedzi. 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, będą one wyświetlane komunikat o błędzie lub formularz żądania zgody administratora). Zarówno, Contacts.Read jak i Mail.Read będzie wyświetlany w wierszu zgody. Jeśli udzielono zgody, a logowanie będzie kontynuowane, zwrócony token dotyczy programu Microsoft Graph i zawiera Mail.Read Contacts.Readi .

.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_tokenwartość , a nie token dostępu.

Ta konfiguracja nie powinna być używana przez nowych klientów przeznaczonych dla Platforma tożsamości Microsoft. Pamiętaj, aby przeprowadzić migrację do biblioteki Microsoft Authentication Library (MSAL) z biblioteki uwierzytelniania usługi Azure AD (ADAL).

Przepływ udzielania poświadczeń klienta i .default

Innym sposobem jest .default żą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 internetowego 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. Oto internetowy interfejs API, {resource} który aplikacja zamierza wywołać, i chce uzyskać token dostępu. Wystawianie żądania poświadczeń klienta przy użyciu poszczególnych uprawnień aplikacji (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 końcowy, na przykład w https://contoso.com/ przeciwieństwie do https://contoso.com. Końcowy ukośnik może powodować problemy z walidacją 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 po żądaniu tokenu. Dlatego w przypadku żądania tokenu i https://management.azure.com/ jego użycia .defaultnależy zażądać https://management.azure.com//.default (zwróć uwagę na podwójny ukośnik!).

Ogólnie rzecz biorąc, jeśli sprawdzisz, czy token jest wystawiany, a token jest odrzucany przez interfejs API, który powinien go zaakceptować, rozważ dodanie drugiego ukośnika i spróbuj ponownie.

Zobacz też