Add Microsoft 365 to SaaS Agent

Task List

Task 1: Prepare Microsoft 365 for use with CI Sync

1. In the Azure Portal, navigate to Azure Active Directory -> App Registrations and click New Registration

2. On the Register an application form complete as follows:

   1. Enter the Name (Note: Syncfish recommend using “CI Sync Agent Connector for Microsoft 365”)

   2. Under Supported account types select “Accounts in this organizational directory only ({Your Domain/Tenant Name} only - Single tenant)”

   3. Click Register

3. Navigate to API permissions and click Add Permission

4. Click on Microsoft Graph

5. Click on Application permissions

6. Use the Select permissions list to scroll down and select each of the following depending on which record types you will be synchronizing (see “Additional Information about required API Permissions” below):

   1. First, find and expand the Calendars set, then tick/select
      Calendars.Read.All

   2. Next, find and expand the Group set, then tick/select
      Group.Read.All

   3. Next, find and expand the GroupMember set, then tick/select
      GroupMember.Read.All

   4. Next, find and expand the Sites set, then tick/select
      Sites.Read.All

   5. Next, find and expand the User set, then tick/select
      User.Read.All

   6. Next, find and expand the Mailboxes set, then tick/select
      MailboxSettings.Read.All

   7. Next, find and expand the Calendars set, then tick/select
      Calendars.Read.All

   8. Finally, click the Add permission button

The following record sets are available for selection when creating a synchronization job with Microsoft 365 as the source system and ServiceNow as the destination system. CI Sync requires access permissions to the related Microsoft 365 objects (via the Microsoft Graph API).

When selecting the API permissions you only need to select those resources/record sets you intend to synchronize via CI Sync. The table below shows which API permissions relate to each recordset.

#1 User.Read and User.Read.All only required for sync Members and/or Owners of M365 Groups or Distribution Lists.

Here are the Azure Portal UI instructions for selecting the various API permisssions.

7. You should now be back on the API Permissions form showing the list of permissions you selected (see screen shot below to validate you have selected the required permissions).

   1. Now, Click Grant admin consent for {Your Domain Name}

8. Click Yes to confirm granting Admin Consent.  The resulting screen should look as shown below.

9. Using the left-hand menu, navigate and select Certificates & secrets.  Select “Client secrets (0)” in the middle of the form and then click the “New client secret” button.

10. Enter a unique Description for the secret associated with this CI Sync Agent Connector for M365 App Registration (e.g. “CI Sync Agent Connector for M365 Client Secret”).

11. Then, select a suitable Expires duration based on your organisational policy.  Finally click the Add button.

12. The form now displays the generated secret value (shown in the Value field)

    1. Use the copy option to make a copy of the value in the Value field.

13. Return to the Overview page for the App Registration.

    1. Use the copy option to make a copy of the “Application (client) ID” GUID value and the “Directory (tenant) ID” GUID value.

You have now granted the App Registration object (i.e. the CI Sync Agent Connector for M365) read permissions to Microsoft 365 which will allow you to use the CI Sync User Interface to schedule synchronization jobs using that same Microsoft 365 as a synchronization source.

Task 2: Add Microsoft 365 as a Source System using the CI Sync SaaS UI

1. Login to your CI Sync SaaS instance at https://YourCo.syncfish.app

2. In the CI Sync UI, navigate to Settings > Connections.

3. Find the “SaaS Agent” sub-heading under the Source Connections section. If you don’t see “SaaS Agent” it means your CI Sync instance hasn’t been configured for this feature. Please contact your Sync representative to discuss.

4. On the right hand side of the form, click the +Add button.

5. The New Connection form now appears. Use the Connection Type drop down list to select the source system you wish to add (in this case Microsoft 365).

