SCIM inbound provisioning endpoints - PingFederate

SCIM inbound provisioning endpoints - PingFederate - 11.1

PingFederate Server

bundle

pingfederate-111

ft:publication_title

PingFederate Server

Product_Version_ce

PingFederate 11.1

/pf-scim/v1/Users

The users endpoint is where client applications make HTTP requests to create, retrieve, update, and delete or deactivate users. This REST-based endpoint accepts POST, GET, PUT, and DELETE methods, as described in the following table.

Note:

HTTP requests must be made using either Basic or client-certificate application authentication. JSON is currently the only supported format for the HTTP message body.

HTTP method	Description
POST	/pf-scim/v1/Users Sends user attributes in JSON format—defined in the SCIM Core Schema—to create a new user. A successful response is indicated by an HTTP 201 status code and a message body containing the user record that has been added to the target datastore. The user ID is set as the id attribute in the JSON response, and the full URL to reference the user is in the HTTP response Location header. For an existing user, you can also use the POST method to either update or delete or disable a user record by appending the user ID to the path in the format of /pf-scim/v1/Users/`user_id` and setting the request header X-HTTP-Method-Override value to PUT or DELETE, respectively. For more information, see the PUT and DELETE method descriptions at the end of this topic.
GET	/pf-scim/v1/Users Retrieves all user records. A successful response is indicated by an HTTP 200 status code and a list of all users and their attributes. /pf-scim/v1/Users/`user_id` Retrieves the user record of a specific user. A successful response is indicated by an HTTP 200 status code and the requested user record. /pf-scim/v1/Users?attributes=`attribute` Retrieves the specific attribute from all users. A successful response is indicated by an HTTP 200 status code and a list of the desired attribute from all users. Note: For more information, see 3.2.2 List/Query Resources in SCIM Specification. /pf-scim/v1/Users?filter=`filter` Retrieves resources based on the filter. A successful response is indicated by an HTTP 200 status code and a list of resources matching the filter. Note: For more information, see 3.2.2.1 Filtering in SCIM Specification. /pf-scim/v1/Users?sortBy=`attribute`&sortOrder=ascending\|descending Retrieves all user records and sorts them based on a specific attribute in ascending or descending order. A successful response is indicated by an HTTP 200 status code and a sorted result set. Depending on the implementation of the target datastore, the target datastore might not return the user records that do not contain a value for that specific attribute as indicated by the sortBy parameter in the request. Note: For more information, see 3.2.2.2 Sorting in SCIM Specification. /pf-scim/v1/Users?startIndex=`x`[&count=`y`] Retrieves the user records starting with a specific index number, a positive integer `x`. If the optional count parameter is included, with a positive integer `y`, the endpoint limits the number of user records in the result set. A successful response is indicated by an HTTP 200 status code and a limited set of user records. Note: For more information, see 3.2.2.3 Pagination in SCIM Specification. Tip: You can use a combination of the aforementioned parameters in one query to narrow your search results.
PUT	/pf-scim/v1/Users/`user_id` Updates user attributes for the specified user, using JSON in the body of the HTTP request. Attributes not included in the request are set to a default value in the datastore. A successful PUT operation returns an HTTP 200 status code and the entire updated user record within the response body.
DELETE	/pf-scim/v1/Users/`user_id` Deletes or disables the user record for the specified user. Note that whether a user is deleted or disabled is determined by the selection of the SCIM DELETE message behavior option on the Delete/Disable Users tab in the applicable identity provider (IdP) connection. A successful response is indicated by an HTTP 200 status code.

Note:

For a list of HTTP error codes that might be returned, see 3.9 HTTP Response Codes in SCIM Specification.

/pf-scim/v1/Groups

The groups endpoint is where client applications make HTTP requests to create, retrieve, update, and delete groups.

Note:

Inbound provisioning for groups is a per-connection, optional feature. To enable group provisioning, select the User and Group Support option on the Connection Type tab when configuring the applicable IdP connection.

This REST-based endpoint accepts POST, GET, PUT, and DELETE methods, as described in the following table.

Note:

HTTP requests must be made using either Basic or client-certificate application authentication. JSON is currently the only supported format for the HTTP message body.

