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

      Integration with Keycloak Using SAML for SSO

      This article provides a detailed guide to integrate the OvalEdge application with Keycloak using SAML-based Single Sign-On (SSO). The integration leverages Keycloak as a centralized Identity Provider (IdP) for managing user authentication and authorization. While Keycloak handles authentication, OvalEdge continues to manage application-level permissions and role mappings internally.

      Purpose

      The primary objectives of this integration guide are to:

      • Enable secure SSO authentication for OvalEdge users through Keycloak.
      • Implement centralized access control using Keycloak’s Identity Provider configurations.
      • Streamline user and group management via Keycloak realms, clients, roles, and groups.
      • Enhance security by externalizing authentication logic and minimizing credential management within the application.

      Process Overview

      This guide outlines the following key steps for successful integration:

      1. Create and configure a new realm in Keycloak to logically isolate the OvalEdge environment.
      2. Register the OvalEdge application as a SAML client in Keycloak and define necessary parameters.
      3. Configure client scopes and mappers to pass required user attributes in SAML assertions.
      4. Create users and define roles (e.g., OE_ADMIN, OE_PUBLIC) in Keycloak.

      5. Group users to implement role-based access control and simplify role assignments.
      6. Configure the OvalEdge application to use the Keycloak SAML metadata URL and update the relevant property files.
      7. Restart application services to complete the integration and validate SSO functionality.

      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

      Step-by-Step Configuration

      1. Login to Keycloak

      1. Open the Keycloak Admin Console in a browser.
      2. Log in using valid administrator credentials.

      2. Create a Realm

      1. In the Keycloak Admin Console, click "Create Realm".
      2. Enter a Name for the realm (e.g., OvalEdgeRealm).
      3. Click Create.

      3. Switch to the Newly Created Realm

      1. In the top-left corner, use the dropdown to switch to the newly created realm.

      4. Create a Client

      1. In the left menu, navigate to Clients.
      2. Click Create Client.
      3. On the client creation page:
        • Client Type: Select SAML.
        • Client ID: Use the format http://<DNS or IP of OE App>/saml/metadata.
        • Name: Enter a name for the client (e.g., OvalEdgeSAMLClient).
      4. Click Next, then click Save.

      5. Configure Client Settings

      1. Navigate to Clients, and click the newly created Client ID.
      2. Under General Settings, keep the Client ID unchanged.
      3. In the Access Settings section:
        • Set Valid Redirect URI to:
          http://<DNS or IP of OE App>/ovaledge/saml/SSO
      4. Click Save.

      6. Configure Keys

      1. Navigate to the Keys tab.
      2. Disable the "Keys Signature Required" option.
      3. Click Save, if required.

      7. Create Roles

      1. Navigate to the Roles tab.
      2. Click Add Role, and create the following roles:
        • OE_ADMIN
        • OE_PUBLIC

      8. Configure Client Scopes and Mappers

      1. Navigate to Client Scopes > Assigned Client Scopes.
      2. Click "Add predefined mapper".
      3. Select the following mappers by name:
        • X500 Username
        • Role List
        • X500 Email
        • X500 givenName

      • Configure each mapper as per requirements (refer to UI screenshots for settings).
        • X500 Username
        • Role List
        • X500 Email
        • X500 givenName

          9. Configure Assertion Consumer URLs

          1. Go to the Advanced tab of the client configuration.
          2. Set the following URLs:
            • Assertion Consumer Service POST Binding:
              http://<OE App IP>:8080/ovaledge/saml/SSO
            • Assertion Consumer Redirect Binding URL:
              http://<OE App IP>:8080/ovaledge/saml/SSO
          3. Click Save.

          10. Create Users

          1. Navigate to Users > Add User.
          2. Fill in the required user details and click Create.
          3. After creation:
            • Go to the Credentials tab.
            • Set and save a Password.
            • Navigate to Role Mappings and click Assign Role.
            • Assign the user to OE_ADMIN or OE_PUBLIC role as needed.

            11. Create Groups

            1. Navigate to Groups > Create Group.
            2. Enter the group name (e.g., OE_ADMIN) and click Save.
            3. Click the created group name (OE_ADMIN)
            4. Navigate to the Members tab. Add the required users to the group.

              12. Configure Realm Settings

              1. Navigate to Realm Settings.
              2. Locate and copy the SAML Metadata URL.
              3. Set Require SSL to none.
              4. Paste the copied metadata URL into a text file for later use.

              13. Modify OvalEdge Configuration

              A. Edit oasis.properties File

              1. Navigate to the OvalEdge application VM.
              2. Go to the extprop directory.
              3. Open oasis.properties and update the following:
                • Set saml.metadata.url to the copied metadata URL.
                • Update entityBaseURL with the OvalEdge application base URL (e.g., http://<OE App IP>:8080/ovaledge).
              4. Save the file.

              14. Update Tomcat Environment Configuration

              For Linux

              1. Open setenv.sh in the Tomcat bin directory.
              2. Add the following line:
                -DOVALEDGE_SECURITY_TYPE=saml
              3. Save and close the file.

              For Windows

              1. Open tomcat9w.exe.
              2. Go to the Java tab.
              3. Add: -DOVALEDGE_SECURITY_TYPE=saml
              4. Click Apply and OK.

              15. Restart Tomcat and Validate Integration

              1. Restart the Tomcat service.
              2. Wait for 2–3 minutes.
              3. Open a browser and navigate to the OvalEdge application URL.
              4. Click Login.
              5. Enter the username and password created in Keycloak.
              6. You should be redirected and logged into the OvalEdge application via SSO.

                Conclusion

                By following the steps outlined in this guide, administrators can successfully integrate the OvalEdge application with Keycloak using SAML-based Single Sign-On (SSO). This integration enables centralized authentication, enhances security, and streamlines user and group management. With Keycloak managing identity and access control, and OvalEdge handling application-specific permissions, the setup provides a scalable authentication framework across systems.

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