Udostępnij za pośrednictwem

Przekształcanie aplikacji jednodzierżawowej na wielodziedziczeniową w Microsoft Entra ID

  • Artykuł

Jeśli oferujesz aplikację oprogramowania jako usługę (SaaS) dla wielu organizacji, możesz skonfigurować aplikację tak, aby akceptowała logowania z dowolnej dzierżawy firmy Microsoft Entra, przekształcając ją na wielodzierżawową. Użytkownicy w dowolnej dzierżawie Microsoft Entra będą mogli logować się do Twojej aplikacji po wyrażeniu zgody na użycie swojego konta w tej aplikacji.

W przypadku istniejących aplikacji z własnym systemem kont (lub innymi logowaniami od innych dostawców chmury) należy dodać kod logowania za pomocą protokołu OAuth2, OpenID Connect lub języka SAML (Security Assertion Markup Language) i umieścić przycisk "Zaloguj się za pomocą firmy Microsoft" w aplikacji.

W tym przewodniku dowiesz się, jak wykonać cztery kroki potrzebne do przekształcenia aplikacji z jednym dzierżawcą w wielodostępną aplikację Microsoft Entra.

  1. Zaktualizuj rejestrację aplikacji, aby była wielodostępna
  2. Aktualizowanie kodu w celu wysyłania żądań do punktu końcowego /common
  3. Zaktualizuj swój kod, aby obsługiwał wiele wartości wystawcy
  4. Omówienie zgody użytkownika i administratora oraz wprowadzanie odpowiednich zmian w kodzie

Jeśli chcesz spróbować użyć jednego z naszych przykładów, zapoznaj się z tematem Tworzenie wielodostępnej aplikacji internetowej SaaS, która wywołuje program Microsoft Graph przy użyciu Microsoft Entra ID i OpenID Connect

Wymagania wstępne

Aktualizowanie rejestracji do obsługi wielu najemców

Rejestracje aplikacji internetowych/interfejsów API w usłudze Microsoft Entra ID są domyślnie jednodzierżawowe od momentu tworzenia. Aby utworzyć wielodostępową rejestrację, zaloguj się do centrum administracyjnego Microsoft Entra i wybierz rejestrację aplikacji, którą chcesz zaktualizować. Po otwarciu rejestracji aplikacji wybierz okienko Uwierzytelnianie i przejdź do sekcji Obsługiwane typy kont. Zmień ustawienie na Konta w dowolnym katalogu organizacyjnym.

Po utworzeniu aplikacji z jedną dzierżawą w centrum administracyjnym firmy Microsoft Entra jeden z elementów wymienionych na stronie Przegląd to identyfikator URI identyfikatora aplikacji. Jest to jeden ze sposobów, w jaki aplikacja jest identyfikowana w komunikatach protokołu i można ją dodawać w dowolnym momencie. Identyfikator URI aplikacji dla aplikacji z jedną dzierżawą może być unikalny w skali globalnej w ramach tej dzierżawy. Z kolei w przypadku aplikacji wielodostępnych musi być globalnie unikatowa we wszystkich dzierżawach, zapewniając, że identyfikator Entra firmy Microsoft może znaleźć aplikację we wszystkich dzierżawach.

Jeśli na przykład nazwa dzierżawy to contoso.onmicrosoft.com prawidłowy identyfikator URI identyfikatora aplikacji to https://contoso.onmicrosoft.com/myapp. Jeśli identyfikator URI identyfikatora aplikacji nie jest zgodna z tym wzorcem, ustawienie aplikacji jako wielodostępnego zakończy się niepowodzeniem.

Aktualizowanie kodu w celu wysyłania żądań do /common

