Identity propagation


Identity propagation configurations

The identity propagation API provides for configurable and audit-capable propagation of identities and their attributes between identity stores owned or managed by a customer.

An identity propagation configuration consists of:

  • Plans

    A collection of unidirectional provisioning relationships between pairs of identity stores. For more information, see Propagation plans.

  • Stores

    A connection to an identity store owned by a customer. For more information, see Propagation stores.

  • Rules

    A unidirectional provisioning relationship between a subset of identities on a source identity store and a target identity store. For more information, see Propagation rules.

  • Mappings

    The attribute mappings associated with identity propagation rules. For more information, see Propagation mappings.

Identity propagation configuration revision instances are snapshots of the state of the plan, store, rule, and mapping, entities of a configuration taken at a point in time. A new configuration revision can be created at any time, capturing the current state of those resources.

The API supports the configuration of one or more identity propagation plans on behalf of a customer environment. After configuration, the identity propagation plans are executed in response to changes on watched identity stores. Over time, identities become consistent across all watched (source) and unwatched (target) identity stores defined in an identity propagation plan. Identities are created, updated, and deleted as specified by each plan.

Creating, modifying, or deleting an identity propagation plan can occur at any time with no effect on the contents of the source identity store, which is the PingOne for Customers directory. All actions taken by the can be audited after-the-fact. The contents of identity stores can be modified at any time by external parties, such as administrators or other automated systems. The identity propagation system detects and logs any modifications.

The system monitors the availability of identity stores identified in the plans. If an identity store becomes unavailable, plan execution is paused until the store becomes available again.

Identities from managed identity stores are never duplicated or stored in full by the identity propagation system or its component services. Change summaries and change orders containing some attributes of identities are stored briefly during the provisioning process and can be present in audit logs.

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

Propagation API operations

The identity propagation endpoint supports the following configuration revision operations:

For hands-on experience with the propagation API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Identity propagation revision data model

Property Description
createdAt A date and time when the configuration revision was created.
createdBy A string that specifies the ID of the actor who created the configuration revision.
environment.id A string that specifies the environment resource’s unique identifier associated with the resource.
id A string that specifies the resource’s unique identifier.
previousRevision.id A string that specifies the ID of the previous configuration revision snapshot.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.

Endpoint examples

Create propagation configuration revisions

The POST /environments/{environmentId}/propagation/revisions endpoint creates a new propagation configuration that captures a snapshot of the current identity propagation plan, store, rule, and mapping settings associated with the specified environment resource.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/propagation/revisions" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

This POST does not require a request body.

Get one propagation configuration revision

To get data for a single propagation configuration resource, the GET /environments/{environmentId}/propagation/revisions/{revisionId}:latest operation returns data for the latest propagation configuration revision for the resource with the specified ID.

