SCIM endpoints
The endpoints that a USoft SCIM server exposes. To set the server up, see How to set up USoft as a SCIM server.
The USoft SCIM server implementation follows the SCIM 2.0 specification. Request and response bodies, filtering and pagination are all as that specification describes them.
All endpoints are relative to the base URL displayed on the Rules Service overview page, the final page of the Rules Service configuration wizard. That base URL ends in /scim/v2/.
Media types
| Direction | Media type |
|---|---|
| Responses | application/scim+json |
| Request bodies (POST, PUT, PATCH) | application/scim+json or application/json |
Discovery endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /ResourceTypes | Lists the resource types the server supports |
| GET | /ResourceTypes/{ResourceType} | Returns one resource type |
| GET | /Schemas | Lists the schemas the server supports |
| GET | /Schemas/{SchemaType} | Returns one schema |
| GET | /ServiceProviderConfig | Returns the configuration of the SCIM server |
The discovery endpoints do not require authentication. Any client that can reach the SCIM server can read them, whichever Auth. Scheme you configured. The /Users and /Groups endpoints do require authentication.
/ResourceTypes and /Schemas accept the startIndex and count query parameters.
The USoft platform serves two schemas by default:
- Default user schema -
urn:ietf:params:scim:schemas:core:2.0:User - Default group schema -
urn:ietf:params:scim:schemas:core:2.0:Group
For what these schemas contain, see SCIM users and groups.
Supported capabilities
GET /ServiceProviderConfig reports which parts of the SCIM specification the server supports:
| Capability | Supported | Notes |
|---|---|---|
patch | Yes | PATCH modifies part of a user or group |
filter | Yes | See Query parameters for listing |
sort | No | See Sorting |
bulk | No | Send one request per resource |
etag | No | The server does not version resources |
changePassword | No | Passwords cannot be set over SCIM |
The server advertises two authentication schemes: HTTP Basic, and a static bearer token. Which of the two a client must use is set with Auth. Scheme. See Step 6 of the setup guide.
Supported identity providers
USoft's SCIM server is tested and verified against Microsoft Entra ID and Okta.
Beyond these two, any identity provider that generically implements SCIM 2.0 should also work against the /Users and /Groups endpoints, provided it follows the SCIM 2.0 RFCs and adheres to the capabilities and constraints that GET /ServiceProviderConfig reports, as listed under Supported capabilities above.
/Users and /Groups endpoints
The /Users and /Groups endpoints act only on the users and roles that are linked to SCIM. Users and roles that are not linked to SCIM are never returned and cannot be manipulated. See SCIM users and groups.
/Users
| Method | Endpoint | Description |
|---|---|---|
| GET | /Users | Lists users |
| GET | /Users/{id} | Returns one user |
| POST | /Users | Creates a user |
| PUT | /Users/{id} | Replaces a user |
| PATCH | /Users/{id} | Modifies part of a user |
| DELETE | /Users/{id} | Deletes the user physically |
/Groups
| Method | Endpoint | Description |
|---|---|---|
| GET | /Groups | Lists groups |
| GET | /Groups/{id} | Returns one group |
| POST | /Groups | Creates a group |
| PUT | /Groups/{id} | Replaces a group |
| PATCH | /Groups/{id} | Modifies part of a group |
| DELETE | /Groups/{id} | Unlinks the group from SCIM. The role itself is kept |
Query parameters for listing
GET /Users and GET /Groups support the SCIM 2.0 filtering and pagination parameters:
| Parameter | Description |
|---|---|
filter | Restricts the results to the resources that match the filter expression |
startIndex | The 1-based index of the first result to return |
count | The number of results to return. If you omit it, the server returns at most 500 |
The filter expression itself follows the grammar the SCIM 2.0 specification defines, including its comparison operators (eq, ne, co, sw, ew, pr, gt, ge, lt, le) and logical operators (and, or, not).
A filter can only reference a basic, single-valued attribute of the resource, such as userName, displayName, active or externalId. It cannot reference a complex or multi-valued attribute, such as a user's groups or a group's members, or a sub-attribute of one. It also cannot reference an attribute by its fully qualified schema path (for example urn:ietf:params:scim:schemas:core:2.0:User:userName) — use the plain attribute name instead.
Examples
Filter users by user name:
http://localhost:40506/scim/v2/Users?filter=userName eq "user@usoft.com"
Return the first ten users:
http://localhost:40506/scim/v2/Users?startIndex=1&count=10
In these examples, 40506 is the Server Portnumber configured for the SCIM server.
Sorting
The SCIM 2.0 specification defines sortBy and sortOrder query parameters for ordering the results of a GET that lists resources. The USoft SCIM server does not implement them.
Omitting the resource id
PUT, PATCH and DELETE act on a single resource and require an id in the request URL. If you send one of these requests to /Users or /Groups without an id, the server returns HTTP 400 (Bad Request) with scimType invalidValue and a message stating that the id is missing.
Related documentation
- Introduction to SCIM - what SCIM is and why USoft implements it as a SCIM server.
- How to set up USoft as a SCIM server
- How to connect an identity provider to a USoft SCIM server
- SCIM users and groups - how SCIM users and groups map onto Authorizer data.
- SCIM logging - the structure of
SCIM-<portnr>.logand how to use it as an audit trail. - Schemas and extension properties