What is the PingOne for Customers Management API?
The PingOne for Customers Management API provides the interface to configure and manage your PingOne organization. The Management API includes the following endpoints.
PingOne uses an organization-based model to define tenant accounts and their related entities. The organization is the top-level identifier. It defines your entire enterprise within the PingOne for Customers platform.
For more information, see Organizations.
An organization contains one or more environments. Environments define separate working domains within an organization. Environments are used to model regions within a large global enterprise such as NA (North America), EU (European Union), or AP (Asia-Pacific). They are also used as the defining entity to segregate enterprise operations by functionality, staging environments, or configurations.
For more information, see Environments.
Environments contain the core resources on which all identity services are built. Environments encompass:
In PingOne, a population defines a set of users, similar to an organizational unit (OU). In a given environment, you can use populations to simplify the management of users. For example, you can create a population for similar types of users and apply a password policy to that population. You must create at least one population before you can create users. An individual user cannot belong to more than one population simultaneously, but users can be moved to a different populations.
For more information, see Populations.
Users are unique entities that interact with the applications and services within the environment to which the they are assigned. User resources in PingOne are the full representation of a user profile, including the user’s relationships, roles, devices, and attributes. Users are associated with populations rather than defined within a population. The user’s association with a population is established as a property on the user resource.
Applications and resources
Applications in PingOne define the connection between the PingOne for Customers platform and the actual application (also thought of as the client configuration). Resources represent the connections to external services, enabling secure access to PingOne resources and other defined external resources.
Activities are collections of user activity information such as login attempts, password reset attempts, and total active user counts. This audit data can be exported, reported on, or streamed out to customer security information and event management (SIEM) solutions.
For more information, see User activities.
Branding and images
Branding can be configured for elements of the PingOne interface. All end user interfaces are branded according to the theme defined in the associated branding resource. Image resources can be configured to upload custom branding image files to the content delivery network (CDN) and manage the lifecycle of those images.
These resources represent the password management actions and password policies that can be applied to users within an environment.
For more information, see Passwords.
These resources represent the sign-on workflow policies to establish an authentication flow during login, re-authentication, or registration actions that identify and verify users. The authentication workflows are part of the authentication API. The
signOnPolicyresource is a proxy back to other APIs to perform authentication actions.
These endpoints manage notification templates resources and notifications content.
Certificates and keys
The certificate management endpoints provide an implementation that supports FIPS 140-2 Level 1 compliant security algorithms to generate key pairs. They manage customer-provided certificates, customer-provided signing/encryption keys, Ping-generated certificates (PKI), and Ping-generated signing/encryption keys.
For more information, see Certificate management.
The identity provider endpoints manage external identity provider configurations to enable social login and inbound SAML login features in PingOne for Customers. An external identity provider configuration allows linked users to authenticate and gain access to PingOne resources using the login flow and credentials provided by the external identity provider. PingOne supports Facebook and SAML as external identity providers.
Roles and permissions
Roles and permissions are defined at the root of the platform. Roles are assigned to users, and these user roles include a
scope property to grant the user permissions corresponding to the role. For example, a role of Identity Admin contains permissions allowing the subject to read and edit user data. When this role is assigned to a user, it can be assigned with the scope property that identifies a population or an environment to which the permissions apply.
Self-service application permissions are described using scopes rather than roles. Scopes are more narrowly defined roles in that a scope cannot cross an environment boundary, and it is restricted to a specific task. For example, the
p1:read:user scope grants permission to read the user resource’s data only; it does not grant permission to read another user’s data or perform create, update, or delete operations on user resources.
The license resource identifies the organization that owns the license, the licensing package type, and the expiration date for the license.
For more information, see Licensing.
Active identity counts use authentication and password-evaluation user events to determine whether an identity is active within a specified sampling period. Total identity counts provide the number of unique identities associated with a specified environment per day.
Note to application developers
You can experience latency when creating resources across services in the PingOne for Customers multi-region architecture, where the newly created resource has not propagated through the system to allow for the successful completion of a follow-up request. For example, if you create a resource with one internal service, it is possible that other internal services might not be aware of that new resource in time for your code’s next step. An immediate call to the second resource can fail. Given this potential for latency, all applications should be written to retry the request.
The primary areas where this latency can be experienced are:
Users and Devices
Latency occurs when you create a user and then try immediately to add a device associated with the new user resource.
Applications and Secrets
Latency occurs when you create an application and then try immediately to retrieve the system-generated secret.
Applications and Scopes
Latency occurs when you create an application and then try immediately to retrieve its resource access grants.
SAML configuration and attributes
Latency occurs when you create a SAML configuration and then try immediately to retrieve its attribute mappings.
Environments, role assignments, and applications
Latency occurs when you create an environment and then try immediately to retrieve its role assignments or add an application to the new environment.
Populations and role assignments
Latency occurs when you create a population and then try immediately to retrieve its role assignments.