Zarządzanie logowaniem jednokrotnym

2026-11-17

Logowanie jednokrotne (SSO) umożliwia użytkownikom logowanie do DJI FlightHub 2 przy użyciu kont firmowych. Firmowy dostawca tożsamości (IdP) uwierzytelnia użytkowników, a FlightHub 2 wykorzystuje zwrócone informacje o tożsamości i mapowania ról do utworzenia sesji logowania i przyznania odpowiednich uprawnień. Hasłami kont firmowych zarządza firmowy system tożsamości.

Ta funkcja jest dostępna w pakiecie Enterprise w chmurze publicznej oraz w wersji lokalnej. Ten przewodnik jest przeznaczony dla administratorów organizacji i administratorów firmowych systemów tożsamości. Obejmuje konfigurację źródeł tożsamości, zarządzanie autoryzacją, testowanie i włączanie oraz zarządzanie logowaniem do kont lokalnych.



Przegląd

Źródła tożsamości i proces logowania

Realm to niezależna konfiguracja źródła tożsamości SSO w FlightHub 2. Każdy Realm używa jednego protokołu i dopasowuje żądania logowania na podstawie domeny adresu e-mail. Odpowiednia aplikacja w firmowym IdP i Realm w FlightHub 2 muszą mieć zgodne protokoły, dane uwierzytelniające aplikacji, adresy URL wywołań zwrotnych i ustawienia przekazywania ról.

Gdy użytkownik rozpoczyna logowanie SSO w FlightHub 2, system wybiera włączone źródło tożsamości na podstawie domeny wprowadzonego adresu e-mail i przekierowuje użytkownika do firmowego IdP w celu uwierzytelnienia. Następnie FlightHub 2 weryfikuje zwrócone informacje o tożsamości i dopasowuje rolę zarządzania użytkownika. Użytkownicy muszą ponownie się uwierzytelnić, jeśli firmowa sesja logowania wygasła lub IdP wymaga ponownego uwierzytelnienia.

Domena adresu e-mail służy wyłącznie do wyboru źródła tożsamości. Nie jest unikalnym identyfikatorem użytkownika i nie przyznaje bezpośrednio uprawnień. Uprawnienia dostępu do projektu należy skonfigurować osobno po zalogowaniu przez SSO.


Wybór protokołu

FlightHub 2 obsługuje OIDC, SAML 2.0 i OAuth2.

PorównanieOIDCSAML 2.0OAuth2
Źródło informacji o tożsamościID TokenAsercja SAMLInformacje o użytkowniku w formacie JSON zwracane przez User URL
Metoda konfiguracjiDiscovery URLIdP Metadata URL lub plik Metadata XMLRęczna konfiguracja punktów końcowych autoryzacji, Token i informacji o użytkowniku
Ustawienie pobierania rólRole PathRole AttributeRole Path (UserInfo)
Unikalny identyfikator użytkownikaissuer + subIdP Entity ID + persistent NameIDRealm + value identified by USER_ID_KEY
Odpowiednie zastosowaniaFirmowe systemy tożsamości obsługujące OpenID ConnectFirmowe systemy tożsamości, które już używają SAMLSystemy udostępniające autoryzację OAuth2 i API informacji o użytkowniku

Uwaga:

  • OIDC jest zalecany, gdy firmowy IdP obsługuje wiele protokołów. Jeśli firma używa już SAML do integracji innych aplikacji, może nadal korzystać z SAML.
  • OAuth2 jest protokołem autoryzacji. Przed wybraniem OAuth2 ustal z administratorem IdP, które pola API informacji o użytkowniku udostępniają stabilny identyfikator użytkownika, nazwę konta i informacje o rolach.
  • Zarówno OIDC, jak i OAuth2 używają przepływu kodu autoryzacyjnego z weryfikacją PKCE. Różnią się sposobem pobierania informacji o tożsamości:
    • OIDC: Weryfikuje ID Token w celu ustalenia tożsamości użytkownika.
    • OAuth2: Używa Access Token do wywołania User URL oraz pobrania i przetworzenia informacji o użytkowniku. Nie korzysta z mechanizmów weryfikacji tożsamości OIDC: ID Token, Discovery ani JWKS.
  • SAML 2.0 obsługuje wyłącznie logowanie rozpoczynane w FlightHub 2 (SP-Initiated), a nie bezpośrednio w portalu aplikacji firmowego IdP.


Przygotowanie do konfiguracji

Przed użyciem SSO w wersji lokalnej należy włączyć HTTPS. Skonfiguruj HTTPS w środowisku wdrożenia i upewnij się, że FlightHub 2 jest dostępny przez HTTPS, zanim skonfigurujesz źródło tożsamości SSO.

Jako administrator organizacji otwórz Ustawienia logowania SSO dla organizacji, kliknij Utwórz Realm i wybierz protokół.

