SCIM 2.0 Protocol

Owned by Kai Bjørnstad (Deactivated)
Last updated: May 19, 2020
7 min read

Current version of the standard is governed by the following documents: RFC 7642, RFC 7643, and RFC 7644. Note that Buypass does not support SCIM 1.0.

The SCIM 2.0 protocol does not define a scheme for multi-tenancy. Hence SCIM operations towards various eID-schemes and OpenID Security Domains will be separated using different base-urls (variations in both host-names and/or URL-prefixes.

For example: “https://SECURITYDOMAIN.buypass.no/scim/v2/{resource}” or “https://api.buypass.no/SECURITYDOMAIN/scim/v2/{resource}”.

Schema

A SCIM "resource" is a JSON object, ex. "User" and "Group" resources. Each JSON resource representation contains a "schemas" attribute that contains a list of one or more URIs that indicate included SCIM schemas that are used to indicate the attributes contained within a resource (within a User or Group object).

Example of a “User” resource listing two “schemas” values:

{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ], "id":"2819c223-7f76-453a-919d-413861904646", "externalId":"bjensen", "userName":"bjensen", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "employeeNumber": "701984", "costCenter": "4130", ... }, ....... }

This “User” object may contain attributes both from the “urn:ietf:params:scim:schemas:core:2.0:User” (SCIM 2.0 Core) schema and the “urn:ietf:params:scim:schemas:extension:enterprise:2.0:User” (the SCIM 2.0 Enterprise User Schema Extension.

Specific information about what attributes are defined within a schema may be obtained by querying the "/Schemas" endpoint for a schema definition (see https://tools.ietf.org/html/rfc7643#section-8.7.1). This is one of the main methods the SCIM protocol support schema extensions. See SCIM 2.0 Extensions.

While SCIM schemas and an associated extension model are defined in RFC 7643, SCIM clients should expect that some attribute schema may change from service provider to service provider and also across OpenID Security Domains. Hence it is quite reasonable to expect that most of the security domains support only a subset of the schema(s) and attributes defined.

Endpoints and operations

The SCIM protocol specifies well-known endpoints and HTTP methods for managing resources defined in the SCIM Core Schema document, ex. "User" and "Group" resources correspond to "/Users" and "/Groups", respectively.

Along with HTTP headers and URIs, SCIM uses JSON payloads to convey SCIM resources, as well as protocol-specific payload messages that convey request parameters and response information such as errors. A SCIM "resource" is a JSON object that may be created, maintained, and retrieved via HTTP request methods. The HTTP methods are basically mapped “CRUD” operations on each endpoint/each resource.

Note that some of the SCIM specified well-known endpoints and operations are optional. This means that both different endpoints and the various operations on an endpoint are optional and may vary depending on context and security domain.

The table below describes an overview of the endpoints and operations supported by Buypass in a typical setup:

Endpoint

Operations

Description

Endpoint

Operations

Description

/Users

Full support:

  • GET (Retrieves a user, including attributes)

  • POST (Creates a user, with attributes)

  • DELETE (Delete a user)

Limited support:

  • PUT (Modifies an existing user by replacing one or more user attributes)

No support:

  • PATCH (Modify an existing user by "add", "remove", or "replace" attribute values)

This endpoint is typically used by IAM/IDM and administrator systems.

Full support is provided for the basic operations. Note that in some schemes, the GET may return more or less user attributes/data than provided in the POST.

Filtering may have limited support/support will be implemented as required by the security domain.

Limited support is provided for updating user attributes as this is highly dependent on the security domain. In some cases there might be no option to update the user data, in others only a very limited part of the data may be updated by external clients.

/Me

Supported only in some defined domains/contexts.

Full support:

  • GET (Retrieves the authenticated user, including attributes)

  • DELETE (Delete the authenticated user)

Limited support:

  • POST (Creates the authenticated user, with attributes. This will basically act as a “register” function and only be applicable in some contexts.)

  • PUT (Modifies the existing authenticated user by replacing one or more user attributes)

No support:

  • PATCH (Modify an existing authenticated user by "add", "remove", or "replace" attribute values)

This endpoint is used by self-service applications.

This endpoint will be implemented in the cases where a self-service application is needed. The endpoint set the operational context of the SCIM API to only operate on the authenticated end-user itself. This enables the option of creating simple 3rd-party self-service interfaces on top of the SCIM API.

Note that the attributes, operations and data available in this endpoint may differ from that of the /Users.

/Groups

Supported only in some defined domains/contexts.

Full support:

  • GET (Retrieves a group, including attributes)

  • POST (Creates a group, with attributes)

  • DELETE (Delete a group)

No support:

  • PUT (Modifies an existing group by replacing one or more group attributes)

  • PATCH (Modify an existing group by "add", "remove", or "replace" attribute values)

This endpoint is typically used by IAM/IDM and administrator systems.

Note that this endpoint, and support for the “Group” resource in general will only be implemented for specific contexts and security domains.

"Group" resources are meant to enable expression of common group-based or role-based access control models. Buypass primarily provide authentication services, not authorization services. Hence group information will have a very limited scope, ex. for simple administration interfaces.

 

/ServiceProviderConfig

Full support:

GET (Retrieve this SCIM API, and Security Domains configuration)

Discovery endpoint.

This endpoint will return a JSON structure that describes the SCIM specification features available for this instance.

/Schemas

Full support:

GET (Retrieve one or more supported schemas)

Discovery endpoint.

This endpoint is used to retrieve information about resource schemas supported in this instance.

/ResourceTypes

Full support:

GET (Retrieve supported resource types)

Discovery endpoint.

This endpoint is used to discover the types of resources available

/Bulk

Not supported

The SCIM bulk operation is an optional server feature that enables clients to send a potentially large collection of resource operations in a single request.

[prefix]/.search

Not supported

Enable clients to execute queries without passing parameters on the URL by using the HTTP POST verb combined with the "/.search" path extension.

Discovery endpoints

As listed in the table above, SCIM defines three endpoints to facilitate discovery of SCIM service provider features (se also RFC 7644, Service Provider Configuration Endpoints). These endpoints can be queried for a security domain to discover what features are implemented in a specific domain and what schemas are supported.

Below are examples of output generated by these endpoints:

ServiceProviderConfig

Request using curl:

curl -X GET "https://api.buypass.no/SECURITYDOMAIN/scim/v2/ServiceProviderConfig" -H "accept: */*"

Response as JSON:

The respone indicates that “patch” and “bulk” is not supported and “oauthbearertoken” is the only available authentication method.

{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig" ], "documentationUri": "https://developer.buypass.com", "patch": { "supported": false }, "bulk": { "supported": false, "maxOperations": 1000, "maxPayloadSize": 10000 }, "filter": { "supported": true, "maxResults": 25 }, "changePassword": { "supported": false }, "sort": { "supported": false }, "etag": { "supported": false }, "authenticationSchemes": [ { "name": "OAuth2 Bearer Token", "description": "Authentication Scheme using OAuth2 Bearer Token Standard", "specUri": "https://tools.ietf.org/html/rfc6750", "documentationUri": "https://developer.buypass.com", "type": "oauthbearertoken", "primary": true } ], "meta": { "resourceType": "ServiceProviderConfig", "location": "https://api.buypass.no/SECURITYDOMAIN/scim/v2/ServiceProviderConfig" } }

Schemas

Request using curl:

Response as JSON:

The “attributes” listing is omitted readability, replaced with “….”. Note that the endpoint list to available schemas; the core “urn:ietf:params:scim:schemas:core:2.0:User“ schema and the extension “urn:ietf:params:scim:schemas:extension:buypass:fido2:User” (see also SCIM 2.0 Extensions). The “location” attributes point to endpoints where more specific schema information exists.

ResourceTypes

Request using curl:

Response as JSON:

Note that the response indicating support only for the “User” resource, and not “Group”. The response also lists how an extension has been added as part of the “User” resource: the “urn:ietf:params:scim:schemas:extension:buypass:fido2:User” resource type. The “location” attributes point to endpoints where more specific resource type information exists.

Resource endpoints

As mentioned, what resources and operations that are available is highly dependent on the business rules of each OpenID Security Domains. For example the “Group” resource will probably only be needed in a limited set of cases.

The “resource” concept in SCIM also dictate that a SCIM resource is implemented as separate root endpoints. This means that if there is a need for new resources as extension, they will appear as new endpoints.

Users

The “User” resource is part of the SCIM Core schema. Below is an example of the minimal required SCIM representation in JSON format:

A SCIM Core full representation is documented here: https://tools.ietf.org/html/rfc7643#section-8.2

Me

The schema and operations on the “Me” resource are basically the same as for the “User” resource. The main difference is operational context and authorisation. The “Me” resource is basically an alias for the “User” resource currently authenticated towards the SCIM API.

Un short, the “Me” resource only makes sence in a self-service context, where the user is logged in (typically by using Authentication with OIDC), and where the SCIM 2.0 API authentication is done using the end-user Access Token. Hence all operations happen in context of the authenticated user.

Groups

The “Group” resource is part of the SCIM Core schema. Below is an example of the SCIM representation in JSON format:

Resource extension endpoints

The SCIM specification enable both extensions in the form of extra attributes on existing resources, but also as new separate resources if needed.

At the time of writing, no such extensions are needed/available.