Konfiguration von Microsoft Entra ID als OIDC-Server auf der Zyxel USG FLEX H Serie

OpenID Connect (OIDC) ist ein Authentifizierungsprotokoll basierend auf OAuth 2.0, das es der Zyxel-Firewall ermöglicht, Benutzer über einen externen Identitätsanbieter (IdP) zu authentifizieren.

Die Zyxel USG FLEX H Serie unterstützt OIDC-Authentifizierung mit Microsoft Entra ID für Captive Portal und SSL VPN mit OpenVPN Connect.

Anstatt getrennte Benutzeranmeldeinformationen auf der Firewall zu verwalten, werden Benutzer zu Microsoft Entra ID weitergeleitet und authentifizieren sich mit ihrem bestehenden Organisationskonto. Die Zyxel-Firewall validiert dann die OIDC-Authentifizierungsantwort und verwendet die zurückgegebenen Benutzerinformationen zur Zugriffsautorisierung.

Dieser Artikel beschreibt, wie Microsoft Entra ID als OIDC-Server auf der Zyxel USG FLEX H Serie konfiguriert wird, einschließlich benutzer- und gruppenbasierter Authentifizierung.

Hinweis: OIDC-Authentifizierung wird nicht für Remote Access VPN/IKEv2 oder SSL VPN mit SecuExtender unterstützt.

Wenn Sie Google als OIDC-Anbieter konfigurieren möchten, lesen Sie Wie man Google als OIDC-Identitätsanbieter auf der Zyxel USG FLEX H Serie konfiguriert.

Voraussetzungen

Bevor Sie die Microsoft Entra ID OIDC-Authentifizierung auf der Zyxel-Firewall konfigurieren, stellen Sie sicher, dass die folgenden Anforderungen erfüllt sind:

• Eine Zyxel-Firewall mit uOS 1.39 oder höher.
• Zugriff auf einen Microsoft Entra ID Mandanten mit Berechtigung zur Registrierung von Anwendungen.
• Ein Benutzerkonto in Microsoft Entra ID, das für Tests verwendet wird.
• Eine Sicherheitsgruppe in Microsoft Entra ID, falls gruppenbasierte Authentifizierung erforderlich ist.
• Ein öffentlich erreichbarer FQDN für die Zyxel-Firewall.
• Ein gültiges HTTPS-Zertifikat, das für den Firewall-FQDN konfiguriert ist.
• Internetverbindung von der Zyxel-Firewall zu den Microsoft Entra ID Authentifizierungsendpunkten.
• Captive Portal muss auf der Zyxel-Firewall aktiviert sein, wenn OIDC-Authentifizierung für die Anmeldung am Captive Portal verwendet wird.

Beispielumgebung

Für diesen Artikel wird die folgende Testumgebung verwendet:

1. Microsoft Entra ID konfigurieren

1.1 Anwendung registrieren

1. Melden Sie sich im Microsoft Entra Admin Center an.
2. Gehen Sie zu Identität → Anwendungen → App-Registrierungen.
3. Klicken Sie auf Neue Registrierung.
4. Konfigurieren Sie die Anwendung wie folgt:

Für Unterstützte Kontotypen wählen Sie Konten in diesem Organisationsverzeichnis (Einzelmandant).

Klicken Sie auf Registrieren.

Hinweis: Die Umleitungs-URI wird in einem späteren Schritt konfiguriert, nachdem die OIDC-Callback-URL von der Zyxel-Firewall erhalten wurde.

1.2 Anwendungskennungen notieren

Nach der Registrierung der Anwendung öffnen Sie die Übersichtsseite der Anwendung.

Der Abschnitt Essentials enthält die für die OIDC-Konfiguration auf der Zyxel-Firewall erforderlichen Kennungen:

• Anwendungs-(Client-)ID — identifiziert die registrierte Anwendung.
• Verzeichnis-(Mandanten-)ID — identifiziert den Microsoft Entra Mandanten.
• Unterstützte Kontotypen — bestätigt, dass die Anwendung als Einzelmandantenanwendung konfiguriert ist.

Die Anwendungs-(Client-)ID wird später in der Zyxel OIDC-Konfiguration als Client-ID eingetragen.

Die Verzeichnis-(Mandanten-)ID wird verwendet, um die Microsoft Entra OIDC Issuer-URL zu erstellen.

Für eine Einzelmandantenanwendung hat die Issuer-URL folgendes Format:

https://login.microsoftonline.com/<TENANT_ID>/v2.0

1.3 Client-Geheimnis erstellen

Die Zyxel-Firewall benötigt eine Client-Anmeldeinformation, um die OIDC-Anwendung bei der Kommunikation mit Microsoft Entra ID zu authentifizieren.

