Keycloak Using OIDC

This article provides step-by-step instructions to integrate the OvalEdge application with Keycloak using OpenID Connect (OIDC)-based Single Sign-On (SSO). The integration enables centralized authentication through Keycloak while OvalEdge continues to manage internal access control.

Purpose

The objectives of this guide are to:

• Enable secure OIDC-based SSO authentication for OvalEdge users.

• Centralize identity and access management using Keycloak as the Identity Provider (IdP).

• Simplify user provisioning and implement role-based access control.

Process Overview

This guide covers the following high-level steps:

1. Access the Keycloak Admin Console.

2. Create a new Realm.

3. Register OvalEdge as an OIDC Client.

4. Configure client credentials and redirect URIs.

5. Create roles and users.

6. Assign roles to users.

7. Configure client scopes and mappers.

8. Retrieve OpenID Endpoint Configuration.

9. Update OvalEdge configuration files.

10. Restart services and verify authentication.

Prerequisites

• Access to the Keycloak Admin Console.

• Administrator credentials for Keycloak.

• OvalEdge application URL.

• Access to the OvalEdge server (VM).

• Access to the Tomcat directory and environment files.

Steps

Access the Keycloak Admin Console

• Open the Keycloak Admin Console in a browser.

• Log in using valid administrator credentials.

• Use the Realm dropdown to view and manage realms.

Create a New Realm

• Click Create Realm.

• Enter a unique name for the new realm.

• Click Create.

  
• Confirm the realm appears in the Realm dropdown.

Configure a Client for OvalEdge

• Select the newly created realm.

• Navigate to Clients and click Create Client.

  
• Enter the following details:

  • Client Type: OpenID Connect

  • Client ID: oe-keycloak (example; use a meaningful identifier)

  • Name and Description: Provide descriptive names.

    
• Click Next.

Capability Config:

• Enable Client Authentication.

• Set Authentication Flow to Standard Flow.

  
• Click Next.

Login Settings:

• Root URL: https://client.ovaledge.com/ovaledge

• Home URL: https://client.ovaledge.com/ovaledge

• Redirect URIs: https://client.ovaledge.com/ovaledge/oauth2/code/keycloak

  

Note:

• Do not include /login at the end of the URL.

• Replace client.ovaledge.com with the actual domain.

• Use only specific redirect URIs for security.

• Click Save to complete client creation.

Manage Client Credentials

• Navigate to Clients and select the created Client ID.

• Go to the Credentials tab.

• Set Client ID and Secret as the Client Authenticator.

  
• Click Save to generate the client secret.

• Record the generated Client Secret for later use.

Create Roles

• Navigate to the Roles tab.

• Click Create Role.

  
• Enter the role name (e.g., OE_ADMIN).

• Optionally add a description.

  
• Click Save.

Create Users and Assign Roles

• Navigate to Users and click Add User.

  
• Fill in the required details and click Create.

• Open the created username to access User Details.

• Go to the Role Mappings tab.

  
• In Client Roles, select the relevant client.

  
• Assign the created role (e.g., OE_ADMIN) and click Assign.

  

Configure Client Scopes

• Navigate to Client Scopes.

  
• Select the predefined Roles client scope.

• In Settings:

  • Enable Include in token scope.

  • Ensure First Name, Last Name, and Email Address are included.

    
• Click Save.

Enable Client Role Mappers

• Navigate to the Mappers tab.

• Select or create role mappers for the client.

  
• Set Client ID to oe-keycloak.

• Enable Add to ID token for relevant mappers.

  
• Save the configuration.

Obtain OpenID Endpoint Configuration

• Navigate to Realm Settings.

• Under the Endpoints tab, click OpenID Endpoint Configuration.

  
• Copy the base URL up to /openid-connect.

  
• Save this URL for OvalEdge configuration.

Configure OvalEdge

• Log in to the OvalEdge Application VM.

• Open the oasis.properties file in the extprop folder.

• Update or add the following values:

  • Client ID: from Keycloak client setup.

  • Client Secret: from Keycloak client credentials.

  • OIDC base URL: from the OpenID Endpoint Configuration.

    
• Save and close the file.

Tomcat Configuration:

• Navigate to the Tomcat bin folder.

For Linux:

• Edit setenv.sh.

• Add:

  -DOVALEDGE_SECURITY_TYPE=oauth2

  
• Save and close the file.

For Windows:

• Open tomcat9w.exe.

• Go to the Java tab.

• Add:

  -DOVALEDGE_SECURITY_TYPE=oauth2

  
• Click Apply and OK.

Restart Services:

• Restart the Tomcat service.

• Wait 2–4 minutes.

• Open the OvalEdge application in a browser.

  

Validate Integration:

• Click Login with Keycloak.

• Enter the Keycloak username and password.

  
• Upon successful authentication, it will be redirected to the OvalEdge home page.

  

---

Copyright © 2025, OvalEdge LLC, Peachtree Corners, GA, USA.