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:
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:
Configuring a gateway in PingOne.
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.
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.
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.
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 . |
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 . |
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. |
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. |