PingOne Platform APIs

Gateways

Gateway resources provide the communication linkage between PingOne and your remote directory. Use these requests to manage gateway resources, including the request body properties required to create a PingFederate, PingOne AIC, or PingAM connection.

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}}/v1/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, PING_ONE_AIC, PING_AM, RADIUS, and AUTHORIZE.

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"]). This must not be the host name and port number of a load balancer.

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 PING_ONE or LDAP. If set to PING_ONE, 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 Server, IBM (Tivoli) Security Directory Server, and LDAPv3-compliant Directory Server.

Gateway RADIUS 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 or EAP-MSCHAP 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.blastRadiusMitigation

Object

Optional

Mutable

The blastRadiusMitigation object contains two optional fields that can be used to block Blast RADIUS attacks. Since these two options use different approaches to deal with the same issue, you should not set more than one of them to true. If both are set to true, an error is returned.

radiusClients.blastRadiusMitigation.requireMsgAuth

Boolean

Optional

Mutable

Set requireMsgAuth to true to require that all requests from the client include the Message-Authenticator attribute. Any requests without the attribute will be ignored.

radiusClients.blastRadiusMitigation.limitProxyState

Boolean

Optional

Mutable

For older clients that don’t support sending the Message-Authenticator attribute, you can set limitProxyState to true. This instructs the gateway to ignore requests that don’t contain the Message-Authenticator attribute but contain the Proxy-State attribute.

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.

Authorize gateway data model

Property Type Required Mutable Description

authorizationVersionId

UUID

Required

Mutable

A string that specifies the ID of the Authorization Version deployed to any gateway instances associated with this Authorize gateway. Versioning allows independent development and deployment of policies.

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.

Gateway errors

In addition to the general error codes, gateway operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [type must not be null] or Validation Error : [serversHostAndPort must not be empty]

When and details

When: A POST or PUT request omits the type property, or omits the LDAP settings.serversHostAndPort property

Details: must not be null or must not be empty

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [type must be supported]

When and details

When: A POST or PUT request supplies a type value the service does not support

Details: must be supported

400

INVALID_DATA

INVALID_VALUE

Message:

Validation Error : [radiusClients[<index>].blastRadiusMitigation The provided value is not a valid blastRadiusMitigation setting. Note that requireMsgAuth cannot be enabled when limitProxyState is enabled.]
When and details

When: A POST or PUT request sets both radiusClients.blastRadiusMitigation.requireMsgAuth and limitProxyState to true

Details:

The provided value is not a valid blastRadiusMitigation setting. Note that requireMsgAuth cannot be enabled when limitProxyState is enabled.

400

REQUEST_FAILED

ITEM_LIMIT_EXCEEDED

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST request creates an LDAP Gateway with more user types than the limit allows, or a PUT request adds user types beyond the limit (removing or editing existing user types over the limit is allowed)

Details: The gateway has reached the maximum number of user types allowed (limit = <maximum>)

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST request would exceed the environment’s gateway limit

Details: Maximum number of gateways in this environment have been created.

400

REQUEST_FAILED

INVALID_PARAMETER

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A GET request supplies an expand value other than instances

Details: <expandValue> is not supported

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A PUT request attempts to change the gateway’s type, or an Authorize Gateway PUT request changes the settings.capabilities value

Details: is immutable with target type, or Capabilities field cannot be changed. with target capabilities

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: An LDAP Gateway POST or PUT request supplies connection security that does not match the port (StartTLS or no security on a port ending in 389, or a non‑TLS security on a port ending in 636)

Details: Ports ending in 389 should use either no connection security or StartTLS. or Ports ending in 636 should use TLS connection security. with target connectionSecurity

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT request supplies a gateway name that already exists in the environment, an LDAP Gateway request with duplicate user type names, or an LDAP Gateway PUT request with duplicate user type IDs

Details: A resource with the specified name already exists. with target name, All user types must have unique names with target userTypes[<index>].name, or All user types must have unique ids with target userTypes[<index>].id

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: An LDAP Gateway POST or PUT request with newUserLookup references a population that does not exist in the environment, omits the username attribute mapping, supplies an invalid attribute mapping value, maps the same attribute name more than once, maps memberOfGroupIDs or memberOfGroupNames, or sets updateUserOnSuccessfulAuthentication to true without LDAP as the password authority and a valid newUserLookup.attributeMappings

