Synchronizacja katalogu Entra AD
Gdy firma prowadzi symulacje phishingu wobec 50, 500 albo 5 000 pracowników, ręczne utrzymywanie listy kontaktów na bieżąco nie jest realne. PhishSpot łączy się z Microsoft Entra ID (dawniej Azure AD) i pobiera użytkowników oraz grupy bezpośrednio z Twojego katalogu. Nowi pracownicy się pojawiają, odchodzący zostają wyłączeni, członkostwo w grupach odpowiada aktualnej strukturze — bez ręcznej edycji arkusza.
Ten rozdział opisuje konfigurację integracji, harmonogram synchronizacji, co i jak jest importowane, ręczne synchronizacje oraz log historii, do którego zaglądasz gdy coś wygląda nie tak.
25.1 Po co synchronizacja katalogu?
Dział zatytułowany „25.1 Po co synchronizacja katalogu?”Alternatywa to import z CSV (Rozdział 5 Kontakty opisuje ścieżki ręczne). Są w porządku dla proof-of-concept albo jednorazowych pilotaży, ale w produkcji szybko się dezaktualizują. Synchronizacja katalogu daje:
- Autorytatywne źródło. Twój IT już utrzymuje Entrę. PhishSpot dziedziczy tę pracę — brak równoległej listy do utrzymania.
- Automatyczny onboarding. Nowy pracownik, którego konto Entra zostało założone dziś, pokaże się w PhishSpot rano (albo szybciej, w zależności od harmonogramu) i od razu staje się prawidłowym celem dla kampanii autopilotów.
- Eleganckie obsłużenie odchodzących. Gdy IT wyłącza konto w Entra, pasujący Contact w PhishSpot zostaje oznaczony
disabled— pozostaje w bazie do raportów historycznych, ale autopiloty przestają go obsługiwać. - Grupy nadążają. Członkostwo w „Engineering”, „Finance”, „Zarząd” — cokolwiek zdefiniowano w Entra — zostaje odbite w grupach PhishSpot, więc odbiorcy autopilotów automatycznie podążają za strukturą organizacji.
Jeśli chcesz też, żeby użytkownicy logowali się do swojego portalu szkoleniowego przez Microsoft, ta sama integracja obsługuje ten przepływ — patrz Rozdział 24 Logowanie przez Microsoft 365.
25.2 Połączenie z Entra
Dział zatytułowany „25.2 Połączenie z Entra”
- Otwórz Ustawienia konta → Integracje. Zobaczysz siatkę kart integracji. Znajdź kartę Microsoft Entra ID; pokazuje szary punkt statusu („nieaktywna”) dopóki nie zostanie połączona.
- Kliknij Połącz z Microsoft. PhishSpot poprosi o tenant ID Entra (GUID, np.
1f3a8d2e-...). Znajdziesz go w centrum administracyjnym Entra w sekcji „Właściwości”. - Zatwierdź. PhishSpot generuje token state podpisany HMAC i przekierowuje Cię na ekran zgody administracyjnej Microsoft pod
login.microsoftonline.com/<tenant>/v2.0/adminconsent. Musisz być zalogowany jako Global Administrator w docelowym tenancie — zgoda administracyjna nadaje aplikacji enterprise PhishSpot uprawnienia odczytu katalogu w imieniu wszystkich użytkowników. - Ekran zgody pokazuje żądane uprawnienia:
User.Read.All— odczyt profili użytkowników (do listy kontaktów).Group.Read.All— odczyt definicji grup.
- Nadaj. Microsoft przekierowuje z powrotem do callbacku PhishSpot z
admin_consent=True&tenant=<ID>&state=<HMAC>. PhishSpot weryfikuje HMAC, zapisuje token aplikacji ograniczony do tenanta i zmienia status integracji na aktywna.
Połączone. Karta Microsoft pokazuje zielony punkt statusu, tenant ID monospace i znacznik czasu zgody.
Ograniczenie importu do wybranych grup
Dział zatytułowany „Ograniczenie importu do wybranych grup”W formularzu połączenia lub ustawieniach synchronizacji wpisz maksymalnie 50 identyfikatorów obiektów grup Entra. Możesz oddzielić je spacjami, przecinkami lub nowymi wierszami. Import uwzględnia grupy zagnieżdżone i nie powiela użytkownika należącego do kilku grup. Puste pole oznacza cały tenant. Po kompletnym imporcie użytkowników kontakty wcześniej zaimportowane przez tę integrację, które opuściły zakres, zostają dezaktywowane. Zmiany grup nie zmieniają odbiorców rozpoczętych kampanii.
Na koncie demo wybierz odizolowaną grupę testową. Import obejmuje tylko skrzynki dopuszczone do wysyłki demo, z fikcyjnymi danymi profilu. Bez wybranej grupy synchronizacja pozostaje wyłączona także po uzyskaniu zgody.
Rejestracja aplikacji Microsoft musi mieć uprawnienia aplikacyjne User.Read.All i Group.Read.All. Żądanie zgody używa https://graph.microsoft.com/.default i obejmuje uprawnienia skonfigurowane w tej rejestracji. Logowanie SSO korzysta z osobnego przepływu uprawnień delegowanych.
25.3 Harmonogram synchronizacji
Dział zatytułowany „25.3 Harmonogram synchronizacji”Kliknij Zarządzaj na aktywnej karcie Microsoft, aby otworzyć ustawienia integracji. Dwa checkboxy i jeden dropdown:
- Synchronizuj użytkowników do kontaktów — domyślnie WŁ. Pobiera każdego użytkownika Entra (z wybranego zakresu grup lub całego tenantu, jeśli zakres jest pusty) i upsertuje jako rekord
Contactw PhishSpot. - Synchronizuj grupy — domyślnie WŁ. Pobiera każdą grupę Entra (security i Microsoft 365 groups) i upsertuje jako
Group. Członkostwa są uzgadniane w tym samym przebiegu. - Harmonogram — jedno z:
- Wyłączony — brak automatycznej synchronizacji. Możesz nadal odpalać ją ręcznie (§25.5).
- Co godzinę — uruchamia się co godzinę o pełnej.
- Codziennie — uruchamia się raz dziennie o 02:00 UTC. Domyślny dla tenantów produkcyjnych.
- Co tydzień — uruchamia się raz w tygodniu, w poniedziałki o 02:00 UTC.
Zapisz ustawienia. Scheduler platformy (ScheduledDirectorySyncsJob) rozsyła w każdym interwale, kolejkując jeden DirectorySyncJob per aktywna integracja pasująca do harmonogramu.
Pierwsza synchronizacja po świeżym połączeniu jest zwykle największa — importuje wszystko. Kolejne dotykają tylko tego, co się zmieniło (kilka zmodyfikowanych użytkowników, jedna utworzona grupa, jedno usunięte członkostwo), więc są szybkie — zwykle poniżej minuty nawet dla tysięcy użytkowników.
25.4 Co jest importowane
Dział zatytułowany „25.4 Co jest importowane”Dla każdego użytkownika Entra importer tworzy lub aktualizuje Contact kluczowany po Entra Object ID (oid). Mapowanie:
| Pole Contact w PhishSpot | Źródło Entra |
|---|---|
email | userPrincipalName (fallback do mail) |
first_name, last_name | givenName, surname |
title | jobTitle |
department | department |
location | officeLocation (fallback do city + country) |
telephone | mobilePhone (fallback do businessPhones) |
external_id | id (OID Entry) |
external_state | active jeśli accountEnabled=true, inaczej disabled |
source | zawsze :entra |
synced_at | znacznik czasu synchronizacji |
Dla każdej grupy Entra importer tworzy Group kluczowany po OID grupy:
| Pole Group w PhishSpot | Źródło Entra |
|---|---|
name | sluggowany displayName (np. „Dział IT” → dzial-it) |
display_name | displayName (zachowuje wielkość liter i polskie znaki) |
external_id | id grupy |
source | :entra |
Członkostwo jest uzgadniane per synchronizacja: PhishSpot listuje aktualnych członków każdej grupy Entra, usuwa lokalne rekordy ContactGroup dla kontaktów, których już nie ma w grupie Entra, i tworzy nowe dla dodanych.
Ważne: Kontakty, których konto Entra zostało usunięte (a nie tylko wyłączone), nie znikają z PhishSpot — są oznaczane external_state: disabled, żeby raporty historyczne pozostały spójne. Aby całkowicie wyczyścić kontakt, usuń go ręcznie z UI PhishSpot.
25.5 Ręczna synchronizacja („Synchronizuj teraz”)
Dział zatytułowany „25.5 Ręczna synchronizacja („Synchronizuj teraz”)”Strona zarządzania integracją ma przycisk Synchronizuj teraz. Kliknij go aby natychmiast zakolejkować DirectorySyncJob, niezależnie od harmonogramu. Używaj do:
- Początkowego połączenia — większość adminów klika Synchronizuj teraz raz, zaraz po nadaniu zgody, żeby pierwszy import nie czekał na jutrzejszy cron o 02:00 UTC.
- Push onboardingowy — gdy IT oznaczy w Entra 20 nowych pracowników, chcesz mieć ich w PhishSpot przed następnym zaplanowanym przebiegiem.
- Troubleshooting — żeby spróbować ponownie po przejściowym błędzie Microsoft Graph widocznym w logu aktywności.
Ręczna synchronizacja zapisuje wpis DirectorySyncLog z trigger: manual — przydatne do odróżniania świadomych akcji admina od przebiegów z crona przy audytowaniu.
25.6 Historia synchronizacji
Dział zatytułowany „25.6 Historia synchronizacji”Pod ustawieniami tabela aktywności pokazuje ostatnie 50 przebiegów synchronizacji. Kolumny:
| Kolumna | Co pokazuje |
|---|---|
| Rozpoczęto | Kiedy przebieg się zaczął |
| Wyzwalacz | Ręczny (admin kliknął Synchronizuj teraz), Zaplanowany (cron), lub Callback OAuth (auto-sync zaraz po nadaniu zgody) |
| Status | W trakcie, Sukces, Błąd, lub Częściowy (kolorowy badge) |
| Zmiany | Użytkownicy utworzeni / zaktualizowani / wyłączeni, grupy utworzone / zaktualizowane, zmiany członkostwa |
| Czas trwania | Wall-clock czas przebiegu |
Przykładowa tabela aktywności z fikcyjnymi danymi:
| Rozpoczęto | Wyzwalacz | Status | Zmiany | Czas trwania |
|---|---|---|---|---|
| 6 godzin temu | Zaplanowany | Sukces | 0c · 7u · 0d / 0c · 0u / 1m | 22 s |
| 2 dni temu | Zaplanowany | Sukces | 1c · 2u · 1d / 0c · 0u / 2m | 19 s |
| 7 dni temu | Ręczny | Sukces | 0c · 4u · 0d / 0c · 0u / 0m | 14 s |
| 8 dni temu | Zaplanowany | Błąd | — | 1 s |
| 10 dni temu | Zaplanowany | Sukces | 1c · 3u · 0d / 0c · 0u / 1m | 16 s |
Przebieg zakończony błędem lub częściowym wynikiem wymaga sprawdzenia. Błąd uprawnień Microsoft Graph (403) oznacza konieczność sprawdzenia uprawnień aplikacyjnych i zgody administratora. Kolejny zaplanowany przebieg może ponowić import po przejściowej awarii.
25.7 Rozwiązywanie problemów
Dział zatytułowany „25.7 Rozwiązywanie problemów”Przycisk Połącz zabiera mnie na ekran „odmowa zgody”. Zalogowałeś się jako użytkownik bez uprawnień admin w tenancie. Wyloguj się ze wszystkich kont Microsoft, zaloguj się od nowa jako Global Administrator i spróbuj jeszcze raz.
Synchronizacja przechodzi, ale nie pojawiają się kontakty. Otwórz log aktywności. Jeśli status to Sukces i wszystkie zmiany są zerowe, Twój tenant Entra nie ma użytkowników pasujących do filtra (sprawdź identyfikatory grup i ich członków; konta demo importują wyłącznie dopuszczone skrzynki). Sprawdź w Entra, że oczekiwani użytkownicy mają accountEnabled=true.
„Tenant mismatch” na callbacku. Tenant ID Entra, który wprowadziłeś, nie pasuje do tenanta, którego admin nadał zgodę. Rozłącz i połącz ponownie z poprawnym tenant ID.
Częściowe synchronizacje. Jeśli synchronizacja kończy się statusem Częściowy, część upsertów się udała, a część nie — zwykle dlatego, że jeden rekord użytkownika złamał constraint unikalności (np. dwóch użytkowników Entra ma ten sam email). Status i liczniki pokazują częściowy postęp. Logi nie ujawniają adresów użytkowników. Niekompletny lub przerwany import użytkowników nie dezaktywuje brakujących kontaktów.
Harmonogram jest „Wyłączony”, a spodziewałem się Codziennie. Harmonogram domyślnie pokazuje ostatnio zapisaną wartość — nie ma platformowego defaultu. Nowe połączenia są tworzone z Wyłączony, żebyś mógł przejrzeć ustawienia zanim automatyzacja ruszy.
25.8 Odnośniki
Dział zatytułowany „25.8 Odnośniki”- Logowanie SSO Microsoft używające tej samej integracji: Rozdział 24 Logowanie przez Microsoft 365.
- Lista kontaktów, do której trafiają zaimportowane kontakty: Rozdział 5 Kontakty.
- Funkcja Grup odzwierciedlająca grupy Entra: Rozdział 6 Grupy.
- Autopiloty, które automatycznie włączają nowo zsynchronizowane kontakty przez flagę Auto-dołączaj nowych członków: Rozdział 23 Autopiloty.
- Webhooks mogące powiadamiać systemy zewnętrzne, gdy kontakty albo grupy się zmieniają: Rozdział 26 Webhooks.