Single-Sign-On-Verwaltung

2026-11-17

Single Sign-On (SSO) ermöglicht Benutzern, sich mit ihren Unternehmenskonten bei DJI FlightHub 2 anzumelden. Der Identitätsanbieter (IdP) des Unternehmens authentifiziert die Benutzer. FlightHub 2 verwendet die zurückgegebenen Identitätsinformationen und Rollenzuordnungen, um eine Anmeldesitzung einzurichten und die entsprechenden Berechtigungen zu erteilen. Die Passwörter der Unternehmenskonten werden vom Identitätssystem des Unternehmens verwaltet.

Diese Funktion ist für das Enterprise-Paket der Public Cloud und die On-Premises-Version verfügbar. Diese Anleitung richtet sich an Organisationsadministratoren und Administratoren des Identitätssystems des Unternehmens. Sie behandelt die Konfiguration von Identitätsquellen, die Berechtigungsverwaltung, das Testen und Aktivieren sowie die Verwaltung der Anmeldung mit lokalen Konten.



Übersicht

Identitätsquellen und Anmeldeablauf

Ein Realm ist eine eigenständige Konfiguration einer SSO-Identitätsquelle in FlightHub 2. Jeder Realm verwendet ein Protokoll und ordnet Anmeldeanfragen anhand der E-Mail-Domain zu. Die entsprechende Anwendung im IdP des Unternehmens und der FlightHub 2-Realm müssen übereinstimmende Protokolle, Anwendungszugangsdaten, Callback-URLs und Einstellungen zur Rollenausgabe verwenden.

Wenn ein Benutzer die SSO-Anmeldung in FlightHub 2 startet, wählt das System anhand der Domain der eingegebenen E-Mail-Adresse eine aktivierte Identitätsquelle aus und leitet den Benutzer zur Authentifizierung an den IdP des Unternehmens weiter. FlightHub 2 validiert anschließend die zurückgegebenen Identitätsinformationen und ordnet die Verwaltungsrolle des Benutzers zu. Benutzer müssen sich erneut authentifizieren, wenn die Anmeldesitzung des Unternehmens abgelaufen ist oder der IdP eine erneute Authentifizierung verlangt.

Die E-Mail-Domain dient ausschließlich zur Auswahl einer Identitätsquelle. Sie ist keine eindeutige Benutzerkennung und erteilt nicht unmittelbar Berechtigungen. Projektzugriffsberechtigungen müssen nach der SSO-Anmeldung separat konfiguriert werden.


Auswahl eines Protokolls

FlightHub 2 unterstützt OIDC, SAML 2.0 und OAuth2.

VergleichOIDCSAML 2.0OAuth2
Quelle der IdentitätsinformationenID TokenSAML AssertionVon User URL zurückgegebene Benutzerinformationen im JSON-Format
KonfigurationsmethodeDiscovery URLIdP Metadata URL oder Metadata-XML-DateiEndpunkte für Autorisierung, Token und Benutzerinformationen manuell konfigurieren
Einstellung zum RollenabrufRole PathRole AttributeRole Path (UserInfo)
Eindeutige Benutzerkennungissuer + subIdP Entity ID + persistent NameIDRealm + value identified by USER_ID_KEY
Geeignete AnwendungsfälleIdentitätssysteme von Unternehmen, die OpenID Connect unterstützenIdentitätssysteme von Unternehmen, die bereits SAML verwendenSysteme, die OAuth2-Autorisierung und eine API für Benutzerinformationen bereitstellen

Hinweis:

  • OIDC wird empfohlen, wenn der IdP des Unternehmens mehrere Protokolle unterstützt. Wenn das Unternehmen bereits SAML zur Integration anderer Anwendungen verwendet, kann es SAML weiterhin nutzen.
  • OAuth2 ist ein Autorisierungsprotokoll. Klären Sie vor der Auswahl von OAuth2 mit dem IdP-Administrator, welche Felder der API für Benutzerinformationen die stabile Benutzer-ID, den Kontonamen und die Rolleninformationen bereitstellen.
  • OIDC und OAuth2 verwenden beide den Authorization Code Flow mit PKCE-Validierung. Sie rufen Identitätsinformationen auf unterschiedliche Weise ab:
    • OIDC: Überprüft den ID Token, um die Identität des Benutzers festzustellen.
    • OAuth2: Verwendet einen Access Token, um User URL aufzurufen und Benutzerinformationen abzurufen und zu parsen. Die OIDC-Mechanismen zur Identitätsvalidierung über ID Token, Discovery oder JWKS werden dabei nicht verwendet.
  • SAML 2.0 unterstützt nur die in FlightHub 2 gestartete Anmeldung (SP-Initiated), nicht die direkt im Anwendungsportal des IdP des Unternehmens gestartete Anmeldung.


Vorbereitung der Konfiguration

HTTPS muss aktiviert sein, bevor SSO in der On-Premises-Version verwendet werden kann. Konfigurieren Sie HTTPS in der Bereitstellungsumgebung und stellen Sie sicher, dass FlightHub 2 über HTTPS erreichbar ist, bevor Sie eine SSO-Identitätsquelle konfigurieren.

Öffnen Sie als Organisationsadministrator die SSO-Anmelde-Einstellungen der Organisation, klicken Sie auf Realm erstellen und wählen Sie ein Protokoll aus.

