PingIntelligence

Configuring Dashboard sso.properties for PingFederate

To complete the Dashboard’s single sign-on (SSO) authentication, configure the <installation_path>/pingidentity/webgui/sso.properties file.

The following table describes the SSO properties.

Property Description

pi.webgui.sso.oidc.provider.issuer-uri

Configure the URI of the OpenID Connect (OIDC) service provider (PingFederate). For example, pi.webgui.sso.oidc.provider.issuer-uri=https://pf_installed_host:9031.

The Dashboard retrieves the PingFederate OpenID Provider configuration using the following URL: <pi.webgui.sso.oidc.provider.issuer-uri>/.well-known/openid-configuration.

This is a mandatory property.

pi.webgui.sso.oidc.client.id

Configure the OIDC client ID. The default value is PingIntelligence. Make sure to configure the same value in PingFederate. If you want to change the default value, change the client ID in PingFederate as well. For more information, see Configuring an OAuth client in PingFederate for PingIntelligence Dashboard SSO.

This is a mandatory property.

pi.webgui.sso.oidc.client.secret

Set the client secret value in plain-text of the OAuth client created for the Dashboard application in PingFederate. The secret value is obfuscated in the Dashboard. The default value configured in sso.properties is changeme.

This is a required property only if the value of the property pi.webgui.sso.oidc.client.authentication-method is not set to NONE.

pi.webgui.sso.oidc.client.authentication-method

Configure the OIDC client authentication method. The possible values are:

  • BASIC - Basic authentication header based client authentication

  • POST - Client credentials sent in POST body for authentication

  • NONE - Client does not authenticate itself

The default value is BASIC.

If Client Authentication configuration in the OAuth client created in PingFederate is set to NONE, then use NONE for this property. If Client Authentication is set to CLIENT SECRET, use BASIC or POST. This is a mandatory property.

pi.webgui.sso.oidc.provider.user-uniqueid-claim-name

The value of this property should be the claim name that holds the unique value to identify the signed-on user. It provisions a new user in the Dashboard data source or updates the user if it already exists with updated claim, if any. The default value in the Dashboard is sub.

This is a mandatory property.

pi.webgui.sso.oidc.provider.user-first-name-claim-name

The value of this property should be the claim name that holds the first name of the signed-on user.

The default value for the claim is given_name.

If you configure any other non-standard claim to send the value of first name in UserInfo, the name of that claim should be configured in the Dashboard properties as follows.

pi.webgui.sso.oidc.provider.user-first-name-claim-name=my_first_name_claim

This is a mandatory property.

pi.webgui.sso.oidc.provider.user-last-name-claim-name

The value of this property should be a claim name that holds the last name of the signed-on user.

The default value for the claim is family_name.

If you configure any other non-standard claim to send the value of last name in UserInfo, the name of that claim should be configured in Dashboard properties as follows:

pi.webgui.sso.oidc.provider.user-last-name-claim-name=my_last_name_claim

This is a mandatory property.

pi.webgui.sso.oidc.provider.user-role-claim-name

The value of this property should be a claim name that holds the value of the role of the signed-on user.

The default value in the Dashboard is role.

If the user uses a different claim name in PingFederate to send the role value, the same should be updated in this property. For example, pi.webgui.sso.oidc.provider.user-role-claim-name=my_role_claim_name.

This is a mandatory property.

pi.webgui.sso.oidc.client.additional-scopes

The value of this property should be any additional scopes (comma separated) that need to be passed in the authorization request if required by the enterprise for retrieving the role claim. For example, pi.webgui.sso.oidc.client.additional-scopes=read, read_role.

Such scopes, if any, should be created in PingFederate and attached to the OAuth client created in PingFederate for the Dashboard and configured to return the role claim for authorization in the Dashboard. This is not a mandatory property.

Example

The following is a sample snippet of sso.properties.

## PingIntelligence WebGUI SSO properties file
# This is in standard java properties file format
# comments are denoted by number sign (#) as the first non blank character
# multiline values are ended with '\' as end of line

# OIDC Provider uri
# WebGUI queries <issuer-uri>/.well-known/openid-configuration to get OIDC provider metadata
# issuer ssl certificate is not trusted by default. So import issuer ssl certificate into config/webgui.jks
# issuer should be reachable from both back-end and front-end
 pi.webgui.sso.oidc.provider.issuer-uri=https://localhost:9031

# OIDC Client id
pi.webgui.sso.oidc.client.id=PingIntelligence

# OIDC Client secret
# This can be empty
 pi.webgui.sso.oidc.client.secret=OBF:AES:BcB3MOE/K+VAa579oBpky4PrIo4z9LnI4vXsltqI=

# OIDC Client authentication mode.
# Valid values: BASIC, POST, and NONE
 pi.webgui.sso.oidc.client.authentication-method=BASIC

# claim name for unique id of the user in UserInfo response
# a new user is provisioned using this unique id value
 pi.webgui.sso.oidc.provider.user-uniqueid-claim-name=sub

# claim name for first name of the user in UserInfo response
# either first name or last name can be empty, but both should not be empty
 pi.webgui.sso.oidc.provider.user-first-name-claim-name=given_name

# claim name for last name of the user in UserInfo response
# either first name or last name can be empty, but both should not be empty
 pi.webgui.sso.oidc.provider.user-last-name-claim-name=family_name

# claim name for role of the user in UserInfo response
# valid values for roles are ADMIN,REGULAR
 pi.webgui.sso.oidc.provider.user-role-claim-name=role

# additional scopes in authorization request
# multiple scopes should be comma (,) separated
# openid,profile scopes are always requested
 pi.webgui.sso.oidc.client.additional-scopes=exclusive