The PingOne gateways API connects resources in one security domain (for example, an on-premises datacenter or a hosted private cloud) with an environment in the PingOne platform. Gateways give customers the ability to tie their on-premises resources into PingOne. At this time, PingOne supports the LDAP and PING_FEDERATE gateway types.

Customers can create gateway resources in PingOne and then manage the gateways from PingOne. Gateway endpoints return information about the health of the gateway, errors generated by the gateway, and gateway instance runtime metrics.

The following resources are managed through the PingOne Gateway service.

Gateways and gateway instances

To create the communication linkage between PingOne and your remote directory, you must deploy software in your infrastructure that can communicate with both PingOne and your remote directory. There are two parts to successfully getting the software in place. The first is configuring a Gateway in PingOne. The second is running the “gateway as a Docker container” in your environment. The running software is known as a gateway instance. For testing purposes, a single gateway instance is sufficient, but for production deployments, multiple gateway instances should be deployed for high availability.

Gateway credential

The gateway instance running within your infrastructure authenticates with PingOne through a gateway credential. Gateway credentials are supplied to a gateway instance at startup. A gateway credential is like a password, so it should be protected. For security reasons, PingOne doesn’t store the gateway credentials that you have generated, but you can always create a new one in the PingOne console. Multiple gateway instances can use the same gateway credential. For more information about gateway credentials, see Gateway Credentials.

Gateway base data model

Property Description
credentials (Optional) An array of objects that specifies the list of gateway credentials. The objects have information about the credential and these are the credentials that gateway instances use or could be actively using. The maximum number of credentials is five. If there are no gateway credentials specified for a gateway, this property is not present.
description (Optional) A string that specifies the description of the resource.
_embedded.instances An array of gateway instances. Active instances are returned for the gateway resource when expand=instances is specified in the request.
enabled A boolean that specifies whether the gateway is enabled. This is a required property.
environment.id A string that specifies the environment resource’s unique identifier associated with the resource.
id A string that specifies the resource’s unique identifier.
name A string that specifies the resource name, which must be provided and must be unique within an environment. Valid characters are any Unicode letter, mark, numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen.
supportedVersions An array that lists the LDAP gateway versions associated with this gateway resource. This information is returned on a GET {{apiPath}}/environments/{{envID}}/gateways request, and it is used to trigger alerts if the gateway tries to connect with an unsupported version (or a version that is not the latest or recommended version).
supportedVersions.version A string that specifies the gateway version number.
supportedVersions.image A string that identifies the gateway image path.
supportedVersions.recommended A boolean that specifies whether this is the recommended LDAP gateway version.
supportedVersions.latest A boolean that specifies whether this is the latest LDAP gateway version.
type A string that specifies the type of gateway resource. Options are LDAP and PING_FEDERATE. This is a required property.

Gateway LDAP data model

Property Description
bindDN A string that specifies the distinguished name information to bind to the LDAP database (for example, uid=pingone,dc=example,dc=com).
bindPassword A string that specifies the bind password for the LDAP database. This is a required property.
connectionSecurity (Optional) A string that specifies the connection security type. Options are None, TLS, and StartTLS. The default value is None.
serversHostAndPort An array of strings that specifies the LDAP server host name and port number (for example, ["ds1.example.com:389", "ds2.example.com:389"]).
userTypes (Optional) An array of the userTypes properties for the users to be provisioned in PingOne. userTypes specifies which user properties in PingOne correspond to the user properties in an external LDAP directory. You can use an LDAP browser to view the user properties in the external LDAP directory.
userTypes.allowPasswordChanges (Optional) Defaults to false if this property isn’t specified in the request. If false, the user cannot change the password in the remote LDAP directory. In this case, operations for forgotten passwords or resetting of passwords are not available to a user referencing this gateway.
userTypes.id (Optional) The UUID of the user type. This correlates to the password.external.gateway.userType.id User property.
userTypes.newUserLookup (Optional) The configurations for initially authenticating new users who will be migrated to PingOne. Note: If there are multiple users having the same user name, only the first user processed is provisioned.
userTypes.newUserLookup.attributeMappings A list of objects supplying a mapping of PingOne attributes to external LDAP attributes. One of the entries must be a mapping for "username”. This is required for the PingOne user schema.
userTypes.newUserLookup.attributeMappings.name The PingOne username attribute. See Users properties for the complete list of PingOne user attributes.
userTypes.newUserLookup.attributeMappings.value A placeholder reference to the corresponding external LDAP attribute for name.
userTypes.newUserLookup.ldapFilterPattern (Optional) The LDAP user search filter to use to match users against the entered user identifier at login. For example, (((uid=${identifier})(mail=${identifier})). Alternatively, this can be a search against the user directory.
userTypes.newUserLookup.population (Optional) The PingOne population to use to create user entries during lookup.
userTypes.newUserLookup.population.id (Optional) The ID of the population to use to create user entries during lookup.
validateTlsCertificates (Optional) A boolean that specifies whether or not to trust all SSL certificates (defaults to true). If this value is false, TLS certificates are not validated. When the value is set to true, only certificates that are signed by the default JVM CAs, or the CA certs that the customer has uploaded to the certificate service are trusted.
vendor A string that specifies the LDAP vendor. Options are PingDirectory, Microsoft Active Directory, Oracle Directory Server Enterprise Edition, Oracle Unified Directory, CA Directory, OpenDJ Directory, IBM (Tivoli) Security Directory Server, and LDAP v3 compliant Directory Server.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.