Keycloak (OIDC) - Web Console

This guide provides configuration instructions for integrating Keycloak with Genian ZTNA, a network access control system, for authentication functionality.

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

Prerequisites

  • Keycloak server installation and operation (version 20.0 or higher)
  • Keycloak Admin Console access permissions
  • Genian ZTNA Web Console administrator privileges
  • Network connection (communication between Genian ZTNA ↔ Keycloak server)

Purpose of Integration

Genian ZTNA and Keycloak integration provides the following benefits:

  • No need to manage separate administrator databases for ZTNA and Keycloak authentication.
  • Administrators can authenticate to ZTNA Web Console using SSO with their Keycloak accounts.
  • Provides secure administrator authentication through the OIDC standard protocol.
  • Utilizes Keycloak's powerful authentication/authorization management features.
  • Enables integrated management through multi-Realm and Federation features.

Supported Features

Keycloak 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 UserInfo Endpoint
  • Keycloak Groups integration

Integration Setup Method

The Genian ZTNA and Keycloak 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: Keycloak Realm Creation and Setup

  1. Access the Keycloak Admin Console and log in with the administrator account.

  2. Click the Realm selection dropdown in the left menu and select Create realm.

  3. Enter Realm creation information.

    • Realm name: Enter "genian-ztna"
    • Enabled: Keep checked
    • Click the Create button.

  4. With the created Realm selected, click Realm settings in the left menu.

  5. In the General tab, verify the Realm General.

    • Require SSL: Select "External requests" or "All requests" (HTTPS environment recommended)
    • User registration: Configure as needed (generally disabled)

Step 2: Keycloak Client Creation

  1. Click Clients in the left menu.

  2. Click the Create client button.

  3. In General settings, enter the following:

    • Client type: Select "OpenID Connect"
    • Client ID: Enter "genian-ztna-adminconsole"
    • Name: Enter "Genian ZTNA Admin Console"
    • Description: Enter "Genian ZTNA Admin Console OIDC Integration"
    • Click the Next button.

  4. In Capability config, set the following:

    • Client authentication: Check 'On' (Confidential client)
    • Authorization: 'Off' (generally unnecessary)
    • Standard flow: Check 'On' (Authorization Code Flow)
    • Direct access grants: 'Off' (recommended for security)
    • Click the Next button.

  5. In Login settings, enter the following:

  6. Copy the Client secret from the Credentials tab of the created Client.

    • Client secret example: abc123def456ghi789jkl012mno345pq

Step 3: Keycloak Users

  1. Click Users in the left menu.

  2. Click the Create new user button.

  3. Enter administrator account information.

    • Username: Enter "admin"
    • Email: Enter "admin@company.com"
    • First name: Enter "Admin"
    • Last name: Enter "User"
    • Email verified: Check 'On' (optional)
    • Click the Create button.

  4. Go to the Credentials tab of the created user.

    • Click Set password.
    • Password: Enter temporary password
    • Password confirmation: Re-enter the same password
    • Temporary: 'Off' (so users don't need to change it themselves)
    • Click the Save button.

Step 4: Keycloak Groups Creation

  1. Click Groups in the left menu.

  2. Click the Create group button.

    • Name: Must include the _ADMINROLE_ prefix and roleId (superAdmin) like "_ADMINROLE_superAdmin_ZTNA".
    • Click the Save button.

  3. In the Members tab of the created group, click Add member.

    • Assign users to apply to the _ADMINROLE_superAdmin_ZTNA group.

Step 5: Genian ZTNA OIDC Configuration

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

    • Provider Name - Enter "Keycloak"

    • Issuer - https://{keycloak-server}/realms/{realm name}

    • Client ID - "genian-ztna-adminconsole"

    • Client Secret - Keycloak's Client secret

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

      • You can check related Endpoint information by clicking Endpoints in the General tab of Realm settings.

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

        https://{keycloak-server}/realms/{Realm name}/.well-known/openid-configuration

    • Scope - Enter "openid profile email"

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

      {
    "kc_idp_hint": "saml",
    "kc_locale": "en",
    "prompt": "login"
}

      Note

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

      Keycloak Recommended Parameters:

      • kc_idp_hint: "saml" - Redirect to specific Identity Provider (when using Identity Brokering)
      • kc_locale: "en" - Keycloak UI language setting (en, ko, ja, etc.)
      • kc_action: "UPDATE_PASSWORD" - Require specific action (password change, etc.)
      • prompt: "login" - Force re-authentication
      • prompt: "consent" - Display consent screen every time

      OIDC Standard Parameters:

      • ui_locales: "en-US" - UI language setting (OIDC standard)
      • login_hint: "user@example.com" - User email hint
      • max_age: "3600" - Maximum authentication validity time (seconds)
      • acr_values: "gold" - Authentication context class reference

      For more details, refer to https://www.keycloak.org/docs/latest/securing_apps/index.html#parameters-forwarding.

  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 {given_name} {family_name} for the name.

      • Enter email for the email.

        • OIDC Claims (given_name, family_name, email) items are already defined as standard in Keycloak.

    • 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 Keycloak 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 Keycloak authentication button in Login Button Text that will be shown on the Genian ZTNA Admin Console login screen.

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

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

Note

Please ensure that the Client ID and Client Secret are entered correctly. Also verify that the Keycloak server's Issuer URL is accessible from ZTNA.

Step 5: Keycloak Client Mappers Configuration (Advanced)

You can configure additional group information mapping for JIT Provisioning.

  1. Select the created Client in Keycloak Admin Console.

  2. Go to the Client scopes tab.

  3. Click genian-ztna-adminconsole-dedicated.

  4. In the Mappers tab, click Add mapper > By configuration.

  5. Select Group Membership to add group information.

    • Set an appropriate name in Name.
    • Enter "groups" in Token Claim Name.
    • Turn off Full group path and save.
    • Click the Save button.

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 Keycloak") configured in Step 4 above on the login screen.
  3. A Keycloak authentication page will be displayed in a new popup window.
  4. Enter Keycloak username and password to authenticate.
  5. 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 Keycloak 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
   - keycloak-server (internal domain)
   - your-keycloak.company.com (external domain)
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