Keycloak (OIDC) - CWP

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

Overview

Through OIDC APP integration between Genian ZTNA and Keycloak solutions, user authentication can be performed via Keycloak without the need to manage a separate Genian ZTNA user database.

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

Purpose of Integration

Genian ZTNA and Keycloak integration provides the following benefits:

  • No need to manage separate user databases for ZTNA and Keycloak authentication.
  • Users can authenticate to ZTNA using SSO with their Keycloak accounts.
  • Provides secure user authentication through the OIDC standard protocol.
  • Utilizes Keycloak's powerful authentication/authorization management features.
  • Enables integrated user 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
  • User information retrieval through UserInfo Endpoint
  • Keycloak Groups/Roles 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 (http://localhost:8080/admin) 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-users"
    • 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 (activate when allowing CWP user registration)

Step 2: Keycloak Client Creation (for CWP)

  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-cwp"
    • Name: Enter "Genian ZTNA CWP"
    • Description: Enter "Genian ZTNA User Portal 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: xyz987uvw654rst321opq098mno765lk

Step 3: Keycloak User and Group Setup

  1. Click Groups in the left menu.

  2. Click the Create group button.

  3. Enter user group information.

    • Name: Enter "ztna-users"
    • Description: Enter "ZTNA general user group"
    • Click the Create button.

  4. Create an additional privilege group. (optional)

    • Name: Enter "ztna-vip-users"
    • Description: Enter "ZTNA VIP user group"
    • Click the Create button.

  5. Click Users in the left menu.

  6. Click the Create new user button.

  7. Enter test user account information.

    • Username: Enter "testuser"
    • Email: Enter "testuser@company.com"
    • First name: Enter "Test"
    • Last name: Enter "User"
    • Email verified: Check 'On'
    • Enabled: Check 'On'
    • Click the Create button.

  8. 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: Genian ZTNA OIDC Configuration

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

    • Provider Name - Enter "Keycloak"

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

    • Client ID - "genian-ztna-cwp"

    • Client Secret - Keycloak's Client secret

    • Scope - Enter "openid profile email"

    • 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

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

      {
    "kc_idp_hint": "saml",
    "kc_locale": "ko",
    "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: "ko" - Keycloak UI language setting (ko, en, 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: "ko-KR" - 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 user 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.

  3. Enter the text to display on the Keycloak authentication button in Login Button Text that will be shown on the Genian ZTNA CWP authentication 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 (Group Information Mapping)

Add Groups claim configuration for CWP user permission mapping.

  1. Select the created Client ("genian-ztna-cwp") in Keycloak Admin Console.

  2. Go to the Client scopes tab.

  3. Click genian-ztna-cwp-dedicated.

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

  5. Select Group Membership to add group information.

    • Name: Enter "group membership"
    • Token Claim Name: Enter "groups"
    • Full group path: 'Off' (include only group names)
    • Add to ID token: Check 'On'
    • Add to access token: Check 'On'
    • Add to userinfo: Check 'On'
    • Click the Save button.

Authentication Integration Testing Method

Testing from Genian ZTNA Web Console (SP-initiated SSO)

  1. Access the Web Console and click the Test button in Preferences > User Authentication > Authentication Integration > Authentication Test.
  2. In the popup window, select OIDC as the authentication information store.
  3. In the Provider selection screen, select the configured "Keycloak" Provider.
  4. A Keycloak authentication page will be displayed in a new popup window.
  5. Enter Keycloak username and password to authenticate.
  6. If the 'Authentication successful' message is displayed, the authentication integration was successful.

Testing from Genian ZTNA CWP Page (SP-initiated SSO)

  1. Set the authentication method of the node policy's authentication policy to OIDC.
  2. Access the Genian ZTNA CWP page.
  3. Click the Authentication button on the CWP page.
  4. On the authentication screen, click the authentication button ("Sign in with Keycloak") configured in Step 4 above.
  5. A Keycloak authentication page will be displayed in a new popup window.
  6. Enter Keycloak username and password to authenticate.
  7. Upon successful authentication, JWT ID Token and Access Token are received, user information is extracted, and you are logged into ZTNA CWP.

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 endpoint networks