Ustawienia logowania SSO i przycisk Utwórz Realm

Przed konfiguracją przygotuj z administratorem firmowego IdP następujące informacje:

  • Protokół oraz Client ID, Client Secret lub Metadata odpowiedniej aplikacji.
  • Domenę adresu e-mail używaną do dopasowania źródła tożsamości i konto firmowe do logowania testowego.
  • Pole roli i wartości ról w firmowych informacjach o tożsamości oraz role zarządzania FlightHub 2, które mają zostać przypisane.
  • Punkty końcowe HTTPS IdP i ważne certyfikaty. Upewnij się, że backend FlightHub 2 ma dostęp do punktów końcowych i może zweryfikować ich certyfikaty.

Zasady konfiguracji:

  • W organizacji można jednocześnie włączyć maksymalnie 8 konfiguracji Realm. Niewłączone konfiguracje można zapisać jako wersje robocze lub zachować w stanie wyłączonym.
  • Nazwy Realm muszą być unikalne w obrębie organizacji. Nazwy wyświetlane służą do identyfikacji konfiguracji Realm w interfejsie administracyjnym.
  • Podczas tworzenia Realm pole Login routing email może zawierać pełny, prawidłowy adres e-mail lub samą domenę, na przykład user@example.com. System zapisuje domenę na potrzeby kierowania logowania. Tej samej domeny nie można przypisać do różnych konfiguracji Realm w organizacji.
  • Adresy URL dostępu do FlightHub 2 i punkty końcowe SSO muszą używać HTTPS. Zarejestruj w IdP informacje o wywołaniach zwrotnych wygenerowane przez system dokładnie w podanej postaci. Nie używaj adresu URL strony konfiguracji zamiast adresu URL wywołania zwrotnego.


Konfiguracja źródeł tożsamości

Każda strona konfiguracji Realm zawiera cztery karty: Konfiguracja podstawowa, Zarządzanie autoryzacją, Testowanie i włączanie oraz Konfiguracja zaawansowana. Najpierw uzupełnij konfigurację podstawową i zapisz wersję roboczą, a następnie skonfiguruj mapowania ról, przeprowadź testy i włącz Realm.

OIDC

Konfiguracja podstawowa

PoleInstrukcje konfiguracji
Realm name / Realm display nameWprowadź nazwę identyfikującą źródło tożsamości, na przykład Enterprise_OIDC
Login routing emailWprowadź pełny adres e-mail. Jego domena służy do wyboru źródła tożsamości
Discovery URLWprowadź pełny adres HTTPS Discovery URL podany przez IdP
Client IDWprowadź identyfikator aplikacji zarejestrowanej w IdP
Client SecretWprowadź sekret odpowiedniej aplikacji. Po zapisaniu wartość nie jest wyświetlana w postaci jawnej
Callback URLGenerowany po zapisaniu wersji roboczej. Zarejestruj go dokładnie w podanej postaci jako prawidłowy URI przekierowania w IdP
Web Origin URLGenerowany przez system. Zarejestruj go w Web Origins zgodnie z wymaganiami IdP

Po zapisaniu wersji roboczej skopiuj rzeczywiste informacje o wywołaniach zwrotnych dla wdrożenia i dokończ konfigurację aplikacji IdP. Przykładowe adresy URL w formularzu tworzenia nie mogą być używane do integracji. Zwykłe logowanie i Logowanie testowe mogą używać różnych adresów URL wywołań zwrotnych. Zarejestruj każdy adres URL zgodnie z wdrożeniem.

W sekcji Zarządzanie autoryzacją ustaw Role Path zgodnie z tablicą ról zwracaną przez IdP, na przykład roles lub claims.roles. Zasady mapowania ról opisano poniżej w sekcji Zarządzanie autoryzacją.

Konfiguracja zaawansowana

  • Unikalny identyfikator tożsamości: Stała wartość issuer + sub. Nie można zamiast niej użyć adresu e-mail.
  • Claim nazwy wyświetlanej użytkownika: Domyślnie name. Służy wyłącznie do wyświetlania i wyszukiwania, a nie do dopasowywania tożsamości ani przypisywania uprawnień.
  • Odświeżanie Discovery: Po początkowym pobraniu automatyczne odświeżanie jest domyślnie wyłączone. Użyj Odśwież teraz, aby ponownie pobrać konfigurację. Jeśli odświeżanie się nie powiedzie, zachowywana jest ostatnia prawidłowa konfiguracja. Ustawienia automatycznego odświeżania i jego interwału zależą od opcji dostępnych we wdrożeniu.
  • Zaawansowane opcje protokołu: Skonfiguruj Scope, który musi zawierać co najmniej openid. Authorization Endpoint, Token Endpoint i JWKS URI można nadpisać ręcznie.
  • Ręczne nadpisywanie: Odświeżanie Discovery nie nadpisuje pól ustawionych ręcznie. Kliknij Przywróć wartości automatyczne, aby przywrócić wykryte wartości. Ręczne nadpisywanie nie zastępuje pobierania i weryfikacji Discovery podczas zapisywania konfiguracji.

