Overview
The System for Cross-domain Identity Management (SCIM) is a standardized API for provisioning and managing user and group objects across different platforms. Whereas each platforms RESTful API may have its own unique endpoints and attributes, SCIM defines a common set of endpoints and attributes to be used for certain object types; this allows SCIM-compliant systems to leverage each other's APIs without mapping custom attributes. Additional information is available at simplecloud.info.
itopia CAS introduced a new, SCIM 2.0-compliant API endpoint in Q2 2021 to coexist alongside our robust RESTful API. itopia will continue to support and develop our standard RESTful API; you can learn more about our REST API in Getting Started with the CAS REST API.
SCIM API Endpoint
Because of the standardized framework of the SCIM standard, CAS generates a unique SCIM API endpoint for each CAS deployment. The endpoint resembles the following: https://cas-scim.itopia.com/api/v1/deployments/XXXX, where XXXX is the deployment's unique ID. You can find the exact endpoint URI for each of your deployments in the CAS Admin Console:
Log in to the CAS Admin Console (cas.itopia.com) as a user with Deployment Owner or Organization Owner rights.
Click on your user name in the top-right corner to open the Admin menu, and select Manage Organization.
Select the API Keys tab.
In the API Access Information section, expand the CAS SCIM API container and locate the appropriate endpoint URI for your desired deployment.
Authentication
The CAS SCIM API relies on a secret key bearer token. Administrators can generate one or more tokens in the CAS Admin Console; these tokens never expire and can be used for standard bearer authorization when accessing the CAS SCIM API endpoint.
To generate a new API key:
Log in to the CAS Admin Console (cas.itopia.com) as a user with Deployment Owner or Organization Owner rights.
Click on your user name in the top-right corner to open the Admin menu, and select Manage Organization.
Select the API Keys tab.
Click the Create button.
In the New API key window, specify the following:
Description - Provide a short, descriptive name for the key you are generating. itopia recommends generating a unique key for each system that will access the API; this makes it easier to audit usage and revoke access to a key without affecting multiple systems
Key Type - Select Secret Token. The CAS SCIM API does not support the use of JSON Web Token (JWT) tokens. Conversely, the CAS REST API does not support the use of secret tokens
Assign Admin Role - The SCIM API supports only a single administrative role that grants full access to the API. This field cannot be edited.
Grant access to specific deployments - Each API key can only be used to access a single deployment. Select the CAS deployment to which the key should be assigned.
Click Create.
The secret token will be displayed on screen. Copy the key and store it in a secure location. Once you close this screen, you will be unable to view the key again.
The bearer token must be included in every request to the CAS SCIM API; no API endpoints accept non-authenticated requests.
Using the API
The CAS SCIM API supports standard Create, Read, Update, Delete (CRUD) actions for CAS User and Security Group objects. The initial release of the CAS SCIM API is a subset of the full SCIM 2.0 standard as defined in the following RFCs:
Using the root URI for each deployment, the SCIM API supports the following endpoints for various actions; additional endpoints and actions (such as bulk editing) may be added in a future release:
Endpoint | Verb | Action | Details |
/Users | POST | Create user | |
/Users | GET | Query all users | |
/Users?filter | GET | Query users based on filter criteria | |
/Users/{Id} | GET | Details about specific user | |
/Users/{Id} | PATCH | Update settings on user | |
/Users/{Id} | DELETE | Delete user | |
/Groups | POST | Create group | |
/Groups/{Id} | GET | Get group details and members | |
/Groups?filter | GET | Query groups based on filter criteria | |
/Groups/{Id} | PATCH | Update group details or membership |
Assigning Users to Collection Pools
The official SCIM API does not offer an adequate method of assigning users to Collection Pools; therefore, the CAS SCIM API relies on group membership to manage this assignment. When user objects are created in CAS via the SCIM API, they are assigned to the default Collection Pool.
NOTE: You can specify the default Collection Pool for a deployment in the CAS Admin Console. |
Group objects can also be created or updated in CAS via the SCIM API. If the name of a group matches the exact name of a CAS Collection Pool, the members of that group are also synchronized to the corresponding Collection Pool. For example, to assign users to the "Accounting v2" Collection Pool, you would:
Provision the users in CAS using the CAS SCIM API. The users will be created in CAS, assigned random passwords, and assigned to the default Collection Pool.
Create a group in your source directory named "Accounting v2" and add the users as members of this group.
Use the CAS SCIM API to sync the group and its membership to CAS.
When the group is synced to CAS via the SCIM API, the following rules are observed:
A CAS security group (and corresponding Active Directory security group) are created, if they do not already exist
The membership of the source group is synchronized to the CAS security group
Members of the source group are assigned to the corresponding Collection Pool based on a matching name
If users that had previously been a member of the group are removed, the sync will remove them from the corresponding Collection Pool assignment. This behavior does not affect users that are assigned to the Collection Pool through other methods (such as the REST API or the CAS Admin Console); only users that were previously assigned to the Collection Pool via the CAS SCIM API will be removed from the Collection Pool if they are removed from the corresponding group
When users are assigned to Collection Pools via the CAS SCIM API, they are only removed from the default Collection Pool if the source directory also contains a group whose name matches the exact name of a CAS Collection Pool. If this corresponding group name is not synced via the CAS SCIM API, users will be assigned to additional Collection Pools based on their group membership but they will not be unassigned from the default Collection Pool.
Limitations and Considerations
The official SCIM API does not provide a mechanism for securely managing passwords on user objects. Although several proposed extensions have been provided to supporting setting and resetting passwords, the CAS SCIM API does not implement these methods. Thus, when users are created through the SCIM API, CAS will generate a random password for the user and, if the user was created with an email address attribute, the user will receive the password in an email. Support for password management may be added in a future release of the CAS SCIM API.
Bulk actions (using the /bulk endpoint as proposed in the IETF standard) are not currently supported by the CAS SCIM API. This support may be added in a future release of the CAS SCIM API.