How to Create a SCIM 2.0 Server Configuration by Hand

Create a SCIM 2.0 Server Configuration Manually

RFCs are notoriously hard to read, and translating them into correct JSON documents for the service discovery endpoints /ServiceProviderConfig, /ResourceTypes, and /Schemas can be error-prone and open to interpretation. If you’re not yet fully familiar with SCIM, you may want to start with an introduction to SCIM and how it works in practice before diving into the technical details.

RFC 7643 provides the core schemas in JSON form, but they contain errors that must be corrected before use. While tools exist to bridge SCIM and existing REST APIs, if all you need is the service configuration for your application, you can do it manually.

What Do I Need to Support?

From a practical perspective, you need to support at least:

• The core User resource type using the core User schema.

• The core Group resource type using the core Group schema.

The SCIM standard allows you to customize your resources completely, but this would compromise interoperability.

In practice, these two resource types are essential. For each resource, you must support the common attributes id, externalId, and meta with its sub-attributes (except the optional meta.version).

Attributes for the User

The User must include at least the attribute userName. It is highly recommended to support active and password, unless your service does not offer such functionality.

If it is not technically demanding to determine all memberships of a given user, you should also support the groups attribute, including its sub-attributes. Populate groups.display with the displayName of the respective group.

Note that the groups.type sub-attribute has a different meaning than its counterpart in the members attribute of the Group. If you do not have implicit memberships, set it to “direct” instead of omitting the attribute. This is more client-friendly. Don’t forget to adjust canonicalValues for groups.type in the schema to only include “direct”.

Support for other attributes is optional.

1. Download the schema definition. Use our corrected schema definition instead of copying the schemas from the RFC 7643, as the latter contains errors that need manual correction.

2. Go through the schemas and their attributes one by one, creating an initial mapping to the attributes in your application.

3. Look up all mapped attributes in RFC 7643 and verify their meanings. Never use attributes with meanings that differ from the standard. Adjust your mapping table, if necessary.

4. Analyze interdependencies between attributes you want to expose via SCIM and avoid them where possible. The RFC 7643 defines some interdependencies (e.g. between the $ref and value sub-attributes), which clients will expect. However, SCIM schemas do not allow you to specify other interdependencies and they might cause interoperability problems. A client cannot preempt such interdependencies, but only react to results of its actions – and it might not react as you expected. Assume, an attribute cannot be changed because a different boolean attribute is set. You could either reject the operation or have it succeed without actually changing the value. It is easy to see that both cases would provide a bad user experience. Some examples of interdependencies are:

   • Your application requires clients to provide any one of two attributes.

   • Setting one attribute depends on the value of another.

   • Changing one attribute causes changes in another.

5. Remove unsupported attributes and sub-attributes from the core User schema.

6. Review the remaining attributes, check their properties, and adjust them. Do not change the name or type of any attribute. 

7. If you have attributes left without SCIM counterparts, move on to the Enterprise User schema.

8. Create your own schema extensions if necessary. Use the sub-attributes defined in the SCIM standard for better interoperability (type, primary, display, value, $ref).

9. Use our SCIM 2.0 Schema Checker to validate your result.

Attributes for the Group

The Group must include the attributes displayName and members with its sub-attributes. Note that the members.type sub-attribute has a different meaning than its counterpart in the groups attribute of the User. If only users can be members of your groups, set it to “User” instead of omitting the attribute. This is more client-friendly. Don’t forget to adjust canonicalValues for members.$ref and members.type in the schema only to include “User”.

Resource Type and Service Provider Configuration

Defining the core resource types and service provider configuration is straightforward. Download the JSON files, which we have corrected for errata in the RFC, and adjust them as needed.

Service Discovery Configuration Definitions

You can either provide definitions for the configuration resources ServiceProviderConfig, ResourceType, and Schema at the /ResourceTypes and /Schemas endpoints or remove them entirely. The second option is simpler. Do not expect clients to react to any changes in these definitions, as they are not self-explanatory enough. 

A Comment on the Technical Details of the SCIM Standard

Over 96% of all SCIM service providers use SCIM 2.0, the current version defined by:

1. RFC 7642 is informational and “lays out the system’s concepts, models, and flows, and it includes user scenarios, use cases, and requirements.”

2. RFC 7643 is the technical specification for the “schema and extension model for representing users and groups and other resource types.”

3. RFC 7644 is the technical specification of the SCIM Protocol for data exchange.

The RFC 7643 suggests a set of sub-attributes for complex attributes, resulting in consistent naming and usage by service providers (section 2.4):

• type

• primary

• display

• value

• $ref