1. Gehen Sie in der Anwendungsregistrierung zu Verwalten → Zertifikate & Geheimnisse.
2. Wählen Sie den Tab Client-Geheimnisse.
3. Klicken Sie auf Neues Client-Geheimnis.

Konfigurieren Sie das Geheimnis gemäß den Sicherheits- und Geheimnis-Rotationsanforderungen Ihrer Organisation.

Nach der Erstellung zeigt Microsoft Entra ID das Geheimnis unter Client-Geheimnisse an.

1.4 Wert des Client-Geheimnisses kopieren

Kopieren Sie nach der Erstellung des Client-Geheimnisses sofort den Wert und speichern Sie ihn sicher.

Wichtig: Der Wert des Client-Geheimnisses wird nur einmal angezeigt, wenn das Geheimnis erstellt wird. Wenn der Wert verloren geht, erstellen Sie ein neues Client-Geheimnis.

Der unter Wert angezeigte Wert muss in der Zyxel-Konfiguration als Client Secret eingetragen werden.

Verwenden Sie nicht die Secret-ID als Client-Geheimnis.

1.5 Sicherheitsgruppe in Microsoft Entra ID erstellen

Erstellen Sie eine Sicherheitsgruppe, die zur Identifikation von Benutzern für die OIDC-Authentifizierung verwendet wird.

1. Öffnen Sie Microsoft Entra ID → Gruppen → Alle Gruppen.
2. Klicken Sie auf Neue Gruppe.
3. Setzen Sie den Gruppentyp auf Sicherheit.
4. Geben Sie einen Gruppennamen ein.
   In diesem Beispiel verwenden Sie Zyxel-OIDC-Test.
5. Setzen Sie den Mitgliedschaftstyp auf Zugewiesen.
6. Fügen Sie den Testbenutzer der Gruppe hinzu.
7. Erstellen Sie die Gruppe.

Öffnen Sie nach der Erstellung die Gruppe und notieren Sie deren Objekt-ID. Diese ID wird später bei der Erstellung des externen Gruppenbenutzers auf der Zyxel-Firewall verwendet.

Hinweis: Der Gruppenname dient der Verwaltung und Identifikation in Microsoft Entra ID. Die Firewall verwendet die Objekt-ID der Gruppe zur Identifikation.

1.6 Gruppen-Claim konfigurieren

Das OIDC-Token muss Informationen über die Gruppenmitgliedschaft des Benutzers enthalten. Konfigurieren Sie einen Gruppen-Claim in der Microsoft Entra ID Anwendung.

• Öffnen Sie die registrierte Anwendung Zyxel OIDC Test.

• Gehen Sie zu Verwalten → Token-Konfiguration.
• Klicken Sie auf Gruppen-Claim hinzufügen.

• Wählen Sie unter Gruppentypen auswählen, die in Access-, ID- und SAML-Tokens enthalten sein sollen die Option Sicherheitsgruppen.
• Wählen Sie unter Token-Eigenschaften nach Typ anpassen die Option Gruppen-ID.
• Klicken Sie auf Hinzufügen.

Microsoft Entra ID wird nun die Sicherheitsgruppen-ID des Benutzers im OIDC-Token einschließen.

Für dieses Beispiel werden die Gruppeninformationen im groups Claim zurückgegeben.

Die Zyxel-Firewall verwendet diesen Claim später mit:

Gruppenattribut: groups

Hinweis: Der groups Claim erstellt keine Gruppe. Die Gruppe wird im vorherigen Schritt erstellt. Der Gruppen-Claim weist Microsoft Entra ID an, die Gruppeninformationen des Benutzers im OIDC-Token einzuschließen.

Dies ermöglicht der Firewall, die Gruppenmitgliedschaft des Benutzers zu erkennen und den Benutzer der entsprechenden Externen Gruppenbenutzer zuzuordnen.

2. OIDC-Authentifizierung auf der Zyxel-Firewall konfigurieren

Nach der Konfiguration der Anwendung in Microsoft Entra ID konfigurieren Sie den OIDC-Authentifizierungsserver auf der Zyxel-Firewall.

Gehen Sie zu:

Benutzer & Authentifizierung → Benutzer-Authentifizierung → AAA Server

Erstellen Sie einen neuen Authentifizierungsserver und geben Sie folgende Einstellungen ein:

Die Umleitungs-URI wird von der Zyxel-Firewall automatisch basierend auf der Umleitungsadresse und dem HTTPS-Port generiert.

In diesem Beispiel lautet die generierte Umleitungs-URI:

https://h200.zylab.uk:1003/oauth2/callback

Diese URI muss auch in der Umleitungs-URI-Konfiguration der Microsoft Entra Anwendung hinzugefügt werden.

