Opanowanie rejestracji aplikacji wielodzierżawczych w Entra ID dla SPFx

By Mirko Peters · 2026-08-11

Witamy ponownie w podcaście! Jeśli kiedykolwiek próbowałeś przenieść rozwiązanie SharePoint Framework (SPFx), starannie zbudowane w Twojej dzierżawie deweloperskiej, do środowiska klienta, znasz to nieprzyjemne uczucie, gdy wszystko się psuje. Cisza. Puste komponenty webowe. Niekończące się pętle logowania. Uwierzytelnianie między dzierżawami to najlepszy sprawdzian dla deweloperów Microsoft 365,

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

Titelbild: Mastering Multi-Tenant Entra ID App Registrations for SPFx

W tym obszernym przewodniku rozwijamy wszystko, o czym mówiliśmy w ostatnim odcinku. Aby zagłębić się w rozmowę audio, posłuchaj naszego szczegółowego omówienia: Fix Multi-Tenant SPFx Authentication.

Wprowadzenie: Dlaczego wielodzierżawczy SPFx to tryb trudny

Przeniesienie aplikacji SPFx poza granice tożsamości często nazywa się „trybem trudnym” i nie bez powodu. Gdy budujesz w obrębie jednej dzierżawy, Entra ID, struktury witryn SharePoint i uprawnienia do interfejsów API są w dużej mierze domyślne lub łatwo omijane dzięki uprawnieniom globalnego administratora. W chwili gdy wchodzisz w model wielodzierżawczy – czy jesteś niezależnym dostawcą oprogramowania (ISV), który udostępnia komponent webowy jako produkt, czy wewnętrznym zespołem IT zarządzającym dzierżawami wielu spółek zależnych – te skróty znikają.

Masz teraz do czynienia z surowymi granicami katalogów, mechanizmami zgód wymagającymi wyraźnej zgody administratora oraz unikalną topologią witryn. Jeśli rejestracja aplikacji jest zablokowana jako jednodzierżawcza albo Twój kod opiera się na zakodowanych na sztywno parametrach środowiska, wdrożenie na pewno zakończy się niepowodzeniem w środowisku produkcyjnym.

Dla kogo jest ten artykuł

Zanim przejdziemy do mechaniki technicznej, określmy, kto powinien opanować ten wzorzec architektoniczny:

Deweloperzy SPFx i konsultanci Microsoft 365 wdrażający rozwiązania w wielu dzierżawach, którzy chcą uniknąć ręcznej rekonfiguracji przy każdym wdrożeniu u klienta.
Administratorzy IT i dostawcy usług zarządzanych (MSP) obsługujący środowiska SharePoint Online klientów, którzy muszą utrzymać ścisły poziom bezpieczeństwa, umożliwiając jednocześnie nowoczesne rozwiązania deweloperskie.
Partnerzy i dostawcy ISV udostępniający komponenty webowe i rozszerzenia SPFx jako produkty, którzy potrzebują powtarzalnej, skalowalnej ścieżki wejścia na rynek obejmującej setki różnorodnych dzierżaw klientów.

Najważniejsze wnioski

Aby z powodzeniem poruszać się po wdrożeniach wielodzierżawczych, miej te podstawowe zasady na uwadze podczas projektowania architektury:

Uwierzytelnianie to nie szablon: Używaj wielodzierżawczej aplikacji Entra ID i wymagaj zgody administratora dla każdej dzierżawy; weryfikuj te stany bezpieczeństwa w czasie działania.
Nigdy nie wpisuj danych dzierżawy na sztywno: Wczytuj adresy URL, identyfikatory i zakresy dynamicznie ze źródła konfiguracji uwzględniającego dzierżawy; wszelkie niezbędne sekrety po stronie serwera przechowuj bezpiecznie w Azure Key Vault.
Puste wyniki z Graph nie oznaczają wadliwego kodu: Gdy Microsoft Graph zwraca puste tablice, prawie zawsze jest to spowodowane brakiem zgody lub niezgodnością danych katalogowych i filtrów, a nie błędem składni w kodzie.
Jeden pakiet, wiele dzierżaw: Projektuj rozwiązania SPFx całkowicie niezależne od dzierżawy, uzupełnione wdrożeniami przypisanymi do dzierżawy, aby wyeliminować tworzenie osobnych buildów dla każdego klienta.
Wykrywaj błędy wcześnie: Centralizuj telemetrię i kontrole stanu za pomocą Application Insights lub Azure Monitor, dostosowane do każdej dzierżawy.

Najważniejsze punkty

W trakcie naszej technicznej analizy natrafiliśmy na kilka kluczowych kamieni milowych, które musisz uwzględnić w cyklu życia swojego rozwiązania:

