Overview

The System for Cross-domain Identity Management (SCIM) specification is designed to make managing user identities in cloud-based applications and services easier. The specification suite seeks to build upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models. Its intent is to reduce the cost and complexity of user management operations by providing a common user schema and extension model, as well as binding documents to provide patterns for exchanging this schema using standard protocols. In essence: make it fast, cheap, and easy to move users in to, out of, and around the cloud.

Information on this overview page is not normative.

Model

SCIM is built on a object model where a Resource is the common denominator and all SCIM objects are derived from it. SCIM currently has three objects that directly inherit from the Resource object. The ServiceProviderConfiguration and Schema are used for discovery and contain no user information. The CoreResource object is where user and group data are contained, within its two child resources, User and Group.

Example User

This is an example of how user data can be encoded as a SCIM object in JSON. XML encoding is also defined in the specification.

While this example does not contain the full set of attributes available, notice the different types of data that can be used to create SCIM objects. Simple types like strings for id, username, etc. Complex types, i.e. attributes that have sub-attributes, for name and address. Multivalued types for e-mail, phonenumber, address, etc.

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "id":"2819c223-7f76-453a-919d-413861904646",
  "externalId":"bjensen",
  "meta":{
    "created":"2011-08-01T18:29:49.793Z",
    "lastModified":"2011-08-01T18:29:49.793Z",
    "location":"https://example.com/v1/Users/2819c223...",
    "version":"W\/\"f250dd84f0671c3\""
  },
  "name":{
    "formatted":"Ms. Barbara J Jensen III",
    "familyName":"Jensen",
    "givenName":"Barbara"
  },
  "userName":"bjensen",
  "phoneNumbers":[
    {
      "value":"555-555-8377",
      "type":"work"
    }
  ],
  "emails":[
    {
      "value":"bjensen@example.com",
      "type":"work"
    }
  ]
}

Example Group

In addition to users, the SCIM core includes the group concept. Groups are used to model the organizationational structure of provisioned objects. Groups can contain users or other groups .

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "id":"2819c223-7f76-453a-919d-413861904646",
  "displayName": "Tour Guides",
  "members":[
    {
      "value":"2819c223-7f76-453a-919d-413861904646",
      "displayName":"Babs Jensen",
      "type":"User"
    },
    {
      "value":"2819c223-7f76-453a-919d-413861904646",
      "displayName":"Mandy Pepperidge",
      "type":"User"
    }
  ]
}

Operations

For manipulation of resources, SCIM provides a REST API with a rich but simple set of operations, which support everything from patching a specific attribute on a specific user to doing massive bulk updates:

• Create = POST https://example.com/{v}/{resource}
• Read = GET https://example.com/{v}/{resource}/{id}
• Replace = PUT https://example.com/{v}/{resource}/{id}
• Delete = DELETE https://example.com/{v}/{resource}/{id}
• Update = PATCH https://example.com/{v}/{resource}/{id}
• Search = GET https://example.com/{v}/{resource}?filter={attribute}{op}{value}&sortBy={attributeName}&sortOrder={ascending|descending}
• Bulk = POST https://example.com/{v}/Bulk

Discovery

To simplify interoperability, SCIM provides two end points to discover supported features and specific attribute details:

• GET /ServiceProviderConfigs

  Specification compliance, authentication schemes, data models.

• GET /Schemas

  Introspect resources and attribute extensions.

Create Request

To create a resource, send an HTTP POST request to the resource's respective end point. In the example below we see the creation of a User.

As can be seen in this and later examples the URL contains a version number so that different versions of the SCIM API can co-exist. Available versions can be dynamically discovered via the ServiceProviderConfig end point.

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"],
  "externalId":"bjensen",
  "userName":"bjensen",
  "name":{
    "familyName":"Jensen",
    "givenName":"Barbara"
  }
}

Create Response

A response contains the created Resource and HTTP code 201 to indicate that the Resource has been created successfully. Note that the returned user contains more data then was posted, id and meta data have been added by the service provider to make a complete User object. A location header indicates where the resource can be fetched in subsequent requests.

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1"

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "id":"2819c223-7f76-453a-919d-413861904646",
  "externalId":"bjensen",
  "meta":{
    "created":"2011-08-01T21:32:44.882Z",
    "lastModified":"2011-08-01T21:32:44.882Z",
    "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
    "version":"W\/\"e180ee84f0671b1\""
  },
  "name":{
    "familyName":"Jensen",
    "givenName":"Barbara"
  },
  "userName":"bjensen"
}

Get Request

Fetching resources is done by sending HTTP GET requests to the desired Resource end point, as in this example. Note the postfixed '.json' at the end of the URL. This is another method for clients to indicate the desired response format, in addition to using the accept header.

GET /v1/Users/2819c223-7f76-453a-919d-413861904646.json  
Host: example.com
Accept: application/json
Authorization: Bearer h480djs93hd8

Get Response

The response to a GET contains the Resource. The Etag header can, in subsequent requests, be used to prevent concurrent modifications of Resources.

HTTP/1.1 200 OK
Content-Type: application/json
Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
Etag: W/"e180ee84f0671b1"

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "id":"2819c223-7f76-453a-919d-413861904646",
  "externalId":"bjensen",
  "meta":{
    "created":"2011-08-01T21:32:44.882Z",
    "lastModified":"2011-08-01T21:32:44.882Z",
    "location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
    "version":"W\/\"e180ee84f0671b1\""
  },
  "name":{ ...

Filter Request

In addition to getting single Resources it is possible to fetch sets of Resources by querying the Resource end point without the id of a specific Resource. Typically, a fetch request will include a filter to be applied to the Resources. SCIM has support for the filter operations equals, contains, starts with, and more. In addition to filtering the response it is also possible to ask the service provider to sort the Resources in the response.

In addition to filtering the response it is also possible to ask the service provider to sort the Resources in the response, return specific attributes of the resources, and return only a subset of the resources.

• https://example.com/{resource}?filter={attribute} {op} {value} & sortBy={attributeName}&sortOrder={ascending|descending}&attributes={attributes}
• https://example.com/Users?filter=title pr and userType eq “Employee”&sortBy=title&sortOrder=ascending&attributes=title,username

Filter Response

The response to a GET request is a list of matching resources:

{
  "schemas":["urn:scim:schemas:core:1.0"],
  "totalResults":2,
  "Resources":[
    {
      "id":"c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
      "title":"Assistant VP",
      "userName":"bjensen"
    },
    {
      "id":"a4a25dd3-17a0-4dac-a2ac-ce211e125f57",
      "title":"VP",
      "userName":"jsmith"
    }
  ]
}