The on-premise Active Directory (AD) integration is different than cloud-based applications like Okta, OneLogin and G Suite. This integration automatically creates and uploads a CSV from your on-premise AD instance. To do this, we will provide you with a powershell script that your IT team will need to schedule in order to run it on your AD server.
- To run an Active Directory sync, please make sure you are running Powershell version 3.0 or greater.
1. Prepare to Enable Automated Provisioning
- Create Access Groups - You can grant permissions to specific access groups in Genea based upon your AD employee attributes. Please create the appropriate Access Groups in Genea based upon your specific office needs (this could reflect your AD organizational unit structure). For example, Employees, Contractors, and IT Admin access groups.
- Single Location vs. Multiple Locations - If you have multiple office locations enabled with Genea, decide whether you’d like to sync all users to all locations, or to sync specific users per location. This will affect how you set up the integration.
- Mobile Key - Decide whether you would like to assign mobile keys to all newly boarded users by default or if you want to assign them later.
- Enable or Disable User Updates - If you are going to update user attributes (access group, role etc..) after users are synced from AD to Genea, please disable the 'User Updates Syncing' option so that your changes aren't overridden during directory syncs.
2. Enable AD Integration
- Login to your Genea admin dashboard and navigate to the 'Integrations' page.
- Find the Active Directory integration and click 'Install.’
- Once installed, be sure to copy your AD integration API key and download the powershell script.
3. Configure Provisioning Rules
The very first thing you need to configure is your provisioning rules. Employee syncing will not work unless you have defined at least one rule.
With provisioning rules, you can decide:
- To what 'access group' each user should be assigned.
- What 'role' each user should be assigned in Genea.
- Whether newly on-boarded users should automatically receive mobile keys.
- The office locations to which an employee is granted access.
Simple Provisioning Rule:
You can have one simple default rule where every user synced to Genea is granted common door access and a regular user role.
For example, you can define a rule where every user synced from AD is assigned to the 'Employee' access group and to the 'User' role. Genea administrators can later modify any of these user attributes manually within their Genea admin dashboard.
You don't need to provide any conditions to define a simple default rule.
Advanced Provisioning Rules
You can get more advanced with the rule engine so that you do not have to worry about updating any user attributes manually within Genea.
As shown below, based upon your 'Organizational Units,' you can sync specific employees to specific locations. You can also assign different door access groups based upon your departments, job titles, cities, etc.
Additionally, you can also drag these rules up or down which sets rule priority. Rules are executed in order based on priority. Once one rule is matched and executed, the rest of the rules will be skipped.
You can add various conditions in a single rule, as shown below. You can either choose the 'match all' conditions or 'match any' conditions option.
You can choose any of the following AD user attributes to define your rule conditions.
USER UPDATE FLAGS
While setting up your integration, you may choose to enable or disable certain user updates from Active Directory to Genea.
If your integration set-up includes a few basic and/or broad rules, or if you plan on changing user attributes manually within Genea after users have been synced via Active Directory, we recommend disabling the ‘Override Roles on Update’ and ‘Override Access Groups on Update’ update flags. If enabled, these User Update flags may override manual changes made to your users’ roles and/or access groups in Genea.
Delete User If No Rules Match: if changes have been made to a user’s profile within Active Directory that no longer qualify them for any of your integration rules, the user will be deactivated within Genea. IMPORTANT NOTE: This flag will only come into play during directory updates. If you deactivate or suspend a user within your directory, the user will automatically be deactivated within Genea, regardless of whether this User Update flag is enabled or not.
IMPORTANT NOTE: If your integration does not include a specialized rule for provisioning system administrators, we recommend disabling the ‘Override Roles on Update’ flag as system administrator privileges may be revoked for existing administrators during updates. To avoid losing administrative privileges while keeping this flag enabled, we recommend creating a specialized rule within your integration that will provision system administrators. Ensure that this rule is placed first within your rule priority list so that system administrators will be provisioned first, then remaining users will be matched to the following rules accordingly.
5. Setting up the script to run via Task Scheduler
Understanding the folder structure :
export_ad_to_sequr.ps1 - This teh main script that needs to scheduled to run perodocally
configs - This the configuration file where you need to specify your Genea inregartion API key and the list of OUs
last_run_time - This holds the last run time of the export script. Usually you do not have to modify anything in here
modules - This folder has set of helper scripts. You do not have to modify anything here.
- Open the configuration file 'configs’. Please update your AD integration API key as noted in the previous step. Please provide the target list of Organizational Units (OUs). Script will only consider this list of OUs for syncing.
- If you wish to sync only the users that were created, updated or deleted from today onwards, please do not modify anything in last_run_time file and leave the value empty. But if you intend to sync all the current users from AD to the Genea, please provide a past date to the timestamp in the following format “M/D/YYYY hh:mm ss A"
- Run the script via powershell to verify that the script is running correctly. You may need to open the shell as Administrator. Right click and select 'Run As Administrator.'
Note: You may have to update or allow an exception on the script execution policy on your AD box. You can run powershell command "Unlock-File" which unlocks the powershell scripts that were downloaded from the internet.
> Unblock-file .\export_ad_to_sequr.ps1
> Unblock-file .\modules\fetch_group_information.ps1
> Unblock-file .\modules\upload_to_sequr.pas1
Now, you’re ready to schedule the script to run automatically.
- Open 'Task Scheduler' on your AD machine with the script.
- Open 'Task Scheduler Library' and select 'Create Task.'
- Adjust the settings accordingly. It’s important that the user account that is set to run this task is able to read OU’s and user accounts in your Active Directory environment.
- Set a schedule for the script to run. Do this by creating a new trigger. In the following screenshot, the script is set to run every 1 hour.
- Define an action for the task to run the powershell script. To do so, under the Actions tab -> Add new -> Select Action as "Start a program". Under Settings-> Programs/scrpits write powershell. Add the argument field as -File <path to the powershell script>.
Once your schedule has been saved, your Genea Access Control + AD integration set-up will be complete. Your users will then sync automatically from Active Directory to Genea, per your set schedule.
If you have any questions about setting up your Active Directory integration, reach out to Genea Support at firstname.lastname@example.org for assistance.