To enable SSO, there are several configuration steps required within the OpenID Connect (OIDC) token provider and PingAccess that you must complete. You can expand a section to view those configurations. You can configure the administrative SSO option to require a specific authentication mechanism, leveraging the OIDC token provider Requested AuthN Context Selector using the PingAccess authentication requirements options.

  • The OIDC provider configuration must be completed. See the configuration instructions for your OIDC token provider:
  • The OIDC token provider server certificate must be imported into a trusted certificate group, and that trusted certificate group must be associated with the OIDC token provider runtime.
  • If you are using PingFederate, you must have a profile scope set up in PingFederate that includes the openid, profile, address, email, and phone scope values. For more information, see the PingFederate documentation for configuring an OAuth client.

If you are using PingFederate as the OIDC token provider, when you configure the client in PingFederate, use the following options:

  • The Client Authentication must be set to anything but None.
  • The Allowed Grant Types must be set to Authorization Code.
  • The Redirect URIs must include https://<PA_Admin_Host>:<PA_Admin_Port>/<reserved application context root>/oidc/cb. The default reserved application context root is /pa.
  • If you are not using administrative roles in PingAccess, the OIDC Policy should be set to a policy that uses issuance criteria to restrict access based on some additional criteria.
    Warning:

    If the selected OIDC policy does not use issuance criteria to limit which users can be granted an access token, all users in the associated identity store configured in PingFederate can authenticate to the PingAccess Admin console and make changes. For more information, see Identifying Issuance Criteria for Policy Mapping in the PingFederate Administrator's Manual.

If you are using PingFederate as the OIDC token provider and plan to use Mutual TLS, you must make two changes to the PingFederate configuration.

  • Enable the use of the secondary HTTPS port in PingFederate by editing the <PF_HOME>/pingfederate/bin/run.properties file and setting the pf.secondary.https.port value to a port value. For more information, see the PingFederate documentation.
  • Modify the openid-configuration.template.json to add the mtls_endpoint_aliases object, with content defined by RFC-8705. For more information about this file, see the PingFederate documentation.

Use the SSO authentication page in PingAccess to enter the client ID for the OAuth client you created in the OIDC token provider.

Info:

Complete the configuration for connecting to the PingFederate OAuth authorization server on the PingFederate for PingAccess SSO configuration page and complete the steps below.

You can configure roles for UI users. Each role grants access to specific features.

  • The Administrator role has full access to the UI, unless the Platform Administrator role is enabled. If the Platform Administrator role is enabled, the Administrator cannot update authorization, user, or environment settings, but can use all other features.
  • The Platform Administrator role has full access to all features. This role can be used with the Administrator role to grant full access to most features without the possibility of accidental lockout, with only the Platform Administrator able to change authorization configurations.
  • The Auditor role can view the user interface but cannot change the configuration.
  1. Click Settings and then go to Admin Authentication > UI Authentication.
  2. In the Authentication Method section, select Single Sign-On.
    Tip:

    To define a fallback administrator authentication method if the OIDC token provider is unreachable, enable the admin.auth=native property in run.properties. This overrides any configured administrative authentication to basic authentication.

  3. In the OpenID Connect Login Type drop-down menu, select a sign-on type:
    • Code is the standard OIDC sign-on flow. This option is the default.
    • POST is a sign-on flow using the form_post response mode, which returns response parameters as application/x-www-form-urlencoded HTML form values.
    • x_post is a sign-on flow based on OIDC that passes claims from the provider through the browser using the implicit grant type.
  4. In the Client ID field, enter the unique identifier assigned when you created the PingAccess OAuth client within your OIDC token provider.
  5. Select a Client Credentials Type, then provide the information required for the selected credential type.

    This is required when configuring the Code sign-on type or if you enabled session validation.

    • Secret – Enter the Client Secret assigned when you created the OAuth relying party client in the token provider.
    • Mutual TLS – Select a configured Key Pair to use for Mutual TLS client authentication.
    • Private Key JWT – Select this option to use Private Key JSON web token (JWT). No additional information is needed.
    Info:

    The OAuth client you use with PingAccess web sessions must have an OIDC policy specified. For more information, see Configuring OpenID Connect Policies.

  6. Optional: If your environment requires an authentication requirements list, from the Authentication Requirements list, select a defined authentication requirements list or click Create to create a new list.
  7. Optional: In the Username Attribute Name field, enter the attribute from the ID token to be used as the display name in the user interface and included in the audit logs.
    If the attribute is not specified or cannot be found, the sub attribute is used.
  8. Optional: If you want to enable advanced settings, click Show Advanced and use one or more of the advanced options.
    Advanced OptionDescription
    Scopes

    To request one or more scopes from the OIDC token provider, select one or more scopes from the Scopes list. If you configured a token provider, published scopes are available to select from the list based on the selected Client ID. You can specify unverified scopes by typing the scope and clicking Use unverified scope "[scopename]".

    You must properly configure your token provider to handle all of the requested scopes you specify, including any custom scope values.

    Note:

    The user can access all attributes by examining browser traces. While they are integrity-protected to prevent changes, you can view any sensitive or confidential attributes should the user decode the ID Token's value.
    Validate Session To validate sessions with the configured PingFederate instance during request processing, in the Validate Session options, click Yes. This option is not supported by PingOne or third-party OIDC token providers.
    Refresh User Attributes To periodically refresh user data from the OIDC token provider, in the Refresh User Attributes options, click Yes and specify a Refresh User Attributes Interval in seconds.
    Cache User Attributes If you want PingAccess to cache user attribute information for use in policy decisions, click Cache User Attributes. When this option is disabled, user attribute information is encoded and stored in the session cookie.
    Enable PKCE If you want PingAccess to send a SHA256 code challenge and corresponding code verifier as a Proof Key for Code Exchange during the code authentication flow, click Enable PKCE.
    Note:

    The OpenID Connect Login Type must be set to Code for PingAccess to use PKCE.
    Use Single-Logout

    To enable the use of single logout (SLO), click Use Single-Logout. This option must be configured in the OIDC provider.

    Note:

    If you are using PingFederate as a token provider, you should enable the Check For Valid Authentication Session in the PingFederate access token management configuration to prevent session replay.
  9. Optional: If you want to enable role-based authorization, perform the following steps:
    1. Click the Roles tab.
    2. To enable role-based authentication, select Enable Roles.
    3. In the Administrator section, click Add Required Attribute as many times as you need.

      For a role to be granted, all configured attribute values must match.

    4. Enter an Attribute Name and Attribute Value for each required attribute.
      Note:

      If you are using PingFederate as a token provider, the attribute name is defined in PingFederate under OAuth Settings > OpenID Connect Policy Management > Your_Policy > Attribute Contact as an extension to the contract. The value you use depends on the configuration of the Contract Fulfillment tab for the policy.

      The attribute named group in your attribute contract can be mapped to an LDAP server attribute source that contains a groupMembership attribute. A valid group membership for the administrator might be the group cn=pingaccess-admins,o=myorg. In this example, you should use group as the Attribute Name and cn=pingaccess-admins,o=myorg as the Attribute Value.
    5. Optional: If you want to add platform administrators, select Enable Platform Administrator Role, then enter an Attribute Name and Attribute Value for each required attribute. Click Add Required Attribute to add a new attribute.
    6. Optional: If you want to add auditors, select Enable Auditor Role, then enter an Attribute Name and Attribute Value for each required attribute. Click Add Required Attribute to add a new attribute.
  10. Click Save.
If you misconfigure Admin UI SSO and are locked out, see Administrative SSO lockout for information about regaining access.