--- title: Managing users description: Instructions for managing your users, either directly through the PingCentral application, or by setting up SSO. component: pingcentral version: 3.1.1 page_id: pingcentral:pingcentral_for_iam_administrators:pingcentral_mng_users/pingcentral_mng_users canonical_url: https://docs.pingidentity.com/pingcentral/3.1.1/pingcentral_for_iam_administrators/pingcentral_mng_users/pingcentral_mng_users.html revdate: October 8, 2025 page_aliases: ["pingcentral_sso_pc.adoc", "pingcentral_mng_users_pc.adoc"] section_ids: managing-users-through-pingcentral: Managing users through PingCentral steps: Steps setting-up-sso-for-pingcentral: Setting up SSO for PingCentral pingcentral_sso: Configuring SSO for PingCentral enable_sso: 1. Enabling SSO for PingCentral conf_oidc: 2. Configuring OIDC for PingCentral example: Example: define_oath: 3. Defining the OAuth client for PingCentral example-2: Example: role_mapping: 4. Configuring PingCentral role mapping next-steps: Next steps resource: Configuring the resource server steps-2: Steps example-3: Example: next-steps-2: Next steps openid_provider: Configuring the OpenID provider configuring-the-access-token-manager-for-pingcentral: Configuring the Access Token Manager for PingCentral steps-3: Steps configuring-the-oidc-policy-for-pingcentral: Configuring the OIDC policy for PingCentral configuring-the-oauth-client-for-pingcentral: Configuring the OAuth client for PingCentral before-you-begin: Before you begin steps-4: Steps test_sso: Testing the SSO configuration before-you-begin-2: Before you begin steps-5: Steps result: Result access_api: Accessing the PingCentral API with SSO enabled before-you-begin-3: Before you begin steps-6: Steps example-4: Example: --- # Managing users You can set up PingCentral so users access the application through 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.\

\
)*, or you can set it up so users access the application directly through a sign-on page. ## Managing users through PingCentral If you have a small number of users, you might want to manually add them to PingCentral and manage their access directly through the application. You need their first and last names, usernames, and the roles they will assume. #### Steps 1. On the **Users** tab, click **Add User**. 2. Enter the username, first name, last name, and email address in the appropriate fields. 3. Select the user's role (either Application Owner or Administrator). Click **Next**. 4. Enter an initial password for the new user in the **Password** field. Passwords must be at least 8 characters long, contain one upper-case letter, one lower-case letter, and one number. 5. Enter it again in the **Confirm Password** field. Click **Save and Close**. The new user appears in the list of PingCentral users in alphabetical order. ![This example of an IAM Administrator's Users screen lists all of the users and displays details regarding each user when the associated expandable icon is clicked.](../_images/eyu1582753148828.png) 6. Update user information or delete a user by selecting the expandable icon associated with the user and clicking the pencil or delete icon. ## Setting up SSO for PingCentral The 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.\

\
)* method is significantly more secure than the password authentication method. At this time, 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.\

