Udostępnij przez

Przewodnik dewelopera dotyczący żądania uprawnień i zgody na platformie microsoft Identity Platform

Aplikacje na platformie tożsamości firmy Microsoft korzystają ze zgody w celu uzyskania dostępu do niezbędnych zasobów lub interfejsów API. Różne typy zgody są lepsze w przypadku różnych scenariuszy aplikacji. Wybór najlepszego podejścia do wyrażania zgody dla aplikacji pozwala na bardziej skuteczne podejście do użytkowników i organizacji.

W tym artykule dowiesz się więcej o różnych typach zgody i sposobach żądania uprawnień dla aplikacji za pomocą zgody.

Uwaga / Notatka

W przypadku aplikacji w dzierżawach zewnętrznych klienci nie mogą wyrazić zgody na uprawnienia. Administrator musi udzielić zgody aplikacji na dostęp do zasobów w ich imieniu. Aby uzyskać więcej informacji, zobacz Udzielanie zgody administratora.

W scenariuszu ze statyczną zgodą użytkownika musisz określić wszystkie wymagane uprawnienia w konfiguracji aplikacji w centrum administracyjnym firmy Microsoft Entra. Jeśli użytkownik (lub administrator, zgodnie z potrzebami) nie udziela zgody dla tej aplikacji, platforma tożsamości firmy Microsoft monituje użytkownika o wyrażenie zgody w tej chwili.

Uprawnienia statyczne umożliwiają również administratorom wyrażanie zgody w imieniu wszystkich użytkowników w organizacji.

Podczas korzystania ze zgody statycznej i pojedynczej listy uprawnień kod jest przejrzysty i prosty, oznacza również, że aplikacja żąda od razu wszystkich uprawnień, jakie mogłyby być kiedykolwiek potrzebne. To ustawienie może zniechęcać użytkowników i administratorów do zatwierdzania żądania dostępu aplikacji.

Za pomocą punktu końcowego platformy tożsamości firmy Microsoft można zignorować uprawnienia statyczne zdefiniowane w informacjach dotyczących rejestracji aplikacji w centrum administracyjnym firmy Microsoft Entra. Zamiast tego możesz dynamicznie żądać uprawnień z poziomu kodu aplikacji. Możesz zacząć od poproszenia o minimalny zestaw uprawnień z góry i z czasem prosić o kolejne w miarę jak klient korzysta z większej liczby funkcji aplikacji. W tym celu można w dowolnym momencie określić zakresy wymagane przez aplikację, dołączając zakresy w parametrze scope podczas żądania tokenu dostępu — bez konieczności wstępnie zdefiniowanych w informacjach dotyczących rejestracji aplikacji.

Jeśli użytkownik nie wyraził zgody na żadne z zakresów w żądaniu, zostanie wyświetlony monit o zgodę na wszystkie uprawnienia w tym żądaniu. Zostaną one przyznane oprócz wszelkich innych uprawnień, które zostały już przyznane dla tej aplikacji (tj. przyrostowe). Zgoda przyrostowa dotyczy tylko uprawnień delegowanych, a nie uprawnień aplikacji.

Umożliwienie aplikacji dynamicznego żądania uprawnień za pomocą parametru scope zapewnia deweloperom pełną kontrolę nad środowiskiem użytkownika. Na początku przedstawiasz swoje podejście do uzyskiwania zgody i prosisz o wszystkie uprawnienia w jednym początkowym żądaniu autoryzacji. Jeśli Twoja aplikacja wymaga dużej liczby uprawnień, możesz stopniowo uzyskiwać te uprawnienia od użytkownika, gdy z czasem będą próbowali korzystać z określonych funkcji aplikacji.

Ważne

Zgoda dynamiczna może być wygodna, ale stanowi istotne wyzwanie dla uprawnień wymagających zgody administratora. Środowisko zgody administratora w sekcjach Rejestracje aplikacji i Aplikacje dla przedsiębiorstw w portalu nie jest świadome tych uprawnień dynamicznych w momencie udzielania zgody. Zalecamy, aby deweloper wyświetlił listę wszystkich uprawnień uprzywilejowanych administratora wymaganych przez aplikację w portalu.