SAML 2.0

Konfiguracja podstawowa

  1. Wprowadź nazwę Realm, nazwę wyświetlaną i adres e-mail do kierowania logowania.
  2. Wybierz IdP Metadata URL lub Prześlij XML, aby zaimportować Metadata firmowego IdP. System przetwarza IdP Entity ID, SSO URL, certyfikat podpisywania i Binding.
  3. Zapisz wersję roboczą, aby uzyskać wygenerowane SP Metadata URL i ACS URL, lub pobierz SP Metadata XML.
  4. Przekaż SP Metadata FlightHub 2 administratorowi IdP w celu skonfigurowania odpowiedniej aplikacji SAML. Odczytaj SP Entity ID z rzeczywiście wygenerowanych SP Metadata; nie zakładaj, że jest taki sam jak Metadata URL.
  5. W sekcji Zarządzanie autoryzacją wprowadź nazwę atrybutu roli i skonfiguruj mapowania ról zarządzania.

W przypadku importu z adresu URL backend FlightHub 2 musi mieć dostęp do Metadata URL przez HTTPS. W przypadku przesyłania pliku użyj rzeczywistych Metadata XML wyeksportowanych przez firmowy IdP.

Ustaw Role Attribute na dokładną nazwę z <Attribute Name="..."> w asercji SAML. Domyślna wartość to roles, a wielkość liter w nazwie ma znaczenie. Wiele ról musi być zwracanych jako osobne elementy AttributeValue, a nie połączonych w jeden ciąg znaków. Na przykład:

<Attribute Name="roles">
  <AttributeValue>fh2-member-org</AttributeValue>
</Attribute>

Konfiguracja zaawansowana

  • Unikalny identyfikator tożsamości: Stała wartość IdP Entity ID + persistent NameID. Skonfiguruj IdP tak, aby używał trwałego NameID.
  • Atrybut nazwy wyświetlanej użytkownika: Domyślnie displayName. IdP musi przekazywać ten atrybut.
  • Aktualizacje Metadata: Po początkowym pobraniu automatyczne odświeżanie jest domyślnie wyłączone. W przypadku importu z adresu URL użyj opcji odświeżania dostępnej na stronie. W przypadku przesyłania XML prześlij ponownie zaktualizowany plik. Ustawienia automatycznego odświeżania i jego interwału zależą od opcji dostępnych we wdrożeniu.
  • Zaawansowane opcje protokołu: Ręcznie nadpisz IdP Entity ID, SSO URL, Binding i certyfikat podpisywania lub przywróć wartości automatyczne. Odświeżanie Metadata nie nadpisuje pól ustawionych ręcznie.
  • Zarządzanie certyfikatami: W miarę możliwości importuj i aktualizuj certyfikaty podpisywania za pomocą Metadata. Odcisk certyfikatu służy do weryfikacji certyfikatu i nie może zastąpić zawartości certyfikatu X.509.

OAuth2

Konfiguracja podstawowa

OAuth2 nie używa Discovery. Skonfiguruj punkty końcowe i ścieżki pól informacji o użytkowniku zgodnie z dokumentacją API IdP.

PoleInstrukcje konfiguracji
Realm name / Realm display nameWprowadź nazwę źródła tożsamości, na przykład Enterprise_OAuth2
Login routing emailWprowadź pełny adres e-mail. Jego domena służy do wyboru źródła tożsamości
Authorization URLAdres URL autoryzacji użytkownika podany przez IdP
Token URLAdres URL wymiany kodu autoryzacyjnego podany przez IdP
User URLAdres URL API służącego do pobierania tożsamości i ról użytkownika w formacie JSON przy użyciu Access Token
Client ID / Client SecretIdentyfikator i sekret odpowiedniej aplikacji IdP
USER_ID_KEYŚcieżka pola stabilnego identyfikatora użytkownika w odpowiedzi z informacjami o użytkowniku, na przykład id lub data.id
USER_ACCOUNT_KEYŚcieżka pola nazwy konta w odpowiedzi z informacjami o użytkowniku, na przykład username lub data.username
ScopesSkonfiguruj zgodnie z wymaganiami dotyczącymi uprawnień API informacji o użytkowniku IdP
Callback URLGenerowany po zapisaniu wersji roboczej. Zarejestruj go w IdP dokładnie w podanej postaci

W sekcji Zarządzanie autoryzacją Role Path (UserInfo) musi wskazywać tablicę ról w postaci ciągów znaków w odpowiedzi User URL, na przykład roles lub data.roles. FlightHub 2 nie pobiera ról OAuth2 z Access Token w formacie JWT ani z osobnego API uprawnień.

