Technical Requirements


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


OS    Windows Server 2008 and higher
Run As Privileges    The application must be able to be read Active Directory, and the Run As user will need Read access to AD.


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://adsyncapi.azurewebsites.net/api/PostSyncData/1/{0}?code=trIKfdLq/MtassHlDsihDwaMzGeahLiWISre6L29yOIA2AS=="/>
<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:


"(&amp;(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.


Label in ADLDAP Attribute
First NamegivenName
Middle Name / Initialsinitials
Last Namesn
Logon NameuserPrincipalName
Logon Name (Pre Windows 2000)sAMAccountName
Display NamedisplayName
Full Namename/cn
Descriptiondescription
OfficephysicalDeliveryOfficeName
Telephone NumbertelephoneNumber
Emailmail
Web PagewWWHomePage
Passwordpassword
StreetstreetAddress
PO BoxpostOfficeBox
Cityl
State/Provincest
Zip/Postal CodepostalCode
Countryco
Country 2 Digit Code - eg. USc
Country code -eg. for US country code is 840countryCode
GroupmemberOf
Account Expires (use same date format as server)accountExpires
User Account ControluserAccountControl
User PhotothumbnailPhoto / exchangePhoto (Supports high resolution photo) / jpegPhoto / photo / thumbnailLogo
Profile PathprofilePath
Login ScriptscriptPath
Home FolderhomeDirectory
Home DrivehomeDrive
Log on touserWorkstations
HomehomePhone
Pagerpager
Mobilemobile
FaxfacsimileTelephoneNumber
IP PhoneipPhone
Notesinfo
Titletitle
Departmentdepartment
Companycompany
Managermanager
Mail AliasmailNickName
Simple Display NamedisplayNamePrintable
Hide from Exchange address listsmsExchHideFromAddressLists
Sending Message Size (KB)submissionContLength
Receiving Message Size (KB)delivContLength
Accept messages from Authenticated Users onlymsExchRequireAuthToSendTo
Reject Messages FromunauthOrig
Accept Messages FromauthOrig
Send on BehalfpublicDelegates
Forward ToaltRecipient
Deliver and RedirectdeliverAndRedirect
Use mailbox store defaultsmDBuseDefaults
Outlook Mobile AccessmsExchOmaAdminWirelessEnable
Outlook Web AccessprotocolSettings
Allow Terminal Server LogontsAllowLogon
Terminal Services Profile PathtsProfilePath
Terminal Services Home DirectorytsHomeDir
Terminal Services Home DrivetsHomeDirDrive
Start the following program at logontsInheritInitialProgram
Starting Program file nametsIntialProgram
Start intsWorkingDir
Connect client drive at logontsDeviceClientDrives
Connect client printer at logontsDeviceClientPrinters
Default to main client printertsDeviceClientDefaultPrinter
End disconnected sessiontsTimeOutSettingsDisConnections
Active Session limittsTimeOutSettingsConnections
Idle session limittsTimeOutSettingsIdle
When session limit reached or connection brokentsBrokenTimeOutSettings
Allow reconnectiontsReConnectSettings
Remote ControltsShadowSettings
Protect accidental deletionpreventDeletion
Manager can update membersmanagerCanUpdateMembers
Primary Group IDprimaryGroupID
Administrative GroupmsExchAdminGroup
Exchange Server NamemsExchHomeServerName
Managed BymanagedBy
Target AddresstargetAddress



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.