A PingOne gateway connects resources in a remote security domain (such as, an on-premises datacenter or a hosted private cloud) with a PingOne environment. Gateways give you the ability to tie your organizations on-premise resources into PingOne.

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

Once you’ve created the gateway in PingOne, users in the remote directory are created through the gateway as PingOne users the first time they sign on to PingOne.

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 need to 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:

  1. Configuring a gateway in PingOne.

  2. Running a Docker instance that’s configured for the PingOne gateway in your on-premise or cloud-hosted environment. The running Docker container 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 credentials

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

Gateway role assignments

If you’re using PingFederate, you can manage gateway access to PingOne resources using PingOne’s role-based access control (RBAC) model to assign a role to the gateway. See Gateway Role Assignments for more information.

Gateway base data model {#gateway-base-data-model}

Property Type Required? Mutable? Description
credentials Object[] Optional Mutable 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 String Optional Mutable Specifies the description of the resource.
_embedded.instances Object[] Optional Mutable An array of gateway instances. Active instances are returned for the gateway resource when expand=instances is specified in the request.
enabled Boolean Required Mutable Indicates whether the gateway is enabled.
environment.id String Required Immutable The unique identifier for the environment associated with the resource.
id String Required Immutable The resource’s unique identifier.
name String Required Mutable 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 Object Optional Mutable 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 String Optional Mutable The gateway version number.
supportedVersions.image String Optional Mutable Identifies the gateway image path.
supportedVersions.recommended Boolean Optional Mutable Indicates whether this is the recommended LDAP gateway version.
supportedVersions.latest Boolean Optional Mutable Indicates whether this is the latest LDAP gateway version.
type String Required Immutable The type of gateway resource. Options are LDAP, API_GATEWAY_INTEGRATION, PING_FEDERATE, and RADIUS.

Gateway LDAP data model {#gateway-ldap-data-model}

Property Type Required? Mutable? Description
bindDN String Required Mutable The distinguished name information to bind to the LDAP database (for example, uid=pingone,dc=example,dc=com).
bindPassword String Required Mutable The Bind password for the LDAP database.
connectionSecurity String Optional Mutable The connection security type. Options are None, TLS, and StartTLS. The default value is None.
followReferrals Boolean Optional Mutable Defaults to false if the payload does not contain the property. If set to true, PingOne sends LDAP queries per referrals it receives from the LDAP servers.
kerberos Object Optional Mutable Contains the Kerberos authentication settings. Set this to null to disable Kerberos authentication.
kerberos.serviceAccountPassword String Optional Mutable The password for the Kerberos service account.
kerberos.serviceAccountUserPrincipalName String Required Mutable The Kerberos service account user principal name (for example, “username@domain.com”).
kerberos.minutesToRetainPreviousCredentials Integer Optional Mutable The number of minutes for which the previous credentials are persisted.
serversHostAndPort String[] Required Mutable The LDAP server host name and port number (for example, ["ds1.example.com:389", "ds2.example.com:389"]).
userTypes Object[] Required Mutable 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 Boolean Optional Mutable 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.updateUserOnSuccessfulAuthentication Boolean Optional Mutable If set to true, when users sign on through an LDAP Gateway client, user attributes are updated based on responses from the LDAP server. Defaults to false if this property isn’t specified in the request.
userTypes.id UUID Required Mutable Identifies the user type. This correlates to the password.external.gateway.userType.id User property.
userTypes.name String Required Mutable The name of the user type.
userTypes.newUserLookup Object Optional Mutable 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 Object[] Required Mutable 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 String Required Mutable The PingOne username attribute. See Users properties for the complete list of PingOne user attributes.
userTypes.newUserLookup.attributeMappings.value Object Required Mutable A placeholder reference to the corresponding external LDAP attribute for name.
userTypes.newUserLookup.ldapFilterPattern String Optional Mutable 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 String Optional Mutable The PingOne population to use to create user entries during lookup.
userTypes.newUserLookup.population.id UUID Optional Immutable The ID of the population to use to create user entries during lookup.
userTypes.orderedCorrelationAttributes Object[] Optional Mutable A map of name-value entries used to persist the external LDAP directory attributes.
userTypes.passwordAuthority String Required Mutable This can be either PINGONE or LDAP. If set to PINGONE, PingOne authenticates with the external directory initially, then PingOne authenticates all subsequent sign-ons.
userTypes.searchBaseDn String Optional Mutable The LDAP base domain name (DN) for this user type.
validateTlsCertificates Boolean Optional Mutable Indicates 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 String Required Immutable 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.

Gateway RADIUS data model {#radius-gateway-data-model}

Property Type Required? Mutable? Description
davinci.policy.id String Required Mutable The ID of the Davinci flow policy to use.
defaultSharedSecret String Optional Mutable Value to use for the shared secret if the shared secret is not provided for one or more of the RADIUS clients specified.
networkPolicyServer Object Optional Mutable If specified, the RADIUS gateway authenticates using the MS-CHAP v2 protocol.
networkPolicyServer.ip String Required Mutable The IP address of the Network Policy Server (NPS).
networkPolicyServer.port Integer Required Mutable The port number of the NPS.
radiusClients Object[] Required Mutable Collection of RADIUS clients.
radiusClients.ip String Required Mutable The IP of the RADIUS client.
radiusClients.sharedSecret String Optional Mutable The shared secret for the RADIUS client. If this value is not provided, the shared secret specified with defaultSharedSecret is used. If you are not providing a shared secret for the client, leave out sharedSecret or set it to null.

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.