Opanowanie przepływu zgody administratora dla rozwiązań Microsoft 365 działających w wielu dzierżawach

By Mirko Peters · 2026-08-11

Witamy ponownie na blogu! Jeśli kiedykolwiek próbowałeś wdrożyć niestandardowe rozwiązanie SharePoint Framework (SPFx) ze swojej dzierżawy deweloperskiej do środowiska produkcyjnego klienta…

Automatically translated with AI from the original post. Read the English original

Witamy ponownie na blogu! Jeśli kiedykolwiek próbowałeś wdrożyć niestandardowe rozwiązanie SharePoint Framework (SPFx) z dzierżawy deweloperskiej do środowiska produkcyjnego klienta, znasz to nieprzyjemne uczucie, gdy coś po cichu przestaje działać. Tworzenie rozwiązań dla Microsoft 365 w wielu dzierżawach jest notorycznie trudne. Granice tożsamości, parametry zabezpieczeń, architektura witryn specyficzna dla dzierżawy i przeszkody związane ze zgodą mogą szybko zamienić rutynowe wdrożenie w prawdziwy koszmar. Dlatego zagłębiamy się w opanowanie przepływu zgody administratora dla rozwiązań działających w wielu dzierżawach. Jeśli chcesz poznać temat głębiej w formie audio, koniecznie sprawdź nasz powiązany odcinek podcastu, Fix Multi-Tenant SPFx Authentication, w którym szczegółowo omawiamy dokładnie te scenariusze.

W tym wpisie wyjaśnimy, jak prawidłowo skonfigurować aplikacje, przeprowadzić klientów przez proces wdrażania dzierżawy i zgody administratora bez zbędnych tarć, obsłużyć delegowane zakresy Microsoft Graph, aby uniknąć pustych zbiorów danych, a także tworzyć przejrzyste banery uprawnień w czasie wykonywania oraz stany błędów. Sprawmy, aby tworzenie rozwiązań dla wielu dzierżaw było przewidywalne, bezpieczne i powtarzalne.

Dla kogo jest ten artykuł

Ten przewodnik jest przeznaczony przede wszystkim dla specjalistów, którzy działają w wielu środowiskach Microsoft 365 i potrzebują niezawodnych, skalowalnych architektur. Szczególnie przydatny będzie dla Ciebie, jeśli jesteś:

• Deweloperem SPFx lub konsultantem Microsoft 365, który dostarcza niestandardowe komponenty do wielu dzierżaw klientów.
• Administratorem IT lub dostawcą usług zarządzanych (MSP), który obsługuje środowiska klientów SharePoint Online i Entra ID.
• Partnerem programowym lub niezależnym dostawcą oprogramowania (ISV), który przygotowuje webparty SPFx, rozszerzenia i dodatki do komercyjnej dystrybucji.

Uwierzytelnianie to nie szablon: konfiguracja aplikacji Entra ID dla wielu dzierżaw

Jedną z najbardziej niebezpiecznych pułapek, w jakie wpadają deweloperzy, jest traktowanie uwierzytelniania jako prostego kodu szablonowego, który można kopiować i wklejać z projektu do projektu. Podczas tworzenia rozwiązania przeznaczonego do działania w wielu organizacjach rejestracja aplikacji w Entra ID (dawniej Azure AD) musi być jawnie skonfigurowana pod kątem wielu dzierżaw.

Jeśli rejestracja aplikacji zostanie przypadkowo pozostawiona jako jednodzierżawna, użytkownicy spoza Twojej macierzystej organizacji natychmiast napotkają pętle logowania lub błędy uprawnień. Aby to naprawić, upewnij się, że w rejestracji aplikacji typy obsługiwanych kont są ustawione na konta w dowolnym katalogu organizacyjnym (wielodzierżawcze). Ponadto musisz zdefiniować dokładnie te delegowane zakresy Graph, których wymaga Twoje rozwiązanie, zgodnie z zasadą najmniejszych uprawnień, oraz skonfigurować precyzyjne identyfikatory URI przekierowania, uwzględniające zarówno domeny SharePoint Online, jak i lokalne środowisko deweloperskie.

Budowanie płynnego, prowadzonego przepływu wdrożenia i zgody administratora