SSO-Anmelde-Einstellungen und die Schaltfläche Realm erstellen

Bereiten Sie vor der Konfiguration gemeinsam mit dem IdP-Administrator des Unternehmens die folgenden Informationen vor:

  • Das Protokoll und die Client ID, das Client Secret oder die Metadata der entsprechenden Anwendung.
  • Die E-Mail-Domain zur Zuordnung der Identitätsquelle und ein Unternehmenskonto für die Testanmeldung.
  • Das Rollenfeld und die Rollenwerte in den Identitätsinformationen des Unternehmens sowie die zuzuweisenden FlightHub 2-Verwaltungsrollen.
  • Die HTTPS-Endpunkte und gültigen Zertifikate des IdP. Stellen Sie sicher, dass das FlightHub 2-Backend die Endpunkte erreichen und deren Zertifikate validieren kann.

Konfigurationsregeln:

  • In einer Organisation können gleichzeitig höchstens 8 Realms aktiviert sein. Nicht aktivierte Konfigurationen können als Entwürfe gespeichert oder im deaktivierten Zustand beibehalten werden.
  • Realm-Namen müssen innerhalb der Organisation eindeutig sein. Anzeigenamen kennzeichnen die Realms in der Verwaltungsoberfläche.
  • Beim Erstellen eines Realm kann E-Mail für Anmelderouting eine vollständige, gültige E-Mail-Adresse oder nur eine Domain enthalten, zum Beispiel user@example.com. Das System speichert die Domain für das Anmelderouting. Dieselbe Domain kann innerhalb einer Organisation nicht verschiedenen Realms zugewiesen werden.
  • Die Zugriffs-URLs von FlightHub 2 und die SSO-Endpunkte müssen HTTPS verwenden. Registrieren Sie die vom System generierten Callback-Informationen exakt wie angegeben im IdP. Verwenden Sie die URL der Konfigurationsseite nicht anstelle einer Callback-URL.


Konfiguration von Identitätsquellen

Jede Realm-Konfigurationsseite hat vier Registerkarten: Basiskonfiguration, Berechtigungsverwaltung, Testen und Aktivieren sowie Erweiterte Konfiguration. Schließen Sie zunächst die Basiskonfiguration ab und speichern Sie einen Entwurf. Konfigurieren Sie anschließend die Rollenzuordnungen, führen Sie die Tests aus und aktivieren Sie den Realm.

OIDC

Basiskonfiguration

FeldKonfigurationshinweise
Realm-Name / Realm-AnzeigenameGeben Sie einen Namen zur Kennzeichnung der Identitätsquelle ein, zum Beispiel Enterprise_OIDC
E-Mail für AnmelderoutingGeben Sie eine vollständige E-Mail-Adresse ein. Ihre Domain dient zur Auswahl der Identitätsquelle
Discovery URLGeben Sie die vollständige, vom IdP bereitgestellte HTTPS-Discovery-URL ein
Client IDGeben Sie die im IdP registrierte Anwendungskennung ein
Client SecretGeben Sie das Secret der entsprechenden Anwendung ein. Nach dem Speichern wird der Klartextwert nicht angezeigt
Callback URLWird nach dem Speichern des Entwurfs generiert. Registrieren Sie sie exakt wie angegeben als gültige Weiterleitungs-URI im IdP
Web Origin URLWird vom System generiert. Registrieren Sie sie gemäß den Anforderungen des IdP unter Web Origins

Kopieren Sie nach dem Speichern des Entwurfs die tatsächlichen Callback-Informationen der Bereitstellung und schließen Sie die Konfiguration der IdP-Anwendung ab. Platzhalter-URLs im Erstellungsformular können nicht für die Integration verwendet werden. Die reguläre Anmeldung und die Testanmeldung können unterschiedliche Callback-URLs verwenden. Registrieren Sie jede URL entsprechend der Bereitstellung.

Legen Sie in der Berechtigungsverwaltung Role Path entsprechend dem vom IdP zurückgegebenen Rollenarray fest, zum Beispiel roles oder claims.roles. Die Regeln zur Rollenzuordnung finden Sie weiter unten unter Berechtigungsverwaltung.

Erweiterte Konfiguration

  • Eindeutige Identitätskennung: Fest auf issuer + sub eingestellt. Eine E-Mail-Adresse kann nicht stattdessen verwendet werden.
  • Claim für den Benutzeranzeigenamen: Standardwert ist name. Dient nur zur Anzeige und Suche, nicht zum Identitätsabgleich oder zur Berechtigungszuweisung.
  • Discovery-Aktualisierung: Nach dem ersten Abruf ist die automatische Aktualisierung standardmäßig deaktiviert. Verwenden Sie Jetzt aktualisieren, um die Konfiguration erneut abzurufen. Wenn die Aktualisierung fehlschlägt, bleibt die letzte gültige Konfiguration erhalten. Die Einstellungen für automatische Aktualisierung und Intervalle hängen von den in der Bereitstellung verfügbaren Optionen ab.
  • Erweiterte Protokolloptionen: Konfigurieren Sie Scope; dieser muss mindestens openid enthalten. Authorization Endpoint, Token Endpoint und JWKS URI können manuell überschrieben werden.
  • Manuelle Überschreibungen: Überschriebene Felder werden durch Discovery-Aktualisierungen nicht überschrieben. Klicken Sie auf Automatische Werte wiederherstellen, um die über Discovery ermittelten Werte wiederherzustellen. Manuelle Überschreibungen ersetzen beim Speichern der Konfiguration nicht den Discovery-Abruf und dessen Validierung.

