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.provisionerId

String

Required

Immutable

Identifier of the source store provisioner.

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.provisionerId

String

Required

Immutable

Identifier of the target store provisioner.

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.

Propagation rule errors

In addition to the general error codes, propagation rule 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: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT request omits a required property (name, plan, or, on an active rule with a directory source store, populationExpression)

Details: must not be null or must not be empty, with the target set to the failing property

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 rule name that already exists in the environment

Details: Rule with name <name> already exists, with target name

400

INVALID_DATA

SIZE_LIMIT_EXCEEDED

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 name over 256 characters or a description over 1024 characters

Details: name length is over max character limit or description length is over max character limit

400

INVALID_DATA

NOT_FOUND or INVALID_VALUE

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 references a plan, parentRule, sourceStore, or targetStore that does not exist in the environment

Details: plan not found or parentRule not found (detail code NOT_FOUND), or source connection does not exist or target connection does not exist (detail code INVALID_VALUE), with the target set to the referenced property

400

INVALID_DATA

EMPTY_VALUE

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

When and details

When: A PUT request removes the sourceStore or targetStore from an existing rule, or a POST request omits one of them while supplying the other

Details: source store cannot be removed from an existing rule, target store cannot be removed from an existing rule, A source store must be specified if a target store has been provided, or A target store must be specified if a source store has been provided

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 changes the sourceStore or targetStore of an existing rule

Details: source store cannot be changed on an existing rule or target store cannot be changed on an existing rule

400

REQUEST_FAILED

None

Message: The rule must specify a sourceStore of type directory or targetStore of type PingOne

When and details

When: A POST or PUT request pairs stores that define neither an inbound nor an outbound relationship

Details: None.

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 POST or PUT request references a store type that is not allowed for the rule direction, or on a writeback rule references a source or target store type that writeback does not support, or targets a store other than the parent rule’s source store

Details: source store type <type> is not allowed for inbound provisioning, target store type <type> is not allowed for outbound provisioning, <storeType> is not a supported source store for writeback rules, <storeType> is not a supported target store for writeback rules, or target store does not match the source store of the parent rule

400

INVALID_DATA

EMPTY_VALUE

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

When and details

When: An active outbound LDAP Gateway rule omits the configuration.BASE_DN or configuration.RDN_ATTRIBUTE property, or an active inbound LDAP Gateway rule omits the configuration.USERS_BASE_DN or configuration.AUTHENTICATE_VIA_AD_LDAP property, or sets AUTHENTICATE_VIA_AD_LDAP to true without the GATEWAY_USER_TYPE_* configuration properties

Details: <property> is required, with the target set to the corresponding configuration.<property> path

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 active outbound LDAP Gateway rule has no mapping for the configured RDN_ATTRIBUTE

Details: rule cannot be enabled if the <rdnAttribute> attribute has no mapping

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 POST or PUT request on an inbound LDAP Gateway rule supplies an LDAP_FILTER or GROUP_LDAP_FILTER value that cannot be decoded as an LDAP search filter, or uses an approximate match or extensible match filter

Details: Provided LDAP filter cannot be decoded as a valid LDAP search filter. or:

Approximate Match and Extensible Match Filters are not supported when attempting to determine whether a given entry matches a search filter.

with the target set to the corresponding configuration.<filter> path

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 active rule’s populationExpression is not a valid SCIM filter, or references memberOfGroupNames on a directory source store

Details: populationExpression must be a valid SCIM filter or populationExpression contains an unsupported filter attribute: memberOfGroupNames

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 POST or PUT request supplies groups for a target store type that does not support group provisioning, or supplies more groups than the rule limit (1000 by default) allows

Details: target type does not support groups or cannot exceed limit of <maximum>

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 enables a rule that has no associated attribute mappings, or a DELETE request targets a writeback parent rule that still has a child rule

Details: rule cannot be enabled if there are no associated mappings or rule is marked as a parent for rule <childRuleID>

429

REQUEST_LIMITED

QUOTA_EXCEEDED

Message: The request could not be completed. A rate or quota limit was reached. Please try again later.

When and details

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

Details: The request will exceed your quota.

400

REQUEST_FAILED

INVALID_FILTER

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

When and details

When: A GET …​/syncedGroups request sets limit outside the supported range

Details: Must be between 1 and 1000, with target limit

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 POST or PUT request references an inbound rule source store while the environment does not have inbound LDAP provisioning enabled, or supplies an unsupported inbound rule configuration version value

Details: source store type LdapGateway is not allowed for inbound provisioning or Deprecated rule version: only version <allowedVersion> is allowed when creating a new rule

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

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

When and details

When: A POST or PUT request creates or activates an inbound rule while the environment lacks the inbound provisioning capability, or the actor lacks the additional read permission the change requires (dir:read:schema, dir:read:population, dir:read:group, or gateways:read:gateway)

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 osmosis:read:rule permission (the GET operations), the osmosis:update:rule permission (the POST and PUT operations), or the osmosis:delete:rule permission (the DELETE operation). Synced-rule reads additionally require dir:read:userSyncedStores (user synced rules) or dir:read:groupSyncedRules (group synced rules)

Details: None.

404

NOT_FOUND

None

Message: Resource not found: {environmentId=<envID>, id=<ruleID>}

When and details

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

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 …​/users/{userID}/syncedRules or GET …​/groups/{groupID}/syncedRules request references a user or group that does not exist in the environment

Details: None.

404

NOT_FOUND

None

Message:

Resource not found: Resource Not Found with environmentId=<envID>, userId=<userID> or groupId=<groupID>, ruleId=<ruleID>
When and details

When: A GET …​/syncedRules/{ruleID} or GET …​/syncedGroups/{groupID} request references a synced resource that does not exist

Details: None.