Oczekiwanie, że zwykli użytkownicy biznesowi poradzą sobie z oknami zgody, może zablokować Twoje wdrożenie. Co gorsza, oczekiwanie, że administratorzy IT klienta bezkrytycznie zaufają niezwiązanemu z kontekstem monitowi, często kończy się zablokowaniem instalacji. Aby zbudować zaufanie i usprawnić wdrożenie, potrzebujesz prowadzonej strony wdrożeniowej.

Profesjonalne doświadczenie wdrożeniowe zapewnia administratorom klienta przejrzysty przegląd wymaganych zakresów, dokładny administracyjny adres URL zgody, który uruchamia udostępnienie aplikacji przedsiębiorstwa, oraz instrukcje weryfikacji krok po kroku. Dzięki obsłudze zgody dla poszczególnych grup odbiorców — umożliwiając administratorom udzielenie zgody dla całej organizacji lub wybranych grup pilotażowych — obniżasz próg wejścia i eliminujesz tarcia przy wdrażaniu.

Obsługa delegowanych zakresów Graph i zapobieganie pustym zbiorom danych

Czy zdarzyło Ci się wdrożyć webpart, który świetnie działał w środowisku deweloperskim, a po zainstalowaniu w dzierżawie klienta wyświetlał całkowicie puste strony? To klasyczny objaw brakującej zgody administratora dzierżawy lub niezgodnych danych katalogu.

Kiedy Microsoft Graph zwraca puste zbiory danych, rzadko jest to błąd w logice aplikacji. Znacznie częściej oznacza to, że aplikacja się uwierzytelniła, ale administrator dzierżawy nie udzielił jeszcze zgody na wymagane uprawnienia delegowane (delegated scopes) albo że stosowane filtry danych organizacji nie pasują do profili użytkowników lub struktury witryn klienta. Zawsze testuj zapytania w Graph Explorer, używając reprezentatywnego kontekstu użytkownika klienta, i projektuj logikę aplikacji tak, aby elegancko obsługiwała częściowe lub brakujące zbiory danych, zamiast zgłaszać nieobsłużone wyjątki.

Tworzenie pomocnych banerów uprawnień w czasie działania i stanów błędów

Nawet przy najlepiej przygotowanym wdrożeniu administratorzy czasami pomijają zakres uprawnień albo later odbierają uprawnienia. Gdy to się zdarzy, aplikacja nie powinna się zawiesić ani wyświetlać niezrozumiałego błędu w konsoli JavaScript. Zamiast tego powinna prezentować pomocne banery uprawnień w czasie działania oraz kontekstowe stany błędów.

Sprawdzając uprawnienia asynchronicznie w czasie działania, Twoje web parts SPFx mogą natychmiast wykryć nieprawidłowy lub brakujący zakres tokenu. Po wykryciu braku wyświetl czytelny, profesjonalny baner informujący użytkownika, że wymagana jest zgoda administratora, wraz z bezpośrednim linkiem do przewodnika wdrożeniowego lub adresu URL zgody. Dzięki temu frustrujące zgłoszenie do wsparcia zamienia się w samoobsługowe rozwiązanie dla klienta.

Wyniesienie konfiguracji na zewnątrz i utrzymanie pakietu SPFx wolnego od sekretów

Wpisywanie na stałe identyfikatorów dzierżawy, identyfikatorów klienta, punktów końcowych API lub sekretów klienta w pakiecie SPFx to poważne naruszenie bezpieczeństwa i ślepy zaułek operacyjny. Jeśli zaszyjesz te dane w kodzie, będziesz zarządzać dziesiątkami unikalnych kompilacji dla każdego wdrażanego klienta.

Właściwym podejściem jest projektowanie pakietu SPFx w sposób całkowicie niezależny od dzierżawy. Przechowuj ustawienia konfiguracji w lokalizacji uwzględniającej dzierżawę, na przykład w scentralizowanej liście konfiguracji SharePoint, w zewnętrznym API lub w usłudze Azure App Configuration. Jeśli usługi zaplecza wymagają sekretów aplikacji, przechowuj je i zarządzaj nimi bezpiecznie w usłudze Azure Key Vault, zamiast osadzać je w pakietach kodu po stronie klienta.

