Add MS Defender for Cloud Apps

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 Defender for Cloud Apps”)

   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 APIs and then select “Microsoft Graph”

5. Click Application permissions, then

   1. Enter “cloudapp” into the Select permissions search box.

   2. Locate and expand the CloudApp.Discovery permission group.

   3. Then tick “CloudApp-Discovery.ReadAll”

   4. Finally click Add permission.

6. 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).

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

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

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

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

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

13. The form now displays the generated secret value (shown in the Value field). Use the copy option to make a copy of the value in the Value field.

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

15. 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 Defender for Cloud Apps) read permissions to MS Defender for Cloud Apps which will allow you to use the CI Sync User Interface to schedule synchronization jobs using that same Defender for Cloud Apps as a synchronization source.

Option 2 Instructions - reuse your existing Defender for Endpoint App Regisration to implement CI Sync for Defender for Cloud Apps

1. In the Azure Portal, navigate to Azure Active Directory -> App Registrations and search for/locate the existing one for Defender for Endpoint (it should be named something like “CI Sync Agent Connector for Defender for Endpoint“).

2. Click on the App Registration to open the Overview page.

3. Navigate to API permissions and click Add a Permission

4. Click on Microsoft APIs and then select “Microsoft Graph”

5. Click Application permissions, then

   1. Enter “cloudapp” into the Select permissions search box.

   2. Locate and expand the CloudApp.Discovery permission group.

   3. Then tick “CloudApp-Discovery.ReadAll”

   4. Finally click Add permission.

6. 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).

7. 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. Lastly, you need to know the client secret assocaited with this existing App Registration. The client secret value is used by the CI Sync Admin when they follow the instructions later in this page. If you don’t know the value of the client secret you will need to generate a new secret, capture it and store it securely so it can be shared with the CI Sync Admin so they can use it when they follow the instructions later in this page.

You have now updated the App Registration object (i.e. the CI Sync Agent Connector for Defender for Endpoint one) to also have permissions to read MS Defender for Cloud Apps data. This will allow you to use the CI Sync User Interface to schedule synchronization jobs using Defender for Cloud Apps as a synchronization source.

You can now skip to Task 2 further below.

Firstly, Context about the purpose of CI Sync RecVer Database

• The RecVer database is a small checksum database used by CI Sync to support the delta synchronization functionality (i.e. the functionality of CI Sync to only sync those records which have changed since the previous sync job). 

• Each source connection you create (using the CI Sync Agent Configuration Utility) requires its own RecVer database.  That is, each RecVer database is specific to each individual source system connection.

Second, options for the RecVer database technology and the hosting server/VM

• IF the source system technology is based on Microsoft SQL (such as SCCM, Lansweeper, etc) THEN the CI Sync RecVer database must be Microsoft SQL Server.  In this circumstance:

  • The RecVer database must be hosted on the same SQL Server as the source system database itself.

• IF the source system technology is NOT based on Microsoft SQL (such as Intune, Azure, VMware, etc) THEN the CI Sync RecVer database can be hosted on either Microsoft SQL or MongoDB. In this circumstance:

  • For a SQL based RecVer SQL database, the RecVer DB can be hosted on any SQL server you chose as long as it is “nearby” the VM running the CI Sync Agent (i.e. the Windows Service) itself. Note: “Nearby” means having low latency between the CI Sync Agent VM and the SQL Server hosting the RecVer DB).

  • For a MongoDB based RecVer database, the MongoDB database and CI Sync Agent must both be hosted on the same VM.

Third, SQL authenitcation options

If you are using a MS SQL source system (such as SCCM or Lansweeper) and therefore using MS SQL to host the RecVer database you need to decide how the CI Sync Agent will authenticate to SQL.

The CI Sync Agent (i.e. the Windows Service) requires read/write access to the RecVer database. The CI Sync Agent also requires read access to the relevant SQL based source system (e.g. SCCM, Lansweeper, etc).

When you use the CI Sync Agent Config Utility to create the source system connection (so you can ultimately run sync jobs from that source system) you have the following options for authentication between the CI Sync Agent (i.e. the Windows Service) and the RecVer DB and source system iteself:

1. Integrated Security: This option uses the Windows User Account you created for the CI Sync Agent Windows Service.

2. SQL Native Login: This option uses a native SQL username and password you enter into the CI SYnc Config Utility when you are creating the source system connection.

Note: In either case (Integrated Security or SQL Native Login), the account/login only needs least privileged access to the SQL DBs. Permissions are set either by your DBA (through a manual process) or the Config Utility (through the automated process) as explained further below. 

Finally, options for the SQL RecVer DB creation and setting of SQL permissions

If you are using a MS SQL source system (such as SCCM or Lansweeper) and therefore using MS SQL to host the RecVer database you have two options for for creating the SQL based RecVer DB and for setting pemissions to it (the RecVer DB) and to the source system itself.

Your options are as follows:

1. MS SQL Setup Option 1: In this option you use the CI Sync Config Utility to automatically create the RecVer database and grant the CI Sync Agent (i.e. the Windows Service) access to the source system SQL database.

