PingOne Platform APIs

Propagation Rules

Identity propagation rule entities represent a unidirectional provisioning relationship between a subset of identities on a source identity store and a target identity store. Rules contain attribute mappings, which must be added manually. The PingOne API does not include the default attribute mappings defined by each identity store automatically.

Note: To reflect the propagation rules API changes in the PingOne Admin Console, you must create a new propagation revision.

The PingOne Admin Console does display the default attribute mappings. When defining the connection in the Admin Console, if a rule does not have any user-defined mappings, the identity store’s default mappings can be used. If at least one attribute mapping is defined in a rule, then all default mappings are ignored.

The examples that follow show common actions to find and manage identity propagation rule resources. You need the Environment Admin role to perform operations on identity propagation rule entities.

For known limitations when configuring rules, refer to Known issues for provisioning through an LDAP gateway.

Propagation rule data model

Property Type Required? Mutable? Description

active

Boolean

Optional

Mutable

Whether this rule is active; defaults to false.

createdAt

DateTime

N/A

Read-only

Date and time the propagation rule was created.

configuration

Object

Required/Optional

Mutable

An Outbound LDAP configuration data object is required for outbound LDAP Gateway stores (type LdapGateway). An Inbound LDAP configuration data object is required for an inbound LDAP Gateway stores (where users user are provisioned into PingOne). Optional for all other cases and ignored if used.

deprovision (deprecated)

Boolean

Optional

Mutable

Deprecated, use managed in Propagation Stores. Whether to enable deprovisioning of users for a store when it is deleted. The deprovisioning occurs when a new revision is created (Create Propagation Revision). Not applicable on writeback rules and ignored if used.

description

String

Optional

Mutable

Description of the propagation rule.

environment.id

String

N/A

Read-only

Identifier (UUID) of the PingOne environment associated with the propagation rule.

groups

Object[]

Optional

Mutable

Array of objects, each of which contains the identifier of a group.

groups.id

String

Required

Mutable

Identifier (UUID) of the group to include in this propagation rule.

id

String

N/A

Read-only

Identifier (UUID) of the propagation rule.

name

String

Required

Mutable

Unique name of the propagation rule.

parentRule.id

String

Required/Optional

Immutable

Identifier (UUID) of the inbound propagation rule associated with this writeback propagation rule. Required for a writeback propagation rule, but should not be used with any other propagation rule.

plan.id

String

Required

Immutable

Identifier (UUID) of the propagation plan associated with this propagation rule.

populationExpression

String

Optional

Mutable

SCIM filter on any user attribute of the source identity store to filter the source population. Not applicable on writeback rules and ignored if used.

populations.id (deprecated)

String[]

Optional

Mutable

Deprecated, use populationExpression. If both are present, populationExpression applies and populations.id ignored. Array of identifiers (UUID) of populations associated with this propagation rule. Not applicable on writeback rules and ignored if used.

ruleType

String

Required

Immutable

Type of this propagation rule. Can be any type from Propagation store type of Propagation store data models by store type type.

sourceStore.displayName

String

Required

Immutable

Name displayed in the admin console for the source identity store associated with this propagation rule.

sourceStore.id

String

Required

Immutable

Identifier (UUID) of the source identity store associated with this propagation rule.

sourceStore.type

String

Required

Immutable

Type of rule of the source identity store associated with this propagation rule. Can be INBOUND or OUTBOUND.

syncStatus.failedCount

Integer

N/A

Read-only

Count of failed synchronization events since the last revision.

syncStatus.failedDeprovisionCount

Integer

N/A

Read-only

Count of failed deprovisioning synchronization events since the last revision.

syncStatus.groupFailedCount

Integer

N/A

Read-only

Count of failed group synchronization events since the last revision.

syncStatus.groupSuccessCount

Integer

N/A

Read-only

Count of successful group synchronization events since the last revision.

syncStatus.groupTotal

Integer

N/A

Read-only

Count of groups that will synchronize to the target store.

syncStatus.lastResyncAt

DateTime

N/A

Read-only

Last rule resynchronization in yyyy-MM-dd’T’HH:mm:ss.SSS’Z' format.

syncStatus.partialSyncTotal

Integer

N/A

Read-only

Count of users for which an account exists at the target but is out of sync with the source because onUpdate is set to false.

syncStatus.sourceDetails

String

N/A

Read-only

Details of any source synchronization errors.

syncStatus.sourceLastSyncAt

DateTime

N/A

Read-only

Last source synchronization in yyyy-MM-dd’T’HH:mm:ss.SSS’Z' format.

syncStatus.sourceSyncState

String

N/A

Read-only

Current state of synchronization with a source store. Can be FAILED, POLLING, or POLL_COMPLETE.

syncStatus.successCount

