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

# PingID User Management

> The exact provider-side configuration depends on your organization’s PingID and PingFederate architecture.

Service
`Authentication`

Availability
2023.1 or later

> [card] [Prerequisites](#prerequisites)
>
> Details from Ping admins

> [card] [Configure GermainUX](#configure-germainux)
>
> Adding the Ping connection

> [card] [OAuth Provider Settings](#oauth-provider-settings)
>
> Endpoint paths behind gateways

> [card] [Troubleshooting](#troubleshooting)
>
> Diagnosing failed PingID logins

> [!NOTE]
>
> Integrate GermainUX with your organization’s Ping Identity environment to provide centralized authentication and single sign-on through OAuth 2.0 and OpenID Connect (OIDC).

The exact provider-side configuration depends on your organization’s PingID and PingFederate architecture. Contact GermainUX Support if you need assistance coordinating the configuration with your identity-management team.

## Prerequisites

Before configuring the integration, obtain the following information from your Ping Identity administrator:

| Requirement | Description |
| - | - |
| **Ping Identity domain** | Public domain through which GermainUX accesses the authentication endpoints. |
| **Client ID** | Identifier assigned to the GermainUX OAuth client. |
| **Client secret** | Secret assigned to the OAuth client, unless an approved public-client configuration is used. |
| **Redirect URI** | GermainUX callback URL registered with the provider. |
| **OAuth endpoints** | Authorization, token, UserInfo, and JWK Set URLs. |
| **Scopes** | Claims GermainUX is authorized to request. |
| **Username claim** | Claim that uniquely identifies the GermainUX user, typically `email`. |

## Configure Ping Identity

Create an OAuth/OIDC client for GermainUX in your Ping Identity environment.

Configure the client with the following settings:

| Setting | Value |
| - | - |
| **Grant type** | Authorization Code |
| **Redirect URI** | `{baseUrl}/login/oauth2/code/{registrationId}` |
| **Scopes** | `openid`, `profile`, `email`, and `roles` |
| **Username claim** | `email` |
| **PKCE** | Enable when required by your organization’s security policy. |

The redirect URI registered with Ping Identity must exactly match the URI generated by GermainUX.

Record the client ID, client secret, endpoint URLs, and supported scopes before proceeding.

## Configure GermainUX

### Set the Default Redirect Path

**1. Sign in to GermainUX as an administrator**

**2. Go to System > System Settings > Root Config (Advanced)**

**3. Navigate to:**

```text theme={null}
services > authentication
```

1. In **AuthenticationConfig**, set **Default Redirect Path** to the GermainUX Workspace URL.

   ![PingID User Management: Set the Default Redirect Path](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/pingid/2e989fcb-0b9f-4d67-a433-ec63ccdd5aa3.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=70ba151e71038d0a304027339d33841b)

For example:

```text theme={null}
/germainapm/workspace/app
```

### Add the OAuth Provider

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

**2. Click Add New Configuration**

**3. Select OAuth Provider**

**4. Click Next**

**5. Configure the provider using the settings below**

**6. Click Finish**

**7. Restart the Tomcat services to apply the configuration**

## OAuth Provider Settings

| Field | Value or description |
| - | - |
| **Provider Name** | A recognizable name, such as `PingID`. |
| **Client ID** | Client ID provided by the Ping Identity administrator. |
| **Client Secret** | Client secret provided by the Ping Identity administrator. |
| **Authorization Grant Type** | `authorization_code` |
| **Redirect URI Template** | `{baseUrl}/login/oauth2/code/{registrationId}` |
| **Authorization URI** | `https://<yourPingIDDomain>/fss/as/authorization.oauth2` |
| **Token URI** | `https://<yourPingIDDomain>/fss/as/token.oauth2` |
| **User Info URI** | `https://<yourPingIDDomain>/fss/idp/userinfo.openid` |
| **JWK Set URI** | `https://<yourPingIDDomain>/fss/pf/JWKS` |
| **User Name Attribute** | `email` |
| **JWS Algorithm** | Leave blank unless your Ping Identity administrator specifies an algorithm. |
| **Role List Path** | Leave blank unless roles are returned through a specific claim. |
| **Scopes** | `openid`, `profile`, `email`, `roles` |
| **Use PKCE** | Enable to require Proof Key for Code Exchange. |

The endpoint paths can vary when PingFederate is deployed behind a gateway or under a custom context path such as `/fss`. Confirm the URLs through your Ping Identity configuration or OpenID Provider metadata.

The standard PingFederate token endpoint is `/as/token.oauth2`, as documented in the official [PingFederate token endpoint reference](https://docs.pingidentity.com/pingfederate/13.1/developers_reference_guide/pf_token_endpoint.html).

## Public OAuth Clients and PKCE

A confidential OAuth client using a client secret is recommended for GermainUX server-side authentication.

If your organization requires a public OAuth client:

| Requirement | Details |
| - | - |
| Security approval | Confirm that the configuration is approved by your security team. |
| PKCE | Enable **Use PKCE**. |
| Client secret handling | Do not place a client secret in browser-side code or another publicly accessible location. |

## Validate the Integration

After restarting Tomcat:

**1. Open the GermainUX login page**

**2. Confirm that Login with PingID appears as an authentication option**

**3. Select the PingID option**

**4. Authenticate through your organization’s Ping Identity service**

**5. Confirm that you are redirected to the GermainUX Workspace**

**6. Verify that the correct GermainUX user and permissions are applied**

## Troubleshooting

If authentication fails, verify the following:

| Check | Details |
| - | - |
| The redirect URI matches exactly in Ping Identity and GermainUX. | Ensure exact match between configured URIs. |
| The client ID and client secret are correct. | Verify values recorded from the Ping Identity administrator. |
| The authorization and token endpoints are not identical. | Ensure distinct endpoint URLs for authorization and token exchange. |
| All configured endpoints are reachable from the GermainUX server. | Confirm network accessibility from the GermainUX server. |
| The requested scopes are authorized for the OAuth client. | Verify the OAuth client has the required scopes. |
| The UserInfo response contains the configured `email` claim. | Check UserInfo payload for the claim used as username. |
| The JWK Set endpoint is accessible. | Confirm the JWK Set URI responds and is reachable. |
| Tomcat was restarted after the configuration changed. | Restart Tomcat to apply changes. |
| The user is authorized to access the GermainUX OAuth client. | Ensure user authorization in Ping Identity for the client. |

For additional diagnostic information, enable `DEBUG` logging in the REST service for:

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

Attempt another login and review the REST service logs for redirect, token-exchange, signature-validation, or claim-mapping errors.

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