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.Directory.Read.All— odczyt członkostwa w grupach.openid/profile/email— potrzebne dla przepływu logowania SSO.
- 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.
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 wyłączeniem gości i kont wyłączonych) 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 |
Typowa tabela aktywności dla małej organizacji wygląda tak (rzeczywisty przykład z działającego setupu):
| 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 |
Nieudane przebiegi rozwijają się, pokazując komunikat błędu Microsoft Graph — większość to przejściowe odpowiedzi rate-limit (HTTP 429), które kolejny zaplanowany przebieg czysto absorbuje.
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 (goście i konta wyłączone są pomijane). 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). Sprawdź wpis w logu aktywności; komunikat błędu zawiera dotknięte adresy.
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.