Wichtig: Verwenden Sie für das Feld Client Secret den Wert des Microsoft Entra Client-Geheimnisses. Verwenden Sie nicht die Secret-ID.

Erweiterte Einstellungen

Konfigurieren Sie die folgenden erweiterten Einstellungen:

3. Umleitungs-URI in Microsoft Entra ID konfigurieren

Verwenden Sie die von der Zyxel OIDC-Konfiguration generierte Umleitungs-URI.

1. Öffnen Sie in der Microsoft Entra Anwendung Verwalten → Authentifizierung.
2. Klicken Sie auf Umleitungs-URI hinzufügen.

Geben Sie die in der Zyxel OIDC-Konfiguration angezeigte Umleitungs-URI ein:

https://<firewall-FQDN>:1003/oauth2/callback

Klicken Sie auf Konfigurieren.

Wichtig: Die Umleitungs-URI muss exakt mit der auf der Zyxel-Firewall konfigurierten URI übereinstimmen.

4. OIDC-Konfiguration validieren

1. Klicken Sie auf der Zyxel-Firewall auf Test, um die OIDC-Konfiguration zu validieren.

Die Firewall öffnet einen neuen Browser-Tab und leitet den Benutzer zur Microsoft Entra ID Anmeldeseite weiter.

Beim ersten Anmelden zeigt Microsoft Entra ID möglicherweise eine Seite Berechtigungen angefordert an.

Überprüfen Sie die angeforderten Berechtigungen und klicken Sie auf Akzeptieren.

1. Wenn Sie Administrator sind und die Zustimmung für alle Benutzer im Mandanten erteilen möchten, wählen Sie vor dem Klicken auf Akzeptieren die Option Zustimmung im Namen Ihrer Organisation. Erteilen Sie die organisationsweite Zustimmung nur, nachdem Sie bestätigt haben, dass die angeforderten Berechtigungen für die Anwendung erforderlich sind.

Hinweis: Die Zustimmungsseite wird normalerweise nur angezeigt, wenn eine Zustimmung erforderlich ist. Nachdem die erforderliche Zustimmung erteilt wurde, sollte sie bei nachfolgenden Anmeldungen nicht erneut angezeigt werden, es sei denn, es werden zusätzliche Berechtigungen angefordert oder die bestehende Zustimmung wird entfernt.

5. Authentifizierungstest verifizieren

Nach erfolgreicher Anmeldung zeigt die Firewall das Ergebnis des OIDC-Authentifizierungstests an.

Die Meldung OIDC-Authentifizierung erfolgreich (verifiziert) bestätigt, dass die Firewall den Benutzer erfolgreich mit Microsoft Entra ID authentifiziert und die erwarteten Benutzerinformationen erhalten hat.

Das Ergebnis zeigt auch die vom Identitätsanbieter empfangenen Attribute:

• Benutzername – das Konto des authentifizierten Benutzers.
• Benutzerattribut – das Attribut, das als Anmeldename verwendet wird.
• Gruppenattribut – das Attribut, mit dem die Gruppeninformationen des Benutzers abgerufen werden.
• Gruppenliste – Gruppen, die von Microsoft Entra ID für den authentifizierten Benutzer zurückgegeben werden.

In diesem Beispiel ist das Gruppenattribut als groups konfiguriert, sodass die Firewall die Gruppeninformationen des Benutzers aus dem groups Claim erhält.

Hinweis: Die genauen Werte im Testergebnis hängen vom angemeldeten Benutzer und der Microsoft Entra ID Konfiguration ab.

6. Externen Gruppenbenutzer erstellen

Nach erfolgreichem OIDC-Authentifizierungstest erstellen Sie einen externen Gruppenbenutzer auf der Zyxel-Firewall.

Gehen Sie zu:

Benutzer & Authentifizierung → Benutzer/Gruppe → Benutzer

Erstellen Sie einen neuen Benutzer mit folgenden Einstellungen:

• Benutzername: Geben Sie einen Namen für die externe Gruppe ein.
• Benutzertyp: External Group User
• Authentifizierungsserver: Wählen Sie den konfigurierten Microsoft Entra ID OIDC-Server aus.
• Gruppenkennung: Geben Sie die Microsoft Entra ID Gruppenkennung ein.
• Beschreibung: Geben Sie eine optionale Beschreibung ein.

Die Gruppenkennung muss mit der Gruppen-ID übereinstimmen, die Microsoft Entra ID im groups Claim während des OIDC-Authentifizierungstests zurückgibt.

Zum Beispiel zeigte das OIDC-Testresultat in unserer Testumgebung die Gruppe im Attribut group_list. Dieser Wert wird dann als Gruppenkennung für den externen Gruppenbenutzer verwendet.

