What is SCIM?

SCIM is a standard protocol for accessing identity information (users, roles, etc), including querying, retrieval, create, update and delete. The latest version of SCIM, SCIM 2.0, has been defined in a series of RFCs: RFC 7642, RFC 7643 and RFC 7644.

What does SCIM stand for?

Originally it was an acronym for “Simplified Cloud Identity Management”. When SCIM moved to the IETF during the development of SCIM 2.0, the acronym was kept but the expansion was changed to “System for Cross-domain Identity Management”. The reason was that, while SCIM was originally developed for use with Cloud services, it is not in any way exclusive to the Cloud, and can be used just as well with purely on-premise scenarios. The new name reflects that.

Why SCIM?

For many years, the primary protocol used for accessing identity data has been LDAP. LDAP started out (back in 1993) as a simplification of the X.500 Directory Access Protocol (DAP). DAP was originally part of the OSI protocol suite; it is a complex binary protocol, described using ASN.1. In simplifying it, LDAP removed some of the more complex binary encodings from DAP and replaced them with plain text strings; nevertheless, it is still fundamentally a binary ASN.1-based protocol.

Over 20 years later, and the industry has largely moved on from ASN.1 binary protocols. Some of them are still around and still used – the most notable being LDAP and SNMP – but few people designing a new protocol today would choose ASN.1 as a base. The most popular approach for network communication nowadays is RESTful web services using JSON. The key advantages of this approach:

  • It runs over HTTP(S), which is the protocol with the broadest support on the public Internet. Attempts to use other protocols are in many cases blocked by firewalls which will let HTTP(S) through (whether directly, or via a web proxy)
  • Middle boxes such as firewalls, load balancers, API gateways (such as Oracle API Gateway), etc., have excellent support for handling HTTP(S)-based protocols, whereas the support for non-HTTP protocols (such as LDAP) is much more patchy
  • Developers have ample experience with calling REST/JSON APIs, and the ability to call them is increasingly included with popular development platforms. To use binary protocols such as LDAP, you generally need to use an LDAP client library. While SCIM client libraries exist, it is feasible for a developer to call it directly without using any such client; that is far less feasible for LDAP.

What about DSML and SPML?

SCIM is not the first attempt to create a more modern successor protocol to LDAP. DSML (Directory Service Markup Language) was an earlier attempt, based on XML and SOAP. While DSML has seen some adoption over the years, XML-based protocols have lost favour due to their complexity compared to JSON-based protocols. SPML (Service Provisioning Markup Language), which extends DSML with richer provisioning operations, is another; like DSML, it is based on XML and SOAP web services. SCIM can be used to replace the functionality of DSML and SPML.

Summary of the SCIM 2.0 RFCs

SCIM 2.0 is defined in 3 RFCs. I provide below a brief summary of the contents of each one:

  • RFC 7642: This RFC describes some of the chief use cases the SCIM protocol was designed to solve, in particular related to its use with Cloud services. (However, although these use cases provided the original impetus for designing the SCIM protocol, SCIM is by no means limited to these use cases only.)
  • RFC 7643: This defines SCIM schemas. SCIM schemas are conceptually similar to LDAP schemas, however they are expressed in a JSON syntax. Instead of “object classes”, SCIM uses resource types (e.g. “User”) and named schemas. Schemas are named by URIs, generally starting with urn:ietf:params:scim:schemas:.... As well as defining the basic infrastructure of SCIM schemas, this RFC defines two standard resource types (“User” and “Group”) and standard schemas providing a basic set of attributes for those resource types.
  • RFC 7644: This RFC defines the basic operations that must be supported by a SCIM server. As a REST-based protocol, these operations are expressed by standard HTTP verbs such as GET, POST, PUT and DELETE. In addition to those more commonly used HTTP verbs, SCIM also uses the HTTP PATCH verb to perform modification operations.