curl -X GET "https://api.pingone.com/v1/environments/environments/{environmentId}/propagation/revisions/{revisionId}:latest" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
  "id": "7bf54010-3d5b-11ea-b5ca-7911fe7f6eed",
  "environment": {
    "id": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
  },
  "previousRevision": {
    "id": "fdaf570f-9dbe-11e2-7f7f-7f7f7f7f7f7f"
  },
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/revisions/id:latest"
    },
    "create": {
      "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/revisions"
    },
    "previous": {
      "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/revisions/fdaf570f-9dbe-11e2-7f7f-7f7f7f7f7f7f"
    }
  },
  "_embedded": {
    "plans": [
      {
        "id": "8c9cc5b2-4171-4804-abd4-115a8948e453",
        "environment": {
          "id": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
        },
        "name": "Default Plan",
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/plans/8c9cc5b2-4171-4804-abd4-115a8948e453"
          }
        },
        "_embedded": {
          "rules": [
            {
              "plan": {
                "id": "8c9cc5b2-4171-4804-abd4-115a8948e453"
              },
              "sourceStore": {
                "id": "a6f91d1d-b50e-4c22-afd7-9491bf1edf07"
              },
              "targetStore": {
                "id": "407cfeb1-f81b-4ee6-838b-78e24e0ff92b"
              },
              "active": true,
              "populations": [
                {
                  "id": "233c60bc-cd43-4f83-9fce-00e90d31bd16"
                },
                {
                  "id": "122b60bc-cd43-4f83-9fce-00e90d31bd16"
                }
              ],
              "id": "86b88c9c-613d-4cdd-a0af-71d0dfba0c2f",
              "environment": {
                "id": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
              },
              "_links": {
                "self": {
                  "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
                },
                "targetStore": {
                  "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/stores/407cfeb1-f81b-4ee6-838b-78e24e0ff92b"
                },
                "sourceStore": {
                  "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/stores/a6f91d1d-b50e-4c22-afd7-9491bf1edf07"
                },
                "plan": {
                  "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/plans/8c9cc5b2-4171-4804-abd4-115a8948e453"
                }
              },
              "_embedded": {
                "mappings": [
                  {
                    "id": "1fe0ec15-77a0-44a4-af34-3b9b66a69285",
                    "environment": {
                      "id": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
                    },
                    "rule": {
                      "id": "86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
                    },
                    "sourceAttribute": "username",
                    "targetAttribute": "userName",
                    "_links": {
                      "self": {
                        "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/mappings/1fe0ec15-77a0-44a4-af34-3b9b66a69285"
                      },
                      "rule": {
                        "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
                      }
                    }
                  },
                  {
                    "id": "87df213e-b11f-4a17-aba3-9acfaff57406",
                    "environment": {
                      "id": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
                    },
                    "rule": {
                      "id": "86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
                    },
                    "sourceAttribute": "email",
                    "targetAttribute": "workEmail",
                    "_links": {
                      "self": {
                        "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/mappings/87df213e-b11f-4a17-aba3-9acfaff57406"
                      },
                      "rule": {
                        "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/rules/86b88c9c-613d-4cdd-a0af-71d0dfba0c2f"
                      }
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    ],
    "stores": [
      {
        "id": "407cfeb1-f81b-4ee6-838b-78e24e0ff92b",
        "environment": {
          "id": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
        },
        "image": {
          "id": "0e3954ed-bdda-41e3-95de-a2da324a449e",
          "href": "https://d3uinntk0mqu3p.cloudfront.net/branding/market/0e3954ed-bdda-41e3-95de-a2da324a449e.png"
        },
        "description": "description initial",
        "type": "scim",
        "status": "ACTIVE",
        "configuration": {
          "freezeAccountOnDeprovisioning": "false",
          "AUTHENTICATION_METHOD": "OAuth 2 Bearer Token",
          "SCIM_URL": "https://example.com/scim",
          "SCIM_VERSION": "2.0",
          "OAUTH_ACCESS_TOKEN": "12345"
        },
        "name": "Workday",
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/stores/407cfeb1-f81b-4ee6-838b-78e24e0ff92b"
          }
        }
      },
      {
        "id": "a6f91d1d-b50e-4c22-afd7-9491bf1edf07",
        "environment": {
          "id": "0d73e3ae-c424-42fd-ad71-9a1c79e90d06"
        },
        "image": {},
        "type": "directory",
        "status": "ACTIVE",
        "name": "directory",
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/0d73e3ae-c424-42fd-ad71-9a1c79e90d06/propagation/stores/a6f91d1d-b50e-4c22-afd7-9491bf1edf07"
          }
        }
      }
    ]
  }
}

The response data includes a previousRevision ID that specifies the UUID of the configuration revision snapshot that was superseded by the latest snapshot.

To get data for the previousRevision propagation configuration resource, the GET /environments/{environmentId}/propagation/revisions/{previousRevisionId} operation returns data for the previous propagation configuration revision.

curl -X GET "https://api.pingone.com/v1/environments/environments/{environmentId}/propagation/revisions/{previousRevisionId}" \
-H "Authorization: Bearer jwtToken"

If the response data for the previous revision includes a previousRevision propagation configuration resource ID, you can use that ID to get data for the next oldest snapshot. When the GET /environments/{environmentId}/propagation/revisions/{previousRevisionId} no longer returns a previousRevision ID in the response, then you have reached the first recorded snapshot.