Jeśli na przykład User URL zwraca poniższą strukturę, ustaw USER_ID_KEY na id, USER_ACCOUNT_KEY na username, a Role Path na roles:

{
  "id": "user-001",
  "username": "sso-user",
  "roles": ["fh2-member-org"]
}

Te pola są jedynie przykładami. Rzeczywiste ścieżki pól muszą odpowiadać odpowiedzi IdP. Scopes nie określają ról i nie ma ogólnego wymogu uwzględniania openid; należy przestrzegać wymagań API IdP. Nawet jeśli USER_ID_KEY ma wartość sub lub Scopes zawiera openid, ten Realm nadal przetwarza tożsamość i role za pomocą API informacji o użytkowniku OAuth2.

Konfiguracja zaawansowana

Konfiguracja zaawansowana wyświetla regułę stabilnej tożsamości powiązaną z USER_ID_KEY i ścieżkę pola nazwy wyświetlanej użytkownika. Informacje do wyświetlania korzystają z USER_ACCOUNT_KEY; druga ścieżka pola nie jest wymagana.

OAuth2 nie udostępnia Discovery ani importu lub odświeżania Metadata. Po zmianie punktów końcowych aktualizuj je ręcznie. Nowe konfiguracje Realm nie udostępniają starszych opcji zgodności USE_REDIRECT_URL ani SUPER_ACCOUNT. Mechanizmy zgodności uprawnień dla migrowanych konfiguracji nie mają zastosowania do nowych konfiguracji Realm.



Zarządzanie autoryzacją

Pobieranie ról i mapowanie ról zarządzania

W sekcji Zarządzanie autoryzacją skonfiguruj miejsce pobierania ról i zmapuj zewnętrzne wartości Role zwracane przez IdP na role zarządzania FlightHub 2.

Ustawienia pobierania ról i mapowania ról zarządzania

ProtokółUstawienieWymagania
OIDCRole PathWskazuje tablicę ról w postaci ciągów znaków w informacjach o tożsamości, na przykład roles
SAML 2.0Role AttributeOdpowiada Attribute Name w asercji, na przykład roles. Dla wielu ról użyj osobnych elementów AttributeValue
OAuth2Role Path (UserInfo)Wskazuje tablicę ról w postaci ciągów znaków w odpowiedzi User URL, na przykład data.roles

Poniżej wymieniono role zarządzania i ich domyślne mapowania. Skonfiguruj jedną zewnętrzną wartość Role dla każdej roli zarządzania.

Rola zarządzania FlightHub 2Domyślna zewnętrzna wartość RolePriorytet
Administrator organizacjifh2-admin-org1 (najwyższy)
Opiekun urządzeńfh2-admin-device2
Członekfh2-member-org3
  • Aby zalogować się przez nowo utworzony Realm SSO, użytkownik musi zostać dopasowany do co najmniej jednej roli zarządzania.
  • Jeśli dopasowanych zostanie wiele ról zarządzania, używana jest rola o najwyższym priorytecie. Nierozpoznane wartości Role są ignorowane.
  • Zewnętrznych użytkowników SSO nie można mapować na rolę super administratora.
  • Autoryzacja opiera się obecnie na Roles, a nie bezpośrednio na Groups, Security Groups ani innych atrybutach. Jeśli firma zarządza użytkownikami za pomocą grup, skonfiguruj IdP tak, aby przekształcał przynależność do grup w uzgodnioną listę ról.

Uprawnienia do projektów

Role zarządzania SSO i uprawnienia do projektów są niezależne. Po pomyślnym zalogowaniu administrator nadal musi dodać użytkowników SSO w sekcji zarządzania członkami projektu, przypisać role w projekcie i dopasować użytkowników za pomocą stabilnego unikalnego identyfikatora dla odpowiedniego Realm. Informacje o konfiguracji ról w projekcie znajdziesz w dokumencie Zarządzanie rolami użytkowników projektu.



Testowanie i włączanie

Procedura testowania

  1. Uzupełnij sekcje Konfiguracja podstawowa i Zarządzanie autoryzacją, a następnie kliknij Zapisz wersję roboczą.
  2. Otwórz Testowanie i włączanie i uruchom Test łączności, aby sprawdzić wymagane pola, HTTPS, punkty końcowe protokołu oraz odpowiednią konfigurację Discovery, Metadata lub certyfikatów.
  3. Uruchom Logowanie testowe, uwierzytelnij się przy użyciu konta testowego na otwartej stronie IdP i wróć do pierwotnej strony konfiguracji.
  4. Sprawdź zwrócony stabilny identyfikator, nazwę wyświetlaną, adres e-mail, listę Role i rolę zarządzania. Upewnij się, że pobieranie i mapowanie ról działa zgodnie z oczekiwaniami.
  5. Po pomyślnym przejściu testów kliknij Zapisz i zastosuj i upewnij się, że źródło tożsamości jest włączone.
