Skip to main content
ServiceAuthentication
Availability8.6.0 or later

Configure Okta

Setting up the identity provider

Configure the Groups Claim

Mapping Okta groups to roles

Configure GermainUX

Connecting the app settings

Okta Provider Settings

Client type and domain values

​
GermainUX Okta integration

GermainUX can use Okta as an OAuth 2.0 and OpenID Connect identity provider, enabling users to access the Germain Workspace through enterprise single sign-on. The integration supports:
  • Okta-managed users
  • Centralized access control
  • Multi-factor authentication when enforced by Okta
  • Okta group-to-GermainUX Role mapping
  • Centralized access revocation

​
Before You Begin

You need:
  • Administrator access to Okta
  • Administrator access to GermainUX
  • The public URL of the GermainUX instance
  • An Okta OIDC or OAuth 2.0 application
  • The Okta client ID and client secret
  • The Okta groups that will map to GermainUX Roles
Okta User Management: Before You Begin
Ensure that the corresponding Roles already exist in GermainUX.

​
Configure Okta

​
Open the Application

1

Sign in to the Okta Admin Console

2

Go to Applications > Applications

3

Open the OIDC or OAuth 2.0 application used by GermainUX

4

Select the General tab

5

Locate the Login section

​
Configure the Redirect URI

Add the GermainUX sign-in redirect URI:
Example:
The redirect URI configured in Okta must exactly match the URI used by GermainUX, including:
  • Protocol
  • Hostname
  • Port, when applicable
  • Path
  • Registration identifier
  • Letter case

​
Record the Client Credentials

From the Client Credentials section, record:
  • Client ID
  • Client secret
These values are required when configuring the OAuth provider in GermainUX. Store the client secret securely and do not include it in documentation, email, or unsecured configuration files.

​
Configure the Groups Claim

GermainUX can use the groups returned by Okta to assign GermainUX Roles.
  1. Open the application’s Sign On tab.
  2. Locate the OpenID Connect ID Token configuration.
  3. Configure a groups claim.
  4. Ensure that the claim is named groups.
  5. Include the groups that must be mapped to GermainUX Roles.
    Group Claim Filter for OpenID

    Group Claim Filter for OpenID - GermainUX

​
Map Okta Groups

To include Okta-managed groups:

​
Map Active Directory Groups

When Okta is connected to Active Directory, an expression can be used to return selected AD groups. Example:
Adjust the expression to match your Okta and Active Directory configuration.
Security recommendation: Return only the groups required by GermainUX instead of exposing every group assigned to the user.
Okta User Management: Map Active Directory Groups

​
Configure GermainUX

​
Configure the Default Redirect Path

1

Log in to the Germain Workspace as an administrator

2

Go to System > System Settings > Root Config (Advanced)

3

Navigate to: monitoringConfig > systemConfig > authentication

4

Set defaultRedirectPath to the Germain Workspace URL

Example:
Okta User Management: Configure the Default Redirect Path

​
Add the Okta Authentication Provider

  1. Go to System > Auth Settings > Authentication.
  2. Click Add New Configuration.
  3. Select OAuth Provider.
    Select OAuth provider

    Select OAuth provider - GermainUX

  4. Click Next.
  5. Configure the provider.
  6. Click Finish.
  7. Restart the Tomcat services to apply the configuration.

​
Okta Provider Settings

Okta User Management: Okta Provider Settings
Replace <yourOktaDomain> with the organization’s Okta domain—for example:
A confidential client with a protected client secret is recommended. When using a public client, configure PKCE according to your organization’s security requirements.

​
Configure Role Mapping

The group names returned in the Okta groups claim must match Roles configured in GermainUX. To review or create Roles, go to: Germain Workspace > Left Menu > System > Auth Settings > User Roles For example: Confirm that:
  • Every required Okta group has a matching GermainUX Role
  • Role names use identical spelling and capitalization
  • Each Role contains the appropriate permissions
  • Users are assigned to the correct Okta groups

​
Log In with Okta

After the configuration is applied, the GermainUX login page displays an Okta login option.
  1. Open the GermainUX login page.
  2. Select Login with Okta.
  3. Authenticate through Okta.
  4. Complete multi-factor authentication if required.
  5. Okta redirects the user to GermainUX.
  6. GermainUX maps the returned groups to Roles and opens the Workspace.
    Okta User Management: Log In with Okta

​
Validate the Integration

Test the integration with a non-administrator account. Confirm that:
  • Login with Okta appears on the login page
  • The user is redirected to the correct Okta organization
  • Authentication completes successfully
  • The user’s email is returned as the username
  • Okta groups map to the expected GermainUX Roles
  • The user can access only authorized features and data
  • Users without access to the Okta application cannot enter GermainUX
  • Removing a user from an Okta group removes the corresponding GermainUX permissions

​
Troubleshooting

If Okta authentication fails:
1

Confirm that the redirect URI in Okta exactly matches the URI generated by GermainUX

2

Verify the client ID and client secret

3

Confirm that the Okta domain and endpoint URLs are correct

4

Verify that the requested scopes are enabled

5

Confirm that the groups claim is included in the returned user information

6

Verify the Role List Path

7

Confirm that matching Roles exist in GermainUX

8

Review the GermainUX REST service logs

For additional diagnostics, temporarily enable DEBUG logging for:
Reproduce the login attempt, review the REST service logs, and then restore the normal logging level.

​
Get Help

Contact GermainUX Support

The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

Can't find what you need?

Search all GermainUX docs with Ctrl + K, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.