GitHub OAuth Configuration

Introduction

OvalEdge is a data catalog that creates a comprehensive compilation of all the data sources in an organization for better data access and analysis. The OvalEdge application can be accessed with the regular user credentials provided by the OvalEdge administrator team, or it can be accessed through the GitHub user credentials. Here, the user accessing GitHub can also access the OvalEdge through the OAuth Configuration.

To access the OvalEdge application through GitHub, the following tasks need to be completed:

Create an OAuth App in the GitHub application
Configure the OAuth App in the GitHub application
Configure the OAuth Properties in the OvalEdge application
Enable the OAuth authentication in the OvalEdge application
Access to the OvalEdge application through GitHub

Creating an OAuth App

To create an OAuth App in the GitHub application, complete the following steps:

Enter the GitHub web address (https://github.com/) in the web browser; the GitHub home page is displayed.
On the GitHub home page, click on the Sign In button. The Sign in GitHub page is displayed.
In the Sign in GitHub page, enter the required username or email address and password in the respective Username or email address and Password fields.
Click on the Sign in button to validate the entered user credentials, and the GitHub home page is displayed.

Note: If the entered user credentials are invalid, an appropriate error message is displayed.
On the GitHub home page in the header menu, click on the User Profile icon, and the user profile settings dropdown is displayed.
In the user profile settings dropdown, select the Settings option. The Public profile home page is displayed.
In the public profile home page, click on the Public email field. The email address associated with the logged-in user is displayed in the Public email field. If the logged-in user's email address is not displayed in the Public email field, then click on the email settings hyperlink. The Emails page is displayed.
In the Emails page, uncheck the “Keep my email addresses private” checkbox. Here, the system will automatically update the email settings and set the user's email address as public.
To verify the email address as public, click on the Profile link. The Public Profile main page is displayed.
In the Public profile page, click on the Public email field. The email address associated with the logged-in user is displayed in the dropdown.
Select the email address from the Public email dropdown list and set it as public.

Note: By default, the logged-in user's First Name and Last Name are displayed in the Name field. Enter the user's first and last name if the name is not shown.
Click the Developer Settings link on the Public profile page in the left menu. The Developer Settings home page is displayed.
In the Developer Settings page, click on the OAuth Apps link. The OAuth Apps section is displayed on the right section of the page.
In the OAuth Apps section, click on the New OAuth App button. The Register a new OAuth application page is displayed.
On the Register a new OAuth application page, enter the following details:
1. Enter the name of the application in the Application Name textbox.
  Example: OvalEdge
2. Enter the homepage URL of the application in the Homepage URL textbox.
  Example: http://localhost:8080/ovaledge
3. Enter the description of the application in the Application description textbox.
  Example: OvalEdge OAuth
4. Enter the authorization callback URL in the Authorization callback URL textbox.
  Example: http://localhost:8080/ovaledge
  
  Note: All the mandatory fields in the Register a new OAuth application page are notified with a "*", without entering the details in the mandatory fields, if the user clicks on the Register application button, an appropriate error message is displayed.
After entering the details in the required fields, click on the Register application button, and the newly created application page is displayed.
In the newly created application page, verify the Client ID and Client secrets and capture the Client details; these details will be used in the OAuth Properties configuration.
If the Client secrets are unavailable, click the Generate a new client secret button. The Client secrets textbox is displayed.
In the Client secrets textbox, enter the required client secrets code and click the Generate a new client secret button. The entered client secrets code is generated, and the newly created application page is displayed.
After verifying the Client ID and Client secrets details, click the Update application button. The “application updated successfully” message will be displayed.

Configuring OAuth Properties

Complete the following steps to configure the OAuth Properties in the OvalEdge Application.

Open the “oasis.properties” file which is configured as externally.
/home/ovaledge/extprop/oasis.properties
In the above file modify the oasis properties as mentioned below.
Existing Properties:
spring.security.oauth2.client.registration.google.clientId=clientId
spring.security.oauth2.client.registration.google.clientSecret=clientSecret
spring.security.oauth2.client.registration=google

Modified Properties:
spring.security.oauth2.client.registration.github.clientId=clientId
spring.security.oauth2.client.registration.github.clientSecret=clientSecret
spring.security.oauth2.client.registration=github
spring.security.oauth2.client.registration.github.orgs=<Organization Name>
spring.security.oauth2.client.registration.github.scopes=user:email,read:org
Enter the Client ID and Client secrets captured from the newly created application page of GitHub in the respective clientId and clientSecret values.

Note:

- The oasis properties path varies from one Client to another Client, if the Client provides the external path for the oasis properties file, then the user should access the respective external path and modify the oasis properties.
- The spring.security.oauth2.client.registration.github.orgs should be provided with the organization names configured at GitHub. Here, multiple organization names can be included with comma-separated values, and the organization names provided under this property will be validated against the configured GitHub organization names.
- The spring.security.oauth2.client.registration.github.scopes should be provided with the user:email and read:org scopes to read the primary email address and organization details from GitHub.

Enable OAuth Authentication

Complete the following steps to enable the OAuth Authentication in the OvalEdge Application.

Navigate to the Tomcat bin folder and create or update the bat file using the command below.
Window
Update the setenv.bat to set CATALINA_OPTS="-DOVALEDGE_SECURITY_TYPE=oauth2"

Linux
Update the setenv.sh to export CATALINA_OPTS="-DOVALEDGE_SECURITY_TYPE=oauth2"
After updating the above configuration, restart the OvalEdge application.

Accessing the OvalEdge application

To access the OvalEdge application through GitHub, navigate to the OvalEdge Sign In screen, and the new option Continue with GitHub is displayed.
Click on Continue with GitHub on the OvalEdge Sign In screen, and the Sign In to GitHub login screen will be displayed. Here, the user can provide the required GitHub credentials and access the OvalEdge application.