OvalEdge Open Authorization (OAuth2) Setup Guide

Open Authorization (OAuth2) is an industry-standard protocol that allows applications to access user data from other services securely, without exposing user credentials.

This document outlines the procedure for configuring OAuth 2.0 authentication for the OvalEdge application using Azure Active Directory (Azure AD).

Prerequisites

Before starting the configuration, ensure the following conditions are met:

• Azure AD Access: Administrative access to the Azure Portal with permissions to register and manage applications.

• OvalEdge Access: Administrative access to the OvalEdge application and its configuration files.

• Tomcat Knowledge: Familiarity with Tomcat server configuration (setenv.sh for Linux/Mac or setenv.bat for Windows).

• Domain Setup: The fully qualified domain name (FQDN) where OvalEdge is hosted (required for setting the Redirect URI).

Steps Involved

1. Register the Application in Azure AD

   • Log in to the Azure Portal.

   • Navigate to: Azure Active Directory > App registrations.

   • Select + New registration.

   • Enter a descriptive name for the application.

   • Choose the appropriate Supported account types according to organizational requirements.

   • In the Redirect URI section, select Web and enter:

     https://<domainname>/ovaledge/oauth2/code/azure

   • Click Register to complete the registration.

2. Capture Application Credentials

   • In the registered application’s Overview page, copy the following values:

     • Client ID

     • Tenant ID

   • Navigate to Certificates & secrets.

   • Under Client secrets, select + New client secret.

   • Provide a description and choose an expiration period.

   • Click Add, then copy and securely store the generated Client Secret (this value is displayed only once).

3. Configure OvalEdge Properties

   • Update the oasis.properties file in the OvalEdge installation directory with the following entries:

     spring.security.oauth2.client.registration.azure.clientId=<clientId>
     spring.security.oauth2.client.registration.azure.clientSecret=<clientSecret>
     spring.security.oauth2.client.registration=azure
     spring.security.oauth2.tenantId=<tenantId>

1. Enable OAuth2 in Tomcat

   • Configure Tomcat to enable OAuth2 authentication:

     • Linux/Mac

       export CATALINA_OPTS="-DOVALEDGE_SECURITY_TYPE=oauth2"

     • Windows

       SET CATALINA_OPTS="-DOVALEDGE_SECURITY_TYPE=oauth2"

       Restart the Tomcat server after applying the above changes.

2. Enable Hybrid Authentication Mode in OvalEdge

   • Hybrid mode ensures that OvalEdge continues to manage roles while integrating OAuth2 authentication.

     • Log in to OvalEdge > Configuration > SSO Tab.

     • Set the following parameter:

       ovaledge.saml.type=HYBRID

3. Verify OAuth2 Authentication

   • Open a browser and access the OvalEdge application URL.

   • Select Log in with Azure.

   • Enter valid Azure AD credentials.

   • Confirm successful login to verify the OAuth2 integration.

Error Handling and Troubleshooting

• Invalid Redirect URI: Ensure the Redirect URI configured in Azure AD exactly matches the domain name used by OvalEdge.

• Expired Client Secret: Renew the secret in Azure AD and update the oasis.properties file.

• Tomcat Startup Failure: Verify that CATALINA_OPTS is set correctly and does not conflict with other JVM options.

• Login Failure: Check the OvalEdge logs (catalina.out or application logs) for OAuth2-related errors.

---

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