PingCentral

Configuring the OpenID provider

PingCentral is an OpenID relying party for browser-based single sign-on (SSO), as well as an OAuth 2 resource server when directly accessing the admin API.

PingCentral has been tested with PingFederate 9.2.x, 9.3.x, 10.0.x and 10.1.x, serving as both the OpenID provider and OAuth 2 authorization server. This section provides tips for integrating PingCentral into an existing OpenID Connect (OIDC) 1.0 SSO infrastructure using PingFederate as the OpenID provider.

As long as an OpenID provider is able to provide the endpoints and claims required by PingCentral (most notably the username and role), other OpenID Connect 1.0 providers, can also be used.

To configure the OpenID provider:

  1. Configure the Access Token Manager (ATM) for PingCentral.

  2. Configure the OIDC policy for PingCentral.

  3. Configure the OAuth client for PingCentral.

This section doesn’t provide all of the details of setting up access token managers, OIDC policies, or attribute contracts because these topics are complex and often specific to a customer environment.

Configuring the Access Token Manager for PingCentral

About this task

The access token manager associated with the OIDC Policy must support signed JSON Web Token (JWT) tokens. To validate the token signature, PingCentral must be able to access a JSON Web Key Set (JWKS) endpoint URL in PingFederate. See Configuring JSON-token management in the PingFederate Server guide for additional information.

Signing certificates and JSON Web Encryption (JWE) encryption (symmetric or asymmetric) are not currently supported.

Steps

  1. In PingFederate, go to Applications → OAuth → Access Token Management and click Create New Instance.

  2. On the Instance Configuration tab, add one or more symmetric keys, signing certificates, or both.

    1. Click Add a new row to…​ or click Update to modify an existing entry.

      The Key ID field values must be unique across all JSON-token management instances, including child instances.

    2. If you have not yet created or imported your certificate into PingFederate, click Manage Signing Certificates and complete the task.

      To use an RSA-based algorithm for JSON Web Signature (JWS), the key size of the signing certificate must be at least 2,048 bits. For an EC-based JWS algorithm, the key size depends on the chosen algorithm.

  3. On the Instance Configuration tab, select the Use Centralized Signing Key option.

    This image displays this option with this description:

  4. Select Show Advanced Fields and specify the path in the JWKS Endpoint Path field. This setp is optional when an algorithm is selected in the JWE Algorithm list.

    This image displays this option with this description: Path on PingFederate server to publish a JWKS with the keys and certificates that the partners can use for signature verification. If specified, the path must begin with a forward slash, such as /oauth/jwks. The resulting URL is https://<pf_host>:<pf.https.port>/ext/<JWKS Endpoint Path>. The path must be unique across all plugin instances, including any child instances.

    This path must be explicitly configured in PingCentral. See Configuring resource server functionality.

  5. If you define either or both of the issuer or audience claim values within the access token manager, you can configure PingCentral to validate them.

    These claim values are also defined in the Issuer Claim Value andAudience Claim Value fields.

Configuring the OIDC policy for PingCentral

About this task

The OAuth client will be associated with an OIDC Policy, which could be the default policy. This policy must map an attribute into the expected claim to signify the user’s PingCentral role, which is defined in the Attribute Contract, Attribute Sources & User Lookup, and Contract Fulfillment in PingFederate.

In addition to the sub claim, the important claim is the PingCentral-Role claim. Optionally, you can also include the given_name and family_name claims with the profile scope.

You can fulfill the sub claim from the access token, and you need to fulfill the PingCentral-Role claim using an OGNL expression based on group memberships in your directory. The following is an example of an OGNL expression used in Contract Fulfillment to map roles.

// Reads the memberOf attribute values from the access token.
#pcrole = #this.get("memberOf"),
// If the values in memberOf contain the IAM administrator's group name, send 'IAM-ADMIN' in the claim value.
#pcrole ==null?"False":#this.get("memberOf").toString().contains("pingcentral-iamadmins")? "IAM-Admin":
// If the values in memberOf contain the application owner's group name, send 'Application-Owner' in the claim value or send 'NoAccess'.
#pcrole ==null?"False":#this.get("memberOf").toString().contains("pingcentral-appowners")? "Application-Owner" :"NoAccess"

memberOf must be in your access token contract or retrieved through a lookup for the expression to work.

If the default PingCentral role claim name and values need to be altered to match the OIDC policy, update the <PingCentral_install>/conf/application.properties file.

Configuring the OAuth client for PingCentral

Before you begin

Define a PingCentral-specific OAuth client. These steps explain how to configure PingFederate as the OpenID provider. See Configuring OAuth clients in the PingFederate Server guide for additional information.

Steps

  1. In PingFederate, go to Applications → OAuth → Clients.

  2. In the Client ID field, enter a unique identifier the client provides to the resource server (RS) to identify itself. This identifier is included with every request the client makes.

  3. In the Name field, enter a descriptive name for the client instance. This name appears when the user is prompted for authorization.

  4. In the Client Authentication field, select Client Secret, and manually enter a secret or click Generate Secret to have one created for you.

    You will also use this secret when you configure SSO for PingCentral. See Configuring SSO for details.

  5. In the Redirection URIs field, enter this URI: https://<pc-host>:<pc-port>/login/oauth2/code/pingcentral.

  6. Locate the Allowed Grant Types field and select Authorization Code.

  7. Optional: If you want API access with bearer tokens, locate the field and select the Resource Owner Password Credentials option.

    PingCentral doesn’t support ID token encryption.

  8. From the Default Access Token Manager list, select your access token manager.

  9. In the OpenID Connect section, from the ID Token Signing Algorithm list, select RSA using SHA-256. From the Policy list, select your OIDC policy.

  10. Click Save.