How to Configure Microsoft Entra ID as an OIDC Server on Zyxel USG FLEX H Series

OpenID Connect (OIDC) is an authentication protocol based on OAuth 2.0 that allows the Zyxel firewall to authenticate users through an external Identity Provider (IdP).

The Zyxel USG FLEX H Series supports OIDC authentication with Microsoft Entra ID for Captive Portal and SSL VPN with OpenVPN Connect.

Instead of maintaining separate user credentials on the firewall, users are redirected to Microsoft Entra ID and authenticate using their existing organizational account. The Zyxel firewall then validates the OIDC authentication response and uses the returned user information to authorize access.

This article describes how to configure Microsoft Entra ID as an OIDC Server on the Zyxel USG FLEX H Series, including user and group-based authentication.

Note: OIDC authentication is not supported for Remote Access VPN/IKEv2 or SSL VPN with SecuExtender.

If you want to configure Google as the OIDC provider, see How to Configure Google as an OIDC Identity Provider on Zyxel USG FLEX H Series.

Prerequisites

Before configuring Microsoft Entra ID OIDC authentication on the Zyxel firewall, make sure the following requirements are met:

• A Zyxel firewall with uOS 1.39 or later.
• Access to a Microsoft Entra ID tenant with permission to register applications.
• A user account in Microsoft Entra ID that will be used for testing.
• A security group in Microsoft Entra ID if group-based authentication is required.
• A publicly reachable FQDN for the Zyxel firewall.
• A valid HTTPS certificate configured for the firewall FQDN.
• Internet connectivity from the Zyxel firewall to Microsoft Entra ID authentication endpoints.
• Captive Portal enabled on the Zyxel firewall if OIDC authentication is used for Captive Portal sign-in.

Example environment

For this article, the following test environment is used:

1. Configure Microsoft Entra ID

1.1 Register an application

1. Sign in to the Microsoft Entra admin center.
2. Go to Identity → Applications → App registrations.
3. Click New registration.
4. Configure the application as follows:

For Supported account types, select Accounts in this organizational directory only (Single tenant).

Click Register.

Note: The Redirect URI will be configured in a later step after obtaining the OIDC callback URL from the Zyxel firewall.

1.2 Record the application identifiers

After the application is registered, open the application's Overview page.

The Essentials section contains the identifiers required for the OIDC configuration on the Zyxel firewall:

• Application (client) ID — identifies the registered application.
• Directory (tenant) ID — identifies the Microsoft Entra tenant.
• Supported account types — confirms that the application is configured as a single-tenant application.

The Application (client) ID will later be entered in the Zyxel OIDC configuration as Client ID.

The Directory (tenant) ID is used to construct the Microsoft Entra OIDC Issuer URL.

For a single-tenant application, the issuer URL has the following format:

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

1.3 Create a client secret

The Zyxel firewall needs a client credential to authenticate the OIDC application when communicating with Microsoft Entra ID.

1. In the application registration, go to Manage → Certificates & secrets.
2. Select the Client secrets tab.
3. Click New client secret.

Configure the secret according to your organization's security and secret-rotation requirements.

After creating the secret, Microsoft Entra ID displays the secret under Client secrets.

1.4 Copy the client secret value

After the client secret is created, copy the Value immediately and store it securely.

Important: The client secret Value is displayed only once when the secret is created. If the value is lost, create a new client secret.

The value shown under Value is the value that must be entered into the Zyxel configuration as Client Secret.

Do not use the Secret ID as the client secret.

1.5 Create a Security Group in Microsoft Entra ID

Create a security group that will be used to identify users for OIDC authentication.

1. Open Microsoft Entra ID → Groups → All groups.
2. Click New group.
3. Set Group type to Security.
4. Enter a group name.
   In this example, use Zyxel-OIDC-Test.
5. Set Membership type to Assigned.
6. Add the test user to the group.
7. Create the group.

After creating the group, open it and note its Object ID. This ID will be used later when creating the External Group User on the Zyxel firewall.

Note: The group name is used for administration and identification in Microsoft Entra ID. The firewall uses the group's Object ID to identify the group.

1.6 Configure the Groups Claim

The OIDC token must contain information about the user's group membership. Configure a groups claim in the Microsoft Entra ID application.

• Open the registered application Zyxel OIDC Test.

• Go to Manage → Token configuration.
• Click Add groups claim.

• Under Select group types to include in Access, ID, and SAML tokens, select Security groups.
• Under Customize token properties by type, select Group ID.
• Click Add.

Microsoft Entra ID will now include the user's security group ID in the OIDC token.

For this example, the group information is returned in the groups claim.

The Zyxel firewall will use this claim later with:

Group Attribute: groups

Note: The groups claim does not create a group. The group is created in the previous step. The groups claim tells Microsoft Entra ID to include the user's group information in the OIDC token.

This allows the firewall to identify the user's group membership and map the user to the corresponding External Group User.

2. Configure OIDC Authentication on the Zyxel Firewall

After configuring the application in Microsoft Entra ID, configure the OIDC authentication server on the Zyxel firewall.

Go to:

User & Authentication → User Authentication → AAA Server

Create a new authentication server and enter the following settings:

The Redirect URI is generated automatically by the Zyxel firewall based on the Redirect Address and HTTPS port.

