Provisioning REST with PingOne

The REST provisioning connection enables you to configure provisioning between PingOne and a REST-based target system. Using REST with PingOne, you can import users from REST-based target systems into PingOne and provision users and groups from PingOne to REST endpoints.

Provisioning capabilities

Resource Capability Description Inbound Outbound

Resource	Capability	Description	Inbound	Outbound
User	Create	Creates a new user record in the destination.	Yes	Yes
Read	Retrieves or polls user attributes for synchronization.	Yes	Yes
Update	Modifies existing attributes, such as `job title`.	Yes	Yes
Delete	Deletes a user or temporarily suspends an account.	Yes	Yes
Group	Create	Provisions a new group in the target application.	No	Yes
Rename	Updates the display name or identifier of an existing group.	No	Yes
Delete	Removes a group from the target application.	No	Yes
Membership	Add and remove	Adds and removes users within groups.	No	No

User

Create

Creates a new user record in the destination.

Yes

Read

Retrieves or polls user attributes for synchronization.

Yes

Update

Modifies existing attributes, such as job title.

Yes

Delete

Deletes a user or temporarily suspends an account.

Yes

Group

Create

Provisions a new group in the target application.

Yes

Rename

Updates the display name or identifier of an existing group.

Yes

Delete

Removes a group from the target application.

Yes

Membership

Add and remove

Adds and removes users within groups.

Before you begin

Make sure that you have:

Administrator access to the REST-based application or service that you want to provision.
User and group schema definitions you can upload in the Object Types section.
The authentication details from your REST account:
- Service URI
- Authentication Method
- Client ID
- Client Secret
- Token Endpoint
- Grant Type
- Scope
- Authorization Token Prefix
- Auth Token
Users assigned to a specific population or group in PingOne designated for REST provisioning. Learn more in Adding a user in PingOne and Managing groups.

Steps

Create a REST connection:

In the PingOne admin console, go to Integrations > Provisioning.
Click and then click New Connection.
Click Select for Identity Store.
Click Select for the SaaS REST connection, and click Next.
Enter a Name and Description for this provisioning connection.
Click Next.

In the Configure Authentication section, enter the following configurations that apply to your REST account:

Authentication Method: Select one of the following:

OAUTH: Enter the following:

Configuration Example

Configuration	Example
Service URI	`https://api.example.com`
Client ID	`example-client-id`
Client Secret	`example-client-secret`
Token Endpoint	`https://api.example.com/oauth/token`
Grant Type	Select client_credentials or refresh_token. When refresh_token is selected, the Refresh Token field is required.
(Optional) Scope	`read write`

Service URI

https://api.example.com

Client ID

example-client-id

Client Secret

example-client-secret

Token Endpoint

https://api.example.com/oauth/token

Grant Type

Select client_credentials or refresh_token. When refresh_token is selected, the Refresh Token field is required.

(Optional) Scope

read write

Token: Enter the following:

Configuration Example

Service URI

https://api.example.com

Authorization Token Prefix

Bearer

Auth Token

example-auth-token

Configuration	Example
Service URI	`https://api.example.com`
Authorization Token Prefix	`Bearer`
Auth Token	`example-auth-token`

Configure REST object types.

REST uses two object types, User Object and Group Object. For each object type, construct a JSON payload using the following structure and paste it into the UI.

{
  "schema": [],
  "operations": {},
  "exceptions": {}
}

Specific configuration information can be found in the following schema, operations, and exceptions tables:

Configuration Definition

Schema

To create schemas, provide the name and value type for each attribute.

For Group Object, only the group name is provisioned. Consequently, any attributes defined in the group schema map exclusively to the group name.

"schema": [
    {
      "fieldName": null,
      "type": null,
      "flags": []
    }
  ]

fieldName: The attribute name.
type: The type of value for the attribute with the following available values:
- BOOLEAN
- INTEGER
- STRING
flags: Determines attribute limits with the following available values:
- NOT_UPDATEABLE
- NOT_CREATABLE
- MULTIVALUED
- REQUIRED

Configuration Definition

Operations

You must define the operations GET, CREATE, UPDATE, DELETE, and QUERY for both the User Object and Group Object.

For inbound user provisioning, configure only the QUERY operation. Use the application’s user query API and the documented settings for dividing results into pages. Inbound synchronization requires this configuration.

"operations": {
  "GET": {},
  "CREATE": {},
  "UPDATE": {},
  "DELETE": {},
  "QUERY": {}
}