Pakowanie raz, wdrażanie wszędzie: strategia jednego potoku

Gdy kod jest sterowany konfiguracją i wolny od sekretów, możesz przyjąć strategię wdrażania przez jeden potok. Oznacza to, że rozwiązanie kompilujesz i pakujesz do jednego pliku .sppkg tylko raz, a dokładnie ten sam pakiet wdrażasz we wszystkich dzierżawach klientów.

Wykorzystując wdrożenia o zasięgu dzierżawy tam, gdzie jest to odpowiednie, możesz publikować rozwiązanie w centralnych katalogach aplikacji (App Catalog) i automatyzować potoki CI/CD, które obsługują kompilację, łączenie, pakowanie i publikowanie bez ręcznych rozgałęzień kodu. Znacznie to upraszcza kontrolę wersji i gwarantuje, że każdy klient działa na dokładnie tym samym, przetestowanym pliku binarnym.

Monitorowanie, telemetria i wczesne wykrywanie awarii

Gdy zarządzasz rozwiązaniami działającymi w dziesiątkach różnych dzierżaw klientów, nie możesz polegać na tym, że klienci zgłoszą każdy błąd. Potrzebujesz proaktywnego wglądu w kondycję aplikacji. Centralizacja telemetrii jest niezbędna.

Skonfiguruj komponenty SPFx tak, aby wysyłały ustrukturyzowane dane telemetryczne, obejmujące identyfikatory dzierżaw, identyfikatory korelacji, aktywne funkcje i komunikaty o błędach, bezpośrednio do usługi Application Insights lub pulpitów Azure Monitor. Konfiguracja alertów o powtarzających się błędach uwierzytelniania lub przekroczeniach czasu Graph pozwala zespołowi inżynierskiemu wykryć i usunąć problemy, zanim zauważą je klienci.

Typowe pułapki i sposoby ich naprawiania

Nawet przy starannym planowaniu pewne przeszkody w środowiskach wielodzierżawnych pojawiają się regularnie. Oto najczęstsze objawy, z jakimi spotykają się deweloperzy, i sposoby ich naprawy:

• Objaw: Pętle logowania lub błędy o treści „działa w mojej dzierżawie, ale nie w ich”.
  Przyczyna: Rejestracja aplikacji została przypadkowo ustawiona jako jednodzierżawna albo adres URL odpowiedzi nie zgadza się z konfiguracją.
  Naprawa: Zmień typ rejestracji aplikacji na wielodzierżawny, sprawdź i zaktualizuj identyfikatory URI przekierowania, a następnie ponownie uruchom przepływ zgody administratora.
• Objaw: Microsoft Graph zwraca puste zbiory danych.
  Przyczyna: Brak zgody administratora dzierżawy lub zbyt restrykcyjne filtry użytkowników/grup.
  Naprawa: Uruchom przepływ zgody administratora, przetestuj dokładne zapytania API w Graph Explorer na prawdziwym koncie klienta i złagodź zbyt restrykcyjne filtry zapytań.
• Objaw: Użytkownicy nie mogą dodać webpartu do swoich nowoczesnych stron.
  Przyczyna: Pakiet nie został wdrożony w całej dzierżawie lub zasady aplikacji organizacji go blokują.
  Rozwiązanie: Sprawdź stan wdrożenia w katalogu aplikacji (App Catalog) oraz ustawienia aplikacji Microsoft 365 na poziomie dzierżawy i zasady wdrażania.
• Objaw: Konieczność ponownej kompilacji i przebudowy rozwiązania przy drobnych zmianach konfiguracji.
  Przyczyna: Zakodowane na stałe identyfikatory, adresy URL lub punkty końcowe.
  Rozwiązanie: Przenieś wartości konfiguracji do listy programu SharePoint lub bezpiecznego magazynu konfiguracji i pobieraj je dynamicznie w czasie wykonywania.

Zarządzanie, podstawy bezpieczeństwa i zasada najmniejszych uprawnień

Działanie w środowiskach przedsiębiorstw oznacza, że zarządzanie bezpieczeństwem jest obowiązkowe. Aby chronić klientów i utrzymać zgodność z wymogami, stosuj się do następujących podstawowych zasad bezpieczeństwa:

