SCIM, or the System for Cross-Domain Identity Management, is a normalized set of HTTP-based protocols and schemas utilized to provision, manage, and deprovision users between disparate service providers.
Put another way, SCIM is designed to enable many third-party services to share profile details, enabling a more feature-rich SSO experience. The concepts of Modern Authentication enable a user to log in to a single Identity Provider (IdP) and then utilize many Services Providers (SPs). In the case of an organization such as Alchemy, users are created in a Human Resources Management System (HRMS) and, via SCIM, are provisioned into an Okta tenant. These users are then pushed, via SCIM into an Office 365 tenant, as well as many other third-party SPs. As users update their profiles in the HRMS, Okta, O365, or other SCIM supported applications, the data is synchronized via SCIM between the SP and Okta, then pushed out to the other SPs by Okta using their Life Cycle Management (LCM) solution.
Think of the typical life cycle of a user in an organization: They apply, interview, and then are hired into the organization (Joiner), they then are promoted, shift jobs or move around within the organization (Mover), and eventually retire or resign, leaving the organization (Leaver). This Joiner-Mover-Leaver model represents a series of entitlements, updates, and changes to the users’ capabilities and personal information. SCIM is the glue that allows all the service providers to remain in sync, replicating the relevant elements of the user profile automatically between service providers that can provide business value to the individual, without manual account creation, updates, or deactivation.
SCIM under the Hood
SCIM is nothing more than a specification for a set of HTTP endpoints that utilize RESTful web services with JSON payloads. These endpoints are specific (typically) to Users and Groups, exchanging data between the internal systems and external systems (Service Provider[s], [SP]). As these endpoints must be available to the larger internet, it is critical that the development of a SCIM solution consider the security of the contained APIs. The typical process of doing this is using an Identity Provider (IdP) and Modern Authentication models. Before an SCIM solution is deployed, it is critical that the security of the endpoints be configured using best practices. Failure to do so will expose the management of internal Groups and Users to the internet as a whole!
The initial conversation between the SCIM solution and the SP starts with the aptly named /ServiceProviderConfig endpoint. This is a GET request that tells the SP what functionality the SCIM server will support. This can be modified on a per-SP basis, especially if each service provider is uniquely identified using the authentication controls. This endpoint, along with the /Schemas and /ResourceTypes endpoints, allows for the self-discovery and specification of the functionality of a particular SCIM implementation. Schemas are defined as the core user schema (RFC 7643) and additional custom schemas, as defined by the implemented SCIM solution. Resource Types identify the resources that the SCIM solution will support, typically one or both of “Users” and “Groups.”
The /Users and /Groups endpoints can support multiple HTTP method types to perform various actions. The support of these methods is determined by the implementation of the SCIM solution (e.g., a SCIM solution might allow for the reading of Groups, but not their creation, update, or deletion). The GET methods are designed to read one or more resources—following the standard semantic HTTP REST format(s). SCIM supports querying, pagination, and resource filtering within its specification—all using a POST method.
The DELETE method enables the removal of a Resource and should be implemented with care. It is important to note that some SCIM implementations will favor updating the “active” value of a User Resource to “false” rather than supporting delete functionality. This again is ultimately up to the implementation of the SCIM solution.
The POST, PUT, and PATCH methods oversee the creation and updating of Users and Groups. According to the SCIM specification, the POST method is utilized for the creation of a new Resource. To update an existing resource, the PUT or PATCH methods must be used. The PUT method requires that the whole resource be provided, with all updates, whereas the PATCH method is designed to perform a partial update of a resource.
SCIM Data Models
The SCIM Data model, defined in RFC 7643, outlines the core attribute data types that can be provided when defining any resource. The SCIM specification covers the following data types:
- String—any set of characters
- Boolean—a true/false value
- Decimal—a decimal number
- Integer—a whole number
- DateTime—an ISO formatted date and time stamp
- Binary—arbitrary binary data that must be Base64 encoded (e.g., an image)
- Reference—a reference to another data set or endpoint
- Complex—another JSON object that must be composed of only simple (non-complex) attributes
Each Resource object, when returned from the SCIM server, should contain the Resource Type, Schemas (including any custom schemas), Common attributes, Core attributes, and any Extended attributes. Common attributes are common across all SCIM Resources (e.g., “id”) while Core attributes are those attributes that sit at the top level of the Resource. In the case of a User Resource, this would include the “userName” attribute. It is important to note that the common attribute of a user called “name” is a complex attribute, with many sub-values.
Extended attributes are limited only to the number of schema definitions that are provided, included, and referenced within the Resource when it is presented by the SCIM solution. While each organization can define their own schema for custom attributes, the SCIM specification includes Enterprise User representations under the schema name “urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.”
Building a SCIM Solution
When the decision has been made to build a SCIM solution, it is important to understand the core methods and data models defined within the SCIM specification. Most organizations with existing datasets will implement the SCIM solution as a software proxy for their internal systems, using it to map structured data models to their existing data models. This decouples, using a standard contract, the external and internal data structures so that modifications can be applied to internal data models with minimal or no disruption or modification to the external contracts.
To plan, build, deploy, and manage a custom SCIM solution, follow these steps:
- Determine the technology stack. This will include the software language, framework, and tools that are utilized.
- Determine the hosting method. The SCIM solution will need to be publicly available. Should this be hosted in a data center or in the cloud? What is the High Availability (HA) standard?
- Determine the SCIM internal access. Access to internal APIs, data models, or other sensitive data will be necessary. Determine how the SCIM will do this and what controls will be put in place to protect data.
- Determine the SCIM security model. Will an IdP such as Okta or Microsoft Azure Active Directory (AAD) be utilized to secure the endpoints? Will each client have its own credentials, or will shared credentials be utilized?
- Determined Supported Resources and Functions. Will the SCIM support Users? Groups? Both? What methods will be supported? Will these be supported for all clients?
- Understand SCIM data models. What data maps to the Core User and Group schemas? Is the Enterprise User schema needed? How do those attributes map to internal data models? Is a custom schema required?
- Map internal data models to SCIM data models. Build the mapping strategy.
- Determine needed audit logs or metrics. What logs will need to be recorded? How long do those need to persist? Will there need to be audit logs? How long should those be retained?
- Build the SCIM solution. Implement the endpoints, schema mapping, security, and logging/metrics.
- Test the SCIM solution. Build automated tests as development occurs, to minimize recursion and human error. Run tests every time the code changes, and automate the build to require that each and every test passes. Manually confirm functionality when development is complete.
- Deploy the SCIM solution. Automate the deployment and HA configuration of the SCIM solution. If possible, ensure auto-scaling is available to handle high-load events.
- Monitor the SCIM solution. Monitor, control, maintain, and check the logs and metrics. Ensure the solution is performing as expected and the deployment can handle the load.
SCIM is a powerful tool that can provide incredible automation capabilities to any organization; however, development of a SCIM solution that is not well planned, tested, and/or secured can be incredibly harmful and dangerous to the integrity of an organization. Remember that a day of planning up front can save weeks or months of trouble, debugging, reworking, or modification down the road.
Considering building a SCIM solution but worried about getting it right? Take the fear and worry out of the process, and talk to an Alchemist today. We are more than happy to help you understand, plan, build, deploy, and manage a fully functional SCIM solution for your organization.