W przypadku aplikacji wielodostępnej aplikacja nie może natychmiast określić, z którego dzierżawcy pochodzi użytkownik, więc niemożliwe jest wysłanie żądań do odpowiedniego punktu końcowego. Zamiast tego żądania są wysyłane do wspólnego punktu końcowego (https://login.microsoftonline.com/common), który obsługuje wszystkie dzierżawy firmy Microsoft Entra, działając jako centralne centrum obsługujące żądania.

Otwórz aplikację w środowisku IDE i edytuj kod, a następnie zmień wartość identyfikatora dzierżawy na /common. W przypadku aplikacji SAML można to skonfigurować w pliku XML dostawcy tożsamości. Ten punkt końcowy nie jest dzierżawą ani wystawcą. Gdy Platforma tożsamości Microsoft odbiera żądanie w /common punkcie końcowym, loguje użytkownika, odnajdując dzierżawcę, z którego pochodzi użytkownik. Ten punkt końcowy współpracuje ze wszystkimi protokołami uwierzytelniania obsługiwanymi przez identyfikator Firmy Microsoft (OpenID Connect, OAuth 2.0, SAML 2.0, WS-Federation).

Odpowiedź logowania do aplikacji zawiera następnie token reprezentujący użytkownika. Wartość wystawcy w tokenie informuje aplikację, z której dzierżawy pochodzi użytkownik. Gdy odpowiedź zostanie zwrócona z punktu końcowego /common , wartość wystawcy w tokenie odpowiada dzierżawie użytkownika.

Uwaga

Istnieją w rzeczywistości 2 urzędy dla aplikacji wielodostępnych:

  • https://login.microsoftonline.com/common w przypadku aplikacji przetwarzających konta w dowolnym katalogu organizacyjnym (dowolnym katalogu Microsoft Entra) i osobistych kontach Microsoft (takich jak Skype, XBox).
  • https://login.microsoftonline.com/organizations w przypadku aplikacji przetwarzających konta w dowolnym katalogu organizacyjnym (dowolny katalog firmy Microsoft Entra):

Wyjaśnienia w tym dokumencie używają common. Możesz jednak zastąpić ją, organizations jeśli aplikacja nie obsługuje kont osobistych Microsoft.

Zaktualizuj swój kod, aby obsługiwać wiele wartości wystawców

Aplikacje internetowe i internetowe interfejsy API odbierają i weryfikują tokeny z Platforma tożsamości Microsoft. Natywne aplikacje klienckie nie weryfikują tokenów dostępu i muszą traktować je jako nieprzezroczyste. Zamiast tego żądają i otrzymują tokeny z platformy tożsamości Microsoft, i robią to, aby wysłać je do interfejsów API, gdzie są następnie weryfikowane.

Aplikacje wielodostępne muszą wykonywać więcej kontroli podczas sprawdzania poprawności tokenu. Aplikacja wielodostępna jest skonfigurowana do korzystania z metadanych kluczy z /organizations URL kluczy lub /common URL kluczy. Aplikacja musi zweryfikować, czy właściwość issuer w opublikowanych metadanych jest zgodna z oświadczeniem iss w tokenie, oprócz zwykłego sprawdzenia, czy oświadczenie iss w tokenie zawiera oświadczenie identyfikatora dzierżawy (tid). Aby uzyskać więcej informacji, zobacz Weryfikowanie tokenów.

Aby użytkownik zalogował się do aplikacji w usłudze Microsoft Entra ID, aplikacja musi być zarejestrowana w dzierżawie użytkownika. Organizacja może następnie wykonywać takie czynności, jak stosowanie unikatowych zasad, gdy użytkownicy z dzierżawy logują się do aplikacji. W przypadku aplikacji z jedną dzierżawą można użyć rejestracji za pośrednictwem centrum administracyjnego firmy Microsoft Entra.

W przypadku aplikacji wielodostępnej początkowa rejestracja aplikacji znajduje się w dzierżawie Microsoft Entra wykorzystywanej przez dewelopera. Gdy użytkownik z innej dzierżawy loguje się do aplikacji po raz pierwszy, identyfikator Entra firmy Microsoft prosi o zgodę na uprawnienia żądane przez aplikację. Jeśli wyrażą zgodę, wówczas w dzierżawie użytkownika zostanie utworzona reprezentacja aplikacji o nazwie główny element usługi, a logowanie może być kontynuowane. Pełnomocnictwo jest również tworzone w katalogu, który zapisuje zgodę użytkownika na korzystanie z aplikacji. Aby uzyskać szczegółowe informacje na temat obiektów aplikacji (Application) i głównego elementu usługi (ServicePrincipal) oraz ich powiązań, zobacz Application objects and service principal objects (Obiekty aplikacji i obiekty głównego elementu usługi).

Diagram przedstawiający zgodę użytkownika na aplikację jednowarstwową.

Uprawnienia żądane przez aplikację mają wpływ na środowisko wyrażania zgody. Platforma tożsamości Microsoft obsługuje dwa rodzaje uprawnień;

  • Delegowane: to uprawnienie przyznaje aplikacji możliwość działania jako zalogowany użytkownik dla podzbioru rzeczy, które użytkownik może wykonać. Na przykład możesz przyznać aplikacji delegowane uprawnienie do odczytywania kalendarza zalogowanego użytkownika.
  • Tylko aplikacja: To uprawnienie jest przyznawane bezpośrednio tożsamości aplikacji. Na przykład możesz przyznać aplikacji uprawnienie tylko do odczytu listy użytkowników w dzierżawie, niezależnie od tego, kto jest zalogowany do aplikacji.

Regularni użytkownicy mogą wyrazić zgodę na niektóre uprawnienia, podczas gdy inni wymagają zgody administratora dzierżawy.

Aby dowiedzieć się więcej na temat zgody użytkownika i administratora, zobacz Konfigurowanie przepływu pracy zgody administratora.

Uprawnienia dotyczące tylko aplikacji zawsze wymagają zgody administratora dzierżawy. Jeśli aplikacja żąda uprawnień tylko do aplikacji, a użytkownik próbuje zalogować się do aplikacji, zostanie wyświetlony komunikat o błędzie informujący, że użytkownik nie może wyrazić zgody.

Niektóre delegowane uprawnienia wymagają również zgody administratora dzierżawy. Na przykład możliwość zapisywania zwrotnego do identyfikatora Entra firmy Microsoft jako zalogowanego użytkownika wymaga zgody administratora dzierżawy. Podobnie jak w przypadku uprawnień tylko do aplikacji, jeśli zwykły użytkownik próbuje zalogować się do aplikacji, która żąda delegowanego uprawnienia wymagającego zgody administratora, aplikacja otrzymuje błąd. Deweloper, który opublikował zasób, określa, czy uprawnienie wymaga zgody administratora, a te informacje można znaleźć w dokumentacji zasobu. Dokumentacja uprawnień interfejsu API programu Microsoft Graph wskazuje, które uprawnienia wymagają zgody administratora.

Jeśli aplikacja używa uprawnień, które wymagają zgody administratora, rozważ dodanie przycisku lub linku, w którym administrator może zainicjować akcję. Żądanie wysyłane przez aplikację dla tej akcji to zwykłe żądanie autoryzacji OAuth2/OpenID Connect, które zawiera prompt=consent również parametr ciągu zapytania. Po wyrażeniach zgody administratora i utworzeniu jednostki usługi w dzierżawie klienta kolejne żądania logowania nie wymagają parametru prompt=consent . Ponieważ administrator zatwierdził żądane uprawnienia, żaden inny użytkownicy w dzierżawie nie są monitowani o zgodę.

Administrator dzierżawy może wyłączyć możliwość wyrażania zgody na aplikacje przez zwykłych użytkowników. Jeśli ta funkcja jest wyłączona, zgoda administratora jest zawsze wymagana do używania aplikacji w dzierżawie. Aplikację można przetestować przy użyciu wyłączonej zgody użytkownika końcowego w centrum administracyjnym firmy Microsoft Entra. W obszarze Aplikacje>dla przedsiębiorstw Zgoda i uprawnienia zaznacz opcję Nie zezwalaj na zgodę użytkownika.

Parametr prompt=consent może być również używany przez aplikacje, które żądają uprawnień, które nie wymagają zgody administratora. Przykładowy przypadek użycia polega na tym, że aplikacja wymaga środowiska, w którym administrator dzierżawy "zarejestruje się" jednorazowo, a żaden inny użytkownik nie zostanie poproszony o zgodę od tego momentu.

Jeśli aplikacja wymaga zgody administratora, a administrator zaloguje się bez wysyłania parametru prompt=consent , gdy administrator pomyślnie wyrazi zgodę na aplikację, ma zastosowanie tylko dla konta użytkownika. Użytkownicy regularni nie będą mogli się zalogować ani wyrazić zgody na aplikację. Ta funkcja jest przydatna, jeśli chcesz przyznać administratorowi dzierżawy możliwość eksplorowania aplikacji przed zezwoleniem innym użytkownikom na dostęp.

Aplikacja może mieć wiele warstw, z których każda jest reprezentowana przez własną rejestrację w identyfikatorze Entra firmy Microsoft. Na przykład aplikacja natywna, która wywołuje internetowy interfejs API lub aplikację internetową, która wywołuje internetowy interfejs API. W obu tych przypadkach klient (aplikacja natywna lub aplikacja internetowa) żąda uprawnień do wywołania zasobu (internetowego interfejsu API). Aby klient mógł pomyślnie wyrazić zgodę na dzierżawę klienta, wszystkie zasoby, do których żąda uprawnień, muszą już istnieć w dzierżawie klienta. Jeśli ten warunek nie zostanie spełniony, Microsoft Entra ID zwraca błąd wskazujący, że zasób musi być najpierw dodany.

Wiele warstw w jednej dzierżawie

Jeśli aplikacja logiczna składa się z co najmniej dwóch rejestracji aplikacji, na przykład oddzielnego klienta i zasobu, możesz napotkać pewne problemy. Jak na przykład wprowadzić zasób do zewnętrznej dzierżawy jako pierwszy krok? Microsoft Entra ID obejmuje ten przypadek, umożliwiając wyrażenie zgody klienta i zasobu w jednym kroku. Użytkownik widzi całkowitą sumę uprawnień żądanych przez klienta i zasób na stronie zgody. Aby włączyć to zachowanie, rejestracja aplikacji zasobu musi zawierać identyfikator aplikacji klienta jako element knownClientApplications w manifeście aplikacji. Na przykład:

"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]

Możesz odnieść się do przykładu wielodostępnej aplikacji jako demonstracji. Poniższy diagram zawiera przegląd zgody dla aplikacji wielowarstwowej zarejestrowanej w jednym dzierżawcy.

Diagram przedstawiający zgodę na wielowarstwową znaną aplikację kliencką.

Wiele poziomów w wielu dzierżawach

Podobny przypadek występuje, jeśli różne warstwy aplikacji są zarejestrowane w różnych tenantach. Rozważmy na przykład przypadek utworzenia natywnej aplikacji klienckiej, która wywołuje interfejs API usługi Exchange Online. Aby opracować aplikację natywną, a następnie umożliwić jej działanie w dzierżawie klienta, element główny usługi Exchange Online musi być dostępny. W tym miejscu deweloper i klient muszą zakupić usługę Exchange Online, aby jednostka usługi została utworzona w swoich dzierżawach.

Jeśli jest to interfejs API utworzony przez organizację inną niż firma Microsoft, deweloper interfejsu API musi umożliwić klientom wyrażenie zgody na aplikację w dzierżawach klientów. Zalecany projekt to utworzenie przez dewelopera zewnętrznego interfejsu API, który może również działać jako klient sieciowy w celu zaimplementowania rejestracji. Można;

  1. Postępuj zgodnie z wcześniejszymi sekcjami, aby upewnić się, że interfejs API implementuje wielodostępne wymagania dotyczące rejestracji/kodu aplikacji.
  2. Oprócz ujawniania zakresów/ról interfejsu API upewnij się, że rejestracja zawiera uprawnienie "Zaloguj się i przeczytaj profil użytkownika" (domyślnie udostępniane).
  3. Zaimplementuj stronę logowania/rejestracji w kliencie internetowym i postępuj zgodnie ze wskazówkami dotyczącymi zgody administratora.
  4. Gdy użytkownik wyrazi zgodę na aplikację, w ich dzierżawie zostają utworzone główny usługowy i linki delegowania zgody, a aplikacja natywna może uzyskać tokeny dla interfejsu API.

Poniższy diagram zawiera przegląd zgody dotyczącej wielowarstwowej aplikacji zarejestrowanej w różnych dzierżawach.

Diagram przedstawiający zgodę na wielowarstwową aplikację wielopartyjną.

Użytkownicy i administratorzy mogą w dowolnym momencie odwołać zgodę na twoją aplikację:

  • Użytkownicy odwołują dostęp do poszczególnych aplikacji, usuwając je z listy aplikacji Panel dostępu.
  • Administratorzy odwołują dostęp do aplikacji, usuwając je przy użyciu sekcji Aplikacje dla przedsiębiorstw w centrum administracyjnym firmy Microsoft Entra. Wybierz aplikację i przejdź do karty Uprawnienia , aby odwołać dostęp.

Jeśli administrator wyrazi zgodę na aplikację dla wszystkich użytkowników w dzierżawie, użytkownicy nie będą mogli odwołać dostępu indywidualnie. Tylko administrator może odwołać dostęp i tylko dla całej aplikacji.

Aplikacje wielodostępne i buforowanie tokenów dostępu

Aplikacje wielodostępne mogą również uzyskiwać tokeny dostępu w celu wywoływania interfejsów API chronionych przez identyfikator Entra firmy Microsoft. Typowy błąd podczas korzystania z biblioteki Microsoft Authentication Library (MSAL) z aplikacją wielodostępną polega na początkowym żądaniu tokenu dla użytkownika przy użyciu metody /common, odebraniu odpowiedzi, a następnie zażądaniu kolejnego tokenu dla tego samego użytkownika również przy użyciu polecenia /common. Ponieważ odpowiedź z identyfikatora Entra firmy Microsoft pochodzi z dzierżawy, a nie /common, biblioteka MSAL buforuje token jako będący z dzierżawy. Kolejne wywołanie /common w celu uzyskania tokenu dostępu dla użytkownika pomija wpis pamięci podręcznej, a użytkownik jest proszony o ponowne zalogowanie. Aby uniknąć pominięcia pamięci podręcznej, upewnij się, że kolejne wywołania zalogowanego użytkownika są wykonywane do punktu końcowego najemcy.

Zobacz też