GET: Use GET to retrieve specific objects:
```
"GET": {
    "path": null,
    "method": null,
    "idPath": null,
    "namePath": null,
    "headers": {},
    "responseMapping": {},
    "requestBody": {},
    "additionalStep": [
      {
        "resourceName": null,
        "method": null,
        "path": null,
        "valuePath": null
      }
    ]
  }
```
- path: Resource path. To include the unique ID in the path, use the uid variable.
- method: HTTP method.
- idPath: Response path to assign the resource UID.
- namePath: Response path to assign the resource NAME.
- (Optional) headers: HTTP headers sent in the request, indicated by key-value pairs.
- (Optional) queryParams: Query parameters to add to the request URL.
- responseMapping: Configures the data mapping based on the API response. If no mapping is required, set both the key and value as "/" : "/".
- (Optional) requestBody: Defines the JSON structure of the request for the query. To enter the unique ID in the body, enter the uid variable.
- (Optional) additionalStep: Creates additional queries to retrieve extra attributes.
QUERY: Use QUERY to list objects and handle segments:
```
"QUERY": {
    "path": null,
    "method": null,
    "idPath": null,
    "namePath": null,
    "headers": {},
    "responseMapping": {},
    "pagination": {
        "offSetPagination": {
            "type": null,
            "param": null,
            "path": null,
            "requestBody": null
         },
        "cookiePagination": {
            "type": null,
            "param": null,
            "path": null,
            "requestBody": null
          },
          "pageSizePagination": {
              "type": null,
              "param": null,
              "path": null,
              "requestBody": null
          },
          "pagedResultsCookie": {
              "type": null,
              "path": null,
              "regularExpression": null
          }
    },
    "additionalStep": [
      {
        "resourceName": null,
        "method": null,
        "path": null,
        "valuePath": null,
        "requestBody": null
      }
    ]
  }
```
- path: Resource Path. To include the unique ID in the path, use the uid variable.
- method: HTTP method.
- idPath: Response path to assign the resource UID.
- namePath: Response path to assign the resource NAME.
- (Optional) headers: HTTP headers sent in the request, indicated by key-value pairs.
- (Optional) queryParams: Query parameters to add to the request URL.
- (Optional) responseMapping: Matches schema field names as keys to their locations in the API response. For nested objects, map each individual attribute separately instead of linking the entire group. If no mapping is required, set both the key and value as "/": "/".
- (Optional) requestBody: Defines the JSON structure of the request for the query. Provide the body required by the API. The requestBody defines where to assign attributes within the request body.
- (Optional) additionalStep: Creates additional queries to the schema attributes. To make an extra query, include the following properties:
  - path
  - method
  - (Optional) requestBody
  - resourceName: Attribute name which must be in the schema.
  - valuePath: Specifies the direct path to the data extracted from the response. To retrieve a full list of items, use * or fieldName to extract a specific field from every item within that list. For a single object, provide the object name followed by the specific field name required.
- pagination: There are three types of pagination: CookiePagination, OffSetPagination, and PageSizePagination.
  - (Optional) type: An HTTP method location. Can be body or param.
  - (Optional) param: Key-value string to set parameters, where you must provide the key followed by an equal sign = and the available values of the following three variables: _pagedResultsCookie, _pagedResultsOffSet, _pageSize. If you want to add more than one key-value set, separate them with an &.
  - requestBody: Specifies the content required by the API when performing pagination through the request body. To pass pagination values, use variables within the body, such as _pagedResultsCookie, _pagedResultsOffSet, or _pageSize.
  - (Optional)path: Specifies an alternative URL path if a different endpoint than the default operation URL is required.
  - (Optional) regularExpression: Extracts the value of the cookie.
  - pagedResultsCookie: Indicates how to get the cookie or cursor for the next page of results.
    
    type: Pagination type. Available values are body or header.
    
    path: Indicates the path or name of the header containing the cookie.
    
    regularExpression: Extracts the value of the cookie. Specifies the path and method required for the operation, while the requestBody and requestMapping are optional.
