Skip to main content
ServiceAuthentication
Availability2023.4 or later

Configure PingFederate

Creating the OIDC client

OAuth Provider Settings

UserInfo endpoint path

Validate the Integration

Logging in after restart

Troubleshooting

Enabling auth debug logs
PingFederate OIDC Integration with GermainUX Integrate GermainUX with PingFederate using OpenID Connect (OIDC) to provide centralized authentication and single sign-on.

​
Prerequisites

Before beginning, ensure that you have:
  • Administrative access to PingFederate.
  • Administrative access to GermainUX.
  • The public URL of the GermainUX instance.
  • A PingFederate OAuth/OIDC client for GermainUX.
  • The client ID and client secret.
  • The required OIDC endpoint URLs.
  • The claims and group mappings used to assign GermainUX permissions.

​
Configure PingFederate

Create or update an OAuth/OIDC client for GermainUX in PingFederate. Configure the client with the following settings: The redirect URI configured in PingFederate must exactly match the URI configured in GermainUX:
Replace {baseUrl} with the externally accessible GermainUX URL and {registrationId} with the GermainUX OAuth provider registration ID. Configure the PingFederate OpenID Connect policy to return the claims required by GermainUX, including the user identifier and any groups used for role assignment. PingFederate exposes provider metadata through its OpenID Provider configuration endpoint. Use this metadata to confirm the authorization, token, UserInfo, and JWK endpoint URLs. Record the client ID, client secret, endpoint URLs, claim names, and signing algorithm before continuing.

​
Configure the Default Redirect Path

1

Sign in to GermainUX as an administrator

2

Go to System > System Settings > Root Config (Advanced)

3

Navigate to:

  1. Set DefaultRedirectPath to the GermainUX Workspace URL.
For example:

​
Add the OAuth Provider

1

Go to System > Auth Settings > Authentication

2

Click Add New Configuration

3

Select OAuth Provider

4

Configure the provider using the settings below

5

Click Finish

6

Restart Tomcat so that the authentication configuration takes effect

​
OAuth Provider Settings

The standard PingFederate UserInfo endpoint uses /idp/userinfo.openid. See the official PingFederate UserInfo endpoint documentation.

​
Additional Authorization Parameters

If PingFederate requires additional authorization parameters, append them to the authorization URI. For example:
The required acr_values value depends on the authentication policies configured in PingFederate.

​
Configure Role Mapping

Use Role List Path to identify the token or UserInfo claim containing the user’s groups. For example:
Ensure that:
  • PingFederate returns the configured group claim.
  • The returned group values correspond to roles configured in GermainUX.
  • Each user receives only the permissions required for their responsibilities.

​
Validate the Integration

After restarting Tomcat:
1

Open the GermainUX login page

2

Select the PingFederate authentication option, if displayed

3

Authenticate through PingFederate

4

Confirm that the user is redirected to the GermainUX Workspace

5

Verify that the username and assigned roles are correct

6

Confirm that the user can access only the permitted dashboards and features

Depending on the configured authentication policy and the user’s existing PingFederate session, authentication may occur automatically when the user accesses GermainUX.

​
Troubleshooting

If authentication fails, verify:
  • The redirect URI matches exactly in PingFederate and GermainUX.
  • The client ID and client secret are correct.
  • All endpoint URLs are reachable from GermainUX.
  • The configured JWS algorithm matches the algorithm used by PingFederate.
  • The ID token contains the expected sub claim.
  • The group claim matches the configured Role List Path.
  • The returned groups correspond to valid GermainUX roles.
  • The user is authorized to access the PingFederate application.
  • Tomcat was restarted after the configuration changed.
For additional diagnostic information, enable DEBUG logging for the following REST package:
Review the REST and Tomcat logs for authorization errors, token-validation failures, claim-mapping issues, or unreachable endpoints.

​
Security Recommendations

  • Use HTTPS for every authentication endpoint and redirect URI.
  • Store the client secret securely.
  • Enable PKCE where supported and required.
  • Return only the claims required by GermainUX.
  • Apply least-privilege access when mapping groups to roles.
  • Rotate client secrets according to your organization’s security policy.
  • Test authentication and authorization changes in a non-production environment first.

​
Get Help

Contact GermainUX Support

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.

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.