6. Update the fields using these instructions

   1. Connection name

      1. This is a friendly name that represents the source system connection.

      2. The name you enter here will appear when you create a new sync job and are selecting from the available source system list.

      3. Note: Syncfish recommend using a textual suffix on the connection name if for any reason you have setup multiple CI Sync Connections to Microsoft 365.

   2. Alias: Please ingore this field (it is not used for the CI Sync Cloud Agent and is being deprecated).

   3. Environments

      1. Select from the available choices Production, Test, or Production/Test (the latter being both).

      2. The selection you make for this field affects which source systems appear when you create a new sync job (i.e. when you are selecting the source system list based on the “Environment” you have chosen for the sync job). See this page for more details on creating a CI Sync job: Run a Small Initial Sync Job (then run more).

      3. FYI: CI Sync allows a source system to be both Production/Test because CI Sync only reads from a source system (it doesn’t write to it). Destination systems can only be Test or Production (not both).

   4. Directory (tenant) ID

      1. Paste the Azure/Entra Directory (tenant) ID captured by your Azure Admin in Task 1 above.

   5. Application (client) ID

      1. Paste the App Registration Application (client) ID captured by your Azure Admin in Task 1 above.

   6. Client Secret Value

      1. Paste the Client Secret Secret Value captured by your Azure Admin in Task 1 above.

   7. The click the Consent to update fields checkbox.

   8. Finally click the Create connection button.

You will be returned to the main settings screen and your new source system connection will appear in the list as shown below.

Task 3: Check status of new Microsoft 365 Source System connection

1. To check the status of the newly added Microsoft 365 Source System connection click the green Check Status link. This will test whether your CI Sync Microsoft 365 connection can successfully reach and authenticate to the Azure Entra ID defined in the connection itself.

2. 

   If the connection is successful, you will see a green dot next to the source connection name.

3. 

   To test again in the future, you can click the green Refresh Status button.

4. If the test is unsuccessful, you will see a red dot next to the source connection name and an error message underneath. If you need assistance resolving an error, please contact Syncfish support.

This means you are ready to run a sync job using the new source connection using these high-level instructions: Run a Small Initial Sync Job (then run more).

Task 4: Perform Updates in ServiceNow (if required)

In this section your ServiceNow SME will assess various updates to ServiceNow to support this CI Sync connector:

• Task 4a: Assess if the CMDB CI Class Models plug-in is required

• Task 4b: Assess if additional permissions are required

• Task 4c: (Optional though recommended) Assess your ServiceNow CI forms and update to include additional Related Lists

Task 4a: Assess if the CMDB CI Class Models plug-in is required

Task 4b: Assess if additional permissions are required

Context

Depending on the options you choose when creating a sync job from Microsoft 365, CI Sync will create CI-to-CI relationships between objects such as Microsoft 365 Groups, the Group Members of those Groups, and the Group Owners of those Groups. Similar relationships are created for Distribution Lists and the members of those DLs.

CI Sync needs to define several allowed user relationship types (as distinct from the actual relationships themselves) within ServiceNow to support the CI-to-CI relationship examples noted above. The allowed user relationship types are stored in the cmdb_rel_user_type table.

The standard/out-of-the-box roles provided by ServiceNow (and recommended by Syncfish during S3 - Configure ServiceNow for CI Sync) do not provide access to the cmdb_rel_user_type table. Therefore, the CI Sync Integration User account created during S3 - Configure ServiceNow for CI Sync requires additional permissions to write to the cmdb_rel_user_type table.

Syncfish provides a ServiceNow updateset to prepare your ServiceNow instance for CI Sync. The updateset does the following:

• Creates a read/write/create ACL on the cmdb_rel_user_type table.

• Applies the ACL on the cmdb_rel_user_type table and assigns the ACL to the ServiceNow role called “Asset” (which is one of the roles granted to the CI Sync Integration Account created during S3 - Configure ServiceNow for CI Sync).

Instructions

Follow these steps to apply the updateset provided by Syncfish:

1. Download the update set from Syncfish at the below URL:
   https://downloads.syncfish.app/servicenow/cisync-ms365-connector-permissions.xml

2. Login to your ServiceNow instance with Admin permissions.

3. Open a browser and navigate to your ServiceNow instance

4. In the left nav menu search for “Retrieved Update Sets” and click to open

5. Right click on the column heading row and select “Import XML”

6. Select “Choose File”

7. Select the downloaded file “cisync-cmdb-key-value.xml”

8. Click to open the Update Set

9. Click “Preview Update Set”

10. If there are no preview errors, Click “Close”.

11. Click “Commit Update Set”.

12. Your ServiceNow instance is now ready to receive Tag data from Azure via sync jobs from CI Sync.

Task 4c: (Optional though recommended) Assess your ServiceNow CI forms and update to include additional Related Lists