2. MS SQL Setup Option 2: In this option you engage a SQL DBA to manually create the RecVer database and grant the CI Sync Agent (i.e. the Windows Service) access to both the RecVer DB and also to the source system SQL database. The DBA will perform these actions if you don’t have permissions to the SQL server (and therefore you aren’t able to use the CI Sync Config Utility as described in Option 1 above).

And also, have a read of Appendix A - Understand how the CI Sync Agent Authenticates to SQL Server which contains useful diagrams about SQL authentication for the CI Sync Agent.

1. Run the “CISynchronizerAgent Config Utility” from the Windows Start Menu.

2. Within the CI Sync Agent Configuration Utility, navigate to the Source Systems tab, select MS Defender for Cloud Apps and click the Add button.

3. The “Add Connection” form is shown (specific to the source system).

4. In the section titled “Settings for the CI Sync Windows Service” update the values as follows:

   1. Name: Enter a friendly name that describes this source system connection.

   2. Directory (tenant) ID: Enter the value you captured in the very first task at the top of this guide.

   3. Application (client) ID: Enter the value you captured in the very first task at the top of this guide.

   4. Authentication Method: ClientSecret.

   5. Client Secret: Enter the value you captured in the very first task at the top of this guide.

5. Move to section titled “RecVer DB Settings”

5. Update the “RecVer DB Settings” values as follows:

   1. RecVer Type: Set this to SQL Server.