Dzięki temu administratorzy dzierżawy mogą jednorazowo wyrazić zgodę w imieniu wszystkich swoich użytkowników w portalu. Użytkownicy nie muszą przechodzić przez proces wyrażania zgody dla tych uprawnień przy logowaniu. Alternatywą jest użycie dynamicznej zgody dla tych uprawnień. Aby udzielić zgody administratora, indywidualny administrator loguje się do aplikacji, wyzwala monit o zgodę dla odpowiednich uprawnień i wybiera zgodę dla całej organizacji w oknie dialogowym zgody.

W żądaniu autoryzacji openID Connect lub OAuth 2.0 aplikacja może zażądać wymaganych uprawnień przy użyciu parametru scope zapytania. Na przykład gdy użytkownik loguje się do aplikacji, aplikacja wysyła żądanie podobne do poniższego przykładu. (Podziały wierszy są dodawane do czytelności).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

Parametr scope to rozdzielona spacjami lista delegowanych uprawnień, których żąda aplikacja. Każde uprawnienie jest wskazywane przez dołączenie wartości uprawnień do identyfikatora zasobu (identyfikatora URI identyfikatora aplikacji). W przykładzie żądania aplikacja musi mieć uprawnienia do odczytywania kalendarza użytkownika i wysyłania wiadomości e-mail jako użytkownika.

Po zalogowaniu platforma tożsamości firmy Microsoft sprawdza, czy istnieje zgoda istniejącego użytkownika. Jeśli użytkownik nie zatwierdzi żądanych uprawnień, a administrator ich nie zatwierdzi, platforma monituje użytkownika o udzielenie zgody.

W poniższym przykładzie uprawnienia offline_access ("Zachowaj dostęp do danych, do których udzielasz dostępu") oraz User.Read ("Zaloguj się i odczytaj swój profil") są automatycznie uwzględniane w początkowej zgodzie na aplikację. Te uprawnienia są wymagane do prawidłowej funkcjonalności aplikacji.

Uprawnienie offline_access zapewnia aplikacji dostęp do tokenów odświeżania, które mają krytyczne znaczenie dla aplikacji natywnych i aplikacji internetowych. Uprawnienie User.Read daje dostęp do roszczenia sub. Umożliwia to klientowi lub aplikacji poprawne identyfikowanie użytkownika w czasie i uzyskiwanie dostępu do nieugiętych informacji o użytkowniku.

Przykładowy zrzut ekranu przedstawiający zgodę konta służbowego.

Gdy użytkownik zatwierdzi żądanie uprawnień, zostanie zarejestrowana zgoda. Użytkownik nie musi ponownie wyrazić zgody po późniejszym zalogowaniu się do aplikacji.

Żądanie zgody dla całej dzierżawy wymaga zgody administratora. Zgoda administratora wykonywana w imieniu organizacji wymaga uprawnień statycznych zarejestrowanych dla aplikacji. Ustaw te uprawnienia w portalu rejestracji aplikacji, jeśli potrzebujesz administratora, aby wyrazić zgodę w imieniu całej organizacji.

Gdy aplikacja żąda uprawnień delegowanych, które wymagają zgody administratora, użytkownicy zobaczą błąd "nieautoryzowanej zgody" i muszą poprosić administratora o dostęp. Gdy administrator udzieli zgody dla całej dzierżawy, użytkownicy nie będą monitowani ponownie, chyba że zostanie odwołana zgoda lub zostaną dodane nowe uprawnienia.

Administratorzy korzystający z tej samej aplikacji widzą monit o zgodę administratora. Monit zgody administratora zawiera pole wyboru, które umożliwia im przyznanie aplikacji dostępu do żądanych danych w imieniu wszystkich użytkowników dla całego dzierżawcy. Aby uzyskać więcej informacji na temat środowiska zgody użytkownika i administratora, zobacz Środowisko zgody aplikacji.

Przykłady delegowanych uprawnień dla programu Microsoft Graph, które wymagają zgody administratora, to:

  • Odczytywanie wszystkich profilów użytkownika przy użyciu funkcji User.Read.All
  • Zapisywanie danych w katalogu organizacji przy użyciu polecenia Directory.ReadWrite.All
  • Odczytywanie wszystkich grup w katalogu organizacji przy użyciu polecenia Groups.Read.All

Aby wyświetlić pełną listę uprawnień programu Microsoft Graph, zobacz Dokumentacja uprawnień programu Microsoft Graph.

Możesz również skonfigurować uprawnienia do własnych zasobów, aby wymagać zgody administratora. Aby uzyskać więcej informacji na temat dodawania zakresów wymagających zgody administratora, zobacz Dodawanie zakresu wymagającego zgody administratora.

Niektóre organizacje mogą zmienić domyślne zasady zgody użytkownika dla dzierżawy. Gdy aplikacja żąda dostępu do uprawnień, są oceniane względem tych zasad. Użytkownik może wymagać zgody administratora, nawet jeśli nie jest to wymagane domyślnie. Aby dowiedzieć się, jak administratorzy zarządzają zasadami zgody dla aplikacji, zobacz Zarządzanie zasadami zgody aplikacji.

Uwaga / Notatka

W przypadku żądań autoryzacji, tokenu lub zgody w platformie tożsamości Microsoft, pominięcie identyfikatora zasobu w parametrze scope spowoduje domyślne odwołanie do programu Microsoft Graph. Na przykład scope=User.Read parametr jest traktowany jako https://graph.microsoft.com/User.Read.

Uprawnienia aplikacji zawsze wymagają zgody administratora. Uprawnienia aplikacji nie mają kontekstu użytkownika, a udzielenie zgody nie jest wykonywane w imieniu żadnego określonego użytkownika. Zamiast tego aplikacja kliencka ma bezpośrednio przyznane uprawnienia. Tego typu uprawnienia są używane tylko przez usługi demona i inne aplikacje nieinterakcyjne, które działają w tle. Administratorzy muszą skonfigurować uprawnienia z góry i udzielić zgody administratora za pośrednictwem centrum administracyjnego firmy Microsoft Entra.

Jeśli aplikacja żądająca uprawnienia jest aplikacją wielodostępną, jej rejestracja aplikacji istnieje tylko w dzierżawie, w której została utworzona, dlatego nie można skonfigurować uprawnień w dzierżawie lokalnej. Jeśli aplikacja żąda uprawnień, które wymagają zgody administratora, administrator musi wyrazić zgodę w imieniu użytkowników. Aby wyrazić zgodę na te uprawnienia, administratorzy muszą osobiście zalogować się do aplikacji, aby uruchomić proces logowania z akceptacją administratora. Aby dowiedzieć się, jak skonfigurować środowisko zgody administratora dla aplikacji wielodostępnych, zobacz Włącz wielodostępne logowanie

Administrator może udzielić zgody dla aplikacji przy użyciu następujących opcji.

Zazwyczaj podczas tworzenia aplikacji, która wymaga zgody administratora, aplikacja potrzebuje strony lub widoku, w którym administrator może zatwierdzić uprawnienia aplikacji. Ta strona może być następująca:

  • Część procesu rejestracji w aplikacji.
  • Część ustawień aplikacji.
  • Dedykowany proces "łączenia".

W wielu przypadkach warto, aby aplikacja wyświetlała widok "połącz" dopiero po zalogowaniu się użytkownika przy użyciu konta Służbowego Microsoft lub szkolnego konta Microsoft.

Po zalogowaniu użytkownika do aplikacji możesz zidentyfikować organizację, do której należy administrator, zanim poprosisz go o zatwierdzenie niezbędnych uprawnień. Mimo że ten krok nie jest ściśle konieczny, może to pomóc w utworzeniu bardziej intuicyjnego środowiska dla użytkowników organizacji.

Aby zalogować się do użytkownika, postępuj zgodnie z samouczkami dotyczącymi protokołu platformy tożsamości firmy Microsoft.

Żądanie uprawnień w portalu rejestracji aplikacji

W portalu rejestracji aplikacji aplikacje mogą wyświetlać wymagane uprawnienia, w tym uprawnienia delegowane i uprawnienia aplikacji. Ta konfiguracja umożliwia korzystanie z .default zakresu i opcji Udziel zgody administratora w centrum administracyjnym Microsoft Entra.

Ogólnie rzecz biorąc, uprawnienia powinny być definiowane statycznie dla danej aplikacji. Powinny one być nadzbiorem uprawnień, o które aplikacja się ubiega dynamicznie lub w miarę potrzeb.

Uwaga / Notatka

Uprawnienia aplikacji można żądać tylko za pomocą polecenia .default. Jeśli więc aplikacja potrzebuje uprawnień aplikacji, upewnij się, że są one wymienione w portalu rejestracji aplikacji.

Aby skonfigurować listę statycznie żądanych uprawnień dla aplikacji:

  1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator aplikacji w chmurze.
  2. Przejdź do Entra ID>Rejestracje aplikacji>Wszystkie aplikacje.
  3. Wybierz aplikację lub utwórz aplikację , jeśli jeszcze tego nie zrobiono.
  4. Na stronie Przegląd aplikacji w obszarze Zarządzanie wybierz pozycję Uprawnienia API>Dodaj uprawnienie.
  5. Wybierz pozycję Microsoft Graph z listy dostępnych interfejsów API. Następnie dodaj uprawnienia wymagane przez aplikację.
  6. Wybierz pozycję Dodaj uprawnienia.

Odpowiedź pomyślna

Jeśli administrator zatwierdzi uprawnienia aplikacji, pomyślna odpowiedź wygląda następująco:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parametr Opis
tenant Dzierżawca katalogu, który udzielił aplikacji żądanych uprawnień, w formacie GUID.
state Wartość uwzględniona w żądaniu, zwrócona w odpowiedzi tokenu. Może to być ciąg dowolnej zawartości. Stan jest 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.
admin_consent Jest ustawiona na wartość True.

Po otrzymaniu pomyślnej odpowiedzi z punktu końcowego zgody administratora aplikacja otrzymuje żądane uprawnienia. Następnie możesz zażądać tokenu dla żądanego zasobu.

Odpowiedź na błąd

Jeśli administrator nie zatwierdzi uprawnień dla Twojej aplikacji, odpowiedź o niepowodzeniu wygląda następująco:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parametr Opis
error Ciąg kodu błędu, który może służyć do klasyfikowania typów błędów, które występują. Może również służyć do reagowania na błędy.
error_description Określony komunikat o błędzie, który może pomóc deweloperowi zidentyfikować główną przyczynę błędu.

Gdy użytkownik wyrazi zgodę na uprawnienia aplikacji, aplikacja może uzyskać tokeny dostępu reprezentujące uprawnienie aplikacji do uzyskiwania dostępu do zasobu w określonej pojemności. Token dostępu może być używany tylko dla jednego zasobu. Jednak zakodowane wewnątrz tokenu dostępu to każde uprawnienie przyznane przez aplikację dla tego zasobu. Aby uzyskać token dostępu, aplikacja może wysłać żądanie do punktu końcowego tokenu platformy tożsamości firmy Microsoft, w następujący sposób:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Możesz użyć wynikowego tokenu dostępu w żądaniach HTTP do zasobu. Niezawodnie informuje zasób, że Twoja aplikacja ma odpowiednie uprawnienia do wykonania określonego zadania.

Aby uzyskać więcej informacji na temat protokołu OAuth 2.0 i sposobu uzyskiwania tokenów dostępu, zobacz dokumentację protokołu punktu końcowego platformy tożsamości firmy Microsoft.

Treści powiązane

  • Last updated on