Trzy błędy w uwierzytelnianiu, które przekreślają wdrożenia międzydzierżawcze: rejestracje aplikacji jednodzierżawcze, mit jednorazowej zgody oraz osadzanie sekretów bezpośrednio w kodzie po stronie klienta.
Dlaczego Microsoft Graph działa bez zarzutu w Twojej dzierżawie deweloperskiej, a w środowisku klienta zwraca wyłącznie zera – i jak to zweryfikować przed uruchomieniem produkcyjnym.
Pakowanie raz, konfigurowanie wszędzie: architektoniczny schemat w pełni niezależnego od dzierżawy SPFx.
Strategie logowania i monitorowania, które wychwytują ciche problemy z konfiguracją, zanim zauważą je klienci.
Struktury zarządzania, które utrzymują zgodność organizacji z przepisami przy zachowaniu wysokiego tempa dostarczania.

Lista kontrolna na start (do skopiowania)

Rejestracja aplikacji w Entra ID
- Ustaw Supported account types: Multitenant.
- Zdefiniuj dokładne delegowane zakresy Graph potrzebne do działania, zgodnie z zasadą najmniejszych uprawnień.
- Skonfiguruj prawidłowe identyfikatory URI przekierowania, obejmujące zarówno SharePoint Online, jak i lokalne środowiska deweloperskie.
Utwardzanie projektu SPFx
- Używaj MSGraphClient lub AadHttpClient do wszystkich wywołań API wymagających delegowanych uprawnień.
- Odczytuj konfiguracje specyficzne dla dzierżawy (takie jak punkty końcowe i identyfikatory docelowych witryn) z dedykowanej listy konfiguracji w SharePoint lub z bezpiecznego API; zadbaj o to, aby w kodzie frontendu nie znajdowały się żadne sekrety.
- Wdrażaj kontrole uprawnień w czasie wykonywania, które w razie braku uprawnień w łagodny sposób wyświetlają baner „Wymagana zgoda administratora” z bezpośrednim linkiem.
Przepływ wyrażania zgody
- Przygotuj dedykowaną stronę onboardingu dzierżawy, na której wyświetlisz wymagane zakresy, dokładny adres URL zgody administratora oraz kroki weryfikacji.
- Obsługuj modele zgody dla poszczególnych grup odbiorców, rozróżniając wdrożenie obejmujące całą organizację od ukierunkowanej grupy pilotażowej.
Pakowanie i wdrażanie
- Spakuj rozwiązanie jednokrotnie do standardowego pliku .sppkg i włącz wdrażanie w zakresie dzierżawy tam, gdzie jest to właściwe.
- Publikuj przez centralny katalog aplikacji (App Catalog), jednocześnie szczegółowo dokumentując kroki dodawania na poziomie witryny.
- Zautomatyzuj cykl wydań za pomocą solidnego potoku CI/CD (kompilacja, grupowanie, pakowanie, przesyłanie i wdrożenie).
Monitorowanie i wsparcie
- Generuj szczegółową telemetrię, obejmującą identyfikator dzierżawy, identyfikator korelacji, konkretne funkcje i kody błędów.
- Skonfiguruj pulpity w Application Insights lub Azure Monitor wraz z alertami umożliwiającymi podjęcie działań.
- Udokumentuj jasną procedurę wycofania przy użyciu poprzednich wersji pakietu oraz szczegółową mapę wersji dla każdej dzierżawy.

Typowe pułapki (i sposoby ich naprawy)

Nawet doświadczeni deweloperzy wpadają w przewidywalne pułapki podczas konfigurowania aplikacji wielodzierżawowych. Oto, jak szybko je zdiagnozować i usunąć:

Objaw: Pętle logowania lub frustrujący scenariusz „u mnie działa, u nich nie”.
Przyczyna: Rejestracja aplikacji w Entra ID nadal jest skonfigurowana jako jednodzierżawowa albo adresy URL odpowiedzi nie pasują do docelowego środowiska.
Rozwiązanie: Przełącz rejestrację aplikacji na wielodzierżawową, popraw identyfikatory URI przekierowania i wyślij nowe żądanie zgody.
Objaw: Microsoft Graph zwraca całkowicie puste zbiory danych.
Przyczyna: Brak zgody administratora dzierżawy lub zbyt restrykcyjne filtry katalogu.
Rozwiązanie: Uruchom właściwy przepływ zgody administratora, przetestuj zapytania bezpośrednio w Graph Explorer, używając prawdziwego użytkownika z dzierżawy klienta, i złagodź zbyt sztywne założenia lub filtry w kodzie.
Objaw: Użytkownicy nie mogą dodać webpartu do swoich stron.
Przyczyna: Pakiet nie został prawidłowo wdrożony do katalogu aplikacji dzierżawy albo zasady aplikacji organizacji go blokują.
Rozwiązanie: Sprawdź stan wdrożenia w katalogu aplikacji oraz przejrzyj ustawienia i zasady aplikacji dzierżawy.
Objaw: Konieczność ponownego budowania pakietu przy każdej drobnej zmianie konfiguracji u kolejnych klientów.
Przyczyna: Identyfikatory, adresy URL lub sekrety są wpisane na stałe bezpośrednio w pakiecie.
Rozwiązanie: Wynieś konfigurację na zewnątrz: korzystaj z list konfiguracji w SharePoint lub Azure Key Vault i odczytuj te wartości dynamicznie w czasie wykonywania.

