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

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*).<br>

3. **Configure OvalEdge Properties**
   * Update the `oasis.properties` file in the OvalEdge installation directory with the following entries:

     ```properties
     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>
     ```

4. **Enable OAuth2 in Tomcat**

   * Configure **Tomcat** to enable OAuth2 authentication:
     * **Linux/Mac**

       ```bash
       export CATALINA_OPTS="-DOVALEDGE_SECURITY_TYPE=oauth2"
       ```
     * **Windows**

       ```cmd
       SET CATALINA_OPTS="-DOVALEDGE_SECURITY_TYPE=oauth2"
       ```

       <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>Restart the Tomcat server after applying the above changes.</p></div>

5. **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
       ```

6. **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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ovaledge.com/deployment-and-maintenance/authentication-setup/ovaledge-open-authorization-oauth2-setup-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.