In this example, the generated Redirect URI is:

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

This URI must also be added to the Redirect URI configuration of the Microsoft Entra application.

Important: Use the Value of the Microsoft Entra client secret for the Client Secret field. Do not use the Secret ID.

Advanced Settings

Configure the following advanced settings:

3. Configure the Redirect URI in Microsoft Entra ID

Use the Redirect URI generated by the Zyxel OIDC configuration.

1. In the Microsoft Entra application, open Manage → Authentication.
2. Click Add Redirect URI.

Enter the Redirect URI shown in the Zyxel OIDC configuration:

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

Click Configure.

Important: The Redirect URI must exactly match the URI configured on the Zyxel firewall.

4. Validate the OIDC Configuration

1. On the Zyxel firewall, click Test to validate the OIDC configuration.

The firewall opens a new browser tab and redirects the user to the Microsoft Entra ID sign-in page.

During the first sign-in, Microsoft Entra ID may display a Permissions requested page.

Review the requested permissions and click Accept.

1. If you are an administrator and want to grant consent for all users in the tenant, select Consent on behalf of your organization before clicking Accept. Only grant organization-wide consent after confirming that the requested permissions are required for the application.

Note: The consent page is normally shown only when consent is required. After the required consent has been granted, it should not be displayed again for every subsequent sign-in unless additional permissions are requested or the existing consent is removed.

5. Verify Authentication Test

After signing in successfully, the firewall displays the OIDC Authentication Test result.

The OIDC Authentication Successful (Verified) message confirms that the firewall successfully authenticated the user with Microsoft Entra ID and received the expected user information.

The result also shows the attributes received from the identity provider:

• Username – the authenticated user's account.
• User attribute – the attribute used as the login name.
• Group attribute – the attribute used to retrieve the user's group information.
• Group list – groups returned by Microsoft Entra ID for the authenticated user.

In this example, the Group Attribute is configured as groups, so the firewall receives the user's group information from the groups claim.

Note: The exact values shown in the test result depend on the signed-in user and the Microsoft Entra ID configuration.

6. Create an External Group User

After the OIDC authentication test is successful, create an External Group User on the Zyxel firewall.

Go to:

User & Authentication → User/Group → User

Create a new user with the following settings:

• User Name: Enter a name for the external group.
• User Type: External Group User
• Authentication Server: Select the configured Microsoft Entra ID OIDC server.
• Group Identifier: Enter the Microsoft Entra ID group identifier.
• Description: Enter an optional description.

The Group Identifier must match the group ID returned by Microsoft Entra ID in the groups claim during the OIDC authentication test.

For example, in our test environment, the OIDC test result showed the group in the group_list attribute. This value is then used as the Group Identifier for the External Group User.

Note: The Group Identifier is normally the Microsoft Entra ID group object ID (GUID). Use the group ID returned by the OIDC token and not the group display name.

7. Configure the Captive Portal Authentication Policy

After creating the External Group User, configure the Captive Portal Authentication Policy.

Go to:

Captive Portal → Authentication Policy

Create or edit the authentication policy and configure the following settings:

• Enable: Enable the policy.
• Incoming: Select the interface where Captive Portal users connect.
• Source Address: Select the required source address or any.
• Destination Address: Select the required destination address or any.
• Enable Walled Garden: Enable this option.
• Trusted Identity Provider: Select the Microsoft Entra ID OIDC identity provider.
• Sign-in Method: Select Sign-on With.
• Select the configured OIDC authentication server.

The Walled Garden allows unauthenticated users to reach the required identity provider before authentication is completed. This is required for OIDC Sign-On.

Note: The Trusted Identity Provider selected here must match the OIDC authentication server configured under User & Authentication → User Authentication.

8. Save and verify the authentication policy

Click Apply to save the configuration.

The policy should then appear in the Captive Portal → Authentication Policy list.

In our example, the policy uses:

• Sign-in Method: sign-on
• Sign-on With: Entra_ID_Test
• Portal Type: internal

This confirms that the Captive Portal policy is configured to use the Microsoft Entra ID OIDC authentication server.

9. Verify OIDC Authentication

After completing the OIDC configuration, verify the authentication from a client device.

1. Connect a client device to the network protected by the Captive Portal.
2. Open a web browser and access an external website.
3. The Captive Portal login page is displayed.
4. Click Sign in to start the OIDC authentication.

Sign in with a Microsoft Entra ID account.

After successful authentication, the user is redirected back to the network.

The firewall should now recognize the user as an External Group User.

Log & Report → Log / Events → System

Check the firewall logs under:

Troubleshooting: No Groups Found

If OIDC authentication is successful, but the authentication result shows No groups found, check the group configuration on both the firewall and Microsoft Entra ID.

Check the following:

1. On the firewall, make sure Group Attribute is configured.
2. Make sure the value matches the group claim sent by Microsoft Entra ID.
   In this example, the value is groups.
3. Make sure the authenticated user is a member of the expected group.
4. Verify that Microsoft Entra ID sends the group information in the ID token.

For example, if the firewall is configured with Group Attribute = groups, the authentication result should contain the groups attribute and the corresponding group ID.

If No groups found is displayed, the OIDC login itself can still be successful. The problem is specifically related to receiving or mapping the user's group information.