Podstawy ładu i bezpieczeństwa

Bezpieczeństwo nie może być dodatkiem wprowadzanym na końcu, gdy wdrażasz kod w zewnętrznych dzierżawach klientów. Wdroż poniższe podstawy ładu, aby utrzymać zaufanie:

Egzekwuj zakresy zgodne z zasadą najmniejszych uprawnień i regularnie je przeglądaj, aby usuwać nieużywane uprawnienia.
Przechowuj sekrety aplikacji po stronie serwera bezpiecznie w Azure Key Vault i ustal harmonogram regularnej rotacji.
Wykorzystaj zasady uprawnień aplikacji w Teams i SharePoint, aby ściśle ograniczyć grupy docelowe i zapobiec nieautoryzowanemu użyciu.
Prowadź wyczerpujący rejestr zgód, obejmujący informacje o tym, kto wyraził zgodę, kiedy ją udzielono i jakie zakresy zatwierdzono.
Dostosowuj branding webpartu dynamicznie za pomocą interfejsów API motywów Microsoft 365, zamiast umieszczać w kodzie zasoby stylów specyficzne dla dzierżawy.

Plan walidacji (przed przekazaniem klientowi)

Nigdy nie wdrażaj w ciemno. Przejdź przez poniższy plan walidacji, zanim zaprezentujesz rozwiązanie klientowi:

Przetestuj wszystkie wywołania Microsoft Graph bezpośrednio w dzierżawie klienta, używając Graph Explorer, na dokładnie tym samym koncie użytkownika i z tymi samymi delegowanymi zakresami.
Przeprowadź lokalizowane wdrożenie pilotażowe na jednej, odizolowanej kolekcji witryn, z niewielką grupą wybranych użytkowników.
Sprawdź historię wersji i możliwości przywracania bezpośrednio w katalogu aplikacji SharePoint.
Przetestuj scenariusze pracy offline i wygasłych tokenów, aby upewnić się, że komunikaty o błędach i automatyczne procedury odzyskiwania działają zgodnie z oczekiwaniami.

Często zadawane pytania

Czy do SPFx potrzebne są uprawnienia aplikacji?
Zazwyczaj nie. Rozwiązania SPFx działają w kontekście delegowanego użytkownika. Uprawnienia aplikacji wymagają dodatkowych zatwierdzeń administracyjnych oraz wyspecjalizowanych wzorców architektonicznych, dlatego stosuj je wyłącznie wtedy, gdy nie ma innej sensownej alternatywy.

Czy można uniknąć zgody udzielanej osobno w każdej dzierżawie?
Nie. Administrator każdej dzierżawy klienta musi wyraźnie udzielić zgody na żądane zakresy uprawnień Twojej aplikacji. Można jednak znacznie usprawnić ten proces, tworząc prowadzone interfejsy wdrażania oraz proaktywne banery powiadomień podczas działania aplikacji.

Jak utrzymać jedną bazę kodu dla wielu klientów?
Uczyń rozwiązanie w pełni niezależnym od dzierżawy, wynieś wszystkie konfiguracje zależne od środowiska na zewnątrz i zautomatyzuj procesy pakowania oraz wdrażania. Do bezpiecznego zarządzania ustawieniami specyficznymi dla klienta wykorzystaj flagi funkcji.

Jak szybciej diagnozować przypadki „nic się nie wyświetla”?
Zapisuj surowe odpowiedzi Graph wraz z wynikami sprawdzania zakresów. Gdy wystąpi błąd, wyświetl w interfejsie powiadomienie z komunikatem „Brak zgody lub niewystarczający zakres” oraz bezpośrednim linkiem, który pozwoli od razu naprawić problem.

Podsumowanie

Opanowanie rejestracji aplikacji Entra ID działających w wielu dzierżawach dla rozwiązań SharePoint Framework to to, co odróżnia skrypty hobbystów od oprogramowania klasy korporacyjnej. Przechodząc na myślenie oparte na pakowaniu niezależnym od dzierżawy, dynamicznym ładowaniu konfiguracji i solidnej walidacji zgód w czasie działania, wyeliminujesz ciche błędy wdrożeń i zapewnisz każdemu klientowi bezproblemowe doświadczenia.

Więcej o rzeczywistych historiach i decyzjach architektonicznych stojących za tymi rozwiązaniami znajdziesz w powiązanym odcinku podcastu: Fix Multi-Tenant SPFx Authentication. Dziękuję za lekturę i miłego kodowania!