Integer

N/A

Read-only

Count of successful synchronization events since the last revision.

syncStatus.targetDetails

String

N/A

Read-only

Details of any target synchronization errors.

syncStatus.targetLastSyncAt

DateTime

N/A

Read-only

Last target synchronization in yyyy-MM-dd’T’HH:mm:ss.SSS’Z' format.

syncStatus.targetSyncState

String

N/A

Read-only

Current state of synchronization with a target store. Can be SYNCING, SYNC_COMPLETE, or FAILED.

syncStatus.unsyncTotal

Integer

N/A

Read-only

Count of users for which an account exists at the target but was not synced with the source because onCreate is set to false.

syncStatus.userTotal

Integer

N/A

Read-only

Count of users that will synchronize to the target store based on the propagation rule’s filter.

targetStore.displayName

String

Required

Immutable

Name displayed in the admin console for the target identity store associated with this propagation rule.

targetStore.id

String

Required

Immutable

Identifier (UUID) of the target identity store associated with this propagation rule.

targetStore.type

String

Required

Immutable

Type of rule of the target identity store associated with this propagation rule. Can be INBOUND or OUTBOUND.

updatedAt

DateTime

N/A

Read-only

Date and time the propagation rule was updated. Can be null.

Synchronization states are:

  • FAILED - An error occurred polling users from the source or pushing users to the target.

  • POLL_COMPLETE - Polling has completed on the source.

  • POLLING - Store is polling for users' information from the source to be potentially synchronized.

  • SYNC_COMPLETE - Synchronization has completed on the target.

  • SYNCING - Synchronizing users to the target is successful.

Outbound LDAP configuration data object

This outbound LDAP configuration object is required for outbound LDAP Gateway stores (type LdapGateway). An Inbound LDAP configuration data object is required for inbound LDAP Gateway stores (where users user are provisioned into PingOne). For all other cases, optional and ignored if used.

Property Type Required? Mutable? Description

BASE_DN

String

Required

Mutable

The location in the LDAP directory structure where users will be created.

RDN_ATTRIBUTE

String

Required

Mutable

Relative distinguished name is the portion of the DN (distinguished name) that uniquely identifies the user in the LDAP directory. Must be cn for Microsoft Active Directory, uid for PingDirectory.

Inbound LDAP configuration data object

This inbound LDAP configuration object is required for inbound LDAP Gateway stores (where users are provisioned into PingOne). An Outbound LDAP configuration data object is required for outbound LDAP Gateway stores (type LdapGateway). For all other cases, optional and ignored if used.

If AUTHENTICATE_VIA_AD_LDAP is false, then the GATEWAY_USER_TYPE_* configuration attributes are optional and ignored if used. Note that USERS_BASE_DN is always required and unaffected by the value of AUTHENTICATE_VIA_AD_LDAP.

AUTHENTICATE_VIA_AD_LDAP can only be true if a userTypes object is configured in the gateway as returned by Read One Gateway. The remaining configuration attributes are required and must exactly match the corresponding attribute in the userTypes array object.

Note: The userTypes object must not have a newUserLookup property if it is to be used with AUTHENTICATE_VIA_AD_LDAP as true.

For example, the object in the userTypes array is:

"userTypes": [
    {
        "id": "522eea26-d268-4494-a826-434a6b24f35d",
        "name": "AD user type",
        "passwordAuthority": "LDAP",
        "searchBaseDn": "OU=inbound,OU=test,OU=LdapGatewayTest,DC=ldap-test1,DC=lab",
        "orderedCorrelationAttributes": [
            "dn"
        ],
        "allowPasswordChanges": false
    }
],

The mapping is:

  • allowPasswordChanges maps to GATEWAY_USER_TYPE_ALLOW_PASSWORD_CHANGES

  • id maps to GATEWAY_USER_TYPE_ID

  • name maps to GATEWAY_USER_TYPE_NAME

  • orderedCorrelationAttributes maps to GATEWAY_USER_TYPE_CORRELATION_ATTRIBUTES where, for multiple attributes, the JSON array of strings is converted to a single comma-separated string.

  • passwordAuthority maps to GATEWAY_USER_TYPE_PASSWORD_AUTHORITY

Property Type Required? Mutable? Description

AUTHENTICATE_VIA_AD_LDAP

Boolean

Required

Mutable

Whether users are authenticated using LDAP.

GATEWAY_USER_TYPE_ALLOW_PASSWORD_CHANGES

Boolean

Required/Optional

Mutable

Whether users are permitted to change their password. Required as described in this section, optional for all other rules and ignored if used.

GATEWAY_USER_TYPE_CORRELATION_ATTRIBUTES

String

Required/Optional

Mutable

A comma-separated string of one or more attributes. Required as described in this section, optional for all other rules and ignored if used.

