Create SCIM Microservices

Workflow Studio provides a .NET SCIM Microservice template that you can use to create your microservices using the SCIM protocol. As a developer, all you need to do is add the appropriate logic required for your implementation. Once you have added your logic, you build and deploy the microservice to the appropriate environment (such as Azure or IIS) and connect EmpowerID to that environment.

In this tutorial, you will learn how to do the following:

▪ Create a microservice project in Workflow Studio

▪ Open the project in Visual Studio

▪ Add your implementation logic to the microservice

▪ Publish and deploy the microservice

▪ Create the SCIM account store used to connect EmpowerID to the application hosting the microservice

In this article, the microservice is published to an app service in Azure. The details of setting this up are assumed on the reader's part. It is also assumed that the reader has a basic understanding of the SCIM protocol and microservices.

When developing SCIM microservices, you use Workflow Studio to create the template and then use Visual Studio to write the code for your particular microservice implementation.

Create a SCIM microservice in Workflow Studio

In Workflow Studio, right-click on the source control folder where you want to create the SCIM microservice and select New Extension or Library > Azure Services (.NET 6.0).

Workflow Studio generates a stub for the new SCIM microservice.
Click the Properties tab and select SCIM as the ServiceType.

Click the Save button on the Workflow Studio toolbar and name the microservice application as desired.

If you expand the Code Tree for the project, you can see that the template generated several classes for the project. You use these classes to define your models, controllers, and repositories for the SCIM microservice.

Class	Description
`LocationsController.cs`	Controller for location endpoint(s)
`LocationsRepository.cs`	Contains the following implementation methods for retrieving and sending location data to and from the connected system: `Create()` – Create locations in the external system `Query()` – Query and return location data from the external system `Get()` – Returns a single location from the external system `Update()` – Updates a single location in the external system `Patch()` – Adds a new location `Delete()` – Deletes a single location in the external system
`Group.cs`	Model for SCIM groups
`GroupDataExtension.cs`	Class that can be used to extend the group model with additional attributes as needed
`Location.cs`	Model for SCIM locations
`Role.cs`	Model for SCIM roles
`User.cs`	Model for SCIM users
`UserDataExtension.cs`	Class that can be used to extend the user model with additional attributes as needed
`UserLocation.cs`	Class for SCIM user locations
`UserRole.cs`	Class for SCIM user roles
`UserRoleLocation.cs`	Class for SCIM role locations
`RolesController.cs`	Controller for role endpoint(s)
`RolesRepository.cs`	Contains the following implementation methods for retrieving and sending role data to and from the connected system: `Create()` – Create roles in the external system `Query()` – Query and return role data from the external system `Get()` – Returns a single role from the external system `Update()` – Updates a single role in the external system `Patch()` – Adds a new role `Delete()` – Deletes a single role in the external system
`UserLocationsController.cs`	Controller for user location endpoint(s)
`UserLocationRepository.cs`	Contains the following implementation methods for retrieving and sending user location data to and from the connected system: `Create()` – Create user locations in the external system `Query()` – Query and return user location data from the external system `Get()` – Returns a single user location from the external system `Update()` – Updates a single user location in the external system `Patch()` – Adds a new user location `Delete()` – Deletes a single user location in the external system
`GroupsController.cs`	Controller for group endpoint(s)
`GroupsRepository.cs`	Contains the following implementation methods for retrieving and sending group data to and from the connected system: `Create()` – Create groups in the external system `Query()` – Query and return group data from the external system `Get()` – Returns a single group from the external system `Update()` – Updates a single group in the external system `Patch()` – Adds a new group `Delete()` – Deletes a single group in the external system
`UsersController.cs`	Controller for user endpoint(s)
`UsersRepository.cs`	Contains the following implementation methods for retrieving and sending user data to and from the connected system: `Create()` – Create users in the external system `Query()` – Query and return user data from the external system `Get()` – Returns a single user from the external system `Update()` – Updates a single user in the external system `Patch()` – Adds a new user `Delete()` – Deletes a single user in the external system

A health check API can be added for monitoring App Service instance health to increase application availability.

Open the project in Visual Studio.

Close the Workflow Studio microservice project and locate it in your source control tree.
From your source control tree, double-click the project.
This opens the project in Visual Studio.
Write code to implement the class stubs for your specific scenario, and when finished, build the solution.
This publishes the solution as a zip file to the microservices folder in the source control folder on your local machine (e.g., .\empowerid\WFS\microservices).

Next, deploy the microservice to the desired environment. If you are using Azure and have defined an app service for the microservice, you can do this in Workflow Studio.

Deploy the microservice to Azure

In Workflow Studio, select Cloud Explorer.
Right-click Azure App Services Deployment and select Publish App to App Service.
In the Publish to Azure App Service Credentials window, click the Browse from Publish Profile button.
Locate and select the .PublishSettings file for the app service. The .PublishSettings file is the file downloaded for the app service from Azure.

This populates the fields of the Azure App Service Credentials window with the needed deployment information.
Click OK to close the Publish to Azure App Service Credentials window.
In the Open File dialog that appears, search for and select the zip file for the microservice you just published.
Wait for Workflow Studio to deploy the microservice to the app service and click OK to close the Success message box.

Next, create a SCIM account store in EmpowerID for the system you are connecting EmpowerID and verify that the configuration parameters are correct for your system. For details on how to do so, please see SCIM Connector.

Create the SCIM account store

From the navbar of the EmpowerID Web interface, expand Admin > Applications and Directories and select Account Stores and Systems.
Select the Actions tab and then click Create Account Store.
This opens the System Types look up.
Search for SCIM Connector.
Click the SCIM Connector record to select it, and then click Submit.

This opens the SCIM connector form.
Enter the following information in the SCIM connector form:
- Name – Name of the connector
- Base URL – URL for the site hosting the SCIM microservice. For example, enter the URL for the app service if the microservice is hosted in an Azure app service.
- Client Secret – If using OAuth authentication, enter the Client Secret for the app.
- Client ID – If using OAuth authentication, enter the Client ID for the app.
- Certificate – If using certificate-based authentication, enter the thumbprint of the certificate.
When ready, click Submit.

Step 2 – Verify resource system parameters

Navigate to the Find Account Store page (Admin > Applications and Directories > Account Stores and Systems) and search for the SCIM account store you just created.
Click the Account Store link to navigate to the details page for the account store.

Click the Resource System tab and then expand the Configuration Parameters accordion.

The accordion contains the following parameters, some of which may not pertain to your specific implementation.

Name	Value	Description
AccessTokenUrl	{Your Base SCIM Url}/oauth/v2/token	Endpoint for retrieving an access token for the application after authorization
AuthorizationUrl	{Your Base SCIM Url}/oauth/v2/authorize	Authorization endpoint for accessing the application
certificateThumprint	Thumbprint of the authentication certificate, if used	Certificate thumbprint
ClientKey	OAuth Client Key	Client key of the microservice when using OAuth
ClientSecret	OAuth Client Secret (value is encrypted and not visible in the UI)	Client Secret of the microservice when using OAuth
CreateUserUrl	{Your Base SCIM Url}/users	Endpoint of the microservice to create users
EnableGroupInventory	True if inventorying group data from the SCIM application; otherwise, false	Specifies whether to inventory groups
EnableOrgZonesInventory	True if inventorying location data from the SCIM application; otherwise, false	Specifies whether to inventory locations
GetDeleteorUpdateGroupByIdURL	{Your Base SCIM Url}/groups/{0}	Endpoint of the microservice for executing group operations
GetDeleteorUpdateUserByIdURL	{Your Base SCIM Url}/users/{0}	Endpoint of the microservice for executing user operations
GetGroupMemberURL	{Your Base SCIM Url}/groups/members	Endpoint of the microservice for retrieving group membership
IsIncrementalInventory	True if running incremental inventory after the initial full inventory; false if always running full inventory	Specifies whether to run incremental inventory of the SCIM application after the initial full inventory. When running incremental inventory, the system compares the delta from the last inventory and brings those changes in.
QueryGroupsUrl	{Your Base SCIM Url}/groups	Endpoint of the microservice for querying groups
QueryUsersUrl	{Your Base SCIM Url}/url	Endpoint of the microservice for querying users
QueryZonesUrl	{Your Base SCIM Url}/locations	Endpoint of the microservice for querying locations
ServiceURl	Your Base SCIM URL	Endpoint for accessing the microservice

Edit the parameters as needed. To do so, click the Edit button for the parameter to be updated, as shown below.
Enter the appropriate value for the parameter in the Value field and click Save.
Repeat for each parameter that needs to be updated.
As a final step, the account store needs to be configured by an administrator before inventory. This includes configuring attribute flow, account store settings, and enabling the Account Inbox Permanent Workflow. For an example of what needs to be done, see Connect to SCIM applications in the Admin guide.