SAML 2.0

Basiskonfiguration

  1. Geben Sie den Realm-Namen, den Anzeigenamen und die E-Mail für Anmelderouting ein.
  2. Wählen Sie IdP Metadata URL oder XML hochladen, um die Metadata des IdP des Unternehmens zu importieren. Das System parst IdP Entity ID, SSO URL, Signaturzertifikat und Binding.
  3. Speichern Sie den Entwurf, um die generierte SP Metadata URL und ACS URL zu erhalten, oder laden Sie die SP Metadata im XML-Format herunter.
  4. Stellen Sie dem IdP-Administrator die SP Metadata von FlightHub 2 zur Verfügung, um die entsprechende SAML-Anwendung zu konfigurieren. Lesen Sie die SP Entity ID aus den tatsächlich generierten SP Metadata ab; gehen Sie nicht davon aus, dass sie mit der Metadata URL identisch ist.
  5. Geben Sie in der Berechtigungsverwaltung den Namen des Rollenattributs ein und konfigurieren Sie die Zuordnungen von Verwaltungsrollen.

Beim URL-Import muss das FlightHub 2-Backend die Metadata URL über HTTPS erreichen können. Verwenden Sie beim Hochladen einer Datei die tatsächlich vom IdP des Unternehmens exportierten Metadata im XML-Format.

Setzen Sie Role Attribute auf den exakten Namen in <Attribute Name="..."> in der SAML Assertion. Der Standardwert ist roles; beim Namen wird zwischen Groß- und Kleinschreibung unterschieden. Mehrere Rollen müssen als separate AttributeValue-Elemente zurückgegeben werden, nicht zusammengefasst in einer einzelnen Zeichenfolge. Beispiel:

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

Erweiterte Konfiguration

  • Eindeutige Identitätskennung: Fest auf IdP Entity ID + persistent NameID eingestellt. Konfigurieren Sie den IdP so, dass er eine persistente NameID verwendet.
  • Attribut für den Benutzeranzeigenamen: Standardwert ist displayName. Der IdP muss dieses Attribut ausgeben.
  • Metadata-Aktualisierungen: Nach dem ersten Abruf ist die automatische Aktualisierung standardmäßig deaktiviert. Verwenden Sie beim URL-Import die Aktualisierungsoption auf der Seite. Laden Sie beim XML-Upload die aktualisierte Datei erneut hoch. Die Einstellungen für automatische Aktualisierung und Intervalle hängen von den in der Bereitstellung verfügbaren Optionen ab.
  • Erweiterte Protokolloptionen: Überschreiben Sie IdP Entity ID, SSO URL, Binding und Signaturzertifikat manuell oder stellen Sie die automatischen Werte wieder her. Metadata-Aktualisierungen überschreiben keine manuell überschriebenen Felder.
  • Zertifikatsverwaltung: Importieren und aktualisieren Sie Signaturzertifikate nach Möglichkeit über Metadata. Ein Zertifikatsfingerabdruck dient zur Überprüfung eines Zertifikats und kann den Inhalt des X.509-Zertifikats nicht ersetzen.

OAuth2

Basiskonfiguration

OAuth2 verwendet kein Discovery. Konfigurieren Sie Endpunkte und Feldpfade für Benutzerinformationen gemäß der API-Dokumentation des IdP.

FeldKonfigurationshinweise
Realm-Name / Realm-AnzeigenameGeben Sie einen Namen für die Identitätsquelle ein, zum Beispiel Enterprise_OAuth2
E-Mail für AnmelderoutingGeben Sie eine vollständige E-Mail-Adresse ein. Ihre Domain dient zur Auswahl der Identitätsquelle
Authorization URLDie vom IdP bereitgestellte URL zur Benutzerautorisierung
Token URLDie vom IdP bereitgestellte URL zum Austausch des Autorisierungscodes
User URLDie API-URL zum Abruf der Benutzeridentität und der Rollen im JSON-Format mithilfe eines Access Token
Client ID / Client SecretDie Kennung und das Secret der entsprechenden IdP-Anwendung
USER_ID_KEYDer Feldpfad zur stabilen Benutzer-ID in der Antwort mit Benutzerinformationen, zum Beispiel id oder data.id
USER_ACCOUNT_KEYDer Feldpfad zum Kontonamen in der Antwort mit Benutzerinformationen, zum Beispiel username oder data.username
ScopesGemäß den Berechtigungsanforderungen der API für Benutzerinformationen des IdP konfigurieren
Callback URLWird nach dem Speichern des Entwurfs generiert. Registrieren Sie sie exakt wie angegeben im IdP

In der Berechtigungsverwaltung muss Role Path (UserInfo) auf das Array der Rollen-Zeichenfolgen in der Antwort von User URL verweisen, zum Beispiel roles oder data.roles. FlightHub 2 ruft OAuth2-Rollen nicht aus einem JWT Access Token oder einer separaten Berechtigungs-API ab.

