Introduction
Windows Active Directory is a mainstay user directory in most businesses, this article shows you how you can connect your on-premise Active Directory to your cloud tenant enabling your users to manage their account from the cloud.
Important Prerequisites
SSL-Enabled Active Directory
LogonBox is a security product and takes security very seriously, all communications between the LogonBox server and your Active Directory are done over SSL which ensures all passwords and actions are secured. If you do not have SSL setup yet this article covers setting up a simple self-signed SSL certificate for your Active Directory, Enable SSL on AD.
Cloud-Only SSPR Tenants
If you are using the Cloud based SSPR, in order for your tenant to locate your Active Directory, the directory needs to be visible to the tenant. This will all depend on whether the directory is located on the same network as your cloud tenant (if you have hosted your own LogonBox server) or if you are using our own cloud servers. If you have signed up using our cloud service then you will need to install a secure node agent connection in your own network to provide a dedicated, zero firewall callback service to our service, as documented in the article titled Installing a secure node agent.
Create Directory
Whilst managing the correct realm, navigate to User Directory and click Configure User Database located at the top of the User table.
From the form that opens up select Realm Type as Active Directory.
Configuring your standard AD Settings
With the correct realm type selected, the next step requires the Active Directory settings to be configured.
There are two top-level tabs available: Standard and Advanced. We'll first look at the settings in Standard.
Connection
You will need to provide the following information:
- Hostname - the fully qualified hostname of the domain controller you want to get users from.
- Domain - fully qualified domain name of your AD domain.
- Service Username - the service account username that will make the connections to AD to get the list of users/groups. Note that this account needs to be either an AD administrator or have delegated rights on AD to edit user objects in order for Hypersocket to be able to create new AD accounts.
- Service Password - the password for the above user.
If you are happy for your tenant to synchronize with these settings (i.e synchronize all users from your AD), click Update.
If everything is correct the details will be saved and the first synchronisation with your Active Directory will begin.
Wait a couple of minutes then click the refresh icon above the user list and it should show your AD users that have been synced.
Filter users by OU
With the core Active Directory settings configured, your tenant will begin synchronizing all users from your AD. If you wish to limit these to a subset, you can do so under the Filter tab.
Settings here are:
- Include BuiltIn Groups: Include groups from the CN=Builtin AD container. Set this to ON if you want to import AD groups such as Users, Guests or Administrators.
- Include Default Users: Include users and groups from the CN=Users container. Set this to ON if you want to import AD groups such as Domain Users or the AD administrator user account. Note for both this setting and the one above, it may be best to set these to OFF, which will save importing around 50 items that you may not use.
- Base DN: The base DN that you want to use for this realm. You can use this to further filter any users by only looking at any objects from this Base DN and down. You may leave this blank or add in the DC=yourdomain,DC=domain root DN if you do not wish to filter users in this way.
- Include OUs: The names of any OUs (in DN format) that you only want to import users and groups from. Type in the OU name and press enter or click the plus icon to add the filter.
- Exclude OUs: The names of any OUs (in DN format) that you wish to exclude from importing from. Type in the OU name and press enter or click the plus icon to add the filter.
Note that OUs can be entered either with a fully qualified DN, or just the part of the DN without the Base DN (the Base DN relating to the setting you entered for Domain in the first tab).
For example, both of these are valid on our test system
- OU=LogonBox
- OU=LogonBox,DC=tyrellcorp,DC=local
The Exclude OU filter will run after the Include filter, so this can be used to exclude a subset of OUs.
In the above example. LogonBox is being included with the sub OU of CSV being excluded from the import.
Group Filter
LogonBox can also filter users based on their group memberships. This can be used in conjunction with OU filtering, or on its own.
Settings here are:
- Group filter mode: This can be Group Names (where we refer to groups just by their name), DN (Using the full LDAP DN notation for the group) and DN (server side). This last setting is the most efficient as group filtering is done on the DC itself and LogonBox is only given a list of associated users rather than having to filter locally after a full sync.
- Include members of : A list of groups to include members of. Type in a group name and click the + to add it to the list.
- Exclude members of: A list of groups to exclude members of. Type in a group name and click the + to add it to the list.
Principal Filter
The Principal Filter tab works in a similar way to the Group filter, but for ignoring specific usernames and groups (Note: LogonBox also synchronizes groups which can be used for granting permissions to. If you use a group filter, then the group itself will be synced, just not the users. This Ignored Groups filter here will also ignore the group).
Just type in the username or group you wish to exclude from the reconcile and press Enter or click the plus icon.
Advanced Settings
The configuration items below are not necessary to get your Active Directory connected and synching with your tenant, however they may be useful for those that wish to have a little more control.
Click on the Advanced link above the tabs to see the advanced settings.
Advanced
The first tab contains some advanced settings that should in most cases not need to be altered. These settings are:
- Protocol: Can be changed from SSL to Plain. Note though that only SSL connections will allow users to be updated and their passwords reset so should be left as SSL unless you want only a read-only experience. Defaults to SSL.
- Backup Controllers: You can add a list of other AD servers that LogonBox will contact if the primary server is not accessible.
- Follow Referrals: Follows referrals to other domains in the forest (useful for importing users from child domains). Defaults to OFF.
- Enforce Password Rules: When a user performs a password reset enforce password rules on the new password. Defaults to ON.
- Use samAccountName for username: Use the samAccountName instead of the principal name as the primary name for users. Defaults to OFF.
- use samAccountName for group name: Use the samAccountName instead of the principal name as the primary name for groups. Defaults to OFF.
- Connect Timeout: The number of milliseconds to wait for a response when making a connection to the AD server. Defaults to 30000 ms.
- Read Timeout: The number of milliseconds to wait for a response on a read operation from the AD. Defaults to 120000 ms.
- Page Size: The AD returns users in blocks of users called pages. The default of 1000 is fine in most cases.
- Use Exchange addresses for secondary email: Use the Microsoft Exchange provided proxyAddresses to populate secondary email. Defaults to OFF.
- Cache Filtered Groups: When enabled, the synchronize process will pre-cache only those group that would otherwise be included. Defaults to ON.
Reconcile
The Reconcile tab contains settings relating to how LogonBox reconciles your users. The settings here are:
- Reconcile Every (mins): The number of minutes between successful synchronizations/reconciles. Defaults to 240 minutes.
- Retry on Failure (mins): The number of minutes between a failed reconcile and the next reconcile attempt. Defaults to 5.
- Max Failure Count: The realm will be disabled after concurrent failures exceeds this figure. Defaults to 3.
- Rebuild Cache: By default, reconciles will only handle any changes to users or groups to keep things quick. Setting this option to ON will perform a full reconcile of every item and is generally used in certain troubleshooting cases. Defaults to OFF.
- Purge Duplicates: On rare occasions with an out of date cache, duplicate users may be created. Set this to ON to purge any duplicates on the next reconcile. Defaults to OFF
- Cache Passwords: Create a one way hash and store on LogonBox so that subsequent authentication attempts do not need to contact AD. Defaults to ON.
- Purge On Delete: Ordinarily, users are not actually completed removed from the database, they are instead marked as deleted for and hidden from view. When enabled, this option will physically remove all deleted users. Defaults to OFF.
- Use Tags: LogonBox performs optimized synchronisation to only get the changes from AD since the last sync. This uses a tag in AD to track which users have changed. Defaults to ON.
- Maximum Partial Synchronisations: Partial syncs do not detect when users have been deleted in AD. Therefore every x sync will be a full one. This setting sets how many partial syncs take place before a full one triggers. Defaults to 5.
- Partial Synchronizations: The number of partial synchronizations that have taken place. When the maximum is reached, a full synchronization will be forced.
- Max Objects: The maximum number of objects to test for when creating or updating a realm. Defaults to 20000.
- Max Group Cache Size: To aid performance, groups are cached in memory during a synchronize. This setting determines how many groups can be stored at any one time. Defaults to 10000.
- 2nd Level/Query Caching: When enabled, queries and results will be cached by the database persistance layer. This may help performance, but at the expense of system memory. Defaults to ON.
- Flush Limit: After how many records should the internal transaction be flushed to the database transaction. A higher value may help increase the speed of a synchronize at the expense of memory. Defaults to 50.
Status information
There is another tab that only appears after you have configured your Directory and you edit the Directory configuration again. This tab is Status and contains information fields relating to the reconcile status.
These fields are:
- Status: The status of the last reconcile, which can be Completed or Failed.
- Next Due: What date and time the next reconcile will be started.
- Last Performed: What date and time the previous reconcile was started.
- Last Error: If the status is failed, this contains the error that caused the failure.
Conclusion
This article has detailed the core settings needed for your tenant to begin reconciling with your Active Directory. Your tenant should now successfully begin synchronizing with your AD enabling your users to be able to fully manage their Active Directory accounts in the cloud.
