PingFederate Server

SCIM 2.0 inbound provisioning endpoints

PingFederate supports a System for Cross-domain Identity Management (SCIM) 2.0 inbound provisioning and provides five endpoints.

The five endpoints are:

  • /pf-scim/v2/Users

  • /pf-scim/v2/Schemas

  • /pf-scim/v2/ServiceProviderConfig

  • /pf-scim/v2/ResourceTypes

  • /pf-scim/v2/.search

These endpoints are defined in the following SCIM 2.0 specifications:

Begin each endpoint with the fully-qualified server name and port number of your PingFederate server, for example, https://pingidentity.com:9031/pf-scim/v2/Users.

/pf-scim/v2/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 requests, as described in the following table.

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/v2/Users

  • Sends user attributes in JSON format to create a new user. Attributes are defined in the SCIM Core Schema.

  • A successful response returns 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.

GET

/pf-scim/v2/Users

  • Retrieves all user records.

  • A successful response returns an HTTP 200 status code and a list of all users and their attributes.

/pf-scim/v2/Users/user_id

  • Retrieves the user record of a specific user.

  • A successful response returns an HTTP 200 status code and the requested user record.

/pf-scim/v2/Users?attributes=attribute

  • Retrieves the specific attribute from all users.

  • A successful response returns an HTTP 200 status code and a list of the preferred attributes from all users.

  • Learn more in 3.4.2. Query Resources in the SCIM Specification.

/pf-scim/v2/Users?excludedAttributes=attribute

  • Retrieves all attributes from the user except for the specified attribute.

  • A successful response returns an HTTP [.msgph]``200 status code and a list of all attributes except for the specified excluded attribute.

  • Learn more in 3.4.2.5. Attributes in the SCIM specification.

/pf-scim/v2/Users?filter=filter

  • Retrieves resources based on the filter.

  • A successful response returns an HTTP 200 status code and a list of resources matching the filter.

  • Learn more in 3.4.2.2. Filtering in the SCIM specification.

/pf-scim/v2/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 returns 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 don’t contain a value for that specific attribute as indicated by the sortBy parameter in the request.

  • Learn more in 3.4.2.3. Sorting in the SCIM specification.

/pf-scim/v2/Users?startIndex=xy]

  • 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 returns an HTTP 200 status code and a limited set of user records.

  • Learn more in 3.4.2.4. Pagination in the SCIM specification.

You can use a combination of the aforementioned parameters in one query to narrow your search results.

PUT

/pf-scim/v2/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/v2/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 returns an HTTP 200 status code.

/pf-scim/v2/Schemas

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

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

GET

/pf-scim/v2/Schemas

  • Retrieves the resource’s schema for an IdP connection based on the authentication information.

  • A successful response returns an HTTP 200 status code and the results in the message body.

/pf-scim/v2/Schemas/schema_id

  • Retrieves the schema of a specific schema ID.

  • PingFederate supports the urn:ietf:params:scim:schemas:core:2.0:User and urn:ietf:params:scim:schemas:extension:enterprise:2.0:User schemas, as well as an optional custom schema.

Example

$ curl -u basicUser 'https://localhost:9031/pf-scim/v2/Schemas' | python -m json.tool

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 3,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Schema"
            ],
            "id": "urn:ietf:params:scim:schemas:core:2.0:User",
            "name": "User",
            "description": "User Account",
            "attributes": [
                {
                    "name": "active",
                    "type": "boolean",
                    "multiValued": false,
                    "description": "A Boolean value indicating the User's administrative status.",
                    "required": false,
                    "caseExact": true,
                    "mutability": "readWrite",
                    "returned": "default",
                    "uniqueness": "none"
                }
        }
}

/pf-scim/v2/ServiceProviderConfigs

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

Example

$ curl https://localhost:9031/pf-scim/v2/ServiceProviderConfig

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "patch": {
        "supported": true
    },
    "bulk": {
        "supported": false,
        "maxOperations": 0,
        "maxPayloadSize": 0
    },
    "filter": {
        "supported": true,
        "maxResults": 200
    },
    "changePassword": {
        "supported": false
    },
    "sort": {
        "supported": true
    },
    "etag": {
        "supported": false
    },
    "authenticationSchemes": [
        {
            "name": "HTTP Basic",
            "description": "The HTTP Basic Access Authentication scheme. This scheme is not considered to be a secure method of user authentication (unless used in conjunction with some external secure system such as SSL), as the user name and password are passed over the network as cleartext.",
            "specUri": "http://www.ietf.org/rfc/rfc2617.txt",
            "type": "httpbasic",
            "primary": false
        }
    ]
}

The search endpoint is used to query for resources using HTTP POST. Learn more in 3.4.3. Querying Resources Using HTTP POST in the SCIM specification.

Example

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
     "attributes": ["displayName", "userName"],
     "filter":
       "displayName sw \"smith\"",
     "startIndex": 1,
     "count": 10
   }

This sample POST body retrieves a list of the displayName and userName attributes for all users with a displayName that starts with "smith".