Wenn User URL beispielsweise die folgende Struktur zurückgibt, setzen Sie USER_ID_KEY auf id, USER_ACCOUNT_KEY auf username und Role Path auf roles:

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

Diese Felder sind nur Beispiele. Die tatsächlichen Feldpfade müssen mit der IdP-Antwort übereinstimmen. Scopes bestimmen keine Rollen; es gibt keine allgemeine Anforderung, openid einzuschließen. Befolgen Sie die Anforderungen der IdP-API. Auch wenn USER_ID_KEY auf sub gesetzt ist oder Scopes openid enthält, parst dieser Realm Identität und Rollen weiterhin über die OAuth2-API für Benutzerinformationen.

Erweiterte Konfiguration

Die Erweiterte Konfiguration zeigt die mit USER_ID_KEY verknüpfte Regel für die stabile Identität und den Feldpfad für den Benutzeranzeigenamen an. Für Anzeigeinformationen wird USER_ACCOUNT_KEY verwendet; ein zweiter Feldpfad ist nicht erforderlich.

OAuth2 bietet weder Discovery noch Metadata-Import oder -Aktualisierung. Aktualisieren Sie Endpunkte manuell, wenn sie sich ändern. Neue Realms bieten die bisherigen Kompatibilitätsoptionen USE_REDIRECT_URL und SUPER_ACCOUNT nicht an. Das Berechtigungskompatibilitätsverhalten migrierter Konfigurationen gilt nicht für neue Realms.



Berechtigungsverwaltung

Rollenabruf und Zuordnungen von Verwaltungsrollen

Konfigurieren Sie in der Berechtigungsverwaltung die Quelle für den Rollenabruf und ordnen Sie die vom IdP zurückgegebenen externen Role-Werte den FlightHub 2-Verwaltungsrollen zu.

Einstellungen zum Rollenabruf und Zuordnungen von Verwaltungsrollen

ProtokollEinstellungAnforderungen
OIDCRole PathVerweist auf das Array der Rollen-Zeichenfolgen in den Identitätsinformationen, zum Beispiel roles
SAML 2.0Role AttributeEntspricht Attribute Name in der Assertion, zum Beispiel roles. Verwenden Sie für mehrere Rollen separate AttributeValue-Elemente
OAuth2Role Path (UserInfo)Verweist auf das Array der Rollen-Zeichenfolgen in der Antwort von User URL, zum Beispiel data.roles

Die Verwaltungsrollen und ihre Standardzuordnungen sind unten aufgeführt. Konfigurieren Sie für jede Verwaltungsrolle einen externen Role-Wert.

FlightHub 2-VerwaltungsrolleStandardmäßiger externer Role-WertPriorität
Organisationsadministratorfh2-admin-org1 (höchste)
Gerätewartfh2-admin-device2
Mitgliedfh2-member-org3
  • Benutzer müssen mindestens einer Verwaltungsrolle zugeordnet werden, um sich über einen neu erstellten SSO-Realm anzumelden.
  • Wenn mehrere Verwaltungsrollen zutreffen, wird die Rolle mit der höchsten Priorität verwendet. Nicht erkannte Role-Werte werden ignoriert.
  • Externe SSO-Benutzer können nicht der Rolle Super-Administrator zugeordnet werden.
  • Die Autorisierung basiert derzeit auf Rollen, nicht direkt auf Gruppen, Sicherheitsgruppen oder anderen Attributen. Wenn das Unternehmen Benutzer über Gruppen verwaltet, konfigurieren Sie den IdP so, dass er die Gruppenmitgliedschaft in die vereinbarte Rollenliste umwandelt.

Projektberechtigungen

SSO-Verwaltungsrollen und Projektberechtigungen sind voneinander unabhängig. Nach erfolgreicher Anmeldung muss ein Administrator die SSO-Benutzer weiterhin in der Projektmitgliederverwaltung hinzufügen, Projektrollen zuweisen und die Benutzer anhand der stabilen eindeutigen Kennung des entsprechenden Realm zuordnen. Informationen zur Konfiguration von Projektrollen finden Sie unter Projekt-Nutzerrollenverwaltung.



Testen und Aktivieren

Testablauf

  1. Schließen Sie die Basiskonfiguration und die Berechtigungsverwaltung ab und klicken Sie anschließend auf Entwurf speichern.
  2. Öffnen Sie Testen und Aktivieren und führen Sie den Verbindungstest aus, um Pflichtfelder, HTTPS, Protokollendpunkte und die jeweils zutreffende Discovery-, Metadata- oder Zertifikatskonfiguration zu prüfen.
  3. Führen Sie die Testanmeldung aus, authentifizieren Sie sich mit einem Testkonto auf der geöffneten IdP-Seite und kehren Sie zur ursprünglichen Konfigurationsseite zurück.
  4. Prüfen Sie die zurückgegebene stabile Kennung, den Anzeigenamen, die E-Mail-Adresse, die Role-Liste und die Verwaltungsrolle. Stellen Sie sicher, dass Rollenabruf und -zuordnung wie erwartet funktionieren.
  5. Klicken Sie nach bestandenen Tests auf Speichern und anwenden und stellen Sie sicher, dass die Identitätsquelle aktiviert ist.
Verbindungstest und Testanmeldung beide bestanden