• Zawsze żądaj absolutnie minimalnego wymaganego zakresu uprawnień delegowanych i regularnie przeprowadzaj przeglądy zakresów.
• Nigdy nie przechowuj sekretów w postaci jawnego tekstu; wykorzystuj Azure Key Vault i rotuj sekrety według przewidywalnego harmonogramu.
• Używaj zasad uprawnień aplikacji w usługach Microsoft Teams i SharePoint, aby ograniczyć widoczność aplikacji do określonych grup użytkowników.
• Prowadź rejestr zgód, dokumentujący, które dzierżawy klientów wyraziły zgodę, kiedy zgoda została udzielona i jakie zakresy zostały zatwierdzone.
• Dopasuj wygląd wizualny do środowisk klientów, korzystając z interfejsów API motywów SharePoint zamiast dołączania statycznych zasobów CSS przeznaczonych dla konkretnych dzierżaw.

Plan walidacji przed uruchomieniem u klienta

Zanim zatwierdzisz wdrożenie u klienta i uznasz sprawę za zamkniętą, przeprowadź rygorystyczny plan walidacji, aby uniknąć niespodzianek:

• Dokładnie przetestuj wywołania Microsoft Graph w docelowej dzierżawie klienta, używając Eksploratora Graph i tego samego konta oraz tych samych zakresów.
• Przeprowadź kontrolowaną fazę pilotażową na jednej dedykowanej kolekcji witryn z niewielką grupą docelowych użytkowników.
• Sprawdź historię wersji i procedury przywracania bezpośrednio w katalogu aplikacji SharePoint klienta.
• Zasymuluj scenariusze z brakiem połączenia lub wygasłym tokenem, aby upewnić się, że niestandardowe komunikaty o błędach i procesy odzyskiwania działają prawidłowo.

Często zadawane pytania

Czy do SPFx potrzebne są uprawnienia aplikacji?

Zazwyczaj nie. SPFx działa w całości w kontekście delegowanego użytkownika. Uprawnienia aplikacji wymagają dodatkowych zatwierdzeń administracyjnych i specjalistycznych wzorców architektonicznych, dlatego stosuj je wyłącznie wtedy, gdy przetwarzanie w tle poza sesją użytkownika jest niezbędne.

Czy mogę pominąć zgodę dla każdej dzierżawy?

Nie. Model bezpieczeństwa Microsoft wymaga, aby administrator każdej dzierżawy udzielił wyraźnej zgody na zakresy żądane przez aplikację wielodzierżawową. Można usprawnić ten proces, ale nie można go całkowicie ominąć.

Jak utrzymać jedną bazę kodu dla wielu klientów?

Uczyń rozwiązanie w pełni niezależnym od dzierżawy, przenieś dane konfiguracyjne na zewnątrz, zautomatyzuj potoki pakowania i wdrażania oraz wykorzystuj flagi funkcji do dynamicznego zarządzania przełącznikami specyficznymi dla klienta.

Jak szybciej diagnozować przypadek „to jest puste”?

Rejestruj odpowiedzi Microsoft Graph wraz z wynikami sprawdzania zakresów i wyświetlaj w interfejsie powiadomienie wskazujące brak zgody lub niewystarczający zakres, wraz z linkiem bezpośrednim umożliwiającym natychmiastową naprawę.

Podsumowanie

Opanowanie przepływu zgody administratora i uwierzytelniania wielodzierżawowego w rozwiązaniach SPFx odróżnia amatorskie wdrożenia od produktów klasy korporacyjnej. Tworząc wielodzierżawową aplikację Entra ID, budując prowadzone procesy wdrażania, przenosząc konfigurację na zewnątrz i wdrażając proaktywną telemetrię, możesz wyeliminować obawy związane z wdrożeniem i zapewnić płynne doświadczenia każdemu klientowi. Aby dowiedzieć się więcej o realiach obsługi tych wyzwań związanych z tożsamością w praktyce, koniecznie posłuchaj naszej pełnej dyskusji w odcinku podcastu Fix Multi-Tenant SPFx Authentication. Dziękujemy za lekturę i szczęśliwego kodowania!