Use this reference code to get started on building a SCIM endpoint. It contains guidance on how to implement:

1. Basic requirements for CRUD operations on a user and group object (also known as resources in SCIM).
2. Optional features such as filtering and pagination.

1. Visual Studio 2019 (required)
2. .NET core 3.1 or above (required)
3. IIS (required)
4. Postman (optional)

The solution is located in the ScimReferenceApi folder and can be built and run from VisualStudio locally or hosted in the cloud.

1. Click "Clone or download" and click "Open in Desktop" OR copy the link.

2. If you chose to copy the link, open Visual Studio and choose "Clone or check out code.

3. Use the copied link from Github to make a local copy of all files.

4. The Solution Explorer should open. Navigate to Microsoft.SCIM.sln view by double-clicking on it.

5. Click IIS Express to execute. The project will launch as a web page with the local host URL.

1. Open Visual Studio and sign into the account that has access to your hosting resources.

2. While in the SCIMReference.sln view, right-click the SCIMReferenceApi file in the Solution Explorer and select "Publish".

   

3. Click create profile. Make sure App Service and "Create new" is selected.

   

4. Walk through the options in the dialog.

5. Rename the app to a desired name of your choice. The name is used for both the app name and the SCIM Endpoint URL.

   

6. Select the resource group and plan you would like to use and click "Publish".

All the endpoints are are at the {host}/scim/ directory and can be interacted with standard HTTP requests. The /scim/ route can be modified in the ControllerConstant.cs file located in AzureADProvisioningSCIMreference > ScimReferenceApi > Controllers.

The SCIM standard leaves authentication and authorization relatively open. You could use cookies, basic authentication, TLS client authentication, or any of the other methods listed here. You should take into consideration security and industry best practices when choosing an authentication/authorization method. Avoid insecure methods such as username and password in favor of more secure methods such as OAuth. Azure AD supports long-lived bearer tokens (for gallery and non-gallery applications) as well as the OAuth authorization grant (for applications published in the app gallery). This reference code allows you to either turn authorization off to simplify testing, generate a bearer token, or bring your own bearer token.

Option 1: Turn off authorization (this should only be used for testing)

• Navigate to the UsersController.cs or GroupController.cs files located in ScimReferenceApi > Controllers.
  2. Comment out the authorize command.

Option 2: Get a bearer token signed by Microsoft security bearer (should only be used for testing, not in production)

• Post to to the key endpoint with the string "SecureLogin" to retrieve a token. The token is valid for 120 minutes (the validity can be changed in the key controller).

Option 3: Bring your own token

• Option 3a: Generate your own token that matches the specifications of the reference code.
  • By default the issuer, audience, and signer must be "Microsoft.Security.Bearer"
  • These are defaults to get started testing quickly. They should not be relied on in production.
• Option 3b: Generate your own token and update the specifications of the reference code to match your token.
  • Change the specifications in the configure service section of the startup.cs class.
  • Specify the authorization settings you would like to validate.
  • Generate a token on your own that matches those specifications.

Provided below are test cases that you can use to ensure that your SCIM endpoint is compliant with the SCIM RFC.

1. Download the Postman client.

2. Import the Postman collection by copying the link here and pasting it into Postman as shown below:

   

3. Create a Postman environment for testing by specifying the following variables below:

   • If running the project locally:

     Variable	Value
     Server	localhost
     Port	*The port you are using (e.g. :44355)
     API	scim

   • If hosting the endpoint in Azure:

     Variable	Value
     Server	scimreferenceapi19.azurewebsites.net
     Port
     API	scim

4. Turn off SSL Cert verification by navigating to File > Settings > General > SSL certificate verification.

   

5. Ensure that you are authorized to make requests to the endpoint:

   • Option 1: Turn off authorization for your endpoint (this is fine for testing purposes, but there must be some form of authorization for apps being used by customers in production).
   • Option 2: POST to key endpoint to retrieve a token.

6. Run your tests!

This reference code was developed as a .Net core MVC web API for SCIM provisioning. The three main folders are Schemas, Controllers, and Protocol.

1. The Schemas folder includes:
   • The models for the User and Group resources along with some abstract classes like Schematized for shared functionality.
   • An Attributes folder which contains the class definitions for complex attributes of Users and Groups such as addresses.
2. The Controllers folder contains:
   • The controllers for the various SCIM endpoints. Resource controllers include HTTP verbs to perform CRUD operations on the resource (GET, POST, PUT, PATCH, DELETE).
   • Controllers rely on services to perform the actions.
3. The Services folder contains logic for actions relating to the way resources are queried and updated.
   • The service methods are exposed via the IProviderService interface.
   • The reference code has services to return users and groups.
   • The services are based on Entity Framework and DbContext is defined by the class ScimContext.
4. The Protocol folder contains logic for actions relating to the way resources are returned according to the SCIM RFC such as:
   • Returning multiple resources as a list.
   • Returning only specific resources based on a filter.
   • Turning a query into a list of linked lists of single filters.
   • Turning a PATCH request into an operation with attributes pertaining to the value path.
   • Defining the type of operation that can be used to apply changes to resource objects.

This project welcomes contributions and suggestions! Like other open source contributions, you will need to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When submitting a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g. status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.