Edit online

How to Set up OAuth 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/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/facebook.

Custom OAuth Identity Provider

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/oauth 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 custom OAuth Identity Provider supports Open ID Connect, you can extract information about the current user from the ID token provided by the identify provider's server by setting the oauth.generic.userInfo.useIdToken=true property (by default it is set to false).

If this property is set to true, 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).
Notes:
- For the ID Token to be included in the Access Token Response, most Identity Providers require that the openid scope be specified in the list of scopes for the Authorization Code Flow. This can be done using the oauth.generic.client.scope configuration property. For example:
```
oauth.generic.client.scope=email openid
```
- If the oauth.generic.userInfo.useIdToken property is set to true, then the value of the oauth.generic.userInfo.uri is ignored since a request to the associated /userinfo endpoint will not be performed.
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
## 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.

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={okta-base-url}/oauth2/v1/token
oauth.generic.client.userAuthorizationUri={okta-base-url}/oauth2/v1/authorize
oauth.generic.client.scope=openid profile email
# User Info Properties
# The URI of the OAuth Provider's '/userinfo' endpoint
oauth.generic.userInfo.uri={okta-base-url}/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/.

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

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