Technical Requirements

The running of the application will use minimal resources. Operating system and privileges are the only technical requirements.

Overview

Cyber Risk Aware provide support for Synchronizing a customer's Active Directory with a customer's Cyber Risk Aware portal. This is achieved through the use of Cyber Risk Aware's, ADSync tool. The first time this tool runs, it will pass all users from the Active Directory to Cyber Risk Aware's API. The information that is passed is configurable and only the minimum information needed to create the users in the portal is sent. The tool uses a cookie that is stored locally with the tool. This cookie ensures that the next time the tool is run, only the information that has changed (added, updated, deleted) will be passed to Cyber Risk Aware.

The ADSync tool is a simple executable with minimal configuration. The tool must be run manually or scheduled to run periodically. The tool will hold a log file locally that can be used for troubleshooting purposes.

Before you run the sync, If you require additional domains to be added to your portal, please contact support and we will add those for you.

Configuration

The ADSync tool will be sent in a zip file. Once extracted, open the folder to view the files. 

These are the two main files we are concerned with:

• CyberRiskAware.ADSync.exe
• CyberRiskAware.ADSync.exe.config

The file we will be looking at in this section is CyberRiskAware.ADSync.exe.config. This is the configuration file for the application. To edit this file, right click on it and select to edit with a text editor application I.E Notepad or Notepad++. 

Upon opening this file for editing, the first section of the XML markup that we will want to focus on is the 'appSettings' section.

<appSettings>
    <add key="ldap" value="LDAP://DEV.LOCALAD.COM/DC=DEV,DC=LOCALAD,DC=COM"/>
    <add key="filter" value="(objectClass=user)"/>
    <add key="orgId" value=""/>
    <add key="organisationalUnits" value=""/>
    <add key="aduri" value="https://adsynctm.cyberriskaware.com/api/PostSyncData/1/{0}?code=rIKfdLq/MtSYuaqtsHlDsih3jeW1uN7Aa38jDMzGhLiWIS6L29yOIA=="/>
    <add key="ignoreEmails" value="user1@testdomain.com,user2@testdomain.com"/>
  </appSettings>

The three properties in the above section that we would be interested in are:

ORGID

This is a unique ID assigned to your organisation. This id can be found in the Cyber Risk Aware portal on the same page you downloaded the AD Sync tool (Under User Manager -> AD Sync Download). The ID is found directly under the link to download the tool:

Place this Global Organisation ID into the Value attribute for orgId.

LDAP

This is the LDAP connection string for the application. It tells the application which LDAP to connect to. This will need updated to the LDAP path for the Organisation. This path is formatted as follows:

If we have an active directory made up of the Domain Components DC=DEV,DC=SAMPLEAD,DC=COM, then the value for LDAP should be "LDAP://DEV.SAMPLEAD.COM/DC=DEV,DC=SAMPLEAD,DC=COM"

This LDAP value needs to be the base directory. It cannot contain specific Organisation Units.

FILTER

This filter is completely for customization. It tells the application which entities within Active Directory we are interested in. The default for this is to select all objects of type 'User'.

This filter can be edited to provide a more fine-grained search. For example, if we only wanted users with a property set to a certain value, we could have a filter similar to the following:

"(&(objectCategory=person)(objectClass=user)(department=Sales))"

The above filter would select all objects in Active Directory that are of type User and the users are in the department 'Sales'.

ORGANISATIONAL UNITS

If you would like to only induce users that are part of particular Organisation Units, you can do so via the use of this field. If for instance you wished to only Synchronize users in an Organisational Unit called Customer Service, then this value can be set as follows:

<add key="organisationalUnits" value="Customer Service"/>

If you would like to include multiple Organisational Units, then this value can contain a comma separated selection of the Organisational Unit names.

IGNORE EMAILS

If you would like to only exclude users that based on a list of email addresses, you can do so via the use of this field. The value for this field should contain a comma seperated list of the email addresses of the users you wish to exclude from the sync.

<add key="ignoreEmails" value="user1@testdomain.com,user2@testdomain.com"/>

User Filtering 

The next section in the config file is CyberRiskAware.ExclusionProperty

 <CyberRiskAware.ExclusionProperty>
    <fields>
      <add name="givenName" value="john" />
    </fields>
  </CyberRiskAware.ExclusionProperty>

This section is used to provide enhanced filtering of users. Here we can specify the name of an AD attribute (Custom or Core) that we want to user as a filter criteria for excluding users from the Synchronization process. 