Details: population must exist in environment, username attribute mapping must be provided, Cannot map attributes because the attribute value '<value>' is invalid, Cannot map attributes because the attribute name '<name>' is not mapped uniquely, Cannot map sensitive user ping-one attributes: '[memberOfGroupIDs, memberOfGroupNames]', or:

userTypes.updateUserOnSuccessfulAuthentication=true requires LDAP to be the password authority and a valid userTypes.newUserLookup.attributeMappings

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A RADIUS Gateway POST or PUT request omits davinci or its davinci.policy.id, or supplies a radiusClients entry with no sharedSecret while defaultSharedSecret is also empty

Details: DaVinci policy Id cannot be null. or DaVinci policy Id cannot be empty. with target davinci, or RadiusClient[<ip>] shared secret cannot be empty, if default shared secret is empty. with target RadiusClient[<ip>]

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: An Authorize Gateway POST or PUT request references an authorizationVersion that is not compatible with the gateway’s instances or does not exist, or pairs authorizationVersion with API_ACCESS_MANAGEMENT capability or omits DYNAMIC_AUTHORIZATION

Details: The authorize microservice’s validation message, One or more instances associated with the gateway are not compatible with the provided Authorization Version ID,

One or more instances associated with the gateway are running a lower version than the minimum required version (<minimumVersion>) for the provided Authorization Version ID

An Authorization Version with the provided ID was not found, Authorization Version is not valid when Capabilities includes API_ACCESS_MANAGEMENT., or Capabilities must include DYNAMIC_AUTHORIZATION when Authorization Version is specified., with target authorizationVersion.id, authorizationVersion, or capabilities

400

INVALID_DATA or REQUEST_FAILED

INVALID_VALUE, EMPTY_VALUE, REQUIRED_VALUE, or CONSTRAINT_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request. except for the Only one capability can be specified. case, which returns The request could not be completed. There was an issue processing the request.

When and details

When: An Authorize Gateway POST or PUT request supplies an invalid capabilities array (empty, more than one entry, duplicate, non‑string, or unrecognized capability values), or omits settings.authorizationVersion while deployment verification applies

Details: At least one capability must be specified. (detail code EMPTY_VALUE, target capabilities), Duplicate capabilities are not allowed. (detail code INVALID_VALUE, target capabilities[<index>]), Capability must be a string. (detail code INVALID_VALUE, target capabilities[<index>]), Invalid capability. (detail code INVALID_VALUE, target capabilities[<index>]), Only one capability can be specified. (detail code CONSTRAINT_VIOLATION, target capabilities[1]), or Authorization Version cannot be null. (detail code REQUIRED_VALUE, target authorizationVersion)

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: An LDAP Gateway POST or PUT request sets kerberos on a gateway whose vendor is not Microsoft Active Directory, or a RADIUS Gateway PUT request changes authenticationPort while gateway instances are running

Details: Kerberos settings can only be set on LDAP gateways with a vendor type of 'Microsoft Active Directory' or The authentication port cannot be changed while instances are running.

400

INVALID_REQUEST

None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A POST or PUT request sets settings.capabilities to include API_ACCESS_MANAGEMENT while the environment does not have the API Access Management hybrid feature enabled

Details: None.

403

ACCESS_FAILED

LICENSE_EXCEEDED

Message: The request exceeded your license limit.

When and details

When: A POST or PUT request creates or modifies an LDAP Gateway while the environment lacks the canUseLdapGateway capability, sets Kerberos settings while the environment lacks the canUseKerberosGateway capability, or creates or updates an Authorize Gateway while the environment lacks both the canUseApiAccessManagement and canUseDynamicAuthorization capabilities

Details: Capability <capability> is disabled for Environment <envID>

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The authorize microservice denies deployment verification during an Authorize Gateway create or update

Details: You do not have permissions or are not licensed to make this request.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the gateways:create:gateway permission (the POST operation), the gateways:read:gateway permission (the GET operations), the gateways:update:gateway permission (the PUT operation), or the gateways:delete:gateway permission (the DELETE operation)

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A GET, PUT, or DELETE request references a gateway ID that does not exist in the environment

Details: None.