Come configurare Microsoft Entra ID come server OIDC su Zyxel USG FLEX H Series

OpenID Connect (OIDC) è un protocollo di autenticazione basato su OAuth 2.0 che consente al firewall Zyxel di autenticare gli utenti tramite un provider di identità esterno (IdP).

La serie Zyxel USG FLEX H supporta l'autenticazione OIDC con Microsoft Entra ID per Captive Portal e SSL VPN con OpenVPN Connect.

Invece di gestire credenziali utente separate sul firewall, gli utenti vengono reindirizzati a Microsoft Entra ID e si autenticano utilizzando il loro account organizzativo esistente. Il firewall Zyxel quindi convalida la risposta di autenticazione OIDC e utilizza le informazioni utente restituite per autorizzare l'accesso.

Questo articolo descrive come configurare Microsoft Entra ID come server OIDC sulla serie Zyxel USG FLEX H, inclusa l'autenticazione basata su utenti e gruppi.

Nota: L'autenticazione OIDC non è supportata per Remote Access VPN/IKEv2 o SSL VPN con SecuExtender.

Se desideri configurare Google come provider OIDC, consulta Come configurare Google come provider di identità OIDC su Zyxel USG FLEX H Series.

Prerequisiti

Prima di configurare l'autenticazione Microsoft Entra ID OIDC sul firewall Zyxel, assicurati che i seguenti requisiti siano soddisfatti:

• Un firewall Zyxel con uOS 1.39 o successivo.
• Accesso a un tenant Microsoft Entra ID con permessi per registrare applicazioni.
• Un account utente in Microsoft Entra ID che sarà utilizzato per i test.
• Un gruppo di sicurezza in Microsoft Entra ID se è richiesta l'autenticazione basata su gruppi.
• Un FQDN pubblicamente raggiungibile per il firewall Zyxel.
• Un certificato HTTPS valido configurato per il FQDN del firewall.
• Connettività Internet dal firewall Zyxel agli endpoint di autenticazione Microsoft Entra ID.
• Captive Portal abilitato sul firewall Zyxel se l'autenticazione OIDC è usata per l'accesso al Captive Portal.

Ambiente di esempio

Per questo articolo, viene utilizzato il seguente ambiente di test:

1. Configurare Microsoft Entra ID

1.1 Registrare un'applicazione

1. Accedi al Microsoft Entra admin center.
2. Vai su Identità → Applicazioni → Registrazioni app.
3. Clicca su Nuova registrazione.
4. Configura l'applicazione come segue:

Per Tipi di account supportati, seleziona Account solo in questa directory organizzativa (tenant singolo).

Clicca su Registra.

Nota: L'URI di reindirizzamento sarà configurato in un passaggio successivo dopo aver ottenuto l'URL di callback OIDC dal firewall Zyxel.

1.2 Annotare gli identificatori dell'applicazione

Dopo la registrazione dell'applicazione, apri la pagina Panoramica dell'applicazione.

La sezione Essenziali contiene gli identificatori necessari per la configurazione OIDC sul firewall Zyxel:

• ID applicazione (client) — identifica l'applicazione registrata.
• ID directory (tenant) — identifica il tenant Microsoft Entra.
• Tipi di account supportati — conferma che l'applicazione è configurata come tenant singolo.

L'ID applicazione (client) sarà inserito successivamente nella configurazione OIDC di Zyxel come Client ID.

L'ID directory (tenant) viene utilizzato per costruire l'Issuer URL OIDC di Microsoft Entra.

Per un'applicazione tenant singolo, l'URL dell'issuer ha il seguente formato:

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

1.3 Creare un segreto client

Il firewall Zyxel necessita di una credenziale client per autenticare l'applicazione OIDC quando comunica con Microsoft Entra ID.

1. Nella registrazione dell'applicazione, vai su Gestisci → Certificati e segreti.
2. Seleziona la scheda Segreti client.
3. Clicca su Nuovo segreto client.

Configura il segreto in base ai requisiti di sicurezza e rotazione dei segreti della tua organizzazione.

Dopo aver creato il segreto, Microsoft Entra ID mostra il segreto sotto Segreti client.

1.4 Copiare il valore del segreto client

Dopo la creazione del segreto client, copia immediatamente il Valore e conservalo in modo sicuro.

Importante: Il Valore del segreto client viene mostrato una sola volta al momento della creazione. Se il valore viene perso, crea un nuovo segreto client.

Il valore mostrato sotto Valore è quello che deve essere inserito nella configurazione Zyxel come Client Secret.

Non utilizzare l'ID del segreto come segreto client.

1.5 Creare un gruppo di sicurezza in Microsoft Entra ID

Crea un gruppo di sicurezza che sarà usato per identificare gli utenti per l'autenticazione OIDC.

1. Apri Microsoft Entra ID → Gruppi → Tutti i gruppi.
2. Clicca su Nuovo gruppo.
3. Imposta Tipo di gruppo su Sicurezza.
4. Inserisci un nome per il gruppo.
   In questo esempio, usa Zyxel-OIDC-Test.
