Microsoft Entra ID (OIDC) - Web Console

This guide provides configuration instructions for integrating Microsoft Entra ID (formerly Azure AD) with Genian ZTNA, a network access control system, for authentication functionality.

For administrator authentication, the Genian ZTNA Web Console page calls Microsoft Entra ID authentication using the OIDC (OpenID Connect) protocol, Microsoft Entra ID verifies user authentication status, and proper SSO is achieved.

Prerequisites

  • Microsoft Entra ID (formerly Azure AD) tenant
  • Microsoft Entra ID app registration permissions (Application Administrator or Global Administrator)
  • Genian ZTNA Web Console administrator privileges
  • Network connection (communication between Genian ZTNA ↔ Microsoft Entra ID)

Purpose of Integration

Genian ZTNA and Microsoft Entra ID integration provides the following benefits:

  • No need to manage separate administrator databases for ZTNA and Microsoft Entra ID authentication.
  • Administrators can authenticate to ZTNA Web Console using SSO with their Microsoft Entra ID accounts.
  • Provides secure administrator authentication through the OIDC standard protocol.

Supported Features

Microsoft Entra ID OIDC integration supports the following features:

  • Authorization Code Flow (standard OIDC authentication flow)
  • PKCE (Proof Key for Code Exchange) security enhancement
  • JIT (Just-In-Time) Provisioning
  • Access Token and ID Token validation
  • Administrator information retrieval through Microsoft Graph API

Integration Setup Method

The Genian ZTNA and Microsoft Entra ID configuration method covered in this guide provides only the essential items for integration. It is automatically applied after the initial one-time setup.

Step 1: Microsoft Entra ID App Registration

  1. Access https://portal.azure.com and log in with your Microsoft account.

  2. Navigate to Microsoft Entra ID (formerly Azure Active Directory) service.

  3. Click App registrations in the left menu.

  4. Click the New registration button.

  5. Enter app registration information.

  6. Copy the following information from the Overview page of the registered app:

    • Application (client) ID example: 12345678-1234-1234-1234-123456789012

    • Directory (tenant) ID example: 87654321-4321-4321-4321-210987654321

      • Used when constructing Endpoint URLs.

Step 2: Microsoft Entra ID App Authentication Settings

  1. Click Authentication in the left menu of the registered app.

  2. Verify that the Web platform is added in Platform configurations.

  3. Verify that the following is correctly entered in Redirect URIs:

  4. Check the following in Implicit grant and hybrid flows:

    • Access tokens (optional)
    • ID tokens Check (required)

  5. In Advanced settings, configure the following:

    • Treat client as public client : "No" (default)

  6. Click the Save button.

Step 3: Microsoft Entra ID Client Secret Generation

  1. Click Certificates & secrets in the left menu of the app.

  2. Click New client secret in the Client secrets tab.

  3. Enter client secret information.

    • Description: Enter "ZTNA Admin Console Secret"
    • Expires: Select "24 months" (recommended)
    • Click the Add button.

  4. Copy and save the Value of the generated client secret in a secure location.

    • Client secret example: 1a2B3c4D5e6F7g8H9i0J~k1L2m3N4o5P6q7R8s9T0u

Note

The client secret value can only be viewed immediately after creation. It cannot be viewed again once you leave the page, so be sure to save it.

Step 4: Microsoft Entra ID API Permissions Settings

  1. Click API permissions in the left menu of the app.

  2. Click the Add a permission button.

  3. Select Microsoft Graph.

  4. Select Delegated permissions.

  5. Add the following permissions:

    • openid (default, required for OpenID connection)
    • profile (default, user profile information)
    • email (default, email address)
    • User.Read (user General retrieval)
    • Directory.Read.All (optional, for group information retrieval)

  6. Click the Add permissions button.

  7. Click the Grant admin consent for {tenant name} button. (Global Administrator permission required)

  8. Click Yes in the admin consent confirmation dialog.

Step 5: Microsoft Entra ID User and Role Settings

  1. Click Users in the left menu of Microsoft Entra ID.

  2. Verify users who will be granted administrator privileges.

  3. In the Groups menu, click New group to create an administrator group. (optional)

    • Group type: Select "Security"
    • Group name: Enter "_ADMINROLE_roleId" example: _ADMINROLE_superAdmin
    • Group description: Enter "ZTNA administrator group"
    • Members: Add administrator users
    • Click the Create button.

  4. Navigate to Enterprise applications.

  5. Search for and select the created "Genian ZTNA Admin Console" app.

  6. In the Users and groups menu, click Add user/group.

    • Assign administrator users or the _ADMINROLE_superAdmin group.

