SSOReady concepts: SCIM Directories
Understanding SCIM Directories in SSOReady
SCIM directories are how you implement SCIM using SSOReady. Every SCIM directory contains:
- The settings your customer needs to set up a SCIM directory sync from their identity provider into your product, and
- A repository of users and groups. Your customer’s identity provider securely populates the users and groups using the SCIM protocol. Your application uses SSOReady’s SDKs or HTTP API to fetch those users and groups, and provision them inside your product.
Every SCIM directory belongs to exactly one organization. Organizations in turn belong to exactly one environment. You can have any number of SCIM directories within an organization. Up to one SCIM directory per organization can be primary.
The SCIM protocol is designed such that your customer needs to put a SCIM directory’s base URL and bearer token into their identity provider before syncing can begin. When you use SSOReady’s self-service SCIM configuration, your customer can securely do this on their own, without any work on your part.
Properties
SCIM Directory ID
Every SCIM directory has an ID starting with scim_directory_..., for example:
SCIM directory IDs are universally unique.
Primary
Up to one SCIM directory within an organization can be marked as “primary”.
A primary SCIM directory works exactly like any other SCIM directory,
but with one special behavior for your convenience: when you list SCIM
users or
groups, you can provide an
organizationExternalId
or
organizationId.
When you do so, the primary SCIM directory of that organization is SCIM
directory users or groups are listed from.
If none of the SCIM directories in an organization are marked as primary,
listing SCIM users or groups using organizationExternalId or organizationId
for that organization will return an error when from SSOReady’s API.
The solution is to mark one of the SCIM directories as primary, or to pass a
scimDirectoryId
instead.
SCIM Base URL
Every SCIM HTTP server has a base URL, from which the identity provider can determine the SCIM HTTP requests it wants to send when provisioning or deprovisioning users and groups.
SSOReady assigns each SCIM directory a base URL, which needs to be inputted into the customer’s identity provider. SCIM base URLs look something like this:
If you use a custom domain for auth.ssoready.com, then the base URL will
instead look like:
Where auth.yourcompany.com is your custom auth.ssoready.com domain.
SCIM Authentication
When identity providers send requests to the SCIM server runs on your behalf,
they need to include an Authorization HTTP header with a Bearer token to
authenticate their requests.
SSOReady assigns the bearer token for a SCIM server for you They start with
ssoready_scim_bearer_token_.... For example:
The SCIM directory bearer token needs to be inputted by your customer into their identity provider. If you use SSOReady’s self-service SCIM configuration, your customer can configure SAML without any work on your part.
For security, SSOReady only stores a hash of the bearer token. The only way to access a SCIM directory’s bearer token is to generate a new one by rotating the bearer token.
Rotating bearer tokens
If your customer ever loses their SCIM directory bearer token, or accidentally leaks it, you can deactivate the old bearer token and generate a new one by rotating the SCIM directory’s bearer token.
Rotating a SCIM directory’s bearer token will break any outstanding SCIM connections with that directory. Existing connections will fail to authenticate until they are updated with the new bearer token. This won’t cause data loss. It will, however, mean that new users won’t be provisioned or deprovisioned in your application until the customer’s identity provider settings are updated.
Users
SCIM directories contain a list of SCIM users that belong to the directory.
The list of users here is meant to see that the SCIM sync is working, and as a debugging aid. From your application, you can programmatically list the SCIM users in a SCIM directory using the List SCIM Users API endpoint.
Groups
SCIM directories contain a list of SCIM groups that belong to the directory.
The list of groups here is meant to see that the SCIM sync is working, and as a debugging aid. From your application, you can programmatically list the SCIM groups in a SCIM directory using the List SCIM Groups API endpoint.
SCIM Request Logs
SCIM directories contain a list of SCIM request logs that belong to the directory.
The list of SCIM request logs here is meant to show you the SCIM HTTP requests that SSOReady is handling on your behalf. If your customer has misconfigured their SCIM settings in their identity provider, you can see their failing SCIM HTTP requests here.