How to Set up OAuth Authentication

OAuth Authentication User Authentication

By default, OAuth login support is disabled. To enable it for Google or Facebook credentials, use the appropriate procedure below.

Notice:

If your server is behind a proxy, you must first configure the HTTP proxy.

Google

Register Oxygen Feedback Enterprise with Google:
1. To use Google’s OAuth 2.0 authentication system for login, you must set up a project in the Google API Console to obtain OAuth 2.0 credentials.
2. Follow the instructions on the OpenID Connect page, starting in the section, "Setting up OAuth 2.0".
  Step Result: You should have a new OAuth Client with credentials consisting of a Client ID and a Client Secret.
3. Configure the Oxygen Feedback Enterprise server to point to your newly registered application by adding the oauth.google.client.clientId and oauth.google.client.clientSecret properties in the config/feedback-oauth.properties file:
```
#### GOOGLE ####
oauth.google.client.clientId=google-client-id
oauth.google.client.clientSecret=google-client-secret
```
  Note:
  You need to substitute your client ID and client secret for the placeholder text shown in the example above.
Set the redirect URI. In the Set a redirect URI sub-section, ensure that the Authorized redirect URIs field is set to https://<your-app-base-url>/login/oauth2/code/google.
The OAuth redirect URI is the path in the application that the end-user is redirected back to after they have authenticated with Google and have granted access to the application on the OAuth consent screen page.

Facebook

