.. _oidc-keycloak-adminconsole: 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. Recommended Versions -------------------- .. csv-table:: :header: Product Name (Component),Version,Notes :class: longtable :widths: 30 30 40 Genian ZTNA (Policy Server),V6.0 or higher,Release version after 2025.10 Keycloak,20.0 or higher,Integratable as of 2025.10 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Access the Keycloak Admin Console and log in with the administrator account. #. Click the **Realm selection** dropdown in the left menu and select **Create realm**. #. Enter Realm creation information. - **Realm name**: Enter "genian-ztna" - **Enabled**: Keep checked - Click the **Create** button. #. With the created Realm selected, click **Realm settings** in the left menu. #. In the **General** tab, verify the Realm basic settings. - **Require SSL**: Select "External requests" or "All requests" (HTTPS environment recommended) - **User registration**: Configure as needed (generally disabled) Step 2: Keycloak Client Creation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Click **Clients** in the left menu. #. Click the **Create client** button. #. 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. #. 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. #. In **Login settings**, enter the following: - **Root URL**: https://test.genians.net (ZTNA server domain) - **Home URL**: /mc2/ - **Valid redirect URIs**: - https://test.genians.net/mc2/faces/oidc/oidcCallback.xhtml - **Web origins**: https://test.genians.net - Click the **Save** button. #. Copy the **Client secret** from the **Credentials** tab of the created Client. - **Client secret** example: abc123def456ghi789jkl012mno345pq Step 3: Keycloak Users ^^^^^^^^^^^^^^^^^^^^^^ #. Click **Users** in the left menu. #. Click the **Create new user** button. #. 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. #. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Click **Groups** in the left menu. #. Click the **Create group** button. - **Name**: Must include the _ADMINROLE_ prefix and roleId (superAdmin) like "_ADMINROLE_superAdmin_ZTNA". - Click the **Save** button. #. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. 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. .. code:: json { "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. #. 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 | +----------------------------+-----------------------------+ #. 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" #. 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. #. Select the created Client in Keycloak Admin Console. #. Go to the **Client scopes** tab. #. Click **genian-ztna-adminconsole-dedicated**. #. In the **Mappers** tab, click **Add mapper** > **By configuration**. #. 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)** #. Access the Genian ZTNA Admin Console login page. #. Click the authentication button ("Sign in with Keycloak") configured in Step 4 above on the login screen. #. A Keycloak authentication page will be displayed in a new popup window. #. Enter Keycloak username and password to authenticate. #. 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 control policy permissions so that the authentication integration window is displayed even in a blocked state. .. code:: bash 1. How to add permissions 2. Policy > Objects > Network 3. Select Action > Create 4. Enter basic information 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 control policy that controls the admin console