Background

Using SCIM 2.0 to automatically provision users from Azure AD

When Azure AD is used as the identity provider for the applications one of the main requirements coming across is how do we sync the users and groups in the AD to our application level DB for application processing.

Azure Active Directory is providing the facility to automatically provision the users and the groups to the application.

Tech Lead

Testimonial Author

Sammani Palansuriya

This article will give step by step guidelines on how to set up this provisioning for Users

What is SCIM

SCIM stand for “System for Cross Domain Identity Management”. It is an HTTP based protocol that makes managing identities in multi-domain scenarios easier to support through a standardized service. In the SCIM RFC it defines how to build a SCIM API to provision User and groups with all the required information. You can find the SCIM RFC at :

https://tools.ietf.org/html/draft-ietf-scim-api-19
What are the requirements specified in Azure AD for provisioning?

What are the requirements specified in Azure AD for provisioning

  • Supports creating users and/or groups, as per section 3.3 of the SCIM protocol.
  • Supports modifying users and/or groups with patch requests as per section 3.5.2 of the SCIM protocol.
  • Supports retrieving a known resource as per section 3.4.1 of the SCIM protocol.
  • Supports querying users and/or groups, as per section 3.4.2 of the SCIM protocol. By default, uers are queried by external Id and groups are queried by display name.
  • Supports querying user by ID and by manager as per section 3.4.2 of the SCIM protocol.
  • Supports querying groups by ID and by member as per section 3.4.2 of the SCIM protocol.
  • Accepts OAuth bearer tokens for authorization as per section 2.1 of the SCIM protocol

Let’s see step by step how to implement the API and then configure Azure AD to enable automatic provisioning.

Step 1: Define the User model classes as per SCIM

Azure AD supports the schema define in SCIM “Enterprise user 2.0”. You can find the full json representation of SCIM Enterprise user 2.0 at : https://tools.ietf.org/html/rfc7643#section-8.3 Use some Json to C# class tool to generate the Schema classes.

Step 2: Define Content Type

In SCIM protocol it is defined that the API should return the content with the content type as “application/scim+json”.

HTTP Method GET
URL api/scim/users
Parameter
Return Type when resource Found User List
Return Type when resource Not Found User list with 0 as Total Result
Step 5: Define Create ()

When returning the user after creating the resource make sure to set the Meta properties for it as defined in the schema. This meta class has a property called version, which is a Etag which needs to be generated from the application side. This tag is used by the azure AD to check for changes while syncing. See the sample code below.


					return new User
							{
								Id = id,
								Meta = new Meta
								{
									Created = DateTime.Now,
									LastModified = DateTime.Now,
									Location = “http://aa.azurewebsites.net/api/ scim/users/” + id,
									Version = “W/\”e180ee84f0671b1\””
								}
							};
				
HTTP Method POST
URL api/scim/users
Body User Object
Return Type User Object
Why we need SCIM?

To sync users and groups created in the Azure AD to application database we can use the facility provided by Azure AD which is called Automatic provisioning. To enable automatic provisioning, we need to have an API written as per the SCIM protocol so that the azure AD provisioning service will automatically call that API and send the updates to our application side.

If you have used as .net core API you can define the content type in the controller itself as follows.


					[Route (“/api/scim/users”)]
					[Produces (“application/scim+json”)] 
					public class UsersController : Controll
				

If it is a .net framework API you can define in the WebApiConfig in the Register method as follows.


					System.Net.Http.Headers.MediaTypeHeaderValue scimJson = new
					System.Net.Http.Headers.MediaTypeHeaderValue (“application/scim+json”); config.Formatters.JsonFormatter.SupportedMediaTypes.Add(scimJson);
				
Step 3: Define Get ()

Define an API end point to get an User by its ID. ID in this case should be defined as “External ID” when configuring Azure AD provisioning. It could be the Object Id self or email or any other unique property of Azure AD user which used as the unique ID in your Application. Follow the below specification when defining the Get Method.

HTTP Method GET
URL api/scim/user/{id}
Parameter Id
Return Type when resource Found User Object
Return Type when resource Not Found Not Found - 404
Step 4: Define GetALL ()

In SCIM get all method response should contain the following properties. Define a UserList class with following properties.


					public List schemas { get; set; } = new List { “urn:ietf:params:scim:api:messages:2.0:ListResponse” };
					[JsonProperty(“totalResults”)]
					public int TotalResults { get; set;}
					public List Resources { get; set;}
				
Step 6: Define Update ()
Update method is called by Azure AD in two scenarios.
  • When user is updated since last sync.
  • When is deleted. When deleted User object’s Active property is set to 0. So you have to check for this property on this method and create the business logic as per your application requirements.

					return new User
					{                    
					Id = id,
					Meta = new Meta
						{
							Created = DateTime.Now,
							LastModified = DateTime.Now,
							Location = “http://aa.azurewebsites.net/api/ scim/users/” + id,
							Version = “W/\”e180ee84f0671b1\””
							}
						}
				
HTTP Method Patch
URL api/scim/users/{id}
Parameter SCIM Patch Object
Return Type when resource Found User
Return Type when resource Not Found Not Found - 404
Step 7: Configure Automatic provisioning in Azure A
  • Create a non-gallery application in azure AD
  • Then Go to provisioning tab and change the Provisioning mode to “Automatic”
  • Add the Admin Credentials
  • Go to provisioning sections
  • Add your API Url as Tenant url in the Admin Credentials section
  • Add token in as Secret token in the Admin Credentials section
  • Then click Test Connection
  • If you have entered the data your connection will be successful
  • Then click save

Then you can configure the mapping for the properties. Click on the mapping section in the provision blade there you can configure the attribute mapping.

You can find more details on attribute mapping at : https://docs.microsoft.com/en-us/azure/active-directory/active-directory-saas-customizing-attribute-mappings Following above steps your Azure AD with automatically provision users to your application every 20 minutes

Get in touch