Der Verbindungstest validiert nur die Konfiguration und die Endpunkte. Er ersetzt keinen tatsächlichen Anmeldetest eines Benutzers. OIDC erfordert vor der Aktivierung einen erfolgreichen Verbindungstest. Wenn die Testanmeldung nicht bestanden wurde, bedeutet die Aktivierung des Realm nach Bestätigung der auf der Seite angezeigten Risiken nicht, dass die Anmeldevalidierung bestanden wurde. Es wird empfohlen, vor der Aktivierung beide Tests abzuschließen. SAML 2.0 sollte erst aktiviert werden, nachdem beide Tests bestanden wurden. Bei neu erstellten OAuth2-Realms müssen beide Tests bestanden werden; eine verfügbare Schaltfläche oder eine allgemeine Bestätigungsmeldung zeigt nicht an, dass die Tests bestanden wurden.

Wenn der Discovery-Abruf, der Metadata-Import oder der Token-Austausch fehlschlägt, prüfen Sie das Netzwerk des FlightHub 2-Backends, das Vertrauen in TLS-Zertifikate, die Anwendungszugangsdaten, die Callback-URLs und die Protokollparameter. Korrigieren Sie die Konfiguration, speichern Sie sie anschließend und testen Sie erneut.


Pflege von Identitätsquellen

Die Liste ermöglicht das Bearbeiten oder Fortsetzen der Konfiguration sowie das Testen, Aktivieren, Deaktivieren und Löschen von Identitätsquellen. Gehen Sie je nach Status wie folgt vor:

StatusAktion
EntwurfKonfiguration abschließen, speichern und Tests ausführen
Erneuter Test erforderlichÄnderungen an wesentlichen Einstellungen prüfen und die Tests erneut ausführen
Test fehlgeschlagenFehlerergebnisse prüfen, die IdP- oder FlightHub 2-Konfiguration korrigieren und erneut testen
Bereit zur AktivierungTestergebnisse bestätigen und den Realm gemäß den auf der Seite angezeigten Bedingungen aktivieren
AktiviertFür die Anmeldung verfügbar. Nach Änderungen an wesentlichen Einstellungen gemäß der Aufforderung erneut testen
DeaktiviertDie Konfiguration bleibt erhalten, steht aber nicht für die reguläre Anmeldung zur Verfügung

Aktualisieren Sie nach Änderungen an IdP-Endpunkten, Zertifikaten oder Einstellungen zur Rollenausgabe den Realm entsprechend und testen Sie erneut. Manuell überschriebene Felder werden nicht mit automatisch abgerufenen Werten aktualisiert und müssen separat geprüft werden.



Verwaltung der Anmeldung mit lokalen Konten

Der Schalter Passwortanmeldung mit lokalen Konten zulassen auf der Seite SSO-Anmelde-Einstellungen steuert, ob sich reguläre lokale Konten mit einem Passwort anmelden können. Wenn er deaktiviert ist, können reguläre lokale Konten die Passwortanmeldung nicht nutzen. Mitglieder müssen sich dann über eine aktivierte SSO-Identitätsquelle anmelden, die die Tests bestanden hat.

So deaktivieren Sie die Passwortanmeldung mit lokalen Konten:

  1. Konfigurieren, testen und aktivieren Sie mindestens einen Realm und stellen Sie sicher, dass sich Unternehmenskonten erfolgreich anmelden können.
  2. Stellen Sie sicher, dass das Konto des Notfall-Super-Administrators und dessen lokales Passwort funktionieren.
  3. Deaktivieren Sie Passwortanmeldung mit lokalen Konten zulassen und wählen Sie im Dialog Notfall-Super-Administrator festlegen.
  4. Prüfen Sie die Auswirkungen, aktivieren Sie das Bestätigungskontrollkästchen und klicken Sie auf Deaktivierung bestätigen.
Festlegen eines Notfall-Super-Administrators beim Deaktivieren der Anmeldung mit lokalen Konten

Wenn der IdP des Unternehmens nicht verfügbar oder die SSO-Konfiguration fehlerhaft ist, kann der festgelegte Notfall-Super-Administrator mit einem lokalen Passwort auf das System zugreifen, um die Anmeldung mit lokalen Konten wieder zu aktivieren oder die SSO-Konfiguration zu korrigieren. Ein regulärer Organisationsadministrator ist kein Notfall-Super-Administrator. Der Kontoname allein bestimmt nicht, ob eine Notfallanmeldung möglich ist.



Integrationsbeispiel mit Keycloak

Die folgenden Beispiele beschreiben die Konfiguration der einzelnen Protokolle mit Keycloak. Ersetzen Sie die Beispieldomains, Realm-Namen, Client IDs und Feldpfade durch die Werte Ihrer Bereitstellung. Verwenden Sie die von FlightHub 2 generierten Callback-URLs und SP Metadata-Informationen. Die Positionen der Menüs können je nach Keycloak-Version variieren.

Die Screenshots zeigen die Positionen der Konfigurationseinstellungen und wesentliche Optionen. Die in den Screenshots gezeigten Realm-, Client- und Testbenutzernamen sind Beispiele. Verwenden Sie für die tatsächliche Konfiguration die Identitätsquelle, Anwendung und Benutzerinformationen Ihres Unternehmens.


