# 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.