GATEWAY_USER_TYPE_ID

String

Required/Optional

Mutable

Identifier (UUID) of the user type to which this configuration applies. Required as described in this section, optional for all other rules and ignored if used.

GATEWAY_USER_TYPE_NAME

String

Required/Optional

Mutable

Name of the user type to which this configuration applies. Required as described in this section, optional for all other rules and ignored if used.

GATEWAY_USER_TYPE_PASSWORD_AUTHORITY

String

Required/Optional

Mutable

Password authority associated with the user type. Required as described in this section, optional for all other rules and ignored if used.

MFA_USER_DEVICE_MANAGEMENT

String

Optional

Mutable

How incoming user devices are managed. Can be Merge with devices in PingOne, Overwrite devices in PingOne, or Do not manage devices. For more information, see Provisioning options reference.

USERS_BASE_DN

String

Required

Mutable

The LDAP directory location from where the users will be synced into PingOne.

Propagation synchronized rule data model

Property Type Required? Mutable? Description

details

String

N/A

Read-only

Details of any rule synchronization errors.

environment.id

String

N/A

Read-only

Identifier (UUID) of the PingOne environment associated with the propagation rule.

lastSyncAt

DateTime

N/A

Read-only

Last rule synchronization in yyyy-MM-dd’T’HH:mm:ss.SSS’Z' format.

rule.active

Boolean

N/A

Read-only

Whether the rule is active or not.

rule.id

String

N/A

Read-only

Identifier (UUID) of the synchronized rule.

rule.name

String

N/A

Read-only

Name of the synchronized rule.

sourceStore.id

String

N/A

Read-only

Identifier (UUID) of the source identity store associated with this propagation rule.

sourceStore.name

String

N/A

Read-only

Name of the source identity store associated with this propagation rule.

sourceStore.type

String

N/A

Read-only

Type of the source identity store associated with this propagation rule.

status

String

N/A

Read-only

Status of the rule synchronization. Can be SUCCESS or FAILED.

syncedMemberships

Object[]

N/A

Read-only

Array of objects describing the group memberships of the rule and its status within the group.

syncedMemberships.details

String

N/A

Read-only

Details of any rule group synchronization errors.

syncedMemberships.group.id

String

N/A

Read-only

Identifier (UUID) of the group of which the rule is a member.

syncedMemberships.lastSyncAt

DateTime

N/A

Read-only

Last rule group synchronization in yyyy-MM-dd’T’HH:mm:ss.SSS’Z' format.

syncedMemberships.status

String

N/A

Read-only

Status of the rule group synchronization. Can be SUCCESS or FAILED.

targetStore.id

String

N/A

Read-only

Identifier (UUID) of the target identity store associated with this propagation rule.

targetStore.name

String

N/A

Read-only

Name of the target identity store associated with this propagation rule.

targetStore.type

String

N/A

Read-only

Type of the target identity store associated with this propagation rule.

type

String

N/A

Read-only

Status of the rule synchronization. Can be INBOUND or OUTBOUND.

Additional rule data models by request

Read All Rules and Read One Plan’s Rules return a Propagation rule data model modified as described in the table.

Property Type Required? Mutable? Description

rules

Object[]

N/A

Read-only

Array of rule objects as defined in Propagation rule data model

rules.rule

Object

N/A

Read-only

Rule object, replaces id in Propagation rule data model

rules.rule.id

String

N/A

Read-only

Unique identifier (UUID) of the propagation rule

rules.rule.name

String

N/A

Read-only

Name of the propagation rule

The requests Read All Synced Rules for a User, Read One Synced Rule for a User, Read All Synced Rules for a Group, and Read One Synced Rule for a Group return a Propagation rule data model modified as described in the table.

Property Type Required? Mutable? Description

syncedRules

Object[]

N/A

Read-only

Array of synchronized rule objects as defined in [Propagation rule data model]#propagation-rule-data-model)

syncedRules.rule

Object

N/A

Read-only

Rule object, replaces id in Propagation rule data model

syncedRules.rule.active

Boolean

N/A

Read-only

Whether the rule is active or not

syncedRules.rule.id

String

N/A

Read-only

Unique identifier (UUID) of the propagation rule

syncedRules.rule.name

String

N/A

Read-only

Name of the propagation rule

The requests Read All Synced Groups for a Rule and Read One Synced Group for a Rule return a Groups data model modified as described in the table.

Property Type Required? Mutable? Description

syncedGroups

Object[]

N/A

Read-only

Array of synchronized group objects as defined in Groups data model

syncedGroups.group

Object

N/A

Read-only

Group object, replaces id in Groups data model

syncedGroups.group.id

String

N/A

Read-only

Unique identifier (UUID) of the group

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.