Test łączności i Logowanie testowe zakończone pomyślnie

Test łączności weryfikuje wyłącznie konfigurację i punkty końcowe. Nie zastępuje rzeczywistego testu logowania użytkownika. OIDC wymaga pomyślnego testu łączności przed włączeniem. Jeśli Logowanie testowe nie zakończyło się pomyślnie, włączenie Realm po zaakceptowaniu ryzyka zgodnie z komunikatem na stronie nie oznacza pomyślnej weryfikacji logowania. Zaleca się pomyślne ukończenie obu testów przed włączeniem. SAML 2.0 należy włączyć po pomyślnym przejściu obu testów. Nowo utworzone konfiguracje Realm OAuth2 wymagają pomyślnego przejścia obu testów; dostępny przycisk lub ogólny komunikat potwierdzenia nie oznacza, że testy zakończyły się pomyślnie.

Jeśli pobieranie Discovery, import Metadata lub wymiana Token się nie powiedzie, sprawdź sieć backendu FlightHub 2, zaufanie do certyfikatów TLS, dane uwierzytelniające aplikacji, adresy URL wywołań zwrotnych i parametry protokołu. Popraw konfigurację, a następnie zapisz ją i ponownie przeprowadź testy.


Utrzymanie źródeł tożsamości

Lista umożliwia edytowanie lub kontynuowanie konfiguracji, testowanie, włączanie, wyłączanie i usuwanie źródeł tożsamości. Dla poszczególnych stanów postępuj następująco:

StanDziałanie
Wersja roboczaUzupełnij konfigurację, zapisz ją i przeprowadź testy
Wymagany ponowny testSprawdź zmiany kluczowych ustawień i ponownie przeprowadź testy
Test nie powiódł sięSprawdź wyniki nieudanego testu, popraw konfigurację IdP lub FlightHub 2 i ponownie przeprowadź testy
Gotowy do włączeniaPotwierdź wyniki testów i włącz Realm zgodnie z warunkami wyświetlonymi na stronie
WłączonyDostępny do logowania. Po zmianie kluczowych ustawień ponownie przeprowadź testy zgodnie z komunikatami
WyłączonyKonfiguracja jest zachowana, ale niedostępna do zwykłego logowania

Po aktualizacji punktów końcowych IdP, certyfikatów lub ustawień przekazywania ról odpowiednio zaktualizuj Realm i ponownie przeprowadź testy. Pola nadpisane ręcznie nie są aktualizowane automatycznie pobranymi wartościami i należy je sprawdzić osobno.



Zarządzanie logowaniem do kont lokalnych

Przełącznik Zezwalaj na logowanie hasłem do kont lokalnych na stronie Ustawienia logowania SSO określa, czy zwykłe konta lokalne mogą logować się przy użyciu hasła. Gdy jest wyłączony, zwykłe konta lokalne nie mogą korzystać z logowania hasłem, a członkowie muszą logować się przez źródło tożsamości SSO, które jest włączone i pomyślnie przeszło testy.

Aby wyłączyć logowanie hasłem do kont lokalnych:

  1. Skonfiguruj, przetestuj i włącz co najmniej jeden Realm oraz upewnij się, że konta firmowe mogą się pomyślnie logować.
  2. Upewnij się, że konto awaryjnego super administratora i jego lokalne hasło działają.
  3. Wyłącz Zezwalaj na logowanie hasłem do kont lokalnych i wybierz Wyznacz awaryjnego super administratora w oknie dialogowym.
  4. Zapoznaj się ze skutkami, zaznacz pole potwierdzenia i kliknij Potwierdź wyłączenie.
Wyznaczanie awaryjnego super administratora podczas wyłączania logowania do kont lokalnych

Jeśli firmowy IdP jest niedostępny lub konfiguracja SSO jest nieprawidłowa, wyznaczony awaryjny super administrator może uzyskać dostęp do systemu przy użyciu lokalnego hasła, aby ponownie włączyć logowanie do kont lokalnych lub poprawić konfigurację SSO. Zwykły administrator organizacji nie jest awaryjnym super administratorem, a sama nazwa konta nie określa, czy logowanie awaryjne jest dostępne.



Przykład integracji z Keycloak

Poniższe przykłady opisują konfigurację poszczególnych protokołów w Keycloak. Zastąp przykładowe domeny, nazwy Realm, identyfikatory Client ID i ścieżki pól wartościami dla wdrożenia. Użyj adresów URL wywołań zwrotnych i informacji SP Metadata wygenerowanych przez FlightHub 2. Położenie opcji menu może się różnić między wersjami Keycloak.

Zrzuty ekranu pokazują miejsca konfiguracji i kluczowe opcje. Widoczne na nich nazwy Realm, Client i użytkowników testowych są przykładami. W rzeczywistej konfiguracji użyj informacji o źródle tożsamości, aplikacji i użytkownikach swojej firmy.


