Synchronizing Microsoft Entra ID Roles to Appfarm Create

This guide outlines the process of synchronising user roles from Microsoft Entra ID (formerly Azure Active Directory) to Appfarm Create. By following these steps, you can ensure that user permissions are consistently managed and automatically updated within your Appfarm applications based on your organisation's established directory groups.

Prerequisites

Before you begin, ensure you have the following:

• Administrator access to your Microsoft Entra ID tenant.

• Permissions to create and manage applications within Microsoft Entra ID.

• Administrator access to your Appfarm Create environment.

• Familiarity with creating and managing roles, services, and data sources in Appfarm Create.

• Groups in Azure that only include the users who should get roles in Appfarm. We recommend that these groups be given a prefix, e.g. "Appfarm", to make them easier to query.

Step 1: Create Roles in Appfarm Create

For each Microsoft Entra ID user group you wish to mirror, you must first create a corresponding role in Appfarm Create.

1. Navigate to the Roles section in Appfarm Create.

2. Click the Create Custom Role button.

3. Enter a name for the role that corresponds to the Microsoft Entra ID group. Using the exact group name for each role will make matching the results easier later on.

4. Navigate to the Permissions section in Appfarm Create and give the newly created role the permissions it needs.

5. Repeat this process for all user groups you intend to sync.

Step 2: Create a New Service

A service in Appfarm Create will contain the logic for fetching data from Microsoft Entra ID and updating user roles.

1. Navigate to the Services section in Appfarm Create.

2. Click the New Service button.

3. Give the service a descriptive name, such as "Azure Role Sync."

4. Click Create Service.

5. A default Service endpoint will be created for you. Give this a suitable Name and Readable ID

Step 3: Add Roles as an Enum Data Source in the Service

To easily reference your Appfarm roles within the service, add them as an enumerated (enum) data source.

1. Within your newly created service, navigate to the Data tab.

2. Click the next to the + icon and select Enum.

3. From the list of available enums, select Roles. This will make your Appfarm roles available for selection in your service logic.

Step 4: Fetch Groups via Microsoft Graph API

In this step, you will configure the service to communicate with the Microsoft Graph API to retrieve user and group information from your Microsoft Entra ID.

1. In your service, create a new action. Connect the action to the Process Action on the Service endpoint you set up in step 2.

2. Add a Web Request action node.

3. Configure the Web Request to call the Microsoft Graph API. You will need to make authenticated requests. Set up an application registration in Microsoft Entra ID and use the OAuth 2.0 client credentials flow. Make sure the registered app has sufficient API permissions in Azure to read both users and groups. Read the separate guide here. Store your client ID, client secret, and tenant ID securely as Secrets.

4. Fetch groups: Use the appropriate Graph API endpoint to get all relevant Azure groups. For example: GET https://graph.microsoft.com/v1.0/groups Use appropriate query parameters to filter the response and only select the properties needed for the sync. Read more here.

5. Store Fetched Groups: Create a runtime-only data source within the service to store the group data retrieved from the Graph API. This will typically only need to store the group's display name, ID and a reference to the corresponding Appfarm Role. Important: All fetched groups must be updated with a reference to the corresponding Appfarm role, for instance by matching on display name.

Step 5: Iterate Groups, Fetch Users, and Assign Roles

Iterate through the fetched groups to fetch the group members and then assign the corresponding Appfarm role based on their Microsoft Entra ID group memberships.

Add a Foreach action node looping through all the groups fetched in step 4, and for each group, do the following:

1. Fetch Users: Fetch the members of the group by using the appropriate Graph API endpoint. For example: GET https://graph.microsoft.com/v1.0/groups/{id}/transitiveMembers This ensures that all group members are fetched, even through indirect memberships. Note that the default page size in the Graph API is 100 objects. Use query parameters and pagination to include all results. Read more here.

2. Store Fetched Users: Create a runtime-only data source within your service to store the user data retrieved from the Graph API. This will typically be an object class that mirrors the structure of the user data you need, e.g., email, name, Entra ID and a reference to the corresponding Appfarm User. Important: Use a function to update the email of all the fetched users to lowercase, as the API sometimes returns the user's email in a different format. Then, update the reference to the corresponding Appfarm User by matching on email.

3. (Optional) Create User Accounts for Fetched Users: Check if the fetched users have existing user accounts in Appfarm, and if they don't, use a Create User Account action node and databind properties from the runtime-only data source. However, we recommend implementing user synchronisation in a separate service action to keep logic tidy and to be able to run role sync and user sync on different schedules.

4. Remove Roles: Create a runtime-only data source in your service for the Appfarm User object. To this data source, read all users that have the role corresponding to the group in context, but do not exist among the users fetched in step 2. I.e., all users who have a role in Appfarm that they no longer have in Azure. Add an Update User Account action node that removes this role membership from these users.

5. Add Roles: Create a second runtime-only data source in your service for the Appfarm User object. To this data source, read all users that don't have the role corresponding to the group in context, but do exist among the users fetched in step 2. I.e., all users who are missing a role in Appfarm that they have in Azure. Add an Update User Account action node that adds this role membership to these users.

Step 6: Schedule the Service

To ensure roles are kept in sync automatically, schedule the service to run at a regular interval.

1. Navigate to the Schedules section in Appfarm Create.

2. Click the + icon.

3. Give the schedule a name, such as "Nightly Azure Role Sync."

4. Select the Service and the specific Endpoint you created for the role synchronization.

5. Create or use an existing Service Account to run the service. The service account should have a role with permission to update, delete and create users in the roles that should be synced.

6. Define the frequency using a cron expression. For example, to run the sync every night at 2 AM, you would use 0 2 * * *.

7. Enable the schedule.

By following these steps, you have successfully configured an automated process to synchronize user roles from Microsoft Entra ID to Appfarm Create, ensuring a consistent and manageable permission structure across your applications.