> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta User Management

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

Service
`Authentication`

Availability
8.6.0 or later

> [card] [Configure Okta](#configure-okta)
>
> Setting up the identity provider

> [card] [Configure the Groups Claim](#configure-the-groups-claim)
>
> Mapping Okta groups to roles

> [card] [Configure GermainUX](#configure-germainux)
>
> Connecting the app settings

> [card] [Okta Provider 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](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/okta-oauth-integration-with-germain/image-20221209-132011.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=df738ad46f333e8e6baaa4acd319a62f)

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:

```text theme={null}
https://<germainux-host>:<port>/login/oauth2/code/<registration-id>
```

Example:

```text theme={null}
https://germain.example.com/login/oauth2/code/okta
```

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](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/okta-oauth-integration-with-germain/Screenshot-2022-12-21-at-13.12.53.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=1bc73a7b58b1b9f1edef4c26bf5b858a)

   Group Claim Filter for OpenID - GermainUX

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

```text theme={null}
Groups.startsWith("active_directory", "Group_Name", 100)
```

Adjust the expression to match your Okta and Active Directory configuration.

> [!NOTE]
>
> **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](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/okta-oauth-integration-with-germain/image-20230801-142352.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=4767640bb5e0d4b639a6a0673d3b02fc)

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

```text theme={null}
https://germain.example.com/germainapm/workspace/app
```

![Okta User Management: Configure the Default Redirect Path](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/okta-oauth-integration-with-germain/2e989fcb-0b9f-4d67-a433-ec63ccdd5aa3.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=f66feb335ca2a7802bf52825a287be91)

### Add the Okta Authentication Provider

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

   ![Select OAuth provider](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/okta-oauth-integration-with-germain/image-20221209-133232.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=4acd74851546c2e0243fd85bcfeb00ac)

   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

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

![Okta User Management: Okta Provider Settings](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/okta-oauth-integration-with-germain/Screenshot-2022-12-21-at-13.26.15.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=d09f1550458af71dc2cf1c7ef6b7820a)

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

```text theme={null}
https://example.okta.com
```

A confidential client with a protected client secret is recommended. When using a public client, configure [PKCE](https://oauth.net/2/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:

* 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](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/okta-oauth-integration-with-germain/image-20221209-150930.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=47b85e31af9983f891fa0fb155f4f1b1)

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

```text theme={null}
com.germainsoftware.apm.auth.security
```

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

## Get Help

> [card] [Contact GermainUX Support](https://docs.germainux.com/main/support.md)
>
> 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.

> [card] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.