Tworzenie firmowego źródła tożsamości, ról i użytkowników testowych

  1. Zaloguj się do konsoli administracyjnej Keycloak i utwórz lub wybierz firmowy Realm w sekcji Manage realms, na przykład Enterprise.

    Tworzenie Realm w Keycloak, wprowadzanie jego nazwy i włączanie
  2. W sekcji Realm roles utwórz fh2-admin-org, fh2-admin-device i fh2-member-org lub wartości ról odpowiadające mapowaniom FlightHub 2.

    Lista ról Realm w Keycloak i przycisk tworzenia roli
  3. W sekcji Users utwórz i włącz użytkownika testowego. Ustaw hasło w sekcji Credentials i wykonaj wszystkie wymagane działania na koncie.

  4. Przypisz rolę testową na karcie Role mapping użytkownika. Na potrzeby pierwszego testu przypisz tylko jedną rolę zarządzania, na przykład fh2-member-org, aby ułatwić weryfikację wyników.

    Przypisywanie roli członka użytkownikowi testowemu w Keycloak

Firmowy Realm w Keycloak i Realm w FlightHub 2 to odrębne jednostki konfiguracji i nie muszą mieć tej samej nazwy. Podczas integracji wielu protokołów skonfiguruj osobny Client dla każdego protokołu i użyj różnych domen do kierowania logowania.


Integracja OIDC

  1. Utwórz Client OpenID Connect w Keycloak, na przykład Enterprise_OIDC.

  2. Włącz Client authentication i Standard flow oraz wyłącz Implicit flow. Direct access grants nie są wymagane do SSO w przeglądarce. Włącz Require PKCE i ustaw PKCE Method na S256. Te ustawienia znajdziesz w Settings → Capability config.

    Przepływ uwierzytelniania klienta i ustawienia PKCE S256 w Keycloak
  3. Utwórz Realm OIDC w FlightHub 2 i wprowadź adres e-mail do kierowania logowania, Client ID, Client Secret i Discovery URL. Discovery URL w Keycloak ma następujący format:

    https://idp.example.com/realms/Enterprise/.well-known/openid-configuration
    
  4. Zapisz wersję roboczą w FlightHub 2, aby uzyskać rzeczywiste informacje o wywołaniach zwrotnych. Zarejestruj adresy URL wywołań zwrotnych zwykłego i testowego logowania w Valid redirect URIs w Client Keycloak i skonfiguruj Web origins na podstawie informacji wygenerowanych przez FlightHub 2. Pobierz Client Secret z karty Credentials danego Client.

  5. Dodaj User Realm Role Mapper w Client scopes → dedykowany zakres danego Client → Mappers:

    Otwórz Client scopes, wybierz dedykowany zakres bieżącego Client i otwórz konfigurację mappera.

    Pozycja dedykowanego zakresu w sekcji Client scopes w Keycloak
    UstawieniePrzykładowa wartość
    Namesikong-roles
    Token Claim Nameroles
    Claim JSON TypeString
    MultivaluedWłączone
    Add to ID token / Add to access token / Add to userinfoWłączone
    User Realm Role Mapper w Keycloak przekazujący wiele wartości ról w tokenach i informacjach o użytkowniku
  6. W FlightHub 2 ustaw Role Path na roles, skonfiguruj mapowania ról zarządzania i uruchom Test łączności oraz Logowanie testowe. Zweryfikuj role, a następnie zapisz i zastosuj konfigurację.