Hinweis: Die Gruppenkennung ist normalerweise die Objekt-ID (GUID) der Microsoft Entra ID Gruppe. Verwenden Sie die Gruppen-ID, die vom OIDC-Token zurückgegeben wird, und nicht den Anzeigenamen der Gruppe.

7. Captive Portal Authentifizierungsrichtlinie konfigurieren

Nachdem Sie den externen Gruppenbenutzer erstellt haben, konfigurieren Sie die Captive Portal Authentifizierungsrichtlinie.

Gehen Sie zu:

Captive Portal → Authentifizierungsrichtlinie

Erstellen oder bearbeiten Sie die Authentifizierungsrichtlinie und konfigurieren Sie folgende Einstellungen:

• Aktivieren: Aktivieren Sie die Richtlinie.
• Eingehend: Wählen Sie die Schnittstelle aus, an der sich die Captive Portal-Benutzer verbinden.
• Quelladresse: Wählen Sie die erforderliche Quelladresse oder any.
• Zieladresse: Wählen Sie die erforderliche Zieladresse oder any.
• Walled Garden aktivieren: Aktivieren Sie diese Option.
• Vertrauenswürdiger Identitätsanbieter: Wählen Sie den Microsoft Entra ID OIDC Identitätsanbieter aus.
• Anmeldemethode: Wählen Sie Anmelden mit.
• Wählen Sie den konfigurierten OIDC-Authentifizierungsserver aus.

Der Walled Garden ermöglicht es nicht authentifizierten Benutzern, den erforderlichen Identitätsanbieter vor der abgeschlossenen Authentifizierung zu erreichen. Dies ist für OIDC-Anmeldung erforderlich.

Hinweis: Der hier ausgewählte vertrauenswürdige Identitätsanbieter muss mit dem unter Benutzer & Authentifizierung → Benutzer-Authentifizierung konfigurierten OIDC-Authentifizierungsserver übereinstimmen.

8. Authentifizierungsrichtlinie speichern und überprüfen

Klicken Sie auf Übernehmen, um die Konfiguration zu speichern.

Die Richtlinie sollte dann in der Liste unter Captive Portal → Authentifizierungsrichtlinie erscheinen.

In unserem Beispiel verwendet die Richtlinie:

• Anmeldemethode: sign-on
• Anmelden mit: Entra_ID_Test
• Portaltyp: internal

Dies bestätigt, dass die Captive Portal-Richtlinie so konfiguriert ist, dass der Microsoft Entra ID OIDC-Authentifizierungsserver verwendet wird.

9. OIDC-Authentifizierung überprüfen

Nach Abschluss der OIDC-Konfiguration überprüfen Sie die Authentifizierung von einem Client-Gerät.

1. Verbinden Sie ein Client-Gerät mit dem durch das Captive Portal geschützten Netzwerk.
2. Öffnen Sie einen Webbrowser und rufen Sie eine externe Website auf.
3. Die Captive Portal-Anmeldeseite wird angezeigt.
4. Klicken Sie auf Anmelden, um die OIDC-Authentifizierung zu starten.

Melden Sie sich mit einem Microsoft Entra ID-Konto an.

Nach erfolgreicher Authentifizierung wird der Benutzer zurück ins Netzwerk weitergeleitet.

Die Firewall sollte den Benutzer nun als externen Gruppenbenutzer erkennen.

Protokoll & Bericht → Protokolle / Ereignisse → System

Überprüfen Sie die Firewall-Protokolle unter:

Fehlerbehebung: Keine Gruppen gefunden

Wenn die OIDC-Authentifizierung erfolgreich ist, das Authentifizierungsergebnis jedoch Keine Gruppen gefunden anzeigt, überprüfen Sie die Gruppenkonfiguration sowohl auf der Firewall als auch in Microsoft Entra ID.

Überprüfen Sie Folgendes:

1. Stellen Sie auf der Firewall sicher, dass das Gruppenattribut konfiguriert ist.
2. Stellen Sie sicher, dass der Wert mit dem von Microsoft Entra ID gesendeten Gruppen-Claim übereinstimmt.
   In diesem Beispiel ist der Wert groups.
3. Stellen Sie sicher, dass der authentifizierte Benutzer Mitglied der erwarteten Gruppe ist.
4. Überprüfen Sie, ob Microsoft Entra ID die Gruppeninformationen im ID-Token sendet.

Wenn die Firewall beispielsweise mit Gruppenattribut = groups konfiguriert ist, sollte das Authentifizierungsergebnis das Attribut groups und die entsprechende Gruppen-ID enthalten.

Wenn Keine Gruppen gefunden angezeigt wird, kann die OIDC-Anmeldung selbst dennoch erfolgreich sein. Das Problem bezieht sich speziell auf den Empfang oder die Zuordnung der Gruppeninformationen des Benutzers.