Step 6: Genian ZTNA OIDC Configuration

  1. In Genian ZTNA Web Console > Preferences > Environment Settings > Admin Console > OIDC Authentication, copy and enter the following values from Microsoft Entra ID:

    • Provider Name - Enter "Microsoft Entra ID"

    • Issuer - https://login.microsoftonline.com/{Directory(tenant) ID}/v2.0

    • Client ID - Microsoft Entra ID's Application (client) ID

    • Client Secret - Microsoft Entra ID's Client secret value

    • Scope - Enter "openid profile email Group.Read.All"

    • Additional Parameters (Optional) - You can enter Microsoft Entra ID-specific parameters in JSON format.

      {
    "domain_hint": "example.com",
    "login_hint": "user@example.com",
    "prompt": "select_account"
}

      Note

      Additional Parameters configures custom parameters to be included in the OIDC Authorization Request.

      Microsoft Entra ID Recommended Parameters:

      • domain_hint: "example.com" - Azure AD tenant domain hint (simplifies authentication)
      • login_hint: "user@example.com" - Pre-fills user email
      • prompt: "login" - Forces re-authentication
      • prompt: "select_account" - Displays account selection screen
      • prompt: "consent" - Displays consent screen every time

      OIDC Standard Parameters:

      • ui_locales: "en-US" - UI language setting
      • max_age: "3600" - Maximum authentication validity time (seconds)
      • acr_values: "urn:mace:incommon:iap:silver" - Authentication context class reference

      For more details, refer to https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow.

    • Use Discovery - Select "Off" (automatic endpoint discovery does not work)

      • You can check related Endpoint information by clicking Endpoints on the registered App screen.

      • You can check related Endpoint information by accessing the following URL:

        https://login.microsoftonline.com/{Directory(tenant) ID}/v2.0/.well-known/openid-configuration

    {
    "issuer": "https://login.microsoftonline.com/{Directory(tenant) ID}/v2.0",
    "authorization_endpoint": "https://login.microsoftonline.com/{Directory(tenant) ID}/oauth2/v2.0/authorize",
    "token_endpoint": "https://login.microsoftonline.com/{Directory(tenant) ID}/oauth2/v2.0/token",
    "userinfo_endpoint": "https://graph.microsoft.com/oidc/userinfo",
    "jwks_uri": "https://login.microsoftonline.com/{Directory(tenant) ID}/discovery/v2.0/keys"
}

  2. To use JIT provisioning functionality, change JIT provisioning to 'On' in ZTNA.

    • In ZTNA UI's JIT provisioning > Additional Information, click the add button to set the administrator account's name and email.

      • Enter name for the name.

      • Enter email for the email.

        • OIDC Claims (name, email) items are already defined as standard in Microsoft Entra ID.

    • Set the basic permissions for administrators created through JIT provisioning.

      • In ZTNA UI's JIT provisioning > Administrator Management Role, select the management role to assign to new administrators.

      • You can set different permissions per administrator through Microsoft Entra ID Groups.

      • The group name to assign administrators must include the _ADMINROLE_ prefix and roleId (superAdmin) like _ADMINROLE_superAdmin_ZTNA.

        Management Role Value
        superAdmin _ADMINROLE_superAdmin_ZTNA

  3. Enter the text to display on the Microsoft Entra ID authentication button in Login Button Text that will be shown on the Genian ZTNA Admin Console login screen.

    • Example: "Sign in with Microsoft", "Microsoft Login"

  4. Click the Update button at the bottom of the Genian ZTNA Web Console configuration screen.

Note

Please ensure that the Application ID and Client secret are entered correctly. Also verify that the Tenant ID is correctly included in the Issuer URL.

Authentication Integration Testing Method

Testing from Genian ZTNA Admin Console Page (SP-initiated SSO)

  1. Access the Genian ZTNA Admin Console login page.
  2. Click the authentication button ("Sign in with Microsoft") configured in Step 6 above on the login screen.
  3. A Microsoft authentication page will be displayed in a new popup window.
  4. Enter Microsoft account username and password to authenticate.
  5. Complete two-factor authentication (MFA) if required.
  6. Upon successful authentication, JWT ID Token and Access Token are received, administrator information is extracted, and you are logged into the ZTNA Admin Console.

Note

After setting up authentication integration, you must add the Microsoft IdP domain to the Enforcement Policy permissions so that the authentication integration window is displayed even in a blocked state.

1. How to add permissions
2. Policy > Objects > Network
3. Select Tasks > Create
4. Enter General
5. Network Address > Select FQDN > Enter IdP domain
   - login.microsoftonline.com
   - graph.microsoft.com (Microsoft Graph API)
6. Click Create
7. Go to Permissions menu
8. Create permission using the created network object
9. Assign the created permission to the Enforcement Policy that controls the admin console