PingAccess

Admin UI SSO authentication

Configure single sign-on (SSO) for the administrative user interface in PingAccess.

To enable SSO, you must complete several configuration steps within the OpenID Provider (OP) and PingAccess.

If you’re using PingFederate as the token provider, you can configure the administrative SSO option to require a specific authentication mechanism. Configure PingAccess authentication requirements to use the OpenID Connect (OIDC) token provider’s Requested AuthN Context Selector.

Preparing to configure admin UI SSO authentication

About this task

Before you can configure admin UI SSO authentication, you must:

Steps

  1. Configure the OIDC provider.

    Choose from:

  2. Import the OIDC token provider server certificate into a trusted certificate group and associate that trusted certificate group with the OIDC token provider runtime.

    For more information, see Importing certificates.

  3. If you’re using PingFederate as the OIDC token provider, set up a profile scope in PingFederate that includes the openid, profile, address, email, and phone scope values.

    For more information, see Configuring an OAuth client in the PingFederate documentation.

    1. When you configure the client in PingFederate:

      • The Client Authentication must be set to anything except 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’re 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.

        If the OIDC policy you select doesn’t 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 administrative console and make changes.

        For more information, see Identifying Issuance Criteria for Policy Mapping in the PingFederate Administrator’s Manual.

    2. If you plan to use Mutual TLS, you must make two changes to the PingFederate configuration:

      1. Enable the use of the secondary HTTPS port in PingFederate by editing the <pf_install>/pingfederate/bin/run.properties file and setting the pf.secondary.https.port value to a port value. For more information, see the PingFederate documentation.

      2. Modify the openid-configuration.template.json file to add the mtls_endpoint_aliases object, with content defined by RFC-8705. For more information about this file, see the PingFederate documentation.

Configuring admin UI SSO authentication

Before you begin

If you’re using PingFederate as the token provider, complete the configuration for connecting to the PingFederate OAuth authorization server (OAuth AS) on the Configuring PingFederate for PingAccess SSO page.

About this task

You can configure roles for PingAccess administrative console 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 can’t 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 can’t change the configuration.

To configure admin UI SSO:

Steps

  1. Click Settings and then go to Admin Authentication → UI Authentication.

  2. On the Authentication Method page, click Single Sign-On.

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

  3. In the OpenID Connect Login Type list, select a sign-on type:

    Choose from:

    • Code (default): The standard OIDC sign-on flow.

    • POST: 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: 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. If you chose the Code sign-on type or want to enable session validation, select a Client Credentials Type from the following list, then provide the required information for the credential type you chose.

    Choose from:

    • Click Secret to use a client secret. In the Client Secret field, enter the client secret assigned when you created the OAuth relying party client in the token provider.

    • Click Mutual TLS to use Mutual TLS client authentication. In the Key Pair list, select a configured key pair to use for Mutual TLS client authentication.

    • Click Private Key JWT to use Private Key JWT. No additional information is needed.

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

  6. If your environment requires an authentication requirements list, then in 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 isn’t specified or can’t 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 Option Description

    Scopes

    Configure your token provider to handle all of the requested scopes you specify, including any custom scope values.

    • To request one or more scopes from the OIDC token provider, in the Scopes list, select one or more scopes.

      If you configured a token provider, published scopes are available to select in the list based on the selected Client ID.

    • To specify unverified scopes, enter the scope and click Use unverified scope "[scopename]".

      The user can access all attributes by examining browser traces. Although they’re 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, click Yes.

    This option is not supported by PingOne or third-party OIDC token providers.

    Refresh User Attributes

    1. To periodically refresh user data from the OIDC token provider, click Yes.

    2. Specify a Refresh User Attributes Interval in seconds.

    Cache User Attributes

    To have PingAccess cache user attribute information for use in policy decisions, select the Cache User Attributes check box.

    When this option is disabled, user attribute information is encoded and stored in the session cookie.

    Enable PKCE

    To have PingAccess send a SHA256 code challenge and corresponding code verifier as a Proof Key for Code Exchange during the code authentication flow, select the Enable PKCE check box.

    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), select the Use Single-Logout check box.

    You must configure this option in the OIDC provider.

    If you’re using PingFederate as a token provider, enable the Check For Valid Authentication Session in the PingFederate access token management configuration to prevent session replay.

    Include id_token_hint in SLO

    Select the Include id_token_hint in SLO check box to include the id_token_hint parameter in the SLO request that PingAccess makes to the token provider. Use Single-Logout must be selected too.

    The id_token_hint parameter contains the PingAccess session cookie’s id_token, which token providers can use to locate a user’s session. Some token providers might require this parameter, but not all.

    If this option is enabled, PingAccess tracks the id_token attribute. Tracking the id_token attribute increases the PingAccess cookie’s size. This could make the cookie exceed the browser’s limit. For more information, see Minimizing the PingAccess cookie size. PingAccess can also track the id_token attribute if the Track id_token check box is enabled, but this isn’t a prerequisite step to enabling Include id_token_hint in SLO. For more information on this configuration, see step 7c of Configuring OpenID Connect token providers.

  9. Optional: To enable role-based authorization:

    1. Click the Roles tab.

    2. To enable role-based authentication, select the Enable Roles check box.

    3. In the Administrator section, click Add Required Attribute for each attribute you want to add.

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

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

      If you’re 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 Lightweight Directory Access Protocol (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: To add platform administrators:

      1. Select the Enable Platform Administrator Role check box.

      2. Enter an Attribute Name and Attribute Value for each required attribute.

      3. Click Add Required Attribute to add a new attribute.

    6. Optional: To add auditors:

      1. Select the Enable Auditor Role check box.

      2. Enter an Attribute Name and Attribute Value for each required attribute.

      3. Click Add Required Attribute to add a new attribute.

  10. Click Save.

Troubleshooting

If you misconfigure admin UI SSO and are locked out, see Administrative SSO lockout for information about regaining access.