HTTP method	Description
POST	/pf-scim/v1/Groups Sends group attributes in JSON format—defined in the SCIM Core Schema—to create a new group. A successful response is indicated by an HTTP 201 status code and a message body containing the group record that has been added to the target datastore. The group ID is set as the id attribute in the JSON response, and the full URL to reference the group is in the HTTP response Location header. For an existing group, you can also use the POST method to either update or delete the group by appending the group ID to the path, in the format of /pf-scim/v1/Groups/`group_id`, and setting the request header X-HTTP-Method-Override value to PUT or DELETE, respectively. For more information, see the PUT and DELETE method descriptions at the end of this topic.
GET	/pf-scim/v1/Groups Retrieves all group records. A successful response is indicated by an HTTP 200 status code and a list of all groups and their attributes. /pf-scim/v1/Groups/`group_id` Retrieve the group record of a specific group. A successful response is indicated by an HTTP 200 status code and the requested group record. /pf-scim/v1/Groups?attributes=`attribute` Retrieves the specific attribute from all groups. A successful response is indicated by an HTTP 200 status code and a list of the desired attribute from all groups. Note: For more information, see 3.2.2 List/Query Resources in SCIM Specification. /pf-scim/v1/Groups?filter=`filter` Retrieves resources based on the filter. A successful response is indicated by an HTTP 200 status code and a list of resources matching the filter. Note: For more information, see 3.2.2.1 Filtering in SCIM Specification. /pf-scim/v1/Groups?sortBy=`attribute`&sortOrder=ascending\|descending Retrieves all group records and sorts them based on a specific attribute in ascending or descending order. A successful response is indicated by an HTTP 200 status code and a sorted result set. Depending on the implementation of the target datastore, the target datastore might not return the group records that do not contain a value for that specific attribute as indicated by the sortBy parameter in the request. Note: For more information, see 3.2.2.2 Sorting in SCIM Specification. /pf-scim/v1/Groups?startIndex=`x`[&count=`y`] Retrieves the group records starting with a specific index number, a positive integer `x`. If the optional count parameter is included, with a positive integer `y`, the endpoint limits the number of user records in the result set. A successful response is indicated by an HTTP 200 status code and a limited set of group records. Note: For more information, see 3.2.2.3 Pagination in SCIM Specification. Tip: You can use a combination of the aforementioned parameters in one query to narrow your search results.
PUT	/pf-scim/v1/Groups/`group_id` Updates group attributes for the specified group, using JSON in the body of the HTTP request. Attributes not included in the request are set to a default value in the datastore. A successful PUT operation returns an HTTP 200 status code and the entire updated group record within the response body.
DELETE	/pf-scim/v1/Groups/`group_id` Deletes the group record for the specified group. A successful response is indicated by an HTTP 200 status code.

Note:

For a list of HTTP error codes that might be returned, see 3.9 HTTP Response Codes in SCIM Specification.

/pf-scim/v1/Schemas

The schemas endpoint is where a client can retrieve a resource's schema. This REST-based endpoint accepts GET method as described in the following table.

Note:

HTTP requests must be made using either Basic or client-certificate application authentication. JSON is currently the only supported format for the HTTP message body.

HTTP method	Description
GET	Retrieves the resource's schema for an IdP connection based on the authentication information. A successful response is indicated by an HTTP 200 status code and the results in the message body.

$ curl -u basicUser 'https://localhost:9031/pf-scim/v1/Schemas' | python -m json.tool
{
    "attributes": [
        {
            "caseExact": false,
            "description": "Unique identifier for the SCIM resource as defined by the Service Provider. Each representation of the resource MUST include a non-empty id value. This identifier MUST be unique across the Service Provider's entire set of resources. It MUST be a stable, non-reassignable identifier that does not change when the same resource is returned in subsequent requests. The value of the id attribute is always issued by the Service Provider and MUST never be specified by the Service Consumer. REQUIRED.",
            "multiValued": false,
            "name": "id",
            "readOnly": true,
            "required": true,
            "schema": "urn:scim:schemas:core:1.0",
            "type": "string"
        },
        ...
    ],
    "description": "Core User",
    "endpoint": "/Users",
    "id": "urn:scim:schemas:core:1.0:User",
    "name": "User",
    "schema": "urn:scim:schemas:core:1.0"
}

/pf-scim/v1/ServiceProviderConfigs

This service provider (SP) configuration endpoint is where developers can retrieve detailed information on the PingFederate SCIM 1.1 implementation. When you enable inbound provisioning for an SP PingFederate server, an HTTP GET request to this endpoint returns a JSON response outlining SCIM 1.1 compliance details.

Note:

The /pf-scim/v1/ServiceProviderConfigs endpoint does not require authentication. JSON is currently the only supported format for the HTTP message body.

$ curl https://localhost:9031/pf-scim/v1/ServiceProviderConfigs
{
  "schemas": ["urn:scim:schemas:core:1.0"],
  ...
  "patch": {
    "supported":false
  },
  "bulk": {
    "supported":false
  },
  "filter": {
    "supported":true
  },
  "changePassword" : {
    "supported":true
  },
  "sort": {
    "supported":false
  },
  "etag": {
    "supported":false
  },
  "xmlDataFormat": {
    "supported":false
  },
  "authenticationSchemes": [
    {
      "name": "HTTP Basic",
      "description": "Authentication using HTTP Basic",
      ...
      "type":"httpbasic"
    },
    {
      "name": "TLS Client Certificate",
      "description": "Authentication via TLS Client Certificate",
      ...
      "type":"tls"
    }
  ]
}