|
| 1 | +--- |
| 2 | +page_type: sample |
| 3 | +languages: |
| 4 | +- csharp |
| 5 | +products: |
| 6 | +- dotnet |
| 7 | +description: SCIM provisioning reference code |
| 8 | +urlFragment: "update-this-to-unique-url-stub" |
| 9 | +--- |
| 10 | + |
| 11 | +# SCIM Reference Code |
| 12 | + |
| 13 | +<!-- |
| 14 | +Guidelines on README format: https://review.docs.microsoft.com/help/onboard/admin/samples/concepts/readme-template?branch=master |
| 15 | +
|
| 16 | +Guidance on onboarding samples to docs.microsoft.com/samples: https://review.docs.microsoft.com/help/onboard/admin/samples/process/onboarding?branch=master |
| 17 | +
|
| 18 | +Taxonomies for products and languages: https://review.docs.microsoft.com/new-hope/information-architecture/metadata/taxonomies?branch=master |
| 19 | +--> |
| 20 | + |
| 21 | +Use this reference code to get started on building a [SCIM](https://docs.microsoft.com/azure/active-directory/manage-apps/use-scim-to-provision-users-and-groups) endpoint. It contains guidance on how to implement: |
| 22 | + |
| 23 | +1. Basic requirements for CRUD operations on a user and group object (also known as resources in SCIM). |
| 24 | +2. Optional features such as filtering and pagination. |
| 25 | + |
| 26 | +> [!NOTE] |
| 27 | +> 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. |
| 28 | +
|
| 29 | +## Capabilities |
| 30 | + |
| 31 | +|Endpoint|Description| |
| 32 | +|---|---| |
| 33 | +|/User|**Perform CRUD operations on a user resource:** <br/> 1. Create <br/> 2. Update <br/> 3. Delete <br/> 4. Get <br/> 5. List <br/> 6. Filter| |
| 34 | +|/Group|**Perform CRUD operations on a group resource:** <br/> 1. Create <br/> 2. Update <br/> 3. Delete <br/> 4. Get <br/> 5. List <br/> 6. Filter | |
| 35 | +|/Schemas|**Retrieve one or more supported schemas.**<br/>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).| |
| 36 | +|/ResourceTypes|**Retrieve supported resource types.**<br/>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).| |
| 37 | +|/ServiceProviderConfig|**Retrieve service provider's SCIM configuration**<br/>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).| |
| 38 | + |
| 39 | +## Prerequisites |
| 40 | + |
| 41 | +1. [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) (required) |
| 42 | +2. [.NET core 3.1 or above](https://dotnet.microsoft.com/download/dotnet-core/3.1) (required) |
| 43 | +3. [IIS](https://www.microsoft.com/download/details.aspx?id=48264) (required) |
| 44 | +4. [Postman](https://www.getpostman.com/downloads/) (optional) |
| 45 | + |
| 46 | +## Clone the repo and build your SCIM endpoint |
| 47 | + |
| 48 | +The solution is located in the ScimReferenceApi folder and can be built and run from VisualStudio locally or hosted in the cloud. |
| 49 | + |
| 50 | +#### Steps to run the solution locally |
| 51 | +1. Click **"Clone or download"** and click **"Open in Desktop"** OR copy the link. |
| 52 | + |
| 53 | +2. If you chose to copy the link, open Visual Studio and choose **"Clone or check out code**. |
| 54 | + |
| 55 | +3. Use the copied link from Github to make a local copy of all files. |
| 56 | + |
| 57 | +4. The Solution Explorer should open. Navigate to **Microsoft.SCIM.sln** view by double-clicking on it. |
| 58 | + |
| 59 | +5. Click **IIS Express** to execute. The project will launch as a web page with the local host URL. |
| 60 | + |
| 61 | +#### Steps to host the solution in the Azure |
| 62 | +1. Open Visual Studio and sign into the account that has access to your hosting resources. |
| 63 | +2. While in the **SCIMReference.sln** view, right-click the **SCIMReferenceApi** file in the Solution Explorer and select **"Publish"**. |
| 64 | + |
| 65 | +  |
| 66 | + |
| 67 | +3. Click create profile. Make sure **App Service** and **"Create new"** is selected. |
| 68 | + |
| 69 | +  |
| 70 | + |
| 71 | +4. Walk through the options in the dialog. |
| 72 | +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. |
| 73 | + |
| 74 | +  |
| 75 | + |
| 76 | +6. Select the resource group and plan you would like to use and click **"Publish"**. |
| 77 | + |
| 78 | +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**. |
| 79 | + |
| 80 | +## Authorization |
| 81 | +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](https://tools.ietf.org/html/rfc7644#section-2). 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. |
| 82 | + |
| 83 | +**Option 1**: Turn off authorization (this should only be used for testing) |
| 84 | +* Navigate to the **UsersController.cs** or **GroupController.cs** files located in **ScimReferenceApi > Controllers**.<br/>2. Comment out the authorize command. |
| 85 | + |
| 86 | +**Option 2**: Get a bearer token signed by Microsoft security bearer (should only be used for testing, not in production) |
| 87 | +* 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). |
| 88 | + |
| 89 | +**Option 3**: Bring your own token |
| 90 | +* **Option 3a**: Generate your own token that matches the specifications of the reference code. |
| 91 | + * By default the issuer, audience, and signer must be "Microsoft.Security.Bearer" |
| 92 | + * These are defaults to get started testing quickly. They should not be relied on in production. |
| 93 | +* **Option 3b**: Generate your own token and update the specifications of the reference code to match your token. |
| 94 | + * Change the specifications in the configure service section of the startup.cs class. |
| 95 | + * Specify the authorization settings you would like to validate. |
| 96 | + * Generate a token on your own that matches those specifications. |
| 97 | + |
| 98 | +## Test your SCIM endpoint |
| 99 | +Provided below are test cases that you can use to ensure that your SCIM endpoint is compliant with the SCIM RFC. |
| 100 | + |
| 101 | +#### Postman instructions |
| 102 | +1. Download the [Postman client](https://www.getpostman.com/downloads/). |
| 103 | +2. Import the Postman collection by copying the link [here](https://aka.ms/ProvisioningPostman) and pasting it into Postman as shown below: |
| 104 | + |
| 105 | +  |
| 106 | + |
| 107 | +3. Create a Postman environment for testing by specifying the following variables below: |
| 108 | + * **If running the project locally**: |
| 109 | + |
| 110 | + |Variable|Value| |
| 111 | + |---|---| |
| 112 | + |Server|localhost| |
| 113 | + |Port|*The port you are using (e.g. **:44355**)| |
| 114 | + |API|scim| |
| 115 | + |
| 116 | + * **If hosting the endpoint in Azure**: |
| 117 | + |
| 118 | + |Variable|Value| |
| 119 | + |---|---| |
| 120 | + |Server|scimreferenceapi19.azurewebsites.net| |
| 121 | + |Port|| |
| 122 | + |API|scim| |
| 123 | + |
| 124 | +4. Turn off SSL Cert verification by navigating to **File > Settings > General > SSL certificate verification**. |
| 125 | + |
| 126 | +  |
| 127 | + |
| 128 | +5. Ensure that you are authorized to make requests to the endpoint: |
| 129 | + * **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). |
| 130 | + * **Option 2**: POST to key endpoint to retrieve a token. |
| 131 | + |
| 132 | +6. Run your tests! |
| 133 | + |
| 134 | +#### Tests executed |
| 135 | + |
| 136 | +|Test|Description| |
| 137 | +|---|---| |
| 138 | +|CRUD operations on a Resource|Test that resources can be made, modified and deleted.| |
| 139 | +|Resource filtering|Test that specific resources are located and returned by filtered value (e.g. **?filters=DisplayName+eq+%22BobIsAmazing%22**).| |
| 140 | +|Attribute filtering|Test that specific attributes are located and returned (e.g. **?attributes=userName,emails**).| |
| 141 | + |
| 142 | +## Navigating the reference code |
| 143 | + |
| 144 | +This reference code was developed as a .Net core MVC web API for SCIM provisioning. The three main folders are Schemas, Controllers, and Protocol. |
| 145 | + |
| 146 | +1. The **Schemas** folder includes: |
| 147 | + * The models for the User and Group resources along with some abstract classes like Schematized for shared functionality. |
| 148 | + * An Attributes folder which contains the class definitions for complex attributes of Users and Groups such as addresses. |
| 149 | +2. The **Controllers** folder contains: |
| 150 | + * The controllers for the various SCIM endpoints. Resource controllers include HTTP verbs to perform CRUD operations on the resource (GET, POST, PUT, PATCH, DELETE). |
| 151 | + * Controllers rely on services to perform the actions. |
| 152 | +3. The **Services** folder contains logic for actions relating to the way resources are queried and updated. |
| 153 | + * The service methods are exposed via the IProviderService interface. |
| 154 | + * The reference code has services to return users and groups. |
| 155 | + * The services are based on Entity Framework and DbContext is defined by the class ScimContext. |
| 156 | +3. The **Protocol** folder contains logic for actions relating to the way resources are returned according to the SCIM RFC such as: |
| 157 | + * Returning multiple resources as a list. |
| 158 | + * Returning only specific resources based on a filter. |
| 159 | + * Turning a query into a list of linked lists of single filters. |
| 160 | + * Turning a PATCH request into an operation with attributes pertaining to the value path. |
| 161 | + * Defining the type of operation that can be used to apply changes to resource objects. |
| 162 | + |
| 163 | +## Common scenarios |
| 164 | +|Scenario|How-to| |
| 165 | +|---|---| |
| 166 | +|Enable or disable authorization|**Steps**<br/>1. Navigate to the **UsersController.cs** or **GroupController.cs** files located in **ScimReferenceApi > Controllers**.<br/>2. Comment or uncomment out the authorize command.| |
| 167 | +|Add additional filterable attributes|**Steps**<br/>1. Navigate to the **FilterUsers.cs** or **FilterGroups.cs** files located in **ScimReferenceApi > Protocol**.<br/>2. Update the method to include the attributes that you would like to support filtering for. | |
| 168 | +|Support additional user resource extensions|**Steps**<br/>1. Copy the **EnterpriseUser.cs** file located in **ScimReferenceApi > Schemas**.<br/>2. Rename the class to your custom extension name (e.g. customExtensionName.cs)<br/>3. Update the schema to match the desired naming convention.<br/>4. Repeat steps 1 - 3 with the **EnterpriseAttributes.cs** file (located in ScimReferenceApi > Schemas > Attributes) and update it with the attributes that you need.| |
| 169 | + |
| 170 | +## Contents |
| 171 | + |
| 172 | + |
| 173 | +| File/folder | Description | |
| 174 | +|-------------------|--------------------------------------------| |
| 175 | +| `ScimRefrenceAPI` | Sample source code. | |
| 176 | +| `Screenshots` | Screenshots for README. | |
| 177 | +| `.gitignore` | Define what to ignore at commit time. | |
| 178 | +| `CHANGELOG.md` | List of changes to the sample. | |
| 179 | +| `CONTRIBUTING.md` | Guidelines for contributing to the sample. | |
| 180 | +| `README.md` | This README file. | |
| 181 | +| `LICENSE` | The license for the sample. | |
| 182 | + |
| 183 | +## Contributing to the reference code |
| 184 | + |
| 185 | +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. |
| 186 | + |
| 187 | +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. |
| 188 | + |
| 189 | +This project has adopted the [Microsoft Open Source Code of Conduct ](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
0 commit comments