Integracja SAML 2.0

  1. Pobierz IdP Metadata z Keycloak przy użyciu adresu URL w poniższym formacie. Metadata XML zwracane przez ten adres URL można również wykorzystać do przesłania pliku.

    https://idp.example.com/realms/Enterprise/protocol/saml/descriptor
    
  2. Utwórz Realm SAML 2.0 w FlightHub 2, zaimportuj IdP Metadata, zapisz wersję roboczą i pobierz wygenerowane SP Metadata XML.

  3. W Keycloak zaimportuj SP Metadata w Clients → Import client lub ręcznie utwórz Client SAML i zweryfikuj następujące pola:

    UstawieniePrzykładowa wartość
    Client IDEntity ID z SP Metadata FlightHub 2
    NameNazwa identyfikująca aplikację, na przykład Enterprise_SAML
    Valid redirect URIsACS URL FlightHub 2
    Name ID formatpersistent
    Force name ID formatWłączone
    Force POST bindingWłączone, aby zwracać odpowiedź SAML przy użyciu POST
    Sign documents / Sign assertionsWłączone
    Signature algorithmRSA_SHA256
    Client signature requiredWłączone. Zaimportuj certyfikat podpisywania SP z SP Metadata FlightHub 2
    IDP-Initiated SSO URL namePozostaw puste. Rozpocznij logowanie w FlightHub 2

    Poniższy zrzut ekranu pokazuje, gdzie skonfigurować trwały NameID i POST Binding. Zweryfikuj ustawienia podpisów i certyfikatów na podstawie powyższej tabeli.

    Ustawienia trwałego NameID i POST Binding dla SAML w Keycloak
  4. Skonfiguruj mappery ról i informacji o użytkowniku w dedykowanym zakresie Client SAML:

    Typ mapperaKluczowe ustawienia
    Role listName i Role attribute name: roles; NameFormat: Basic; Single Role Attribute: Włączone
    User PropertyUser property: username; Attribute name: displayName
    User PropertyUser property: email; Attribute name: email
    Mapper Role list dla SAML w Keycloak z atrybutem roles i włączoną opcją Single Role Attribute
  5. Sprawdź domyślny zakres role_list danego Client i niestandardowy mapper ról, aby uniknąć zduplikowanych lub sprzecznych danych ról. Jeśli używasz powyższego niestandardowego mappera roles, usuń z tego Client wszelkie sprzeczne przypisania domyślnego zakresu.

  6. W FlightHub 2 ustaw Role Attribute na roles, a atrybut nazwy wyświetlanej użytkownika na displayName, a następnie skonfiguruj mapowania ról zarządzania. Zapisz i zastosuj konfigurację po pomyślnym przejściu obu testów.

Client ID musi zawierać rzeczywisty SP Entity ID, a nie nazwę wyświetlaną aplikacji. AuthnRequest FlightHub 2 może używać Redirect Binding, podczas gdy odpowiedź IdP używa POST Binding; te mechanizmy mają różne zastosowania. Po ponownym utworzeniu Realm SAML w FlightHub 2 pobierz nowe SP Metadata oraz zweryfikuj i zaktualizuj ustawienia Entity ID, ACS i certyfikatów w IdP.


Integracja OAuth2

Keycloak udostępnia punkty końcowe OAuth2 za pośrednictwem Client OpenID Connect. Po stronie FlightHub 2 wybierz protokół OAuth2.

  1. Utwórz osobny Client w Keycloak, na przykład Enterprise_OAuth2. Zgodnie z powyższym przykładem OIDC skonfiguruj Client authentication, Standard flow, PKCE i adresy URL wywołań zwrotnych zwykłego i testowego logowania oraz pobierz Secret właściwy dla tego Client.

  2. Dodaj User Realm Role Mapper w dedykowanym zakresie danego Client. Ustaw Token Claim Name na roles, włącz Multivalued i upewnij się, że Add to userinfo jest włączone.

  3. Utwórz Realm OAuth2 w FlightHub 2 i wprowadź dane uwierzytelniające odpowiedniej aplikacji, adres e-mail do kierowania logowania i następujące ustawienia:

    Pole FlightHub 2Przykład Keycloak
    Authorization URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/auth
    Token URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/token
    User URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/userinfo
    USER_ID_KEYsub
    USER_ACCOUNT_KEYpreferred_username
    Scopesopenid profile email, dla API informacji o użytkowniku Keycloak w tym przykładzie
    Role Path (UserInfo)roles
  4. Zapisz wersję roboczą i skonfiguruj mapowania ról zarządzania. Zapisz i zastosuj konfigurację dopiero wtedy, gdy Test łączności i Logowanie testowe zakończą się pomyślnie, a informacje o użytkowniku i rola zarządzania będą zgodne z oczekiwanymi wynikami.

Przykładowe Scopes i pola użytkownika dotyczą opisanej powyżej konfiguracji Keycloak. Podczas integracji z innym IdP dostosuj je zgodnie z dokumentacją API.



Często zadawane pytania

Dlaczego użytkownicy nie mogą się zalogować, mimo że test łączności zakończył się pomyślnie?

Test łączności sprawdza konfigurację i punkty końcowe. Logowanie testowe weryfikuje rzeczywiste informacje o tożsamości, pobieranie ról i mapowania ról zarządzania. Uruchom Logowanie testowe i sprawdź stabilny identyfikator użytkownika, pola ról, wyniki mapowania, adresy URL wywołań zwrotnych i wyniki weryfikacji podpisów.

Jak rozwiązać problem niezgodności adresu URL wywołania zwrotnego?

Porównaj redirect_uri w rzeczywistym żądaniu z adresem URL wywołania zwrotnego zarejestrowanym dla odpowiedniej aplikacji IdP. Muszą być identyczne, łącznie z protokołem, domeną, portem i ścieżką. Zarejestruj wywołania zwrotne zwykłego i testowego logowania zgodnie z wdrożeniem. Nie używaj adresu URL strony konfiguracji frontendu ani przykładowych wartości z niezapisanego formularza.

Czy adres e-mail do kierowania logowania musi być zgodny z adresem e-mail użytkownika w IdP?

