Implementing SCIM for inbound or outbound provisioning with PingFederate

At a high level, SCIM is easy to get your head around. It’s simple (built on JSON over REST), lightweight, and provides a fairly robust schema for matching basic user attributes (similar to the LDAP inetOrgPerson object class). However, the real challenge is figuring out how to map your attributes to those of your partner through the medium of the SCIM schema. As long as the attributes are straightforward (again, think inetOrgPerson), the mapping is easy. The fun comes when you want to pass custom attributes.

SCIM is completely CRUD (create, read, update, delete) compliant. As with any other REST interface, this is implemented via HTTP methods. The create (HTTP POST), read (HTTP GET) and delete (HTTP DELETE) methods are easy and straightforward. The complexity comes with an update, and that’s due to the nature of multi-valued attributes supported by the SCIM schema. For example, if a user is allowed to have multiple email addresses, then what is intended when a request is sent for a simple update with a new address? Is this an addition to the existing addresses? Is it a replacement of all addresses? Is it simply a replacement of the third address? This update is an HTTP PUT (“hard” update), or an HTTP PATCH (“soft” update). The PUT is pretty straightforward, as it’s holistic. It’s always preceded by a GET, and is then played back to the SCIM Provider with the entire record intact, to include the attributes that are being updated. The PATCH is a bit trickier, and is completely reliant on the SCIM Provider and how they have implemented handling for this type of request. For this reason, PATCH is not required for a SCIM Provider per the SCIM 1.1 specification.

PingFederate can be deployed on either side of the interface. As an identity provider, PingFederate can be deployed as a SCIM Client, providing you with an outbound provisioning solution to any SCIM-speaking partner for provisioning of your users. As a service provider, PingFederate can be deployed as a consumer of SCIM requests, providing you with an inbound provisioning interface, delivering a fully compliant SCIM 1.1 API.

The following is an example of how user data can be encoded as a SCIM object in JSON, using the HTTPS POST profile. The example isn’t exhaustive of all attributes, but does show the structure of a SCIM object that PingFederate SCIM Inbound Provisioning can process and use to manage objects within Active Directory, any LDAPv3 compliant user credential store, or a back-end database.

POST /v1/Users  HTTP/1.1
Accept: application/json
Authorization: Bearer h480djs93hd8
Host: example.com
Content-Length: 164
Content-Type: application/json
{
    "schemas":["urn:scim:schemas:core:1.0"],
    "userName":"joe.bloggs@pegright.com",
    "name":{
        "givenName":"Joe",
        "familyName":"Bloggs"
    },
    "title":"someguy",
    "displayName":"somedisplayname",
    "preferredLanguage":"en_US",
    "phoneNumbers":[
        {
        "type":"work",
        "primary":"true",
        "value":"123-456-7890"
        }
    ],
    "userType":"partner"
}

In this example, because no “password” field is provided, the configuration within PingFederate would need to be configured to manage the user experience, such as prompting to change password on first usage. If successful, the response to such a request would include the entire user record that was created (minus the password), to include the UID maintained by the SCIM Provider. The client would then use this UID for any subsequent GET or DELETE requests (remember, a PUT is just a GET followed by a comprehensive update). That’s pretty much it!

We’re seeing an increase in the number of organizations seeking to simplify their user provisioning architecture and take advantage of the SCIM open standard. Leveraging SCIM for provisioning and de-provisioning provides a standards-based approach to improving the onboarding process and more importantly, quickly removing access. Let us know if we can help with a current or upcoming SCIM implementation.