This is an effective and useful approach that could also have been applied to resources. Every resource type should have a human-readable ID, like userName in the core User, and a display attribute. The core user has a displayName attribute with the same meaning and semantics as display. The core group’s displayName attribute has slightly different semantics: It is non-unique like display, but required, suggesting it should also serve as human-readable ID.

The fundamental improvement of SCIM 2.0 over previous versions is the introduction of the /ResourceTypes and /Schemas discovery endpoints, making SCIM extensible and flexible. Separating resource type and schema definitions allows to use a single schema for several resource types. While this seems like a useful idea, in practice, implementations always use a 1:1 mapping.

Therefore, embedding the schema definition within the resource type would simplify things and eliminate the need for schema extensions. This would even work for the core resources. The RFC states that, “Where permitted, individual values and schema MAY change,” but hardly sets any limits. As a result, core schemas can be – and are – changed almost without restriction and some service providers already add attributes to the core schemas.

Ambiguities in SCIM RFC Language

The RFC 7643 contains a significant amount of imprecision, more than is usual for RFCs. The most notable example is the imprecise use of keywords like REQUIRED and OPTIONAL. For instance, an attribute can have the property “required”: true, whose meaning of this is defined in RFC 7644: a client must supply a value for such attributes when replacing a resource. This is not the same as the REQUIRED keyword defined in RFC 2119. Yet, RFC 7643 equates the attribute property and the keyword in section 2.2, but does not consistently follow this. Throughout RFC 7643, both the keyword and the attribute property seem to indicate that attributes must have a value, which is not the same as requiring the client to provide one.

As a result, many read-only attributes have the required property set, and many attributes are labeled REQUIRED even though they do not need to be supported. The most straightforward interpretation of the REQUIRED keyword for attributes would be to require support of the attribute, i.e. it must be possible that the attribute has a value. Any compliant server must include it in the schema, and clients must be able to handle it.

In this sense, the attribute id is REQUIRED. But what about externalId? Must a server support the externalId attribute to be standard-compliant? Servers cannot declare support for common attributes, as they are always implicitly included in the schema: RFC 7643 states in section 3.1, “Common attributes are considered to be part of every base resource schema.” This suggests that since they are part of the schema, they must be supported. However, some service providers do not support externalId, arguing that the RFC says, “This attribute is OPTIONAL.” Likely, this only means that externalId does not have to have a value and does not have the required property set. This would override the earlier statement: “With the exception of the “ServiceProviderConfig” and “ResourceType” server discovery endpoints and their associated resources, these attributes MUST be defined for all resources.” Here, be defined again seems to mean have a value, since section 5 states that common attributes are also added to the base schema of the ServiceProviderConfig resource.

The central attribute in SCIM is id. Without it, SCIM would not work: Any resource can be accessed directly by appending its id to the endpoint, though this is not explicitly stated in the RFCs. However, it is not true for every resource. One indomitable resource is referenced by its name attribute instead of its id: the resource type resource. This inconsistency is not just academic – a client must check the resource type to determine the base schema of a resource, as described in the RFC. This procedure could have been avoided if the resource simply indicated which of its schemas is the base schema.

Does the SCIM Standard Need an Update?

The RFC 7643 is often vague and difficult to interpret. An updated version, such as SCIM 2.1, would be valuable.

Improvements could include:

• Review and correct all RFC 2119 keywords usage, especially in RFC 7643.

• Clarify the distinction between readWrite and writeOnly. The values indicate differences in readability, which might collide with the returned property. Also, writeOnly might indicate a sensitive value which should not be logged. However, this is a different issue and may be better handled by a new sensitivity property (e.g. default, personal, secret).

• Clarify the role of the id attribute for resource retrieval.

• Clearly state for each attribute whether support is required and if it must always have a value.

• Use schema definitions to define core attribute properties for greater clarity and precision.

• Clarify the meaning of the required property. Clients should provide values for such attributes when creating or replacing resources, not just on replacement.

• Clearly distinguish obligations for servers and clients.

• Define which schema parts can or cannot be changed.

• Replace circular definitions with meaningful ones (e.g. in RFC 7643, for required and changePassword).

• Clarify the meaning of the property “uniqueness”: “server” and require enforcement.

• Add an attribute to resources to specify their base schema.

• Recommend attribute names for human-readable IDs and display purposes for all resources, and add such an ID to the Group schema.

• Remove the outdated canonical values from the ims attribute.

Most service providers and clients would remain compatible, while new implementations would be easier to develop. Another question is whether it is time to begin work on SCIM 3.0, which would allow for incompatible changes. While there are several possible areas of change, none seem valuable enough to justify the effort for most service providers and clients.