How does this application work?
The Active Directory (AD) app is different than cloud-based tools like G Suite, Okta, or OneLogin. This application automatically creates and uploads a CSV from your AD instance. To do this, your IT team will need to install a cron script on your server.
Important Notes:
To run Active Directory sync please make sure you are running Powershell version 3.0 or greater.
In order for Active Directory to sync, Envoy requires that all users have at least a name and valid email.
Tip: You can manually create new employees or add employees from other locations while maintaining your directory sync. This feature is helpful for contractors, temps, or other people who may host visitors/receive deliveries but are not core team members. Learn more about manually adding employees.
Enabling the Envoy + Active Directory application
Go to Apps > All Apps.
Under Directory and SSO, select "Directory settings," navigate to Active Directory. Click “Install.”
Step 1: Run initial sync
Locate Your CRON script, and copy the script found there. Save it as
envoy-ad-sync.ps1on your server.
Read through the top part of the script and customize the variables from the plugin configuration to match your organization’s implementation.
This will typically mean setting the correct Organizational Units (OU’s) and optionally customizing where the sync will save its temporary files.
Run the script via command prompt or PowerShell to verify that the script is correctly syncing users with Envoy. You should be able to confirm the sync is running back on the Envoy dashboard by seeing details on when your last sync ran.
You may need to update the script execution policy settings or configure an exception to allow scripts to run on your Active Directory server.
In order for the Active Directory sync to successfully complete, all entries in the CSV generated by Powershell must have a valid e-mail.
You are required to use TLS 1.2. If you run into issues forcing TLS 1.2, within the Envoy cron script (screenshot above) replace:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
with
ServicePointManager.SecurityProtocol |= (SecurityProtocolType)3072;
Step 2: Setting up the script to run via Task Scheduler
Now, you’re ready to schedule the script to run automatically.
Ensure that the user account designated to run the task has the necessary permissions to read Organizational Units (OUs) and user accounts within your Active Directory environment.
Open Task Scheduler: On the computer where the script is located, access the Task Scheduler. You can do this by searching for "Task Scheduler" in the Windows Start menu.
Navigate to Task Scheduler Library: Once Task Scheduler is open, look for the "Task Scheduler Library" in the left-hand panel and click on it.
Create a New Task: Select the “Create Task” option from the right-hand actions panel to begin setting up your new task
Schedule your script to run daily by creating a new trigger.
Access Trigger Settings: In the "Create Task" dialog, navigate to the "Triggers" tab at the top of the window.
Add a New Trigger: Click on the "New..." button at the bottom of the window to open the "New Trigger" dialog.
Configure the Trigger:
Begin the task: Choose the option "On a schedule" from the drop-down menu to set the task to run based on a specific schedule.
Settings: Select the "Daily" option. This setting will configure the task to repeat every day.
Start Time: Set the start time to ensure the script runs at your specified time (script is set to 1AM in the example).
Confirm and Save: Click "OK" to save the trigger settings.
FAQ
How to alter the script to use a different variable such userPrincipleName:
Replace "mail" with "userPrincipleName" in the script per the screenshot below
How to exclude a sub OU?
Add the following to the "Get-ADUser" line of code
$out += Get-ADUser -searchbase $ou -Properties * -Filter "(mail -like '*@*') -and (Enabled -eq 'True')" | ? {$_.DistinguishedName -notlike "*,OU=[INSERT OU NAME],OU=[INSERT OU NAME]*"} |