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 Postman 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.

  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.

    Screenshot that shows the sample file.

    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.

    Screenshot that shows the Publish window.

  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.

    Screenshot that shows creating a new app service.

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

    Screenshot that shows publishing a new app service.

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. If you want to test the SCIM endpoint by using Postman, add an ASPNETCORE_ENVIRONMENT setting with the value Development.

Screenshot that shows the Application settings window.

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