Enabling OIDC-based authentication - PingFederate - 10.3

PingFederate Server

bundle
pingfederate-103
ft:publication_title
PingFederate Server
Product_Version_ce
PingFederate 10.3
category
Product
pf-103
pingfederate
ContentType_ce

You can enable 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.

Important:

All endpoints must be HTTPS.

  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.
    Note:

    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.
    Property Description
    client.id The client ID to communicate with the OpenID Provider (OP).

    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 suffice, 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.

  4. Restart PingFederate.