5. Imposta Tipo di appartenenza su Assegnato.
6. Aggiungi l'utente di test al gruppo.
7. Crea il gruppo.

Dopo aver creato il gruppo, aprilo e annota il suo Object ID. Questo ID sarà utilizzato successivamente per creare l'utente di gruppo esterno sul firewall Zyxel.

Nota: Il nome del gruppo è usato per l'amministrazione e l'identificazione in Microsoft Entra ID. Il firewall utilizza l'Object ID del gruppo per identificarlo.

1.6 Configurare la dichiarazione dei gruppi (Groups Claim)

Il token OIDC deve contenere informazioni sull'appartenenza ai gruppi dell'utente. Configura una dichiarazione dei gruppi nell'applicazione Microsoft Entra ID.

• Apri l'applicazione registrata Zyxel OIDC Test.

• Vai su Gestisci → Configurazione token.
• Clicca su Aggiungi dichiarazione gruppi.

• Sotto Seleziona i tipi di gruppo da includere nei token Access, ID e SAML, seleziona Gruppi di sicurezza.
• Sotto Personalizza le proprietà del token per tipo, seleziona ID gruppo.
• Clicca su Aggiungi.

Microsoft Entra ID includerà ora l'ID del gruppo di sicurezza dell'utente nel token OIDC.

Per questo esempio, le informazioni sul gruppo sono restituite nella dichiarazione groups.

Il firewall Zyxel utilizzerà questa dichiarazione successivamente con:

Attributo gruppo: groups

Nota: La dichiarazione dei gruppi non crea un gruppo. Il gruppo è stato creato nel passaggio precedente. La dichiarazione dei gruppi indica a Microsoft Entra ID di includere le informazioni sul gruppo dell'utente nel token OIDC.

Questo permette al firewall di identificare l'appartenenza ai gruppi dell'utente e mappare l'utente al corrispondente Utente di gruppo esterno.

2. Configurare l'autenticazione OIDC sul firewall Zyxel

Dopo aver configurato l'applicazione in Microsoft Entra ID, configura il server di autenticazione OIDC sul firewall Zyxel.

Vai a:

Utente e autenticazione → Autenticazione utente → Server AAA

Crea un nuovo server di autenticazione e inserisci le seguenti impostazioni:

L'URI di reindirizzamento è generato automaticamente dal firewall Zyxel in base all'indirizzo di reindirizzamento e alla porta HTTPS.

In questo esempio, l'URI di reindirizzamento generato è:

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

Questo URI deve essere aggiunto anche alla configurazione URI di reindirizzamento dell'applicazione Microsoft Entra.

Importante: Usa il Valore del segreto client Microsoft Entra per il campo Client Secret. Non usare l'ID del segreto.

Impostazioni avanzate

Configura le seguenti impostazioni avanzate:

3. Configurare l'URI di reindirizzamento in Microsoft Entra ID

Usa l'URI di reindirizzamento generato dalla configurazione OIDC di Zyxel.

1. Nell'applicazione Microsoft Entra, apri Gestisci → Autenticazione.
2. Clicca su Aggiungi URI di reindirizzamento.

Inserisci l'URI di reindirizzamento mostrato nella configurazione OIDC di Zyxel:

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

Clicca su Configura.

Importante: L'URI di reindirizzamento deve corrispondere esattamente all'URI configurato sul firewall Zyxel.

4. Validare la configurazione OIDC

1. Sul firewall Zyxel, clicca su Test per validare la configurazione OIDC.

Il firewall apre una nuova scheda del browser e reindirizza l'utente alla pagina di accesso Microsoft Entra ID.

Durante il primo accesso, Microsoft Entra ID potrebbe mostrare una pagina Permessi richiesti.

Esamina i permessi richiesti e clicca su Accetta.

1. Se sei un amministratore e vuoi concedere il consenso per tutti gli utenti del tenant, seleziona Consenti per conto della tua organizzazione prima di cliccare su Accetta. Concedi il consenso a livello organizzativo solo dopo aver confermato che i permessi richiesti sono necessari per l'applicazione.

Nota: La pagina di consenso viene mostrata normalmente solo quando è richiesto il consenso. Dopo che il consenso necessario è stato concesso, non dovrebbe più essere visualizzata ad ogni successivo accesso a meno che non vengano richiesti permessi aggiuntivi o il consenso esistente venga rimosso.

5. Verificare il test di autenticazione

Dopo un accesso riuscito, il firewall mostra il risultato del Test di autenticazione OIDC.

Il messaggio Autenticazione OIDC riuscita (Verificata) conferma che il firewall ha autenticato con successo l'utente con Microsoft Entra ID e ha ricevuto le informazioni utente previste.

Il risultato mostra anche gli attributi ricevuti dal provider di identità:

• Nome utente – l'account utente autenticato.
• Attributo utente – l'attributo usato come nome di login.
• Attributo gruppo – l'attributo usato per recuperare le informazioni sui gruppi dell'utente.
• Elenco gruppi – gruppi restituiti da Microsoft Entra ID per l'utente autenticato.

