PingID User Management | Germain Documentation

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

Sign in to GermainUX as an administrator.
Go to System > System Settings > Root Config (Advanced).
Navigate to:

services > authentication

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

For example:

/germainapm/workspace/app

Add the OAuth Provider

Go to System > Auth Settings > Authentication.
Click Add New Configuration.
Select OAuth Provider.
Click Next.
Configure the provider using the settings below.
Click Finish.
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.

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

Open the GermainUX login page.
Confirm that Login with PingID appears as an authentication option.
Select the PingID option.
Authenticate through your organization’s Ping Identity service.
Confirm that you are redirected to the GermainUX Workspace.
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:

com.germainsoftware.apm.auth.security

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

Service: Authentication

Feature Availability: 2023.1 or later