\
)* is used for SSO. To set up SSO: 1. [Configure SSO for PingCentral](#pingcentral_sso) 2. [Configure the resource server](#resource) 3. [Configure the OpenID provider](#openid_provider) 4. [Test the SSO configuration for PingCentral](#test_sso) You can also access the PingCentral API with SSO enabled using the OIDC protocol. Learn more in [Accessing the PingCentral API with SSO enabled](#access_api). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When SSO access to PingCentral is configured, administrators cannot assign applications to application owners before they access PingCentral. After application owners sign on to PingCentral, administrators can access their account information and assign applications to them. | **Auto-provisioned users** For each SSO user, a local PingCentral user is auto-provisioned the first time they sign on with information obtained from the subject (sub) claim provided by the OpenID provider. The user's first name, last name, and role are also recorded. PingCentral derives the user's name from the `given_name` and `family_name` claims defined by the profile scope. If first-time access to PingCentral is with API access using a bearer token, auto-provisioning occurs if the user's name and role are available. For performance reasons, subsequent bearer token access doesn't update the local user information, such as first name and last name. Although PingCentral administrators can modify or delete auto-provisioned users, doing so results in the SSO user being auto-provisioned again. Because the provisioning process generates a new PingCentral user ID, any application associations with the previous user ID will be lost. ### Configuring SSO for PingCentral With PingCentral, SSO is disabled by default. To configure PingCentral for SSO: 1. [Enable SSO](#enable_sso). 2. [Configure OIDC properties](#conf_oidc) to access OIDC configuration information. 3. [Define an OAuth client](#define_oath) as the OpenID provider. 4. [Configure PingCentral role mapping](#role_mapping). #### 1. Enabling SSO for PingCentral Enable SSO for PingCentral 1. Open the `/conf/application.properties` file. 2. Uncomment the following property and set the value to **true**. ``` pingcentral.sso.oidc.enabled=true ``` 3. Save the file. #### 2. Configuring OIDC for PingCentral Configure OIDC for PingCentral. 1. In the `/conf/application.properties` file, locate the `pingcentral.sso.oidc.issuer-uri` property, uncomment it, and define the Issuer URI. ##### Example: In this example, PingCentral attempts to access 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.\

\
)* configuration information at `https://sso.mycompany.com:9031/.well-known/openid-configuration`. ``` pingcentral.sso.oidc.issuer-uri=https://sso..com:9031 ``` 2. If PingCentral can't access the OIDC configuration information, it fails to start. Make sure the OpenID provider is running and accessible before starting PingCentral. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | In the future, if changes are made on the OpenID Provider that affect the OIDC configuration information used for SSO, you must restart PingCentral to incorporate them. | #### 3. Defining the OAuth client for PingCentral Define an OAuth client for PingCentral at the OpenID provider. 1. In the `/conf/application.properties` file, locate the following property, uncomment it, and provide the client ID and client secret for the OAuth client. ##### Example: ``` pingcentral.sso.oidc.client-id= pingcentral.sso.oidc.client-secret= ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------- | | | Secure the secret using the obfuscation script available in `bin/obfuscate`, and by using output ciphertext rather than the cleartext secret. | 2. Save the file. #### 4. Configuring PingCentral role mapping In PingCentral, two user roles are defined: the IAM Administrator, and the Application Owner. An initial IAM Administrator is created by default and can add other users to PingCentral and assign them to the appropriate role. When SSO is enabled, the OpenID Provider must indicate the PingCentral role with a claim defined in the ID token or UserInfo endpoint. If this claim isn't found, or its value is nonsensical, the user is denied access to PingCentral, and auto-provisioning doesn't occur. With PingFederate, an attribute can be mapped into the appropriate claim. To configure role mapping: 1. In the `/conf/application.properties` file, locate the following attributes and configure them for mapping into the appropriate claim. ``` # The name of the claim which identifies the PingCentral role associated with the user. #pingcentral.sso.oidc.role-claim-name=PingCentral-Role ``` ``` # The expected value of the role claim which indicates the user is a PingCentral administrator. #pingcentral.sso.oidc.role-claim-value-admin=IAM-Admin ``` ``` # The expected value of the role claim which indicates the user is a PingCentral application owner (non-administrator). #pingcentral.sso.oidc.role-claim-value-app-owner=Application-Owner ``` 2. If these default values can be used with the OpenID Provider, no further configuration is required. If the defaults can't be used with the OpenID Provider, set the claim name or values to synchronize PingCentral to the OpenID Provider configuration as shown. ``` pingcentral.sso.oidc.role-claim-name=UserRole pingcentral.sso.oidc.role-claim-value-admin=Admin pingcentral.sso.oidc.role-claim-value-app-owner=Developer ``` ##### Next steps Now, [configure the resource server](#resource). ### Configuring the resource server PingCentral supports OAuth *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)* resource server functionality by validating provided bearer tokens when accessing the Admin API. Only signed 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\.\

\
)* tokens are supported in this release, so a JSON Web Key Set (JWKS) endpoint is required to obtain the public keys for signature validation. If you are using PingFederate 10.1 or later, you can enable the centralized signing key functionality. Additional configuration isn't required in PingCentral to access the centralized JWKS endpoint. If the access token manager has been configured with an explicit JWKS endpoint path, you must also specify this path in PingCentral. | | | | - | ---------------------------------------------------------------------------------------------------------- | | | In PingFederate, this endpoint is exposed as https\://*\*:*\*/ext/*\*. | #### Steps 1. To provide the JWKS endpoint to PingCentral, open the `/conf/application.properties` file, uncomment the `pingcentral.sso.oidc.oauth-jwk-set-uri`property, and define the JWKS endpoint URI, as in this example. ##### Example: ``` pingcentral.sso.oidc.oauth-jwk-set-uri=https://sso.:9031/ext/oauth/pingcentral/jwks ``` 2. Configure the `username-claim` that PingCentral will use with bearer tokens. ``` pingcentral.sso.oidc.oauth-username-claim-name=UserId ``` With bearer tokens, PingCentral looks for the **Username** claim by default. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Although the subject (sub) claim is mandatory with 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.\