Adres e-mail do kierowania logowania służy do wyboru źródła tożsamości, natomiast adres e-mail użytkownika w IdP jest częścią jego profilu. Mają one różne zastosowania. Przestrzegaj wymagań konfiguracji IdP dotyczących kont i adresów e-mail. Domena do kierowania logowania musi spełniać wymagania formatu adresu e-mail i nie może zawierać podkreśleń. Podczas tworzenia Realm wprowadź pełny adres e-mail.

Dlaczego FlightHub 2 nie może pobrać ról zwracanych przez IdP?

W przypadku OIDC sprawdź Role Path względem struktury tablicy w informacjach o tożsamości. W przypadku OAuth2 sprawdź tablicę ról zwracaną przez User URL. W przypadku SAML sprawdź wielkość liter w Attribute Name i upewnij się, że wiele ról korzysta z osobnych elementów AttributeValue. Sprawdź też, czy nie ma konfliktów między domyślnymi i niestandardowymi mapperami IdP, oraz upewnij się, że zwracane wartości Role odpowiadają mapowaniom ról zarządzania.

Dlaczego po pomyślnym zalogowaniu nie widać żadnych projektów?

Role zarządzania SSO nie przyznają automatycznie uprawnień do projektów. Administrator musi dodać użytkownika w sekcji zarządzania członkami projektu, przypisać rolę w projekcie i dopasować użytkownika za pomocą stabilnego unikalnego identyfikatora dla jego Realm.

Czy adres e-mail może być używany jako unikalny identyfikator użytkownika?

Nie. Adresy e-mail mogą się zmieniać lub być ponownie wykorzystywane. OIDC używa issuer + sub, SAML używa IdP Entity ID + persistent NameID, a OAuth2 używa Realm + stable user ID. Nazwy wyświetlane i nazwy kont również nie zastępują stabilnego unikalnego identyfikatora.

Jak rozwiązać problemy z pobieraniem Discovery lub Metadata?

Sprawdź, czy adres URL jest prawidłowy, czy backend FlightHub 2 ma do niego dostęp przez HTTPS i czy ufa certyfikatowi IdP. Dostęp przez przeglądarkę lub zaakceptowanie w niej certyfikatu nie oznacza, że backend FlightHub 2 ma taki dostęp lub ufa temu certyfikatowi. W przypadku SAML można również przesłać rzeczywiste Metadata XML wyeksportowane przez IdP. Po rozwiązaniu problemu zapisz konfigurację i ponownie przeprowadź testy.

Jak rozwiązać problem nieudanej wymiany tokenu po uwierzytelnieniu w IdP?

Sprawdź połączenie sieciowe i zaufanie do certyfikatów TLS między backendem FlightHub 2 a Token URL. Zweryfikuj odpowiednie Client ID, Client Secret, rzeczywisty adres URL wywołania zwrotnego i parametry PKCE. Po rozwiązaniu problemu ponownie przeprowadź testy i upewnij się, że informacje o użytkowniku i role zarządzania są pomyślnie pobierane.

Jak zaktualizować certyfikaty lub punkty końcowe?

W przypadku OIDC odśwież Discovery. W przypadku importu SAML z adresu URL odśwież Metadata; w przypadku przesyłania XML prześlij ponownie zaktualizowany plik. Sprawdź pola nadpisane ręcznie i w razie potrzeby zaktualizuj je lub przywróć wartości automatyczne. W przypadku OAuth2 zaktualizuj punkty końcowe ręcznie. Po wprowadzeniu zmian ponownie przeprowadź testy.

Czy wylogowanie z FlightHub 2 powoduje również wylogowanie użytkownika z firmowego IdP?

Wylogowanie kończy tylko sesję FlightHub 2. Nie wylogowuje użytkownika z firmowego IdP. Przy kolejnym logowaniu firmowa sesja może nadal być aktywna, a Logowanie testowe może wymagać ponownego uwierzytelnienia.

Jak przywrócić dostęp, jeśli IdP ulegnie awarii po wyłączeniu logowania lokalnym hasłem?

Awaryjny super administrator wyznaczony podczas wyłączania logowania do kont lokalnych może użyć lokalnego hasła, aby uzyskać dostęp do systemu, ponownie włączyć logowanie do kont lokalnych lub poprawić konfigurację SSO. Przed wyłączeniem logowania do kont lokalnych upewnij się, że to konto i hasło działają.

Co sprawdzić, jeśli nie można włączyć źródła tożsamości?

Sprawdź, czy wersja robocza została zapisana, wymagane pola są prawidłowe, wymagane jest ponowne testowanie lub osiągnięto limit 8 włączonych konfiguracji Realm. W przypadku nowo utworzonego Realm OAuth2 upewnij się również, że oba testy zakończyły się pomyślnie.

Last Updated: