PingFederate OIDC | Germain Documentation

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

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

Setting	Configuration
Grant type	Authorization Code
Redirect URI	GermainUX OAuth callback URL
Scopes	`openid`, `profile`, `address`, `email`, and `phone`, as required
Subject claim	`sub`
Group claim	For example, `msad_groups`
Signing algorithm	For example, `ES256`

The redirect URI configured in PingFederate must exactly match the URI configured in GermainUX:

{baseUrl}/login/oauth2/code/{registrationId}

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

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

monitoringConfig > systemConfig > authentication

Set DefaultRedirectPath to the GermainUX Workspace URL.

For example:

https://germain.example.com/germainapm/workspace/app

Add the OAuth Provider

Go to System > Auth Settings > Authentication.
Click Add New Configuration.
Select OAuth Provider.
Configure the provider using the settings below.
Click Finish.
Restart Tomcat so that the authentication configuration takes effect.

📁 OAuth Provider Settings

Field	Recommended value or description
Provider Name	A unique name, such as `PingFederate`.
Client ID	Client identifier generated in PingFederate.
Client Secret	Client secret generated in PingFederate. Public clients without a secret are not recommended unless required by the deployment architecture.
Authorization Grant Type	`authorization_code`
Redirect URI Template	`{baseUrl}/login/oauth2/code/{registrationId}`
Authorization URI	`https://<pingfederate-host>/as/authorization.oauth2`
Token URI	`https://<pingfederate-host>/as/token.oauth2`
User Info URI	`https://<pingfederate-host>/idp/userinfo.openid`
JWK Set URI	`https://<pingfederate-host>/pf/JWKS`
User Name Attribute	`sub`
JWS Algorithm	The algorithm configured in PingFederate, such as `ES256`.
Role List Path	The claim containing the user’s groups or roles, such as `msad_groups`.
Scopes	`openid`, `profile`, `address`, `email`, and `phone`, as required.
Use PKCE	Enable when required by your organization’s OAuth security policy.

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:

https://<pingfederate-host>/as/authorization.oauth2?acr_values=R1_AAL1_MS-AD-Kerberos

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:

msad_groups

Ensure that:

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

Open the GermainUX login page.
Select the PingFederate authentication option, if displayed.
Authenticate through PingFederate.
Confirm that the user is redirected to the GermainUX Workspace.
Verify that the username and assigned roles are correct.
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:

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

com.germainsoftware.apm.auth.security

Review the REST and Tomcat logs for authorization errors, token-validation failures, claim-mapping issues, or unreachable endpoints.

🛡️ Security Recommendations

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

Service: Authentication

Feature Availability: 2023.4 or later