In questo esempio, l'Attributo gruppo è configurato come groups, quindi il firewall riceve le informazioni sui gruppi dell'utente dalla dichiarazione groups.

Nota: I valori esatti mostrati nel risultato del test dipendono dall'utente che ha effettuato l'accesso e dalla configurazione di Microsoft Entra ID.

6. Creare un utente di gruppo esterno

Dopo che il test di autenticazione OIDC è riuscito, crea un Utente di gruppo esterno sul firewall Zyxel.

Vai a:

Utente e autenticazione → Utente/Gruppo → Utente

Crea un nuovo utente con le seguenti impostazioni:

• Nome utente: Inserisci un nome per il gruppo esterno.
• Tipo utente: Utente di gruppo esterno
• Server di autenticazione: Seleziona il server OIDC Microsoft Entra ID configurato.
• Identificatore gruppo: Inserisci l'identificatore del gruppo Microsoft Entra ID.
• Descrizione: Inserisci una descrizione facoltativa.

L'Identificatore gruppo deve corrispondere all'ID del gruppo restituito da Microsoft Entra ID nella dichiarazione groups durante il test di autenticazione OIDC.

Ad esempio, nel nostro ambiente di test, il risultato del test OIDC mostrava il gruppo nell'attributo group_list. Questo valore è quindi usato come Identificatore gruppo per l'utente di gruppo esterno.

Nota: L'Identificatore gruppo è normalmente l'Object ID (GUID) del gruppo Microsoft Entra ID. Usa l'ID del gruppo restituito dal token OIDC e non il nome visualizzato del gruppo.

7. Configurare la policy di autenticazione del Captive Portal

Dopo aver creato l'Utente di gruppo esterno, configura la policy di autenticazione del Captive Portal.

Vai a:

Captive Portal → Policy di autenticazione

Crea o modifica la policy di autenticazione e configura le seguenti impostazioni:

• Abilita: Abilita la policy.
• Incoming: Seleziona l'interfaccia dove si connettono gli utenti del Captive Portal.
• Indirizzo sorgente: Seleziona l'indirizzo sorgente richiesto o any.
• Indirizzo destinazione: Seleziona l'indirizzo destinazione richiesto o any.
• Abilita Walled Garden: Abilita questa opzione.
• Provider di identità attendibile: Seleziona il provider di identità OIDC Microsoft Entra ID.
• Metodo di accesso: Seleziona Accesso con.
• Seleziona il server di autenticazione OIDC configurato.

Il Walled Garden consente agli utenti non autenticati di raggiungere il provider di identità richiesto prima che l'autenticazione sia completata. Questo è necessario per l'accesso OIDC.

Nota: Il Provider di identità attendibile selezionato qui deve corrispondere al server di autenticazione OIDC configurato sotto Utente e autenticazione → Autenticazione utente.

8. Salvare e verificare la policy di autenticazione

Clicca su Applica per salvare la configurazione.

La policy dovrebbe quindi apparire nell'elenco Captive Portal → Policy di autenticazione.

Nel nostro esempio, la policy utilizza:

• Metodo di accesso: sign-on
• Accesso con: Entra_ID_Test
• Tipo portale: internal

Questo conferma che la policy del Captive Portal è configurata per utilizzare il server di autenticazione OIDC Microsoft Entra ID.

9. Verificare l'autenticazione OIDC

Dopo aver completato la configurazione OIDC, verifica l'autenticazione da un dispositivo client.

1. Connetti un dispositivo client alla rete protetta dal Captive Portal.
2. Apri un browser web e accedi a un sito esterno.
3. Viene visualizzata la pagina di login del Captive Portal.
4. Clicca su Accedi per avviare l'autenticazione OIDC.

Accedi con un account Microsoft Entra ID.

Dopo un'autenticazione riuscita, l'utente viene reindirizzato nuovamente alla rete.

Il firewall dovrebbe ora riconoscere l'utente come Utente di gruppo esterno.

Log & Report → Log / Eventi → Sistema

Controlla i log del firewall sotto:

Risoluzione problemi: Nessun gruppo trovato

Se l'autenticazione OIDC ha successo, ma il risultato mostra Nessun gruppo trovato, verifica la configurazione dei gruppi sia sul firewall che su Microsoft Entra ID.

Controlla quanto segue:

1. Sul firewall, assicurati che l'Attributo gruppo sia configurato.
2. Assicurati che il valore corrisponda alla dichiarazione dei gruppi inviata da Microsoft Entra ID.
   In questo esempio, il valore è groups.
3. Assicurati che l'utente autenticato sia membro del gruppo previsto.
4. Verifica che Microsoft Entra ID invii le informazioni sui gruppi nel token ID.

Ad esempio, se il firewall è configurato con Attributo gruppo = groups, il risultato dell'autenticazione dovrebbe contenere l'attributo groups e l'ID del gruppo corrispondente.

Se viene mostrato Nessun gruppo trovato, il login OIDC può comunque essere riuscito. Il problema è specificamente legato alla ricezione o alla mappatura delle informazioni sui gruppi dell'utente.