\
)*, it's not required when using OAuth 2. | 3. Configure PingCentral to validate the access token issuer and audience claim values defined in the access token manager. By default, these claims aren't validated. Validation for either or both is enabled by setting the following properties: * `pingcentral.sso.oidc.oauth-iss-claim-value=` * `pingcentral.sso.oidc.oauth-aud-claim-value=` 4. Make sure that the values specified match those defined in the access token manager. | | | | - | ------------------------------------------------ | | | If the values don't match, the validation fails. | | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------- | | | If a blank value is defined in PingFederate, the claim won't be present in the token, so do not enable the validation of that claim in PingCentral. | #### Next steps Now that the resource server is configured, [configure the OpenID provider](#openid_provider). ### Configuring the OpenID provider PingCentral is an OpenID relying party for browser-based 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 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.\

\
)* 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 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. * Step 1. Configuring the Access Token Manager * Step 2. Configuring the OIDC policy * Step 3. Configuring the OAuth client #### Configuring the Access Token Manager for PingCentral The access token manager associated with the OIDC policy must support signed 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\.\

\
)* tokens. To validate the token signature, PingCentral must be able to access a JSON Web Key Set (JWKS) endpoint URL in PingFederate. Learn more in [Configuring an access token management instance](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_configuring_access_token_management_instance.html) in the PingFederate documentation. | | | | - | ---------------------------------------------------------------------------------------------- | | | Signing certificates and JWT 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) *(tooltip: \
\

A signed instance of a JSON Web Token (JWT) based on IETF standard syntax and used for the exchange of signed content.\

\
)*, 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: Select this option to use a centralized key when signing JWTs using an RSA-based or EC-based algorithm.](../_images/ykq1601419120045.jpg) 4. Select **Show Advanced Fields** and specify the path in the **JWKS Endpoint Path** field. This setup 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](../_images/gry1601419191138.jpg) | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------- | | | This path must be explicitly configured in PingCentral. Learn more about this configuration in [Configuring the resource server](#resource). | 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** and**Audience Claim Value** fields. #### Configuring the OIDC policy for PingCentral 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 `/conf/application.properties` file. #### Configuring the OAuth client for PingCentral ##### Before you begin Define a PingCentral-specific 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.\

\
)*. These steps explain how to configure PingFederate as the OpenID provider. Learn more in [Configuring OAuth clients](https://docs.pingidentity.com/pingfederate/latest/administrators_reference_guide/pf_configuring_oauth_clients.html) in the PingFederate documentation. ##### 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 *(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 PingCentral. Learn more about this configuration in [Configuring SSO](#pingcentral_sso). 5. In the **Redirection URIs** field, enter this URI: `https://:/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**. ### Testing the SSO configuration Verify the security and functionality of your PingCentral SSO configuration through testing. #### Before you begin Before testing your SSO configuration for PingCentral: * Configure SSO within PingCentral * Set up the resource server * Establish the required settings for the OpenID provider #### Steps 1. Go to your PingCentral console URL (for example: `https://pingcentral.ad.jibboo.org:9022/pass/login`), and after redirection to PingFederate, sign on with your credentials. A **Request for Approval** window opens. The scopes listed in the window represent the permissions that PingCentral is requesting. These scopes determine what information PingCentral can access and use. 2. Select each check box to approve the scopes for the PingCentral client and click **Allow**. | | | | - | -------------------------------------------------------------------------------------------------------- | | | After testing is successful, you can set the approval window to **Bypass** in the OAuth client settings. | ![Screen capture of the Request for Approval window with the pingcentral\_client requesting permissions for three checked check boxes, Default, OpenID Connect Login, and Profile Access.](../_images/plt1697752459765.jpg) #### Result * If you test as an IAM administrator group member in PingCentral, you can access **Applications**, **Environments**, **Templates**, **Users**, and **Management**. * As an application owner group member, you can access **Applications** and **Management**. * If you tested as a user in neither group, an error message displays. ### Accessing the PingCentral API with SSO enabled Access PingCentral's API with enabled using the OIDC protocol. #### Before you begin Ensure you have an authorization server configured to authenticate users and issue access tokens. Learn more about this configuration in [Configuring the OpenID provider](#openid_provider). #### Steps To access the PingCentral API with SSO enabled: 1. Obtain an access token from the authorization server's response. This token will authorize your API requests. | | | | - | -------------------------------------------------------------------------------------------------------------------------- | | | The access token is a long string of characters and acts as your proof of authorization to access the requested resources. | 2. Include the access token in the API request's authorization header. The PingCentral API server will verify the token's validity, authenticity, and scopes to ensure the necessary permissions. ##### Example: ``` GET /api/resource HTTP/1.1 Host: pingcentral.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJhdWQiOiJhcGkiLCJpc3MiOiJpc3N1ZXIifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When SSO is enabled, local users defined within PingCentral and the default Administrator will not be able to access the application or access the Admin API using HTTP basic authentication. |