Register Oxygen Feedback Enterprise with Facebook:
1. Configure your application’s client ID and client secret (you can obtain them by registering your application with Facebook at https://developers.facebook.com/).
2. Add the oauth.facebook.client.clientId and oauth.facebook.client.clientSecret properties in the $OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-home/config/feedback-oauth.properties file:
```
#### FACEBOOK ####
oauth.facebook.client.clientId=facebook-client-id
oauth.facebook.client.clientSecret=facebook-client-secret
```
  Note:
  You need to substitute your client ID and client secret for the placeholder text shown in the example above.
Set the redirect URI:
1. In the App Dashboard, choose your app and scroll to Add a Product.
2. Click Set Up in the Facebook Login card.
3. Select Settings in the left side navigation panel and under Client OAuth Settings, enter your redirect URL in the Valid OAuth Redirect URIs field for successful authorization.
4. Set the Valid OAuth Redirect URIs field to https://<your-app-base-url>/login/oauth2/code/facebook.

Custom OAuth Identity Provider

Important:

Upgrade notes - Starting with Oxygen Feedback 5.2.1:

The oauth.generic.userInfo.useIdToken property has been removed (see step 6).

If your OAuth provider supports OpenID Connect and you include the openid scope in oauth.generic.client.scope, you must now explicitly configure the following properties:
- oauth.generic.client.issuerUri - The base URL of the authorization server or realm.
- oauth.generic.client.jwksUri - The endpoint returning the public keys for ID token validation.
These settings are required to validate the identity token and complete the login process securely.
The Redirect URI form has been changed to: https://<your-app-base-url>/login/oauth2/code/generic (see step 3b).

To add Log in support for a custom OAuth Identity Provider, you need to configure the associated properties (oauth.generic.*) in the $OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-home/config/feedback-oauth.properties file as follows:

Enable the custom OAuth provider by setting the oauth.generic.enabled property to true.
Set a display name for the custom OAuth provider's associated button from the Log in page using the oauth.generic.name property. For example:
```
oauth.generic.name=My Identity Provider
```
Register Oxygen Feedback Enterprise as a client application with your custom OAuth Provider:
1. Obtain the OAuth2 credentials that consist of a Client ID and a Client Secret and set them as values for the oauth.generic.client.clientId and oauth.generic.client.clientSecret properties (respectively):
```
oauth.generic.client.clientId=generic-client-id
oauth.generic.client.clientSecret=generic-client-secret
```
  Note:
  You need to substitute your Client ID and Client Secret for the placeholder text shown in the example above.
2. Set the Redirect URI. In the Oxygen Feedback Client Configuration section of your OAuth provider, ensure that https://<your-app-base-url>/login/oauth2/code/generic is set as Authorized Redirect URI.
  Note:
  The OAuth Redirect URI is the path in the application that the end-user is redirected back to after they have authenticated with the custom OAuth Identity Provider and have granted access to the application on the OAuth consent screen page.
Configure the user Authorization Endpoint URI by setting the oauth.generic.client.userAuthorizationUri property according to your Identity Provider (refer to their user manual).
Note:
The Authorization URI is the URI that the user is to be redirected to for Oxygen Feedback Enterprise to be granted authorization.
Configure the Access Token Endpoint URI by setting the oauth.generic.client.accessTokenUri property according to your Identity Provider (refer to their user manual).
Note:
This is the endpoint that Oxygen Feedback Enterprise uses to request an access token from the custom Identity Provider.
If the identity provider supports the OpenID Connect (OIDC) protocol and you intend to use OIDC-based login by including the openid scope in the oauth.generic.client.scope property, then you must also configure the following additional properties:
```
oauth.generic.client.issuerUri
oauth.generic.client.jwksUri
```
- oauth.generic.client.issuerUri - Specifies the Issuer URI of the identity provider. This must point to the base URL of the OIDC-compliant authorization server (for example, a Keycloak realm URL such as http://localhost:8080/auth/realms/myrealm). This URI is used internally to validate ID tokens issued by the provider.
- oauth.generic.client.jwksUri - Specifies the full URL of the JSON Web Key Set (JWKS) endpoint exposed by the identity provider. This endpoint returns the public keys used to sign ID tokens. The Oxygen Feedback server uses this URI to verify the digital signature of the received ID token.
  For example (Keycloak):
```
http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/certs
```
If the custom OAuth Identity Provider supports Open ID Connect, and you include the openid scope in the oauth.generic.client.scope property, Oxygen Feedback Enterprise expects that the ID Token is available in the Access Token response under the id_token key (see https://openid.net/specs/openid-connect-core-1_0.html#TokenResponse).

The ID Token is decoded (as it is a JSON Web Token according to the Open ID specification) and the following information about the user is extracted:
- user's identifier
- user's display name
- user's email address
The names of the claims associated with that data can be specified using the properties listed in the next step (oauth.generic.userInfo.claims.id, oauth.generic.userInfo.claims.name, oauth.generic.userInfo.claims.email).

Important:

Starting with Oxygen Feedback 5.2.1, the oauth.generic.userInfo.useIdToken property has been removed.
Configure the User Info Endpoint URI by setting the oauth.generic.userInfo.uri property according to your Identity Provider (refer to their user manual).
Note:
This is the endpoint that Oxygen Feedback Enterprise uses to request information about the authenticated end user. The response should be returned as a set of claims in JSON format.
Oxygen Feedback Enterprise extracts the following informations from the user info response:
1. Email address - The name of the claim that contains the user's email address can be customized by setting the oauth.generic.userInfo.claims.email property. If not set, this property defaults to: email.
  Important:
  If Oxygen Feedback Enterprise cannot retrieve an email address for the authenticated user, the authentication process will fail.
2. User ID - The name of the claim that contains the user's ID can be customized by setting the oauth.generic.userInfo.claims.id property. If not set, this property defaults to: id.
3. User name - The name of the claim that contains the user's name can be customized by setting the oauth.generic.userInfo.claims.name property. If not set, this property defaults to: name.

Example: Keycloak Sample Configuration

############################### KEYCLOAK #######################
#### Custom OAuth Provider (other than Google or Facebook) ####
oauth.generic.enabled=true
## The OAuth Provider's name (used as label for the associated 'Log in' button)
oauth.generic.name=Keycloak
oauth.generic.client.clientId={oxygen-feedback-client-id}
oauth.generic.client.clientSecret={oxygen-feedback-client-secret}
oauth.generic.client.accessTokenUri={keycloak-server-base-url}/auth/realms/{keycloak-realm}/protocol/openid-connect/token
oauth.generic.client.userAuthorizationUri={keycloak-server-base-url}/auth/realms/{keycloak-realm}/protocol/openid-connect/auth
oauth.generic.client.scope=email, openid
# OIDC validation endpoints (required when using 'openid' scope)
oauth.generic.client.issuerUri={keycloak-server-base-url}/auth/realms/{keycloak-realm}
oauth.generic.client.jwksUri={keycloak-server-base-url}/auth/realms/{keycloak-realm}/protocol/openid-connect/certs
## User Info Properties
oauth.generic.userInfo.useIdToken=true
## The URI of the OAuth Provider's '/userinfo' endpoint
oauth.generic.userInfo.uri={keycloak-server-base-url}/auth/realms/{keycloak-realm}/protocol/openid-connect/userinfo
## The names of the claims in the JSON returned by the OAuth Provider's '/userinfo' endpoint
oauth.generic.userInfo.claims.id=sub
oauth.generic.userInfo.claims.name=name
## Mandatory - if an email address could not be obtained for the current user then the authentication process will fail
oauth.generic.userInfo.claims.email=email

You need to replace all placeholders ({xxx-xxx}) with their appropriate values. For more details about how to configure a client application on a Keycloak server, see https://www.keycloak.org/docs/latest/server_admin/index.html#oidc-clients.

Tip:

If your Keycloak server is configured to support OpenID Connect (OIDC), you can retrieve the necessary configuration values from the JSON file available at: {keycloak-server-base-url}/realms/{realm-name}/.well-known/openid-configuration

Example: Okta Sample Configuration

############################### OKTA ############################
### Custom OAuth Provider (other than Google or Facebook) ###
oauth.generic.enabled=true
# The OAuth Provider's name (used as label for the associated 'Log in' button)
oauth.generic.name=Okta
oauth.generic.client.clientId={oxygen-feedback-client-id}
oauth.generic.client.clientSecret={oxygen-feedback-client-secret}
oauth.generic.client.accessTokenUri=https://{yourOktaDomain}/oauth2/v1/token
oauth.generic.client.userAuthorizationUri=https://{yourOktaDomain}/oauth2/v1/authorize
oauth.generic.client.scope=openid profile email
# OIDC validation endpoints (required when using 'openid' scope)
oauth.generic.client.issuerUri=https://{yourOktaDomain}
oauth.generic.client.jwksUri=https://{yourOktaDomain}/oauth2/v1/keys
# User Info Properties
# The URI of the OAuth Provider's '/userinfo' endpoint
oauth.generic.userInfo.uri=https://{yourOktaDomain}/oauth2/v1/userinfo
# The names of the claims in the JSON returned by the OAuth Provider's '/userinfo' endpoint
oauth.generic.userInfo.claims.id=sub
oauth.generic.userInfo.claims.name=name
# Mandatory - if an email address could not be obtained for the current user then the authentication process will fail
oauth.generic.userInfo.claims.email=email

You need to replace all placeholders ({xxx-xxx}) with their appropriate values. For more details about how to configure a client application for Okta, see https://developer.okta.com/docs/guides/implement-auth-code/setup-app/.

Tip:

If your Okta domain supports OpenID Connect (OIDC), you can retrieve the necessary configuration values from the JSON file available at: https://{yourOktaDomain}/.well-known/openid-configuration

Example: Gitlab Sample Configuration

############################### GitLab ############################
### Custom OAuth Provider (other than Google or Facebook) ###
oauth.generic.enabled=true
# The OAuth Provider's name (used as label for the associated 'Log in' button)
oauth.generic.name=Gitlab
oauth.generic.client.clientId={oxygen-feedback-client-id}
oauth.generic.client.clientSecret={oxygen-feedback-client-secret}
oauth.generic.client.accessTokenUri={gitlab-base-url}/oauth/token
oauth.generic.client.userAuthorizationUri={gitlab-base-url}/oauth/authorize
oauth.generic.client.scope=openid
# OIDC validation endpoints (required when using 'openid' scope)
oauth.generic.client.issuerUri={gitlab-base-url}
oauth.generic.client.jwksUri={gitlab-base-url}/oauth/discovery/keys
# User Info Properties
# The URI of the OAuth Provider's '/userinfo' endpoint
oauth.generic.userInfo.uri={gitlab-base-url}/oauth/userinfo
# The names of the claims in the JSON returned by the OAuth Provider's '/userinfo' endpoint
oauth.generic.userInfo.claims.id=sub
oauth.generic.userInfo.claims.name=name
# Mandatory - if an email address could not be obtained for the current user then the authentication process will fail
oauth.generic.userInfo.claims.email=email

You need to replace all placeholders ({xxx-xxx}) with their appropriate values. For more details about how to configure a client application for GitLab, see https://docs.gitlab.com/ee/integration/oauth_provider.html.

Tip:

If your GitLab instance supports OpenID Connect (OIDC), you can retrieve the necessary configuration values from the JSON file available at: {gitlab-base-url}/.well-known/openid-configuration

Important:

For a user to be able to authenticate, they must have a Public email configured in their user profile settings.

Example: GitHub Sample Configuration

############################### GitHub ############################
### Custom OAuth Provider (other than Google or Facebook) ###
oauth.generic.enabled=true
# The OAuth Provider's name (used as label for the associated 'Log in' button)
oauth.generic.name=Github
oauth.generic.client.clientId={oxygen-feedback-client-id}
oauth.generic.client.clientSecret={oxygen-feedback-client-secret} 
oauth.generic.client.accessTokenUri=https://github.com/login/oauth/access_token
oauth.generic.client.userAuthorizationUri=https://github.com/login/oauth/authorize
oauth.generic.client.scope=read:user user:email
# User Info Properties
# The URI of the OAuth Provider's '/user' endpoint
oauth.generic.userInfo.uri=https://api.github.com/user
# The names of the claims in the ID Token or in the JSON returned by the OAuth Provider's '/user' endpoint
oauth.generic.userInfo.claims.id=id
oauth.generic.userInfo.claims.name=name
# Mandatory - if an email address could not be obtained for the current user then the authentication process will fail
oauth.generic.userInfo.claims.email=email

You need to replace all placeholders ({xxx-xxx}) with their appropriate values.

For more details about how to create a client application on GitHub, see https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app.

For more details about how to configure a client application for GitHub, see https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps.