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 that 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 JSON Web Token (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 you want to include authentication requirements for your environment, 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 settings
    Advanced Option Description

    Scopes

    Configure your token provider to handle all of the requested scopes that 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 the attributes are integrity-protected to prevent changes, users can view any of your sensitive or confidential attributes if they can 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

    To periodically refresh user data from the OIDC token provider:

    1. 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 that you want to add.

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

    4. Select 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 that you use depends on the configuration of the Contract Fulfillment tab for the policy. Copy-paste your attribute value to ensure accuracy.

      For example, 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. In the Matching Strategy list, select the context that you want PingAccess to evaluate requests with when looking for a match.

      Case-Sensitive

      To register as a match, the attribute value in the request must be written in the same case as the attribute value that you specify in step 7. By default, PingAccess uses this matching strategy.

      Case-Insensitive

      Case doesn’t matter when looking for a match. Select this option for more flexibility if you might make changes to the attribute source that don’t alter it semantically.

      DN Matching

      Normalizes both the attribute value that you specify in step 7 and any attribute value that PingAccess gathers at runtime from the user identity attributes as an X.500 distinguished name (DN). PingAccess then looks for a match between the distinguished names.

      • If you select DN matching, make sure to select an Attribute Name in step 5 that can contain a DN. The administrative console doesn’t provide a warning if you select an invalid attribute type, but you can check your log files to confirm that you don’t have any DN-related errors.

      • PingAccess validates the Attribute Value that you specify in step 7 to make sure that it’s a valid X.500 DN that follows RFC-1779 or RFC-2253. Copy-paste the attribute value to ensure accuracy.

      • Relative DNs that have non-printable or non-UTF-8 string values, such as email and domain component (DC) relative DNs, are case-sensitive. Otherwise, relative DN values are case-insensitive.

    6. Optional: To add platform administrators:

      1. Select the Enable Platform Administrator Role check box.

      2. Select an Attribute Name, Matching Strategy, and Attribute Value for each required attribute.

      3. To add a new attribute, click Add Required Attribute.

    7. Optional: To add auditors:

      1. Select the Enable Auditor Role check box.

      2. Select an Attribute Name, Matching Strategy, and Attribute Value for each required attribute.

      3. To add a new attribute, click Add Required Attribute.

  10. Click Save.

Troubleshooting

For more information about what to do if you misconfigure admin UI SSO and get locked out, see Administrative SSO lockout.