Skip to content

AzureAD/SCIMReferenceCode

Repository files navigation

page_type languages products description urlFragment
sample
csharp
dotnetcore
SCIM provisioning reference code
update-this-to-unique-url-stub

SCIM Reference Code

The reference code provided in this repository will help you get started building a SCIM endpoint. It contains guidance on how to implement basic requirements for CRUD operations on a user and group object (also known as resources in SCIM) and optional features of the standard such as filtering and pagination. Use the repository Wiki for guidance on how to use this reference.

[NOTE] This code is intended to help you get started building your SCIM endpoint and is provided "AS IS." It is intended as a reference and there is no guarantee of it being actively maintained or supported. Contributions from the community are welcome to help build and maintain the repo.

Capabilities

Endpoint Description
/Users Perform CRUD operations on a user resource:
1. Create
2. Update
3. Delete
4. Get
5. List
6. Filter
/Groups Perform CRUD operations on a group resource:
1. Create
2. Update
3. Delete
4. Get
5. List
6. Filter
/Schemas Retrieve one or more supported schemas.
The set of attributes of a resource supported by each service provider can vary. (e.g. Service Provider A supports “name”, “title”, and “emails” while Service Provider B supports “name”, “title”, and “phoneNumbers” for users).
/ResourceTypes Retrieve supported resource types.
The number and types of resources supported by each service provider can vary. (e.g. Service Provider A supports users while Service Provider B supports users and groups).
/ServiceProviderConfig Retrieve service provider's SCIM configuration
The SCIM features supported by each service provider can vary. (e.g. Service Provider A supports Patch operations while Service Provider B supports Patch Operations and Schema Discovery).

Getting Started

The Microsoft.SystemForCrossDomainIdentityManagement project contains the code base for building a SCIM API. The Microsoft.SCIM.WebHostSample project is there as a sample for using the project. A step by step guide for starting up with the project can be found here.

Navigating the reference code

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 Service folder contains logic for actions relating to the way resources are queried and updated.
    • The reference code has services to return users and groups.
    • The controllers folder contains 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 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.

Contents

File/folder Description
Microsoft.SystemForCrossDomainIdentityManagement Sample source code.
Microsoft.SCIM.WebHostSample Sample implementation of the SCIM library.
.gitignore Define what to ignore at commit time.
CHANGELOG.md List of changes to the sample.
CONTRIBUTING.md Guidelines for contributing to the sample.
README.md This README file.
LICENSE The license for the sample.

Authorization

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). Review the wiki for more details about the current authorization support that this reference code provides.

[NOTE] These authorization methods provided by this repo are solely for testing. When integrating with Azure AD, review the authorization guidance provided here.

Contributing to the reference code

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 opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.