Erstellen einer Unternehmensidentitätsquelle, von Rollen und Testbenutzern

  1. Melden Sie sich bei der Keycloak-Administrationskonsole an und erstellen oder wählen Sie unter Manage realms einen Unternehmens-Realm, zum Beispiel Enterprise.

    Erstellen eines Keycloak-Realm, Eingeben seines Namens und Aktivieren
  2. Erstellen Sie unter Realm roles die Rollen fh2-admin-org, fh2-admin-device und fh2-member-org oder Rollenwerte, die den FlightHub 2-Zuordnungen entsprechen.

    Realm-Rollenliste in Keycloak und die Schaltfläche Create role
  3. Erstellen und aktivieren Sie unter Users einen Testbenutzer. Legen Sie unter Credentials ein Passwort fest und führen Sie alle erforderlichen Kontoaktionen aus.

  4. Weisen Sie auf der Registerkarte Role mapping des Benutzers eine Testrolle zu. Weisen Sie für den ersten Test nur eine Verwaltungsrolle zu, etwa fh2-member-org, damit sich die Ergebnisse leichter überprüfen lassen.

    Zuweisen der Rolle Mitglied an einen Testbenutzer in Keycloak

Ein Unternehmens-Realm in Keycloak und ein Realm in FlightHub 2 sind unterschiedliche Konfigurationseinheiten und müssen nicht denselben Namen haben. Konfigurieren Sie bei der Integration mehrerer Protokolle für jedes Protokoll einen separaten Client und verwenden Sie unterschiedliche Domains für das Anmelderouting.


OIDC-Integration

  1. Erstellen Sie in Keycloak einen OpenID Connect-Client, zum Beispiel Enterprise_OIDC.

  2. Aktivieren Sie Client authentication und Standard flow und deaktivieren Sie Implicit flow. Direct access grants sind für browserbasiertes SSO nicht erforderlich. Aktivieren Sie Require PKCE und setzen Sie PKCE Method auf S256. Diese Einstellungen finden Sie unter Settings → Capability config.

    Client-Authentifizierungsablauf und PKCE-S256-Einstellungen in Keycloak
  3. Erstellen Sie in FlightHub 2 einen OIDC-Realm und geben Sie die E-Mail für Anmelderouting, Client ID, Client Secret und Discovery URL ein. Die Discovery URL von Keycloak hat das folgende Format:

    https://idp.example.com/realms/Enterprise/.well-known/openid-configuration
    
  4. Speichern Sie den FlightHub 2-Entwurf, um die tatsächlichen Callback-Informationen zu erhalten. Registrieren Sie die Callback-URLs für die reguläre Anmeldung und die Testanmeldung unter Valid redirect URIs im Keycloak-Client und konfigurieren Sie Web origins anhand der von FlightHub 2 generierten Informationen. Rufen Sie das Client Secret auf der Registerkarte Credentials des Client ab.

  5. Fügen Sie unter Client scopes → dedizierter Scope des Client → Mappers einen User Realm Role Mapper hinzu:

    Öffnen Sie Client scopes, wählen Sie den dedizierten Scope des aktuellen Client aus und öffnen Sie die Mapper-Konfiguration.

    Eintrag für den dedizierten Scope unter Client scopes in Keycloak
    EinstellungBeispielwert
    Namesikong-roles
    Token Claim Nameroles
    Claim JSON TypeString
    MultivaluedEin
    Add to ID token / Add to access token / Add to userinfoEin
    Keycloak User Realm Role Mapper mit mehrwertiger Rollenausgabe in Tokens und Benutzerinformationen
  6. Setzen Sie in FlightHub 2 Role Path auf roles, konfigurieren Sie die Zuordnungen von Verwaltungsrollen und führen Sie Verbindungstest und Testanmeldung aus. Überprüfen Sie die Rollen, speichern Sie anschließend die Konfiguration und wenden Sie sie an.


