.. _oidc-keycloak: 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. 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 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Access the Keycloak Admin Console (http://localhost:8080/admin) 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-users" - **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 (activate when allowing CWP user registration) Step 2: Keycloak Client Creation (for CWP) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. 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-cwp" - **Name**: Enter "Genian ZTNA CWP" - **Description**: Enter "Genian ZTNA User Portal 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**: /cwp2/ - **Valid redirect URIs**: - https://test.genians.net/cwp2/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: xyz987uvw654rst321opq098mno765lk Step 3: Keycloak User and Group Setup ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Click **Groups** in the left menu. #. Click the **Create group** button. #. Enter user group information. - **Name**: Enter "ztna-users" - **Description**: Enter "ZTNA general user group" - Click the **Create** button. #. Create an additional privilege group. (optional) - **Name**: Enter "ztna-vip-users" - **Description**: Enter "ZTNA VIP user group" - Click the **Create** button. #. Click **Users** in the left menu. #. Click the **Create new user** button. #. 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. #. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. 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. .. code:: json { "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. #. 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. #. 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" #. 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. #. Select the created Client ("genian-ztna-cwp") in Keycloak Admin Console. #. Go to the **Client scopes** tab. #. Click **genian-ztna-cwp-dedicated**. #. In the **Mappers** tab, click **Add mapper** > **By configuration**. #. 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)** #. Access the Web Console and click the **Test** button in **Preferences > User Authentication > Authentication Integration > Authentication Test**. #. In the popup window, select **OIDC** as the authentication information store. #. In the Provider selection screen, select the configured "Keycloak" Provider. #. A Keycloak authentication page will be displayed in a new popup window. #. Enter Keycloak username and password to authenticate. #. If the 'Authentication successful' message is displayed, the authentication integration was successful. **Testing from Genian ZTNA CWP Page (SP-initiated SSO)** #. Set the authentication method of the node policy's authentication policy to **OIDC**. #. Access the Genian ZTNA CWP page. #. Click the **Authentication** button on the CWP page. #. On the authentication screen, click the authentication button ("Sign in with Keycloak") configured in Step 4 above. #. 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, 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 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 endpoint networks