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

# OAuth User Management

> GermainUX supports OAuth 2.0 and OpenID Connect authentication, letting users access the Germain Workspace through an existing identity provider.

Service
`Authentication`

Availability
8.6.0 or later

> **[Integration benefits](#integration-benefits)**
>
> What the integration offers

> **[Before You Begin](#before-you-begin)**
>
> Gather identity provider details

> **[OAuth Provider Settings](#oauth-provider-settings)**
>
> Endpoints and client values

> **[Validate the Configuration](#validate-the-configuration)**
>
> Testing with a standard user

**OAuth and OpenID Connect User Management**

GermainUX supports OAuth 2.0 and OpenID Connect authentication, allowing users to access the Germain Workspace through an organization’s existing identity provider.

## Integration benefits

This integration can provide:

| Feature | Details |
| - | - |
| Enterprise single sign-on | Enterprise single sign-on |
| Centralized user administration | Centralized user administration |
| Identity-provider-controlled authentication policies | Identity-provider-controlled authentication policies |
| Multi-factor authentication when enforced by the provider | Multi-factor authentication when enforced by the provider |
| Group-to-Role mapping | Group-to-Role mapping |
| Centralized access revocation | Centralized access revocation |

> [!NOTE]
>
> **Note:** OAuth 2.0 provides authorization, while OpenID Connect adds user authentication and identity claims. GermainUX uses the information returned by the configured provider to identify the user and determine their Roles.

## Supported Providers

GermainUX can integrate with compatible OAuth 2.0 and OpenID Connect providers.

Provider-specific guides are available for:

| Provider | Configuration Guide |
| - | - |
| **Okta** | [Okta User Management](https://docs.germainux.com/main/okta-oauth-integration-with-germain.md) |
| **PingFederate** | [PingFederate OIDC](https://docs.germainux.com/main/ping-federated-oidc.md) |
| **PingID** | [PingID User Management](https://docs.germainux.com/main/pingid.md) |

Other compatible identity providers can also be configured using the general OAuth provider settings.

## Before You Begin

Obtain the following information from your identity-provider administrator:

| Item | Details |
| - | - |
| Client ID | Client ID |
| Client secret, when using a confidential client | Client secret, when using a confidential client |
| Authorization endpoint | Authorization endpoint |
| Token endpoint | Token endpoint |
| User-information endpoint | User-information endpoint |
| JSON Web Key Set endpoint | JSON Web Key Set endpoint |
| Required scopes | Required scopes |
| Username or identity claim | Username or identity claim |
| Group or Role claim | Group or Role claim |
| Supported token-signing algorithm | Supported token-signing algorithm |
| Required redirect URI | Required redirect URI |

The exact settings depend on the selected identity provider.

## Configure the Identity Provider

Before configuring GermainUX:

**1. Create or select the GermainUX application in the identity provider**

**2. Enable OAuth 2.0 or OpenID Connect authentication**

**3. Configure the GermainUX redirect URI**

**4. Assign the users or groups allowed to access GermainUX**

**5. Configure the claims required for the username and Role mapping**

**6. Record the client credentials and provider endpoints**

The commonly used GermainUX redirect URI template is:

```text theme={null}
{baseUrl}/login/oauth2/code/{registrationId}
```

Use the exact redirect URI generated for your GermainUX environment when configuring the identity provider.

## Configure GermainUX

**1. Log in to the Germain Workspace as an administrator**

**2. Go to System > Auth Settings > Authentication**

**3. Click Add New Configuration**

**4. Select OAuth Provider**

**5. Click Next**

**6. Configure the provider settings**

**7. Click Finish**

**8. Restart the relevant GermainUX services if required**

## OAuth Provider Settings

| Field | Description |
| - | - |
| **Provider Name** | Unique name identifying the provider. This name may appear as a login option. |
| **Client ID** | Client identifier issued to GermainUX by the identity provider. |
| **Client Secret** | Secret issued for a confidential client. Store and protect it as a credential. |
| **Authorization Grant Type** | OAuth flow used for authentication, typically `authorization_code`. |
| **Redirect URI Template** | GermainUX callback URI to which the provider returns the user. |
| **Authorization URI** | Provider endpoint that authenticates and authorizes the user. |
| **Token URI** | Provider endpoint that exchanges the authorization code for tokens. |
| **User Info URI** | Provider endpoint that returns information about the authenticated user. |
| **JWK Set URI** | Provider endpoint containing the public keys used to validate signed tokens. |
| **User Name Attribute** | Claim used to identify the GermainUX user, such as `email` or `sub`. |
| **JWS Algorithm** | Algorithm used to validate signed tokens when required by the provider. |
| **Role List Path** | Claim path containing the user’s groups or Roles. |
| **Scopes** | OAuth or OpenID Connect scopes requested by GermainUX. |
| **Use PKCE** | Enables Proof Key for Code Exchange when required or supported. |

## Users and Groups

Create and manage users in the external identity provider.

To grant access to GermainUX:

**1. Assign the user to the GermainUX application in the identity provider**

**2. Add the user to the appropriate identity-provider groups**

**3. Ensure the required group or Role claims are included in the returned identity data**

**4. Create matching Roles in GermainUX**

**5. Assign the required permissions to those Roles**

To review GermainUX Roles, go to:

**Germain Workspace > Left Menu > System > Auth Settings > User Roles**

Role names and the values returned by the identity provider must match when group-to-Role mapping is used.

## Log In

After the provider is configured, the GermainUX login page displays a corresponding login option.

To sign in:

**1. Open the GermainUX login page**

**2. Select the configured OAuth or OpenID Connect provider**

**3. Complete the provider’s authentication process**

**4. Complete multi-factor authentication if required**

**5. After successful authentication, the provider redirects the user to the Germain Workspace**

GermainUX applies the Roles returned or mapped from the provider to determine the user’s permissions.

![OAuth User Management: Log In](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/oauth-user-management/Screenshot-2022-12-15-at-11.08.12.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=a1f56e6a8d63a75d5f3d5df9ea50a02b)

## Validate the Configuration

Test the integration with a non-administrator account.

Confirm that:

| Check | Result |
| - | - |
| The provider appears on the GermainUX login page | The provider appears on the GermainUX login page |
| The redirect URI works correctly | The redirect URI works correctly |
| Valid users can authenticate | Valid users can authenticate |
| Unauthorized users are rejected | Unauthorized users are rejected |
| The expected username is returned | The expected username is returned |
| Groups map to the correct GermainUX Roles | Groups map to the correct GermainUX Roles |
| Users can access only authorized features and data | Users can access only authorized features and data |
| Logout and subsequent login behave as expected | Logout and subsequent login behave as expected |

## Troubleshooting

If authentication fails:

**1. Verify that the redirect URI exactly matches the URI configured with the provider**

**2. Confirm the client ID and client secret**

**3. Verify the authorization, token, user-information, and JWK endpoints**

**4. Confirm that the required scopes and claims are returned**

**5. Check that the username and Role claim paths are correct**

**6. Verify that matching Roles exist in GermainUX**

**7. 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 logs, and return the package to its normal logging level afterward.

## Get Help

> **[Contact GermainUX Support](https://docs.germainux.com/main/support.md)**
>
> The Germain Team can help you set this up.

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