--- title: Admin UI SSO authentication description: Configure single sign-on (SSO) for the administrative user interface in PingAccess. component: pingaccess version: 9.0 page_id: pingaccess:pingaccess_user_interface_reference_guide:pa_configuring_admin_ui_sso_authn_lp canonical_url: https://docs.pingidentity.com/pingaccess/9.0/pingaccess_user_interface_reference_guide/pa_configuring_admin_ui_sso_authn_lp.html revdate: December 12, 2025 section_ids: preparing-to-configure-admin-ui-sso-authn: Preparing to configure admin UI SSO authentication about-this-task: About this task steps: Steps choose-from: Choose from: configuring-admin-ui-sso-authentication: Configuring admin UI SSO authentication before-you-begin: Before you begin about-this-task-2: About this task steps-2: Steps choose-from-2: Choose from: choose-from-3: Choose from: troubleshooting: Troubleshooting --- # Admin UI SSO authentication Configure single sign-on (SSO) *(tooltip: \
\

The process of authenticating an identity (signing on) at one website (usually with a user ID and password) and then accessing resources secured by other domains without reauthenticating.\

\
)* for the administrative user interface in PingAccess. To enable SSO, you must complete several configuration steps within the OpenID Provider (OP) *(tooltip: \
\

In OAuth terms, an authorization server (AS). The OP/AS issues access tokens to protected resources for approved clients (relying parties). The clients use the access token to access the protected resources hosted by the OAuth resource server.\

\
)* 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](pa_configuring_authn_reqs_lists.html) to use the OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* 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: * [Configure PingFederate runtime](pa_configuring_a_standard_runtime.html). * [Configure PingOne](pa_configuring_p1.html). * [Configure OpenID connect](pa_configuring_oidc.html). 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](pa_importing_certificates.html). 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 OAuth clients](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_configuring_oauth_clients.html) 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://://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 [Defining issuance criteria for policy mapping](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/help_policymanagementtasklet_policyissuancecriteriastate.html) 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 `/pingfederate/bin/run.properties` file and setting the `pf.secondary.https.port` value to a port value. For more information, see [Configuring PingFederate properties](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_config_pf_propert.html). 2. Modify the `openid-configuration.template.json` file to add the `mtls_endpoint_aliases` object, with content defined by [RFC-8705](https://www.rfc-editor.org/rfc/rfc8705#name-metadata-for-mutual-tls-end). For more information about this file, see the [PingFederate documentation](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_customiz_openid_provid_config_endpoint_response.html). ## 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) *(tooltip: \
\

The authorizing service in an OAuth framework that issues and manages access tokens for clients to access protected resources.\

\
)* on the [Configuring PingFederate for PingAccess SSO](pa_pf_for_pa_sso_configuration.html) 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**, 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](pa_configuring_basic_authn.html). | 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) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)*. No additional information is needed. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The OAuth client *(tooltip: \
\

The application in an OAuth framework that requests access to resources. If the request is approved by the authorization server, the client is issued an access token for the resources.\

\
)* you use with PingAccess web sessions must have an OIDC policy specified. For more information, see [Configuring OpenID Connect Policies](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_configuring_oidc_policies.html). | 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. > **Collapse: Advanced settings** > > | Advanced Option | Description | > | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | **Scopes** | Configure your token provider to handle all 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** checkbox. 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** checkbox. The OpenID Connect Login Type must be set to Code for PingAccess to use PKCE. | > | **Max Login Retries** | Enter the maximum number of times PingAccess should retry a sign-on attempt after an authorization code exchange failure.To allow infinite retries, enter a value of `0`. To prevent PingAccess from retrying sign-on attempts, enter `-1`. The default value is `-1`.Applicable only when the **OpenID Connect Login Type** is **Code**. | > | **Login Retry Delay (Sec.)** | Enter the number of seconds PingAccess should wait before retrying a sign-on attempt after an authorization code exchange failure.The default value is `0`.Applicable only when the **OpenID Connect Login Type** is **Code** and a non-negative value is configured in the **Max Login Retries** field. Learn more in the previous step. | > | **Use Single-Logout** | To enable the use of single logout (SLO) *(tooltip: \
\

The process of signing a user out of multiple sites where the user has started a SSO session.\

\
)*, select the **Use Single-Logout** checkbox. 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** checkbox 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 checkbox 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. | > | **Revoke access token on logout** | Select the **Revoke access token on logout** checkbox to help prevent session replay if session validation and single logout aren't available with the token provider.Access token revocation should be compatible with any OIDC provider. Error messages are available in the PingAccess error log. When you enable this checkbox, PingAccess:- Sends an access token revocation request for the associated application to the token provider during sign off, per [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009.txt). This prevents potential bad actors from using stored cookies during future authorization requests when PingAccess must refresh the user attributes. > > - Clears user attributes from the local cache on the engine that received the sign-off request if the **Cache User Attributes** setting is enabled. | 9. (Optional) To enable role-based authorization: 1. Click the **Roles** tab. 2. To enable role-based authentication, select the **Enable Roles** checkbox. 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 > *\* > 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) *(tooltip: \
\

An open, cross platform protocol used for interacting with directory services.\

\
)* 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) *(tooltip: \
\

A name uniquely identifying an object within the hierarchy of a directory tree.\

\
)*. 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](https://www.rfc-editor.org/rfc/rfc1779) or [RFC 2253](https://www.rfc-editor.org/rfc/rfc2253). 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** checkbox. 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** checkbox. 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 You can find more information about what to do if you misconfigure admin UI SSO and get locked out in [Administrative SSO lockout](../troubleshooting/pa_admin_sso_lockout.html).