In the example above, the Sync processes would exclude all users that have the givenName property in AD set to "john". (Note: the value component here is not case sensitive).

Next, we look at the section CyberRiskAware.ADSync section:

<CyberRiskAware.ADSync>
    <add key="FirstName" value="givenName"/>
    <add key="SurName" value="sn"/>
    <add key="Mail" value="mail"/>
    <add key="Department" value="department"/>
    <add key="Country" value="co"/>
    <add key="Office" value="physicalDeliveryOfficeName"/>
    <add key="Phone" value="mobile"/>
  </CyberRiskAware.ADSync>

In this section, we tell the application which properties in Active Directory we are interested in. We also map them to the properties required to create a user in the Cyber Risk Aware portal. They attributes named 'key' are the field name in Cyber Risk Aware whilst the 'value' attributes are the LDAP attribute names. The LDAP attribute names are the underlying names given to the fields in your Active Directory.  The table below lists that fields in the Active Directory UI and the underlying attribute names.

Any of the attributes above can be mapped to the Cyber Risk Aware fields via the config. 

An explanation of the Cyber Risk Aware fields are listed below.

FirstName (Mandatory)

This is the staff members First Name.  by default it is mapped to the givenName LDAP property. This First Name property is a required field.

SurName (Mandatory)

This is the staff members Last Name.  by default it is mapped to the sn LDAP property. This Last Name property is a required field.

Mail (Mandatory)

This is the email address and also the Username of the staff member in the platform. By default it is mapped to the mail property. Mail is a required field. The username must contain a valid domain. If a company 'CyberRiskAware.com' is using this tool, then email addresses would expect to be post fixed with this domain (info@cyberriskaware.com). Valid domains can however be added before running the application if needed.

Department

This is the name of the Department the user will be added to in the platform. If the Department does not exist, then it is added. The default LDAP property here is department.

Country

This is the country in which the staff members work premises resides. Default LDAP attribute is co.

Office

This is the office location. Default LDAP property is physicalDeliveryOfficeName'

Phone

This is the staff members mobile phone number. It is used in Cyber Risk Aware for Smishing Campaigns. Default LDAP property is mobile.

DomainLogin

This is an optional field. It should only be used in cases where the user does not have an email and wishes to use the Domian login such as the UPN or SamAccountName instead.

Custom Fields

The AD Sync tool also has support for custom fields. Within the Cyber Risk Aware portal, we allow up to 10 custom fields. In order to populate the custom fields, they need to be mapped similar to the core properties above. 

    <add key="CustomData1" value="" />

    <add key="CustomData2" value="" />

    <add key="CustomData3" value="" />

    <add key="CustomData4" value="" />

    <add key="CustomData5" value="" />

    <add key="CustomData6" value="" />

    <add key="CustomData7" value="" />

    <add key="CustomData8" value="" />

    <add key="CustomData9" value="" />

    <add key="CustomData10" value="" />

The custom field mappings are also part of the CyberRiskAware.ADSync section and can also be mapped to the LDAP attributes above.

Running the Application

Permissions

The executable file CyberRiskAware.ADSync.exe requires read access to Active Directory. The executable therefore requires that it is run under a user with Active Directory read privileges (e.g. an admin on the Domain Controller).

Scheduling

The tool can be run manually by double clicking on the executable, but it is recommended that you set up a scheduled task to run the executable periodically. One option for this would be to use Microsoft Task Scheduler, but you are free to use another scheduling tool if you like.

A basic setup with Task Scheduler is illustrated below:

From the start menu, search for Task Scheduler

Upon opening the Task Scheduler, select Create Basic Task.

In the resulting dialog, provide a name for the scheduled task and click next.

In the next step, select how often you would like the tool to synchronize with AD. In the example below, we are using a daily trigger.

Click Next.

In the next screen, enter the time you wish the tool to run and also how often it should recur. Then click Next.

For the Action, select Start a Program and click Next.

Next, we need to select the executable to run. So, select browse and locate the CyberRiskAware.ADSync.exe file.

Then click Next.

Finally, confirm the details in the summary, and click finish.

This running of this task should now be automated.

Progress Tracking

The tool works by passing the minimal information it collects from Active Directory to the Cyber Risk Aware platform. Once the information is passed to Cyber Risk Aware, the tools job is complete, but we still need to review how the Cyber Risk Aware platform is progressing with the user synchronization. 

To view the progress, log into the Cyber Risk Aware portal and navigate to User Manager -> User Import / Sync Progress:

This page should show the progress of the Active Directory synchronization process.