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 gateways 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 given to a gateway instance at startup. A gateway credential is like a password, so it should be protected. For security reasons, PingOne does not 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.

LDAP identity provider

For PingOne to check credentials in your LDAP User Directory, you must have an identity provider defined with type LDAP. Here you will have the ability to configure which gateway to use and you can specify runtime authentication configuration like the searchBaseDN and username attribute mapping. For more information about configuring an external LDAP identity provider resource, see CREATE Identity Provider (LDAP).

Gateways base data model

Property Description
credentials 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 A string that specifies the description of the resource.
enabled A boolean that specifies whether the gateway is enabled. This is a required property. 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 consists of any Unicode letter, mark, numeric character, forward slash, dot, apostrophe, underscore, space, or hyphen.
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). This is a required property.
bindPassword A string that specifies the bind password for the LDAP database. This is a required property.
connectionSecurity A string that specifies the connection security type. Options are None, TLS, and StartTLS. The default option is None.
serversHostAndPort An array of strings that specifies the LDAP server host name and port number (for example, ["", ""]). This is a required property.
validateTlsCertificates A boolean that specifies whether or not to trust all SSL certificates. The default value is true. If this value is false, then 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, and LDAP v3 compliant. This is a required property.

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.