This post has been republished via RSS; it originally appeared at: Identity Standards Blog articles.

Anyone who’s tried to manage users in more than one app will tell you that every app tries to perform the same simple actions such as creating or updating users, adding users to groups, or deprovisioning users. Yet, all these simple actions are implemented just a little bit differently, using different endpoint paths, different methods to specify user information, and a different schema to represent each element of information. In the last blog we talked about the value of SCIM and how it helps standardize user provisioning. Now let’s dig deeper into designing, building, and testing your SCIM endpoint. We’ll give general advice about how the spec works, discuss some specifics of our Azure Active Directory (Azure AD) implementation, and share resources we’ve built to expedite your SCIM development.

Protocol overview

SCIM 2.0 (aka IETF RFC 7643 and RFC 7644) defines a standardized API which a client can call to perform typical representational state transfer (REST) operations on resources such as users and groups. There is even a standardized schema so implementers know what kinds of attributes to use within requests. Lastly there is an extensibility model – if you need to expand the set of attributes or resources you want to manage, there are ways for clients to discover your extended support. Here are the critical terms you need to know:

Service Provider: A SCIM service provider is the entity that hosts the SCIM endpoint. The Service Provider is responsible for advertising configuration, securing the API and responding to requests. See Section 3.2 of RFC 7644 for all the endpoints and HTTP verbs involved.

Client: A SCIM client is the entity that makes REST calls to the SCIM endpoint. The client is responsible for acquiring and using a credential that properly authorizes the client to make REST calls to the service provider and to read the service provider’s configuration (aka SCIM discovery) prior to engaging with the service provider so that calls made to the endpoint have a high likelihood of success. Clients also must adhere to service provider rules that fall outside of the specification, such as subscription requirements or bandwidth throttling, and properly handle error conditions.

Note that identity information can flow in both directions between a client and a service provider. Clients may “push” data to the service provider by using CREATE, PUT, PATCH or DELETE, but clients can also “pull” data from a service provider using GET. In this case, our examples revolve around a “push” scenario, where Azure Active Directory (AD) is a client, and an application such as a third party SaaS app or line of business app is the service provider. Azure AD will keep the software-as-as-service (SaaS) app up-to-date, by calling the SaaS app SCIM endpoints when users or groups need to be created, deleted, or updated.

Other models are supported by the spec; For more information on the different ways SCIM entities can combine, read RFC 7642, outlining SCIM “Definitions, Overview, Outlines, and Concepts”.

Designing your SCIM endpoint

Step 1: Define your schema

Every application requires different attributes to create a user or group. Start your integration by identifying the objects (users, groups) and attributes (name, manager, job title, etc.) that your application requires. The SCIM standard defines a schema for managing users and groups. The core user schema only requires three attributes: id (service provider defined identifier), externalId (client defined identifier), and meta (read only metadata maintained by the service provider). All other attributes are optional. In addition to the core user schema, the SCIM standard defines an enterprise user extension and a model for extending the user schema to meet your application’s needs. If, for example, your application requires a user’s manager, you can use the enterprise user schema to collect the user’s manager and the core schema to collect the user’s email.

Learn more about defining your schema.

Step 2: Determine your authorization method

The SCIM standard leaves authentication and authorization relatively open. When selecting an authorization method, take into consideration security best practices and the methods that the client you would like to integrate with supports. The Azure AD SCIM client can be configured to authenticate to a service provider using either admin-set long-lived bearer tokens (for gallery and non-gallery apps) or to request OAuth access tokens via the OAuth authorization code grant (for apps in the gallery). We are looking to support the client credentials grant in the future.

Learn more about the authorization method supported.

Step 3: Determine which SCIM endpoints you would like to implement

There are several endpoints defined in the SCIM RFC. You can get started with the /User endpoint and then expand out from there. The /Schemas endpoint is helpful when using custom attributes or if your schema changes frequently. It enables a client to retrieve the most up-to-date schema automatically. The /Bulk endpoint is especially helpful when supporting groups. Learn more about the different SCIM endpoints.

Step 4: Ensure that you are following SCIM best practices

There are certain best practices for using SCIM. For a full list of best practices, check out the SCIM profile that we released last summer. It simplifies the standard and focuses on the key aspects of the standard that you need to implement. Some notable things to consider:

• Performance is paramount for large organizations. To help improve performance, especially when dealing with large tenants, ensure that PATCH operations are enabled if supporting Groups. Also, ensure that your endpoint has a rate limit above 25 requests/sec. This will allow large organizations to quickly onboard to your application.
• Mistakes happen, so anticipating these errors is a good idea. To enable easier recovery, consider supporting soft deleting or suspending user objects to allow for rolling back accidental deletes. The SCIM RFC supports setting a user object to inactive and later activating the user. This helps ensure that users who were accidentally deleted by the client can be recovered.
• Don’t require a case-sensitive match on structural elements, in particular, PATCH op operation values.
• Implement schema discovery. The SCIM standard provides flexibility to customize your schema to meet your needs. Implement the /Schemas endpoint so that you can communicate changes to your schema to the client(s) that have integrated. In addition, consider whether you are going to integrate with one client or many. Custom attributes may not be available in every client.

Building your SCIM endpoint

Looking for a head start to build your SCIM endpoint? We’ve got you covered. Check out the new reference code project on Github to help you bootstrap development of your SCIM endpoint. The reference code project is written in .net core and shows you how you can build a user, group, schemas, resourceTypes, and serviceProviderConfig endpoint. Note that this reference code is simply a sample that you can use to start your development. It will likely require customization to meet your application’s specific requirements. It is intended as an “AS IS” reference and may or may not be maintained. The reference code is open source and improvements to it are welcome by the community. Check out SCIM Reference Code. 

Testing your SCIM endpoint

Once you’ve built your SCIM endpoint, you’ll want to test it to ensure that your endpoint is compliant with the SCIM RFC. We've provided a set of Postman tests that you can run to verify CRUD operations on users / groups, filtering on users / groups, updating group memberships , and disabling / soft deleting users. Check out SCIM Tests. 

Integrating your SCIM endpoint with Azure AD

Once you’ve got your SCIM endpoint up and running, you can quickly integrate it with Azure AD.

1. Use the SCIM reference guide to understand the Azure AD SCIM implementation.
2. Integrate your SCIM endpoint with the Azure AD provisioning service using a custom application.
3. If your SCIM endpoint will be used by more than one tenant, you should publish it in the Azure AD application gallery. Our team will work with you to test the SCIM endpoint and make it available for others to use.
   
   

Your feedback.

We always love to hear your feedback and suggestions. Let us know what you think in the comments below. You can also post on StackOverflow with questions about developing your SCIM endpoint as well as Azure AD UserVoice feedback forum for new features and capabilities.