PingFederate Server

Enabling OIDC-based authentication

You can enable OpenID Connect (OIDC)-based authentication to the administrative console by setting a property in the run.properties file, and by configuring other properties in the oidc.properties file.

About this task

All endpoints must be HTTPS.

Steps

  1. On your OIDC provider, configure an OAuth client to represent the PingFederate administrative console. Specify the following redirect URI for the client:

    https://<pf_admin_hostname>:<pf_admin_port>/pingfederate/app?service=finishsso

    or, if using pf.admin.baseurl:

    https://<pf.admin.baseurl>/pingfederate/app?service=finishsso

    You need the client’s credentials in the following steps.

  2. Edit the <pf_install>/pingfederate/bin/run.properties file, and set the pf.console.authentication property to OIDC.

    You might need to configure the pf.admin.baseurl property as well. This property defines the URL that PingFederate’s administrative node uses to populate resource references in Administrative API responses. The administrative node also uses it for the redirect URL it sends to an OpenID Provider for administrator OIDC login (for example, https://pingfederate-admin.example.com or, if the load balancer uses a custom port, https://pingfederate-admin.example.com:8443). The default value is blank.

    Use pf.admin.baseurl instead of pf.admin.hostname. If run.properties defines both, PingFederate ignores pf.admin.hostname. But if run.properties defines only pf.admin.hostname, PingFederate constructs the URL the same way it does in versions of PingFederate before 10.3.

  3. Edit the <pf_install>/pingfederate/bin/oidc.properties file, and modify the applicable properties as described in the following table.

    PingFederate begins to validate the properties defined in oidc.properties at start up. This will not include validations that PingFederate can only perform during run time, such as validating the value of issuer against the value of iss from an ID token.

    Incorrectly configured properties in oidc.properties can cause PingFederate to fail to start.
    Property Description

    client.id

    The client ID to communicate with the OpenID Provider.

    This property is required.

    client.secret

    The client secret used to communicate with the OpenID Provider.

    The client secret should be in obfuscated format. We recommend that the secret be obfuscated using one of the following utilities in the ../bin directory:

    • On Windows: obfuscate.bat

    • On Linux: ./obfuscate.sh

    For example: obfuscate.bat secret

    This property is required when the client authentication is either client_secret_basic or client_secret_post.

    client.authn.method

    The type of client authentication that is expected by the token endpoint in the OpenID Provider. Supported values include:

    • client_secret_basic – Client credentials using the HTTP Basic authentication scheme.

    • client_secret_post – Client Credentials included in the request body.

    • private_key_jwt – Client authenticates in accordance with JSON Web Token (JWT).

    This property is required.

    authorization.endpoint

    The authorization endpoint at the OpenID Provider.

    This property is required.

    token.endpoint

    The token endpoint at the OpenID Provider. PingFederate OIDC login only supports the authorization code flow.

    This property is required.

    user.info.endpoint

    The endpoint that is accessed when the required claims are not present in the ID tokens.

    This property is optional.

    end.session.endpoint

    The end session endpoint at the OpenID Provider. When no value is provided, the administrator will be redirected to the default PingFederate logout page.

    This property is optional.

    issuer

    The issuer identifier of the OpenID Provider. The value provided is matched with the iss claims in the obtained ID token.

    This property is required.

    acr.values

    The authentication context class reference values that will be used by the OpenID Provider.

    This property is optional.

    scopes

    The authorization endpoint at the OpenID Provider. The default setting is openid.

    This property is required.

    username.attribute.name

    The name of the claim that represents the username of the administrator. The default setting is sub.

    This property is required.

    role.attribute.name

    The name of the claim that is used to determine the role for administrators.

    This property is required.

    role.map.admin.n

    Used when multiple values need to be mapped to a single PingFederate role. In this case, multiple properties must be created using a numeric, incremental suffix, starting with 1. For example:

    role.map.admin.1=
role.map.admin.2=
role.map.admin.3=

    role.admin

    role.cryptoManager

    role.userAdmin

    role.expressionAdmin

    The administrator role claim value mapping. For example, assume that admin_role is a claim and the possible values for it are:

    role.admin=admin
role.cryptoManager=crypto
role.userAdmin=uadmin
role.expressionAdmin=eadmin

    When the claim admin_role has more than one value, for example, admin_role :["admin","crypto","uadmin"], the user will be granted admin, crypto, and user administrator roles.

    When the claim admin_role has a single value, for example, admin_role: "admin", the user will be granted admin role.

    This property is required.

    role.auditor

    The auditor role claim value mapping.

    This property is optional.

    Request parameters

    Optional custom properties that you can use to specify allowed incoming parameters and to define static values for outgoing parameters.

    The diagram below shows two examples of request parameter configurations. In the first configuration, the sign on request can override the default value. However, if the incoming request doesn’t provide a value, then the default value is passed to the OIDC provider. In the second configuration, the sign on request cannot override the default value.

    For more information, see the Request Parameters section of the oidc.properties file.
    Diagram of request parameter configurations
    Examples of request parameter configurations in the oidc.properties file

  4. Restart PingFederate.