Konwertowanie aplikacji z jedną dzierżawą na wielodostępny w identyfikatorze Entra firmy Microsoft

  • Artykuł

Jeśli oferujesz aplikację oprogramowania jako usługi (SaaS) dla wielu organizacji, możesz skonfigurować aplikację tak, aby akceptowała logowania z dowolnej dzierżawy firmy Microsoft Entra, konwertując ją na wielodostępną. Użytkownicy w dowolnej dzierżawie firmy Microsoft Entra będą mogli logować się do aplikacji po wyrażeniu zgody na korzystanie z konta w aplikacji.

W przypadku istniejących aplikacji z własnym systemem kont (lub innymi logowaniami od innych dostawców usług w chmurze) należy dodać kod logowania za pomocą protokołu OAuth2, Połączenie OpenID lub SAML i umieścić przycisk "Zaloguj się przy użyciu firmy Microsoft" w aplikacji.

W tym przewodniku z instrukcjami wykonasz cztery kroki potrzebne do przekonwertowania pojedynczej aplikacji dzierżawy na wielodostępną aplikację firmy Microsoft:

  1. Aktualizowanie rejestracji aplikacji w celu wielodostępu
  2. Aktualizowanie kodu w celu wysyłania żądań do punktu końcowego /common
  3. Aktualizowanie kodu w celu obsługi wielu 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 artykułem Tworzenie wielodostępnej aplikacji internetowej SaaS, która wywołuje program Microsoft Graph przy użyciu identyfikatora Entra firmy Microsoft i identyfikatora OpenID Połączenie

Wymagania wstępne

Aktualizowanie rejestracji w celu wielodostępu

Domyślnie rejestracje aplikacji internetowej/interfejsu API w usłudze Microsoft Entra ID są jedną dzierżawą podczas tworzenia. Aby utworzyć wielodostępną rejestrację, zaloguj się do centrum administracyjnego firmy 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 identyfikatora aplikacji dla aplikacji z jedną dzierżawą może być globalnie unikatowy w ramach tej dzierżawy. Z kolei w przypadku aplikacji wielodostępnych musi być globalnie unikatowa we wszystkich dzierżawach, co gwarantuje, ż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ć dzierżawy, z której dzierżawy pochodzi użytkownik, więc nie można wysyłać żądań do punktu końcowego dzierżawy. 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. 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, odkrywając, z której dzierżawy pochodzi użytkownik. Ten punkt końcowy współpracuje ze wszystkimi protokołami uwierzytelniania obsługiwanymi przez identyfikator Firmy Microsoft (OpenID Połączenie, 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 (np. 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ą polecenia common. Możesz jednak zastąpić ją, organizations jeśli aplikacja nie obsługuje kont osobistych Microsoft.

Aktualizowanie kodu w celu obsługi wielu wartości wystawcy

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 odbierają tokeny z Platforma tożsamości Microsoft i robią to, aby wysył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 adresów URL kluczy lub /common kluczy. Aplikacja musi sprawdzić, czy issuer właściwość w opublikowanych metadanych jest zgodna iss z oświadczeniem w tokenie, oprócz zwykłego sprawdzenia, czy iss oświadczenie 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ć reprezentowana w dzierżawie użytkownika. Dzięki temu organizacja może 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 firmy Microsoft entra używanej 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 wyrazi zgodę, wówczas w dzierżawie użytkownika zostanie utworzona reprezentacja aplikacji o nazwie jednostka usługi, a logowanie może kontynuować. Delegowanie jest również tworzone w katalogu, który rejestruje zgodę użytkownika na aplikację. Aby uzyskać szczegółowe informacje na temat obiektów Application i ServicePrincipal aplikacji oraz ich powiązania, zobacz Application objects and service principal objects (Obiekty aplikacji i obiekty jednostki usługi).

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

To środowisko zgody ma wpływ na uprawnienia żądane przez aplikację. 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.

Niektóre uprawnienia mogą być wyrażane przez zwykłego użytkownika, a inne 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. To, czy uprawnienie wymaga zgody administratora, jest określane przez dewelopera, który opublikował zasób, i można go 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 Połączenie, które zawiera prompt=consent również parametr ciągu zapytania. Gdy administrator wyrazi zgodę i jednostka usługi zostanie utworzona w dzierżawie klienta, kolejne żądania logowania nie potrzebują parametru prompt=consent . Ponieważ administrator zdecydował, że żądane uprawnienia są akceptowalne, żaden inny użytkownicy w dzierżawie nie są monitowani o zgodę od tego momentu.

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ładem tego, kiedy będzie to używane, jest to, ż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ę, będzie ona stosowana tylko dla konta użytkownika. Regularni użytkownicy nadal 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, identyfikator entra firmy Microsoft zwraca błąd, który należy najpierw dodać zasób.

Wiele warstw w jednej dzierżawie

Może to być problem, jeśli aplikacja logiczna składa się z co najmniej dwóch rejestracji aplikacji, na przykład oddzielnego klienta i zasobu. Jak najpierw uzyskać zasób do dzierżawy zewnętrznej? Identyfikator entra firmy Microsoft obejmuje ten przypadek, umożliwiając wyrażenie zgody klienta i zasobu w jednym kroku. Użytkownik widzi sumę uprawnień żądanych zarówno przez klienta, jak i zasób na stronie zgody. Aby włączyć to zachowanie, rejestracja aplikacji zasobu musi zawierać identyfikator aplikacji klienta jako knownClientApplications element w manifeście aplikacji. Na przykład:

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

Jest to pokazane w przykładzie aplikacji wielodostępnej. Poniższy diagram zawiera omówienie zgody dla aplikacji wielowarstwowej zarejestrowanej w jednej dzierżawie.

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

Wiele warstw w wielu dzierżawach

Podobny przypadek występuje, jeśli różne warstwy aplikacji są zarejestrowane w różnych dzierżawach. 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 później, aby aplikacja natywna mogła działać w dzierżawie klienta, jednostka usługi Exchange Online musi być obecna. W takim przypadku 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 zapewnić klientom możliwość wyrażania zgody na aplikację w dzierżawach klientów. Zalecanym projektem jest utworzenie interfejsu API przez dewelopera innej firmy, który może również działać jako klient internetowy w celu zaimplementowania rejestracji. Czynność:

  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 uwidaczniania zakresów/ról interfejsu API upewnij się, że rejestracja zawiera uprawnienie "Zaloguj się i odczyt profilu 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ę, jednostki usługi i linki delegowania zgody są tworzone w dzierżawie, a aplikacja natywna może uzyskać tokeny dla interfejsu API.

Poniższy diagram zawiera omówienie zgody dla aplikacji wielowarstwowej 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.
  • Administracja istratory odwołują dostęp do aplikacji, usuwając je przy użyciu narzędzia Sekcja 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 w celu /common uzyskania tokenu dostępu dla użytkownika pomija wpis pamięci podręcznej, a użytkownik zostanie poproszony o ponowne zalogowanie. Aby uniknąć braku pamięci podręcznej, upewnij się, że kolejne wywołania już zalogowanego użytkownika są wykonywane do punktu końcowego dzierżawy.

Zobacz też