SCIM users and groups
How the Users and Groups of a SCIM client map onto USoft Authorizer data. For the endpoints that act on them, see SCIM endpoints.
SCIM manipulations take place in USoft Authorizer, not in your own application.
This is relevant when your application consumes USoft Authorizer as a module and you have written additional constraints on the user table. Those constraints belong to your application, so SCIM manipulations do not trigger them.
Users
A SCIM user is an Application User. SCIM users are stored in the Authorizer table T_AUTH_USER, the same table that holds the other Application Users of your application.
SCIM users are stored with Validation Agent = Single Sign On. See Authentication and the USoft platform for what the Validation Agent of a user controls.
The externalId that the SCIM client assigns to the user is stored in the EXTERNAL_ID column. A user whose EXTERNAL_ID is not empty is therefore linked to SCIM:
SELECT * FROM T_AUTH_USER WHERE EXTERNAL_ID IS NOT NULL
User attributes
By default, the USoft platform serves the urn:ietf:params:scim:schemas:core:2.0:User schema: view the default user schema.
You can also request it from a running SCIM server, at Schemas/urn:ietf:params:scim:schemas:core:2.0:User under its base URL. See Discovery endpoints.
The attributes of the schema map onto the following T_AUTH_USER columns:
| SCIM attribute | Type | Required | Column | Prompt |
|---|---|---|---|---|
id | string | USER_GUID | ||
userName | string | Yes | USERNAME | Name |
displayName | string | No | DISPLAY_NAME | Display Name |
active | boolean | No | ACTIVE | Active |
startDate | dateTime | No | START_DATE | Start date |
endDate | dateTime | No | END_DATE | End date |
externalId | string | No | EXTERNAL_ID |
userName must be unique across the SCIM server.
The schema also declares groups, a multi-valued complex attribute listing the groups the user belongs to. It is read-only, so you cannot change a user's group membership through the user. Use the members attribute of the group instead.
A newly created SCIM user belongs to no group, and so has no role. This does not leave the user with some basic, entry-level access: in the USoft platform, a role is the only mechanism through which a user gets access to anything (see Understanding roles and access rights), so a user with no role cannot log on to the application at all. Creating the user with POST /Users is therefore not enough to give it access — the user must also be added to a group's members attribute.
Deleting a user over SCIM deletes it physically: the record is removed from T_AUTH_USER.
startDate and endDate are not attributes of the core User schema that the SCIM specification defines. The USoft platform adds them to the schema it serves.
Groups
A SCIM group corresponds to a USoft role. Roles are stored in the Authorizer table T_AUTH_ROLE.
The externalId that the SCIM client assigns to the group is stored in the EXTERNAL_ID column of that table. A role whose EXTERNAL_ID is not empty is therefore linked to SCIM:
SELECT * FROM T_AUTH_ROLE WHERE EXTERNAL_ID IS NOT NULL AND DELETED = 'N'
You can only create a SCIM group whose name matches the name of an existing role that is not for some reason marked as deleted. A request that creates a group with a name that matches no role fails.
Group attributes
By default, the USoft platform serves the urn:ietf:params:scim:schemas:core:2.0:Group schema: view the default group schema.
You can also request it from a running SCIM server, at Schemas/urn:ietf:params:scim:schemas:core:2.0:Group under its base URL. See Discovery endpoints.
The attributes of the schema map onto the following T_AUTH_ROLE columns:
| SCIM attribute | Type | Required | Column | Prompt |
|---|---|---|---|---|
id | string | ROLE_GUID | ||
displayName | string | Yes | ROLE_NAME | Role |
externalId | string | No | EXTERNAL_ID |
displayName must be unique across the SCIM server, and must match the name of an existing role. Because the displayName attribute is linked to the key column of the corresponding T_AUTH_ROLE role table in the Authorizer, you cannot change this value through SCIM.
The schema also declares members, a multi-valued complex attribute listing the members of the group. Unlike the groups attribute of a user, members can be written, so this is where you maintain group membership.
Deleting a group over SCIM does not delete the role. It only clears the EXTERNAL_ID column, which unlinks the role from SCIM and takes it out of the SCIM server's scope. The role itself stays available to the application.
A role whose DELETED column is Y is never related to SCIM.
Extending the schema
The schemas above are the ones the SCIM server communicates to the SCIM client by default. You can extend them with additional user properties.
Define the extra properties as a SCIM schema in USoft Definer, as described in Schemas and extension properties. The schema you store is merged with the default schema, so you only need to store the properties you are adding.
Only SCIM records are in scope
The SCIM server acts only on users and roles that are linked to SCIM, that is, on those whose EXTERNAL_ID is filled. Users and roles that are not linked to SCIM, such as administrative system users, service accounts, and database accounts, fall outside its scope:
- They are not returned by any of the endpoints.
- They cannot be manipulated over SCIM.
A POST to /Users for a user that already exists as a non-SCIM user fails.
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 endpoints
- SCIM logging - the
T_AUTH_USERandT_AUTH_ROLEcolumns these SQL statements act on, as seen in the log. - Schemas and extension properties - defining the extra properties to merge into the default schema.
- Creating users
- Understanding roles and access rights
- USoft Authorizer as a module