Setting up your AD Sync

In this article we show you how to set up your AD Sync. You must be the Account Owner or an employee with an IT Support user role in order to perform the initial steps.

Download your AD Script

1. Login to your WhosOnLocation Account

2. Go to Tools > Account > Employee Management

 You will see this screen below:

1.PNG                    

3. Select the ‘Yes’ option alongside Active Directory Sync (AD). The Active Directory Sync Enabled acknowledgment will show. Select Close.

 2_AD.PNG

4. Click Download Script which will have appeared in the API key row.

2.PNG

Please Note: The API key illustrated on this screen is unique to your organization. You do not need to copy it as we pre-populate that into your script when you download it. However, we illustrate it for your reference.

5. Set the New employee policy. When a new employee is added to your WhosOnLocation account via Active Directory Sync visitors will be able to select them as their Host immediately. However, in order for the employee to gain access to their WhosOnLocation account for the purposes of pre-registering visitors, tagging themselves on or off-site, or access any of the User Roles, they must first be sent an activation email. There are two options for activating this email:

  1. Manual Activation means one of your WhosOnLocation Administrators must grant them access manually by sending the employee an Activation Email from the Employee management tools under Tools > Locations > View Location > Employees. On receipt of the activation email, the employee selects the embedded link (inside the email) and they are directed to the login screen of your WhosOnLocation account. They must then create a password in order to log in.
  2. Automatic Activation means when a new employee is added to your WhosOnLocation account via the Active Directory Sync, an activation email is sent automatically to the new employee inviting them to create their own password in order to log in.

Requirements

  • Windows PowerShell 3.0 or greater

Configuration

You must enter five configuration items into the Sync script. We provide default values to assist.

Appkey

  • This is a secure token which uniquely identifies your company in our software, we pre-enter this value for you.

Location (optional)

  • default: ""
  • The staff location normally is matched from the ‘l’ LDAP attribute, this can be overridden by setting the location variable in the script. Multiple copies of the Sync script can be run with different location variable and LDAP parameters to ensure the employees are imported to the correct place.

Group

  • default: ""
  • The script may be run multiple times (eg, with different base OU or filter). To stop your two or more sync actions from overwriting each other please set the 'group' variable in each script. A group is a set of staff, if you set this to a different value for each copy of the script you run then they will not interfere with each other. Staff are only added/changed/removed within each group. The group name is an arbitrary string such as AD1 & AD2.

Process Offline

  • default: ""
  • By default the data is processed as it is uploaded and the result stats are printed on exit. For large extracts this can take longer than the timeout setting on the intermediate proxy/firewall within the customer's network and the connection is closed before completion. By setting process_offline to "true" we will read the data and return immediately, furthermore an email address can be set here and the result stats sent on completion.

Search base

  • example: "CN=Users,DC=example,DC=com"
  • The point within your Active Directory tree to search for user accounts.

ADProps

  • The Active Directory attributes to send to WhosOnLocation. This is pre-set to "'ObjectGUID', 'GivenName', 'Surname', 'DisplayName', 'Title', 'EmailAddress', 'Company', 'OfficePhone', 'MobilePhone', 'Office', 'Department', 'Country', 'thumbnailPhoto'".

Determining your search base

The search base is the location within Active Directory where the user export begins, all matching user objects under this location will be exported. The path is in LDAP Distinguished Name syntax.

If you do not know your user OU then a LDAP browser such as http://www.ldapadmin.org/ can be invaluable.

To use LdapAdmin
 
  1. Go to Start -> Connect -> New Connection
  2. In the host field enter in a domain controller to query, choose GSS-API for authentication
  3. Clicking "Fetch DNs" should return a list, if it does not then the host or authentication is incorrect
  4. Choose the base for your directory, it is usually the first in the list
  5. Once connected, find the container which has your users in it, egldappath.png
  6. Right click on this container and choose "Copy DN to Clipboard"ldapcopy.png
  7. This is the value which should be used in $searchbase

Filtering Users

You should be able to use the Get-ADUser Filter/LDAPFilter and Where options to refine your user list. Using the PowerShell ISE you can highlight the Get-ADUser and Where cmdlets and execute the 'Run Selection' to just extract the users to the console, this can help see what is being exported.  All examples should be verified and tested, the LDAP structure will vary between organizations.

Start by setting your base to the Users organizational unit so you only find accounts in there.
$searchbase   = "CN=User Accounts,DC=example,DC=com"
Then you use Filter and Where options to find exactly what you want. There is a good summary from Microsoft at https://technet.microsoft.com/en-us/library/ee617241.aspx

Example searches

Find all users with an email address assigned
Get-ADUser -Filter {mail -like "*"} ...
Search by Office
Get-ADUser -Filter {(physicalDeliveryOfficeName -eq "Somewhere") ...
Search by OU

Where {$_.enabled -eq $true -and ($_.DistinguishedName -like "*,OU=First OU,CN=Users,DC=company,DC=com" -or $_.DistinguishedName -like "*,OU=Second OU,CN=Users,DC=company,DC=com") }

Exclude an OU from the export

Where {$_.enabled -eq $true -and $_DistinguishedName -notlike "*,OU=SomeGroup,CN=Users,DC=company,DC=com" }

Scheduling

To set up your scheduling, follow the below steps:

1. Open Task Scheduler

Open Task Scheduler and Create a new task. Name it and set the user account to one that is able to query Active Directory to extract the staff list. Enable the 'Run whether user is logged on or not' radio button.

create_task2.png 

2. Set Triggers

Click on the Triggers tab and set your schedule or event that will trigger the running of your PowerShell script. This is typically run once per day but can be any schedule.

triggers2.png

3. Create your Action

Click on the Actions tab and click on New.

Action: Start a program

Program/script: Powershell.exe

You don't need to put a path as it should already be on your system.

4. Set Argument

First you need to set the ExecutionPolicy. You have two options here, you can set the ExecutionPolicy on the machine or you can do it on a per-script basis. Read the PowerShell ExecutionPolicy link below as it talks about or you can issue the command:

Get-Help About_execution_policies

To set the execution policy globally, you can issue this command from within PowerShell:

Set-ExecutionPolicy Unrestricted

Or use one of the other settings available depending on your environment. In the context of this how-to, however, we want to set the execution policy on a per script basis and open up security for us to run the script. This security policy will only be in effect for the script we are running and not compromise security otherwise.

That means we use the following Argument:

-ExecutionPolicy Bypass -File c:\temp\wol2-ldap.ps1

5. Save and Test

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request