CREATE: Use CREATE to provision users and groups:
```
"CREATE": {
    "idPath": null,
    "path": null,
    "method": null,
    "headers": {},
    "queryParams": {},
    "requestMapping": {},
    "unflattenAttributes": [],
    "additionalStep": [
      {
        "method": null,
        "path": null,
        "requestMapping": null,
        "requestBody": null
      }
    ]
  }
```
- idPath: Response path to assign the resource UID (Required).
- path: Resource Path. To include the unique ID in the path, use the uid variable.
- method: HTTP method.
- (Optional) headers: HTTP headers sent in the request, indicated by key-value pairs.
- queryParams: Query parameters to add to the request URL (Optional).
- requestMapping: Maps attribute names as keys to their representation in the request. For complex structures, define the requestBody, property using the appropriate API format, to which the requestMapping values map.
- (Optional) requestBody: Defines the JSON structure of the request for the query. You must provide the body required by the API.
- (Optional) unflattenAttributes: Transforms multivalued attributes into an array of objects. The attributeName represents the name of the attribute, and attributeValue represents the value of the field that the object will have.
- (Optional) additionalStep: Creates additional queries to the schema attributes. Specify path and method. requestBody and requestMapping are optional.
UPDATE: Use UPDATE to modify users and groups:
```
"UPDATE": {
    "path": null,
    "method": null,
    "idPath": null,
    "headers": {},
    "queryParams": {},
    "requestMapping": {},
    "unflattenAttributes": [],
    "additionalStep": [
      {
        "method": null,
        "path": null,
        "requestMapping": null,
        "requestBody": null
      }
    ]
  }
```
- path: Resource Path. To include the unique ID in the path, use the uid variable.
- method: HTTP method.
- idPath: Response path to assign the resource UID.
- (Optional) headers: HTTP headers sent in the request, indicated by key-value pairs.
- (Optional) queryParams: Query parameters to add to the request URL.
- requestMapping: Maps attribute names as keys to their representation in the request. If a complex requestBody is required, define the requestBody property using the appropriate API format, to which the requestMapping values map
- (Optional) requestBody: Defines the JSON structure of the request for the query.
- (Optional) unflattenAttributes: Transforms multivalued attributes into an array of objects.
- (Optional) additionalStep: Configures additional queries. Specify path and method. requestBody and requestMapping are optional.
DELETE: Use DELETE to remove a user or group:
```
"DELETE": {
    "path": null,
    "method": null,
    "queryParams": null,
    "headers": {},
    "requestBody": {},
    "additionalStep": {}
  }
```
- path: Resource path. To include the unique ID in the path, use the uid variable.
- method: HTTP method.
- (Optional) headers: HTTP headers sent in the request, indicated by key-value pairs.
- (Optional) queryParams: The query parameters to add to the request URL.
- (Optional) requestBody: Defines the JSON structure of the request for the query.

Configuration Definition

Configuration	Definition
Exceptions	This section defines the configuration structure for standardizing API errors. `"exceptions": { "BAD_REQUEST": [ { "code": null, "regularExpression": null, "messageErrorPath": null } ] }` `Exception Types (Keys)`: Use the supported standardized keys: `BAD_REQUEST`, `NOT_FOUND`, `ALREADY_EXIST`, `FORBIDDEN`, and `UNAUTHORIZED`. `Array Elements`: Each element within the exception type array must contain: `code`: The specific string error code returned by the API. `messageErrorPath`: The path where the response contains the error field. (Optional) `regularExpression`: Value in the `messageErrorPath`.

Exceptions

This section defines the configuration structure for standardizing API errors.

"exceptions": {
    "BAD_REQUEST": [
      {
        "code": null,
        "regularExpression": null,
        "messageErrorPath": null
      }
    ]
  }

Exception Types (Keys): Use the supported standardized keys: BAD_REQUEST, NOT_FOUND, ALREADY_EXIST, FORBIDDEN, and UNAUTHORIZED.
Array Elements: Each element within the exception type array must contain:
- code: The specific string error code returned by the API.
- messageErrorPath: The path where the response contains the error field.
- (Optional) regularExpression: Value in the messageErrorPath.

Click Next

In the User Actions section, select the following as needed:

Field	Description
Enable users creation	Creates a user in the target identity store when the user is created in the source identity store.
Enable users updation	Updates user attributes in the target identity store when the user is updated in the source identity store.
Enable users deprovision	Deprovisions a user in the target identity store when the user is deprovisioned in the source identity store. If Enable users deprovision is selected, the following options appear: Remove Action: Removes a user in the target identity store when the user is deleted in the source identity store. Deprovision on rule deletion: Deprovisions users if the associated provisioning rule is deleted.

Field

Description

Enable users creation

Creates a user in the target identity store when the user is created in the source identity store.

Enable users updation

Updates user attributes in the target identity store when the user is updated in the source identity store.

Enable users deprovision

Deprovisions a user in the target identity store when the user is deprovisioned in the source identity store. If Enable users deprovision is selected, the following options appear:

Remove Action: Removes a user in the target identity store when the user is deleted in the source identity store.
Deprovision on rule deletion: Deprovisions users if the associated provisioning rule is deleted.

Click Save.
To enable the connection, click the toggle at the top of the details panel to the right (blue).

You can disable the connection by clicking the toggle to the left (gray).

Create an inbound or outbound rule and select the existing REST connection as the target or source.

Validation

Confirm users and groups are successfully provisioned to REST. View the sync status to review synchronization results and any errors. You can find examples in Outbound provisioning sync summary examples.