Keycloak (OIDC) - Web Console

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

For administrator authentication, the Genian NAC 6.0 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 NAC 6.0 Web Console administrator privileges

  • Network connection (communication between Genian NAC 6.0 ↔ Keycloak server)

Purpose of Integration

Genian NAC 6.0 and Keycloak integration provides the following benefits:

  • No need to manage separate administrator databases for NAC 6.0 and Keycloak authentication.

  • Administrators can authenticate to NAC 6.0 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 NAC 6.0 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 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

  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 NAC 6.0 Admin Console"

    • Description: Enter "Genian NAC 6.0 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".

    • Click the Save button.

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

    • Assign users to apply to the _ADMINROLE_superAdmin group.

Step 5: Genian NAC 6.0 OIDC Configuration

  1. In Genian NAC 6.0 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"

    • User ID Claim (Optional) - Enter the OIDC claim name for user identification. (e.g. email, sub, preferred_username, cognito:username, oid)

      • If not set, preferred_username and email are checked in that order.

      • If set, the configured claim is checked first, then preferred_username and email if the value is not found.

      • For Keycloak, preferred_username or email is recommended

    • 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 NAC 6.0.

    • In NAC 6.0 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 NAC 6.0 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.

        Management Role

        Value

        superAdmin

        _ADMINROLE_superAdmin

  3. Enter the text to display on the Keycloak authentication button in Login Button Text that will be shown on the Genian NAC 6.0 Admin Console login screen.

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

  4. Click the Update button at the bottom of the Genian NAC 6.0 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 NAC 6.0.

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 NAC 6.0 Admin Console Page (SP-initiated SSO)

  1. Access the Genian NAC 6.0 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 NAC 6.0 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.

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