SAML 2.0-Integration

  1. Rufen Sie die IdP Metadata aus Keycloak über eine URL im folgenden Format ab. Die von dieser URL zurückgegebenen Metadata im XML-Format können auch zum Hochladen einer Datei verwendet werden.

    https://idp.example.com/realms/Enterprise/protocol/saml/descriptor
    
  2. Erstellen Sie in FlightHub 2 einen SAML 2.0-Realm, importieren Sie die IdP Metadata, speichern Sie den Entwurf und laden Sie die generierten SP Metadata im XML-Format herunter.

  3. Importieren Sie in Keycloak die SP Metadata unter Clients → Import client oder erstellen Sie manuell einen SAML-Client und prüfen Sie die folgenden Felder:

    EinstellungBeispielwert
    Client IDEntity ID aus den SP Metadata von FlightHub 2
    NameEin Name zur Kennzeichnung der Anwendung, zum Beispiel Enterprise_SAML
    Valid redirect URIsACS URL von FlightHub 2
    Name ID formatpersistent
    Force name ID formatEin
    Force POST bindingEin, um die SAML-Antwort über POST zurückzugeben
    Sign documents / Sign assertionsEin
    Signature algorithmRSA_SHA256
    Client signature requiredEin. Importieren Sie das SP-Signaturzertifikat aus den SP Metadata von FlightHub 2
    IDP-Initiated SSO URL nameLeer lassen. Starten Sie die Anmeldung in FlightHub 2

    Der folgende Screenshot zeigt, wo Sie persistente NameID und POST Binding konfigurieren. Überprüfen Sie die Signatur- und Zertifikatseinstellungen anhand der obigen Tabelle.

    Einstellungen für persistente NameID und POST Binding bei SAML in Keycloak
  4. Konfigurieren Sie Mapper für Rollen und Benutzerinformationen im dedizierten Scope des SAML-Client:

    Mapper-TypWesentliche Einstellungen
    Role listName und Role attribute name: roles; NameFormat: Basic; Single Role Attribute: Ein
    User PropertyUser property: username; Attribute name: displayName
    User PropertyUser property: email; Attribute name: email
    SAML Role list Mapper in Keycloak mit dem Attribut roles und aktiviertem Single Role Attribute
  5. Prüfen Sie den standardmäßigen Scope role_list und den benutzerdefinierten Rollen-Mapper des Client, um doppelte oder widersprüchliche Rollenausgaben zu vermeiden. Wenn Sie den oben beschriebenen benutzerdefinierten Mapper roles verwenden, entfernen Sie alle widersprüchlichen Standard-Scope-Zuweisungen für diesen Client.

  6. Setzen Sie in FlightHub 2 Role Attribute auf roles und das Attribut für den Benutzeranzeigenamen auf displayName und konfigurieren Sie anschließend die Zuordnungen von Verwaltungsrollen. Speichern Sie die Konfiguration und wenden Sie sie an, nachdem beide Tests bestanden wurden.

Client ID muss die tatsächliche SP Entity ID verwenden, nicht den Anzeigenamen der Anwendung. Der AuthnRequest von FlightHub 2 kann Redirect Binding verwenden, während die IdP-Antwort POST Binding verwendet; diese Bindings dienen unterschiedlichen Zwecken. Rufen Sie nach dem erneuten Erstellen eines SAML-Realm in FlightHub 2 die neuen SP Metadata ab und überprüfen und aktualisieren Sie die Einstellungen für Entity ID, ACS und Zertifikate im IdP.


OAuth2-Integration

Keycloak stellt OAuth2-Endpunkte über einen OpenID Connect-Client bereit. Wählen Sie auf der FlightHub 2-Seite das Protokoll OAuth2 aus.

  1. Erstellen Sie in Keycloak einen separaten Client, zum Beispiel Enterprise_OAuth2. Konfigurieren Sie gemäß dem obigen OIDC-Beispiel Client authentication, Standard flow, PKCE sowie die Callback-URLs für die reguläre Anmeldung und die Testanmeldung und rufen Sie das eigene Secret dieses Client ab.

  2. Fügen Sie im dedizierten Scope des Client einen User Realm Role Mapper hinzu. Setzen Sie Token Claim Name auf roles und Multivalued auf Ein und stellen Sie sicher, dass Add to userinfo auf Ein gesetzt ist.

  3. Erstellen Sie in FlightHub 2 einen OAuth2-Realm und geben Sie die entsprechenden Anwendungszugangsdaten, die E-Mail für Anmelderouting und die folgenden Einstellungen ein:

    FlightHub 2-FeldKeycloak-Beispiel
    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, für die API für Benutzerinformationen von Keycloak in diesem Beispiel
    Role Path (UserInfo)roles
  4. Speichern Sie den Entwurf und konfigurieren Sie die Zuordnungen von Verwaltungsrollen. Speichern Sie die Konfiguration und wenden Sie sie erst an, nachdem Verbindungstest und Testanmeldung beide bestanden wurden und die Benutzerinformationen und die Verwaltungsrolle den erwarteten Ergebnissen entsprechen.

Die beispielhaften Scopes und Benutzerfelder gelten für die oben beschriebene Keycloak-Konfiguration. Passen Sie sie bei der Integration eines anderen IdP gemäß dessen API-Dokumentation an.



Häufig gestellte Fragen

Warum können sich Benutzer nicht anmelden, obwohl der Verbindungstest bestanden wurde?

Der Verbindungstest prüft die Konfiguration und die Endpunkte. Die Testanmeldung überprüft die tatsächlichen Identitätsinformationen, den Rollenabruf und die Zuordnungen von Verwaltungsrollen. Führen Sie die Testanmeldung aus und prüfen Sie die stabile Benutzer-ID, die Rollenfelder, die Zuordnungsergebnisse, die Callback-URLs und die Ergebnisse der Signaturvalidierung.

Wie behebe ich eine nicht übereinstimmende Callback-URL?

Vergleichen Sie die redirect_uri in der tatsächlichen Anfrage mit der für die entsprechende IdP-Anwendung registrierten Callback-URL. Sie müssen exakt übereinstimmen, einschließlich Protokoll, Domain, Port und Pfad. Registrieren Sie die Callbacks für die reguläre Anmeldung und die Testanmeldung entsprechend der Bereitstellung. Verwenden Sie weder die URL der Frontend-Konfigurationsseite noch Platzhalterwerte aus einem nicht gespeicherten Formular.

Muss die E-Mail für Anmelderouting mit der E-Mail-Adresse des Benutzers im IdP übereinstimmen?

