Share via

Żądanie uprawnień za pośrednictwem zgody

  • Artykuł

Aplikacje w Platforma tożsamości Microsoft polegają na wyrażaniu 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. Wybranie najlepszego podejścia do wyrażania zgody na aplikację pomoże jej bardziej odnieść sukces użytkownikom i organizacjom.

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

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 udzielił zgody dla tej aplikacji, Platforma tożsamości Microsoft wyświetli monit 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 statycznej zgody i jednej listy uprawnień kod jest miły i prosty, oznacza to również, że aplikacja będzie żądać wszystkich uprawnień, których kiedykolwiek potrzebuje z góry. Może to zniechęcić użytkowników i administratorów do zatwierdzania żądania dostępu aplikacji.

Za pomocą punktu końcowego Platforma tożsamości Microsoft można zignorować uprawnienia statyczne zdefiniowane w informacjach dotyczących rejestracji aplikacji w centrum administracyjnym firmy Microsoft Entra. Zamiast tego możesz żądać uprawnień przyrostowo. Możesz poprosić o minimalny zestaw uprawnień z góry i zażądać więcej w miarę upływu czasu, ponieważ klient korzysta z dodatkowych funkcji aplikacji. W tym celu można w dowolnym momencie określić zakresy wymagane przez aplikację, dołączając nowe zakresy w parametrze scope podczas żądania tokenu dostępu — bez konieczności wstępnego definiowania ich w informacjach dotyczących rejestracji aplikacji. Jeśli użytkownik nie wyraził jeszcze zgody na nowe zakresy dodane do żądania, zostanie wyświetlony monit o wyrażenie zgody tylko na nowe uprawnienia. Przyrostowa lub dynamiczna zgoda dotyczy tylko delegowanych uprawnień, a nie uprawnień aplikacji.

Umożliwienie aplikacji dynamicznego żądania uprawnień za pomocą parametru scope zapewnia deweloperom pełną kontrolę nad środowiskiem użytkownika. Możesz również załadować środowisko wyrażania zgody i poprosić o wszystkie uprawnienia w jednym początkowym żądaniu autoryzacji. Jeśli aplikacja wymaga dużej liczby uprawnień, możesz zebrać te uprawnienia od użytkownika przyrostowo, próbując używać niektórych funkcji aplikacji w czasie.

Ważne

Zgoda dynamiczna może być wygodna, ale stanowi duże wyzwanie dla uprawnień wymagających zgody administratora. Środowisko zgody administratora w blokach Rejestracje aplikacji i aplikacji dla przedsiębiorstw w portalu nie wie o tych uprawnieniach dynamicznych w czasie zgody. Zalecamy, aby deweloper wyświetlił listę wszystkich uprawnień uprzywilejowanych administratora, które są wymagane przez aplikację w portalu. Dzięki temu administratorzy dzierżawy mogą wyrazić zgodę w imieniu wszystkich swoich użytkowników w portalu, raz. Użytkownicy nie będą musieli przechodzić przez środowisko wyrażania zgody dla tych uprawnień podczas logowania. 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 Połączenie 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 wprowadzeniu poświadczeń użytkownika Platforma tożsamości Microsoft sprawdza pasujący rekord zgody użytkownika. Jeśli użytkownik nie wyraził zgody na jakiekolwiek żądane uprawnienia w przeszłości, a administrator nie wyraził zgody na te uprawnienia w imieniu całej organizacji, Platforma tożsamości Microsoft prosi użytkownika o udzielenie żądanych uprawnień.

W poniższym przykładzie offline_access uprawnienie ("Zachowaj dostęp do danych, do których udzielono mu dostępu") i User.Read uprawnienie "Zaloguj się i odczytaj swój profil") jest automatycznie uwzględniane w początkowej zgody 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 sub oświadczenia. 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. Administracja zgoda wykonywana w imieniu organizacji wymaga uprawnień statycznych zarejestrowanych w 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żytkownik otrzymuje komunikat o błędzie informujący, że nie ma autoryzacji do wyrażania zgody na uprawnienia aplikacji. Użytkownik musi poprosić administratora o dostęp do aplikacji. Jeśli administrator udziela zgody dla całej dzierżawy, użytkownicy organizacji nie widzą strony zgody dla aplikacji, chyba że wcześniej przyznane uprawnienia zostaną odwołane lub aplikacja żąda nowego uprawnienia przyrostowo.

Administracja istratory korzystające z tej samej aplikacji będą widzieć monit o zgodę administratora. Monit zgody administratora zawiera pole wyboru, które umożliwia im przyznanie aplikacji dostępu do żądanych danych w imieniu użytkowników dla całej dzierżawy. 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

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 scope=User.Read jest odpowiednikiem https://graph.microsoft.com/User.Readelementu .

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 otrzymuje uprawnienia bezpośrednio, te typy uprawnień są używane tylko przez usługi demona i inne aplikacje nieinterakcyjne, które działają w tle. Administracja istratory muszą skonfigurować uprawnienia z góry i udzielić zgody administratora za pośrednictwem centrum administracyjnego firmy Microsoft Entra.

W przypadku, gdy aplikacja żądającą 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ą zalogować się do aplikacji samodzielnie, aby środowisko logowania zgody administratora zostało wyzwolone. Aby dowiedzieć się, jak skonfigurować środowisko zgody administratora dla aplikacji wielodostępnych, zobacz Włączanie logów wielodostępnych

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ęść przepływu rejestracji aplikacji.
  • Część ustawień aplikacji.
  • Dedykowany przepływ "połącz".

W wielu przypadkach warto, aby aplikacja wyświetlała widok "połącz" dopiero po zalogowaniu się użytkownika przy użyciu służbowego konta 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ć użytkownika, postępuj zgodnie z samouczkami dotyczącymi protokołu Platforma tożsamości 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 Udzielania zgody administratora w centrum administracyjnym firmy Microsoft w usłudze Entra.

Ogólnie rzecz biorąc, uprawnienia powinny być definiowane statycznie dla danej aplikacji. Powinny one być nadzbiorem uprawnień, które aplikacja będzie żądać dynamicznie lub przyrostowo.

Uwaga

Uprawnienia aplikacji można żądać tylko za pomocą funkcji .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 jako co najmniej Administracja istrator aplikacji w chmurze.
  2. Przejdź do sekcji Identity>Applications> 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>interfejsu 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żawa katalogu, która przyznała aplikacji żądane uprawnienia, w formacie GUID.
state Wartość uwzględniona w żądaniu, która również zostanie 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 Zostanie ustawiona wartość True.

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

Odpowiedź błędna

Jeśli administrator nie zatwierdzi uprawnień aplikacji, odpowiedź niepomyślnie 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 aplikacji dla tego zasobu. Aby uzyskać token dostępu, aplikacja może wysłać żądanie do punktu końcowego tokenu Platforma tożsamości 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 wskazuje zasób, do którego 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 Platforma tożsamości Microsoft.

Zobacz też