Note that in addition to RFCs, it is important to read the documentation of the implementing products. Most SCIM vendors (Oracle included) add extensions to the standard to support specific functions in their products. These extensions include additional resource types, and additional schemas and attributes.

HTTP verbs used in SCIM

This table shows the HTTP verbs used in SCIM and how SCIM uses them:

HTTP Method Usage in SCIM
GET Retrieves the attributes of a SCIM resource as a JSON document
POST Purpose varies depending on the endpoint. Used to create new resources (e.g. create new users), perform bulk operations, and perform searches.
PUT Modifies an existing resource (e.g. a User) by replacing all of its attributes with new values. This requires the SCIM client to first retrieve the entire resource with GET, then modifying that JSON document by adding/updating/removing the attributes it desires, then PUTting the modified JSON document back to the same resource endpoint.
PATCH Also used to modify an existing resource, but supports finer-grained modification than PUT. Whereas with PUT you have to first retrieve all the attributes, and then send all the attributes (with your changes) back to the server, with PATCH you specify the specific attributes you wish to modify, and only send those attributes to the SCIM server. As a result, PATCH is more efficient than PUT (but is more complex to implement).
DELETE Deletes a specified resource (e.g. a User)

(Acknowledgement: The above table is based on RFC7644 section 3.2.)

HTTP Endpoints used in SCIM

As a REST-based protocol, every SCIM resource has a URL. This URL has three components:

  1. The SCIM server base URL; this includes the protocol scheme (in production environments, should be https://, the hostname (and port if necessary), and the base path of the SCIM endpoint (this will vary from product to product; for the OIM SCIM server, it is /idaas/im/scim/v1
  2. The resource type, for example Users
  3. An identifier of the specific resource. This is usually an opaque string such as a number or a UUID; SCIM clients should not make any assumptions about the structure of SCIM resource identifiers.

To give an example, a individual user resource in the OIM SCIM server might have the URL: https://myoimserver.example.com/idaas/im/scim/v1/Users/136971

The following table shows the SCIM endpoints defined in RFC7644. Note that since implementations are allowed to define new resource types (and indeed, usually will do so), that entails additional endpoints for those additional resource types. The URLs in the table below are relative to the SCIM server base URL.

Resource Endpoint HTTP Verbs Description
User /Users GET, POST, PUT, PATCH, DELETE Retrieve, add, modify and delete users
Group /Groups GET, POST, PUT, PATCH, DELETE Retrieve, add, modify and delete groups
Self /Me GET, POST, PUT, PATCH, DELETE This is an alias for the user the client has authenticated as. It can be used to perform self-service operations, e.g. updating the attributes of your own user account.
Service provider configuration /ServiceProviderConfig GET This resource enables a SCIM client to discover which specific SCIM protocol features a SCIM server supports.
Resource type /ResourceTypes GET Retrieves supported resource types
Schemas /Schemas GET Enables SCIM client to retrieve the schemas this server supports
Bulk /Bulk POST Supports bulk updates to multiple resources (e.g. bulk update many user resources in a single SCIM call)
Search /.search POST Used to perform a search against a specific resource type endpoint, or against all resource types

(Acknowledgement: The above table is based on RFC7644 section 3.2.)

SCIM support in Oracle products

One of the new features introduced in Oracle Identity Manager 11.1.2.3 is a SCIM server. The documentation is here. If you were at OpenWorld 2015 (or saw the replays), you may have seen the announcement of our new Identity Cloud Service (IDCS). At the time of writing, this has not yet been released, but it will heavily use SCIM.

Comments

  1. I would like to connect to the SCIM Web service via a Web Application Firewall. Are there WAFs that understand SCIM? Is there a reference implementation?

    • Hi Jan. I’m not aware of any Web Application Firewall (WAF) with specific awareness of SCIM. But, since it is just JSON over HTTP(S), there is no reason why in principle you could not access it via a WAF.

      There is no official “reference implementation” for SCIM 2.0.

Add Your Comment