6. In the sub-section titled “SQL Server RecVer Settings” update the values as follows:

   1. SQL Server: Enter the SQL Server path in the format: server\instance.

   2. Integrated Security:

      1. Check this checkbox if you want the CI Sync Agent to authenticate to the SQL Server using the Windows User Account you setup for the CI Sync Agent Windows Service (i.e. the account you setup in Task 1: Create Windows Service Account for the CI Sync Agent to use during S4 - Install the On-Prem Multi-Source Agent.

      2. Otherwise, uncheck this checkbox and enter the User ID and Password for a Native SQL Login provided to you by the DBA. (Note: Syncfish do not recommend the SQL Login have sysadmin rights).
         Note: These authentication settings control how the CI Sync Agent Windows Service authenticates with your SQL Server during ongoing operation of the agent (I.e. when sync jobs are running).

   3. Bypass setup, I have manually setup the databases: Do NOT check this checkbox (because the Config Utility will be creating the RecVer database for you).

   4. Existing RecVer Database: Do NOT check this checkbox (as the Config Utility will create the RecVer database for you).
      Note: These RecVer tick boxes (Bypass setup and Existing RecVer) control whether the CI Sync Config UI initiates the setup of the RecVer database (or not if your DBA is doing the SQL setup manually).

   5. RecVer Database: Greyed out so can be ignored.

   6. DB Timeout (Secs):  Sets the connection and statement execution timeouts. Syncfish recommend 60.

7. Locate the “Setup & Test” button

8. Do the following:

   1. Click the “Setup & Test” button.

   2. When the button “Setup & Test” is pressed, the CI Configuration utility will prompt if the user running the utility wants to use Integrated Security or SQL Server security to perform the automated SQL setup and configuration steps.

9. If all is setup correctly you will see “Ok” against each of the setup tasks.  If you see errors recheck the values you entered on the form.

10. After a successful test has been completed, click the Save button.

11. Finally, click Yes to register this new connection (via your CI Sync Agent) with your customer specific CI Sync SaaS instance.

12. Assuming no errors you will see a confirmation message. Click OK and the new connection will appear in the Connections List of the CI Sync Agent.

13. You have now completed the setup of the source connection in the CI Sync Configuration Utility and registered it as a source connection in the CI Sync SaaS application. 

1. Ask you SQL DBA to perform the tasks listed in the table below.

Once your DBA has completed the steps in the table above, use the CI Sync Agent Configuration Utility to setup the source connection and pointing to the RecVer database created by the DBA. See below for instructions on using the CI Sync Agent Configuration Utility.

2. Run the “CISynchronizerAgent Config Utility” from the Windows Start Menu.

3. Within the CI Sync Agent Configuration Utility, navigate to the Source Systems tab, select MS Defender for Cloud Apps and click the Add button.

4. The “Add Connection” form is shown (specific to the source system).

5. In the section titled “Settings for the CI Sync Windows Service” update the values as follows:

   1. Name: Enter a friendly name that describes this source system connection.

   2. Directory (tenant) ID: Enter the value you captured in the very first task at the top of this guide.

   3. Application (client) ID: Enter the value you captured in the very first task at the top of this guide.

   4. Authentication Method: ClientSecret.

   5. Client Secret: Enter the value you captured in the very first task at the top of this guide.

6. Move to section titled “RecVer DB Settings”

7. Update the “RecVer DB Settings” values as follows:

   1. RecVer Type: Set this to SQL Server.

8. In the sub-section titled “SQL Server RecVer Settings” update the values as follows:

   1. SQL Server: Enter the SQL Server path in the format: server\instance.

   2. Integrated Security:

      1. Check this checkbox if you want the CI Sync Agent to authenticate to the SQL Server using the Windows User Account you setup for the CI Sync Agent Windows Service (i.e. the account you setup in Task 1: Create Windows Service Account for the CI Sync Agent to use during S4 - Install the On-Prem Multi-Source Agent.

      2. Otherwise, uncheck this checkbox and enter the User ID and Password for a Native SQL Login provided to you by the DBA. (Note: Syncfish do not recommend the SQL Login have sysadmin rights).
         Note: These authentication settings control how the CI Sync Agent Windows Service authenticates with your SQL Server during ongoing operation of the agent (I.e. when sync jobs are running).

   3. Bypass setup, I have manually setup the databases: Check this checkbox (because your SQL DBA has already manually created the RecVer database and set the relevant permissions for you).

   4. Existing RecVer Database: Check this checkbox (because your SQL DBA has already manually created the RecVer database for you
      Note: These RecVer tick boxes (Bypass setup and Existing RecVer) control whether the CI Sync Config UI initiates the setup of the RecVer database (or not if your DBA is doing the SQL setup manually).

   5. RecVer Database: Enter the name of the RecVer database your DBA created. If your DBA used the suggested name (described on the previous page) it will be called cisee_recver_defender_cloudapps.

   6. DB Timeout (Secs):  Sets the connection and statement execution timeouts. Syncfish recommend 60.

9. Locate the “Setup & Test” button

9. Do the following:

   1. Click the “Setup & Test” button.

   2. If all is setup correctly you will see “Ok” against each of the setup tasks.  If you see errors recheck the values you entered on the form.

10. After a successful test has been completed, click the Save button.

11. Finally, click Yes to register this new connection (via your CI Sync Agent) with your customer specific CI Sync SaaS instance.

12. Assuming no errors you will see a confirmation message. Click OK and the new connection will appear in the Connections List of the CI Sync Agent.

13. You have now completed the setup of the source connection in the CI Sync Configuration Utility and registered it as a source connection in the CI Sync SaaS application. 

Some source systems support Certificate authentication for the authentication principal created in the first step of this guide. In this case, you can configure the CI Sync Agent to use Certificate based authentication rather than Client Secret.

The screen shot/s and instructions below explain how to configure the CI Sync Agent for Certificate Authentication for a given source system. Once you have completed these steps jump back to the relevant task above to finish the steps for setting up your source system connection in the CI Sync Agent Config Utility.

Part A - Import your certificate to the Windows Certificate Store on the VM running the CI Sync Agent.

1. Import the Digital Certificate into the Windows Local Machine Certificate Store.  It is recommended you do not import into the Current User Certificate Store (see Guidance Notes above).

2. Ensure the CI Sync Agent user account (i.e. the user account used by the Windows Service) has sufficient permissions to read the Digital Certificate you imported.  The following steps explain how to check/set the right permissions.

3. Open Microsoft Management Console.

4. Navigate to Certificates - Local Computer → Personal → Certificates

5. Right-click on the relevant certificate (the one you imported) and select All Tasks → Manage Private Keys

6. On the permissions window, click the Add button.

7. Search for Users, locate the CI Sync Agent User (e.g. svc-cisync-agent), press Check Names, then press the OK button.

8. Back on the permissions window, make sure Full control and Read are ticked.  Then click Apply and then Ok.

Part B - Use the CI Sync Agent Config Utility to Reference the Imported Certificate

1. Using the CI Sync Agent Configuration Utility, use the drop down list to set the Authentication Method to Certificate in the Connection Settings section of the Add Connection form.

2. Set the Certificate Location using the following instructions:

   1. The options are as follows (these are the standard values provided by Microsoft):

      1. LocalMachine

      2. CurrentUser

   2. Syncfish Recommendation:

      1. It is strongly recommended you use LocalMachine, as the current user account (the person installing/running the CI Sync Agent Config Utility) is not the same as the CI Sync Agent user account (i.e. the user account used by the Windows Service). 

      2. If you have saved the certificate in the CurrentUser context, rather than the LocalMachine context (of the Windows Certificate Store) it will cause an error when the CI Sync Agent user account (i.e. the user account used by the Windows Service) tries (and fails) to read the certificate from the Windows Certificate Store.

3. Set the Certificate Store using the following instructions:

   1. The options are as follows (these are a standard values provided by the Microsoft and correspond to the folders in the Windows certificate store):

      1. AddressBook

      2. AuthRoot

      3. CertificateAuthority

      4. My

      5. Root

      6. TrustedPeople

      7. TrustedPublisher

   2. Syncfish Recommendation: It is recommended this value be set to the “My” store (this translates to the “Personal/Certificates” path in the Windows Certificate Store).

4. Enter the Certificate Name / Thumbprint value: Enter the subject of the certificate related to the authentication principal created in the first step of this guide.

5. Finally, jump back to the relevant task above to finish the steps for setting up your source system connection in the CI Sync Agent Config Utility.