Integration
      Back to home
      1. Knowledge Base
      2. Installation and System Setup
      3. Integration

      OvalEdge Integration with Keycloak Using OIDC

      This article provides a comprehensive guide to integrating the OvalEdge application with Keycloak using OpenID Connect (OIDC)-based Single Sign-On (SSO). This integration enables centralized authentication through Keycloak while allowing OvalEdge to control internal access.

      Purpose

      The purpose of this document is to:

      • Enable secure OIDC-based SSO authentication for OvalEdge users.
      • Centralize identity and access management using Keycloak as the Identity Provider (IdP).
      • Facilitate streamlined user provisioning and role-based access control.

      Process Overview

      The integration process consists of 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.

      Step-by-Step Procedure

      Step#1: Accessing the Keycloak Admin Console

      1. Log in to the Keycloak Admin Console using valid credentials.
      2. Click the Realm dropdown to view and manage existing realms.

      Step#2: Creating a New Realm

      1. Click Create Realm.
      2. Enter a unique name for the new realm.
      3. Click Create to finalize.
      4. The new realm will appear in the Realm dropdown.

      Step#3: Configuring a Client for OvalEdge

      1. Select the newly created realm.
      2. Navigate to Clients and click Create Client.
      3. Configure the client with the following details:
        • Client Type: OpenID Connect
        • Client ID: oe-keycloak (example; use a meaningful identifier)
        • Name and Description: Provide descriptive names.
      4. Click Next to continue.

      Capability Config:

      • Enable Client Authentication.
      • Set Authentication Flow to Standard Flow.
      • Click Next to proceed to the Login settings.

      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.
      • Only use specific redirect URIs for security.

      • Click Save to complete client creation.

      Step#4: Managing Client Credentials

      1. Navigate to the Clients page and click the created Client ID.
      2. Go to the Credentials tab.
      3. Select Client ID and Secret as the Client Authenticator.
      4. Click Save to generate the client secret.
      5. Note down the generated Client Secret for later use in OvalEdge.

      Step#5: Defining Roles

      1. Go to the Roles tab within the realm.
      2. Click Create Role.
      3. Enter the role name, e.g., OE_ADMIN.
      4. Optionally, provide a description.
      5. Click Save.

      Step#6: Creating Users and Assigning Roles

      1. Navigate to the Users section and click Add User.
      2. Fill in the user details and click Create.
      3. Click on the username to open User Details.
      4. Go to the Role Mapping tab.
      5. In the Client Roles section, select the relevant client.
      6. Assign the previously created role (e.g., OE_ADMIN) by clicking Assign.

       

      Step#7: Configuring Client Scopes

      1. Go to the Client Scopes section.
      2. Select the predefined Roles client scope.
      3. In the Settings tab:
        • Enable Include in token scope.
        • Ensure First Name, Last Name, and Email Address are included.
      4. Click Save.

      Step#8: Enabling Client Role Mappers

      1. Go to the Mappers tab.
      2. Select or create role mappers for the client.
      3. Choose Client ID as oe-keycloak.
      4. Enable Add to ID token for the relevant mappers.
      5. Save the configuration.

      Step#9: Obtaining OpenID Endpoint Configuration

      1. Navigate to Realm Settings.
      2. Under the Endpoints tab, click OpenID Endpoint Configuration.
      3. Copy the base URL up to the /openid-connect path.
      4. This will be required for OvalEdge's OIDC configuration.

      Step#10: OvalEdge Configuration

      1. Log in to the OvalEdge Application VM.
      2. Open the oasis.properties file located in the extprop folder.
      3. 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
      4. Save and close the file.
      5. Navigate to the Tomcat bin folder:
        • For Linux: Edit setenv.sh
        • For Windows: Use tomcat9w.exe
          Add the following Java option: -DOVALEDGE_SECURITY_TYPE=oauth2
      6. Save the changes.
      7. Restart the Tomcat service.
      8. Wait 2–4 minutes and access the OvalEdge application.
      9. Click Login with Keycloak.
      10. Enter the username and password created in Keycloak.
      11. Upon successful authentication, you will be redirected to the OvalEdge home page.

      Conclusion

      By following this structured guide, administrators can successfully integrate OvalEdge with Keycloak using OIDC-based SSO. This integration centralizes user authentication, improves security, and simplifies identity and access management across the enterprise. OvalEdge will leverage Keycloak as the trusted Identity Provider while maintaining its own internal access control mechanisms.

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