Die E-Mail für Anmelderouting wählt die Identitätsquelle aus, während die E-Mail-Adresse des IdP-Benutzers Teil seines Profils ist. Sie dienen unterschiedlichen Zwecken. Befolgen Sie die Konfigurationsanforderungen des IdP für Konten und E-Mail-Adressen. Die Domain für das Anmelderouting muss den Anforderungen an das E-Mail-Format entsprechen und darf keine Unterstriche enthalten. Geben Sie beim Erstellen des Realm eine vollständige E-Mail-Adresse ein.

Warum kann FlightHub 2 die vom IdP zurückgegebenen Rollen nicht abrufen?

Prüfen Sie bei OIDC Role Path anhand der Array-Struktur in den Identitätsinformationen. Prüfen Sie bei OAuth2 das von User URL zurückgegebene Rollenarray. Prüfen Sie bei SAML die Groß- und Kleinschreibung von Attribute Name und stellen Sie sicher, dass für mehrere Rollen separate AttributeValue-Elemente verwendet werden. Prüfen Sie außerdem, ob Konflikte zwischen standardmäßigen und benutzerdefinierten IdP-Mappern vorliegen, und stellen Sie sicher, dass die zurückgegebenen Role-Werte den Zuordnungen von Verwaltungsrollen entsprechen.

Warum sind nach erfolgreicher Anmeldung keine Projekte sichtbar?

SSO-Verwaltungsrollen erteilen nicht automatisch Projektberechtigungen. Ein Administrator muss den Benutzer in der Projektmitgliederverwaltung hinzufügen, eine Projektrolle zuweisen und den Benutzer anhand der stabilen eindeutigen Kennung seines Realm zuordnen.

Kann eine E-Mail-Adresse als eindeutige Benutzerkennung verwendet werden?

Nein. E-Mail-Adressen können sich ändern oder wiederverwendet werden. OIDC verwendet issuer + sub, SAML verwendet IdP Entity ID + persistent NameID und OAuth2 verwendet Realm + stable user ID. Auch Anzeigenamen und Kontonamen ersetzen nicht die stabile eindeutige Kennung.

Wie behebe ich Fehler beim Abruf von Discovery oder Metadata?

Prüfen Sie, ob die URL korrekt ist, das FlightHub 2-Backend sie über HTTPS erreichen kann und das Backend dem IdP-Zertifikat vertraut. Der Zugriff im Browser oder die Akzeptanz eines Zertifikats dort bedeutet nicht, dass das FlightHub 2-Backend ebenfalls auf die URL zugreifen oder dem Zertifikat vertrauen kann. Bei SAML können auch die tatsächlich vom IdP exportierten Metadata im XML-Format hochgeladen werden. Speichern Sie nach der Behebung des Problems und testen Sie erneut.

Wie behebe ich einen Fehler beim Token-Austausch nach der IdP-Authentifizierung?

Prüfen Sie die Netzwerkverbindung und das Vertrauen in TLS-Zertifikate zwischen dem FlightHub 2-Backend und der Token URL. Überprüfen Sie die entsprechende Client ID, das Client Secret, die tatsächliche Callback-URL und die PKCE-Parameter. Testen Sie nach der Behebung des Problems erneut und stellen Sie sicher, dass Benutzerinformationen und Verwaltungsrollen erfolgreich abgerufen werden.

Wie aktualisiere ich Zertifikate oder Endpunkte?

Aktualisieren Sie bei OIDC Discovery. Aktualisieren Sie beim SAML-URL-Import die Metadata; laden Sie beim XML-Upload die aktualisierte Datei erneut hoch. Prüfen Sie manuell überschriebene Felder und aktualisieren Sie sie bei Bedarf oder stellen Sie die automatischen Werte wieder her. Aktualisieren Sie bei OAuth2 die Endpunkte manuell. Führen Sie nach den Änderungen die Tests erneut aus.

Wird der Benutzer beim Abmelden von FlightHub 2 auch vom IdP des Unternehmens abgemeldet?

Durch das Abmelden wird nur die FlightHub 2-Sitzung beendet. Der Benutzer wird dadurch nicht vom IdP des Unternehmens abgemeldet. Die Unternehmenssitzung kann bei der nächsten Anmeldung noch aktiv sein, und die Testanmeldung kann eine erneute Authentifizierung erfordern.

Wie lässt sich der Zugriff wiederherstellen, wenn der IdP nach der Deaktivierung der lokalen Passwortanmeldung ausfällt?

Der beim Deaktivieren der Anmeldung mit lokalen Konten festgelegte Notfall-Super-Administrator kann mit einem lokalen Passwort auf das System zugreifen, die Anmeldung mit lokalen Konten wieder aktivieren oder die SSO-Konfiguration korrigieren. Stellen Sie vor dem Deaktivieren der Anmeldung mit lokalen Konten sicher, dass dieses Konto und das Passwort funktionieren.

Was sollte ich prüfen, wenn sich eine Identitätsquelle nicht aktivieren lässt?

Prüfen Sie, ob der Entwurf gespeichert wurde, die Pflichtfelder gültig sind, ein erneuter Test angefordert wird oder die Grenze von 8 aktivierten Realms erreicht ist. Stellen Sie bei einem neu erstellten OAuth2-Realm außerdem sicher, dass beide Tests bestanden wurden.

Last Updated: