Breadcrumbs

Okta User Management

🔒 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:

Feature

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:

Requirement

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
image-20221209-132011.png


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:

https://<germainux-host>:<port>/login/oauth2/code/<registration-id>

Example:

https://germain.example.com/login/oauth2/code/okta

The redirect URI configured in Okta must exactly match the URI used by GermainUX, including:

Component

Protocol

Hostname

Port, when applicable

Path

Registration identifier

Letter case

🔑 Record the Client Credentials

From the Client Credentials section, record:

Credential

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.

    Screenshot 2022-12-21 at 13.12.53.png
    Group Claim Filter for OpenID - Germain UX

🔗 Map Okta Groups

To include Okta-managed groups:

Setting

Value

Group claim type

Filter

Claim name

groups

Filter

Matches regex .*

🖥️ Map Active Directory Groups

When Okta is connected to Active Directory, an expression can be used to return selected AD groups.

Example:

Groups.startsWith("active_directory", "Group_Name", 100)

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.

image-20230801-142352.png


🖥 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:

https://germain.example.com/germainapm/workspace/app
2e989fcb-0b9f-4d67-a433-ec63ccdd5aa3.png

plus Add the Okta Authentication Provider

  1. Go to System > Auth Settings > Authentication.

  2. Click Add New Configuration.

  3. Select OAuth Provider.

    image-20221209-133232.png
    Select OAuth provider - Germain UX

  4. Click Next.

  5. Configure the provider.

  6. Click Finish.

  7. Restart the Tomcat services to apply the configuration.

📇 Okta Provider Settings

Setting

Value

Provider Name

A descriptive name, such as Okta

Client ID

Client ID copied from Okta

Client Secret

Client secret copied from Okta

Authorization Grant Type

authorization_code

Redirect URI Template

{baseUrl}/login/oauth2/code/{registrationId}

Authorization URI

https://<yourOktaDomain>/oauth2/v1/authorize

Token URI

https://<yourOktaDomain>/oauth2/v1/token

User Info URI

https://<yourOktaDomain>/oauth2/v1/userinfo

JWK Set URI

https://<yourOktaDomain>/oauth2/v1/keys

User Name Attribute

email

JWS Algorithm

Leave blank

Role List Path

userInfo.claims.groups

Scopes

openid, profile, email, groups

Use PKCE

Enable when required or to enforce Proof Key for Code Exchange
Screenshot 2022-12-21 at 13.26.15.png

Replace <yourOktaDomain> with the organization’s Okta domain—for example:

https://example.okta.com

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:

Okta Group

GermainUX Role

germain_apm_admin

germain_apm_admin

germain_apm_user

germain_apm_user

Confirm that:

Check

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.

    image-20221209-150930.png

✅ Validate the Integration

Test the integration with a non-administrator account.

Confirm that:

Check

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

warning 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:

com.germainsoftware.apm.auth.security

Reproduce the login attempt, review the REST service logs, and then restore the normal logging level.

Service: Authentication

Feature Availability: 8.6.0 or later