Tutorial: Develop a sample SCIM endpoint in Microsoft Entra ID

This tutorial describes how to deploy the SCIM reference code with Azure App Service. Then, test the code by using a tool like cURL or by integrating with the Microsoft Entra provisioning service. The tutorial is intended for developers who want to get started with SCIM, or anyone interested in testing a SCIM endpoint.

In this tutorial, you learn how to:

• Deploy your SCIM endpoint in Azure.
• Test your SCIM endpoint.

Deploy your SCIM endpoint in Azure

The steps here deploy the SCIM endpoint to a service by using Visual Studio 2019 and Visual Studio Code with Azure App Service. The SCIM reference code can run locally, hosted by an on-premises server, or deployed to another external service. For information about provisioning an SCIM endpoint, see Tutorial: Develop and plan provisioning for a SCIM endpoint.

Get and deploy the sample app

Go to the reference code from GitHub and select Clone or download. Select Open in Desktop, or copy the link, open Visual Studio, and select Clone or check out code to enter the copied link and make a local copy. Save the files into a folder where the total length of the path is 260 or fewer characters.

Visual Studio

1. In Visual Studio, make sure to sign in to the account that has access to your hosting resources.

2. In Solution Explorer, open Microsoft.SCIM.sln and right-click the Microsoft.SCIM.WebHostSample file. Select Publish.

   

   Note

   To run this solution locally, double-click the project and select IIS Express to launch the project as a webpage with a local host URL. For more information, see IIS Express Overview.

3. Select Create profile and make sure that App Service and Create new are selected.

   

4. Step through the dialog options and rename the app to a name of your choice. This name is used in both the app and the SCIM endpoint URL.

   

5. Select the resource group to use and select Publish.

   

Visual Studio Code

1. In Visual Studio Code, make sure to sign in to the account that has access to your hosting resources.

2. In Visual Studio Code, open the folder that contains the Microsoft.SCIM.sln file.

3. Open the Visual Studio Code integrated terminal and run the dotnet restore command. This command restores the packages listed in the project files.

4. In the terminal, change the directory using the cd Microsoft.SCIM.WebHostSample command

5. To run your app locally, in the terminal, run the .NET CLI command. The dotnet run runs the Microsoft.SCIM.WebHostSample project using the development environment.

   dotnet run --environment Development
   

6. If not installed, add Azure App Service for Visual Studio Code extension.

7. To deploy the Microsoft.SCIM.WebHostSample app to Azure App Services, create a new App Services.

8. In the Visual Studio Code terminal, run the .NET CLI command. This command generates a deployable publish folder for the app in the bin/debug/publish directory.

   dotnet publish -c Debug
   

9. In the Visual Studio Code explorer, right-click on the generated publish folder, and select Deploy to Web App.

10. A new workflow opens in the command palette at the top of the screen. Select the Subscription you would like to publish your app to.

11. Select the App Service web app you created earlier.

12. If Visual Studio Code prompts you to confirm, select Deploy. The deployment process may take a few moments. When the process completes, a notification should appear in the bottom right corner prompting you to browse to the deployed app.

Configure the App Service

Go to the application in Azure App Service > Configuration and select New application setting to add the Token__TokenIssuer setting with the value https://sts.windows.net/<tenant_id>/. Replace <tenant_id> with your Microsoft Entra tenant ID.

When you test your endpoint with an enterprise application in the Microsoft Entra admin center, you have two options. You can keep the environment in Development and provide the testing token from the /scim/token endpoint, or you can change the environment to Production and leave the token field empty.

That's it! Your SCIM endpoint is now published, and you can use the Azure App Service URL to test the SCIM endpoint.

Test your SCIM endpoint

Requests to a SCIM endpoint require authorization. The SCIM standard has multiple options available. Requests can use cookies, basic authentication, TLS client authentication, or any of the methods listed in RFC 7644.

Be sure to avoid methods that aren't secure, such as username and password, in favor of a more secure method such as OAuth. Microsoft Entra ID supports long-lived bearer tokens (for gallery and non-gallery applications) and the OAuth authorization grant (for gallery applications).

Note

The authorization methods provided in the repo are for testing only. When you integrate with Microsoft Entra ID, you can review the authorization guidance. See Plan provisioning for a SCIM endpoint.

The development environment enables features that are unsafe for production, such as reference code to control the behavior of the security token validation. The token validation code uses a self-signed security token, and the signing key is stored in the configuration file. See the Token:IssuerSigningKey parameter in the appsettings.Development.json file.

"Token": {
    "TokenAudience": "Microsoft.Security.Bearer",
    "TokenIssuer": "Microsoft.Security.Bearer",
    "IssuerSigningKey": "A1B2C3D4E5F6A1B2C3D4E5F6",
    "TokenLifetimeInMins": "120"
}

Note

When you send a GET request to the /scim/token endpoint, a token is issued using the configured key. That token can be used as a bearer token for subsequent authorization.

The default token validation code is configured to use a Microsoft Entra token and requires the issuing tenant be configured by using the Token:TokenIssuer parameter in the appsettings.json file.

"Token": {
    "TokenAudience": "8adf8e6e-67b2-4cf2-a259-e3dc5476c621",
    "TokenIssuer": "https://sts.windows.net/<tenant_id>/"
}

Next steps

• Tutorial: Validate a SCIM endpoint
• Tutorial: Develop and plan provisioning for a SCIM endpoint
• Tutorial: Configure provisioning for a gallery app