Active Directory Service. Integration Parameters and Implementation

(1)

Active Directory Service

(2)

AD Integration Parameters and Implementation

2

Overview

Egnyte allows you to externally authenticate your domain’s users with a third party directory service. This article will describe external authentication using Microsoft’s Active Directory product. A separate article describes external authentication using OpenLDAP. Please note that directory service integration is only available to customers on our Enterprise plan.

Getting Started

1. Provide a gateway for Egnyte to query your Active Directory Server via an external IP address or LDAP URL. For better security, please you may choose to elect to enable LDAP over SSL to further encrypt data transmission between the sites. (i.e. give AD server an external IP address). Read the following to learn more: support.microsoft.com/kb/321051

2. Allow the following IP addresses through your firewall. These are the IP addresses of our multiple data centers that may connect to your AD Server:

US West Coast Data Center 208.83.104.114

157.22.19.131

EU Data Center 173.245.120.83 173.245.120.48 US East Coast Data Center

208.83.111.2 208.83.111.131 173.245.120.50 173.245.120.51 173.245.120.44 173.245.120.82 173.245.120.88

For security practices, you may incorporate the follow port access control list to limit traffic between the datacenters and your local Active Directory.

Service Standard Port Number LDAP 389

LDAPS 636 MSFT-GC 3268 MSFT-GC-SSL 3269

 If the Active Directory is designed with subdomains and/or forest trusts, it is required to enable directory communications between Egnyte Cloud File Server and your Active Directory service to communicate over Microsoft Global Catalog with or without SSL ports. This will ensure proper authentication to the subdomains and/or forest trusts.

(4)

4

 Please note that Egnyte Cloud File Server that is setup for AD integrations will require a consistent communication with the Active Directory server to properly authenticate users.

o Egnyte recommends setting up a local administrator account(s) Egnyte Cloud File Sever that’s not integrated into AD authentication to provide you with an alternate means of accessing Egnyte Cloud File Server.

o Egnyte recommend setting up failover ACL policies on the firewall device(s) which may be pointed to a secondary AD server in case the primary AD server goes offline.

3. For Microsoft Active Directory Services (AD), navigate to Configuration >> Security in the Web interface. Scroll down to Active Directory

Enable AD

(5)

5

 LDAP URL

This is the URL to connect to your company's directory server. You may enter a hostname or IP address in the following format - ldap://serverhostname<:port number>, or for a secure connection - ldaps://serverhostname<:port number>.

Note that the port number is optional, if unspecified Egnyte will attempt to connect to port 389 for LDAP and 636 for LDAPS. Examples:

ldaps://directoryserver.acme.com:636 ldap://216.63.17.214:389

 BindDN

BindDN is the username pattern for authentication of directory server requests. Active Directory (AD) refers to the BindDN as userPrincipalName.

Example:

Active Directory - {username}@acme.com

Note: The above example is for domain acme.com. You only need to replace text in bold with your domain name.

 BaseDN

BaseDN is the distinguished name of the entry in the Active Directory hierarchy at which to start the search for user. Examples:

cn=users,dc=acme,dc=com ou=usergroup,dc=acme,dc=com

 Search Filter

Search Filter enables to define the criteria to narrow down user search. Example:

(userPrincipalName={username}@acme.com)

(6)

6

4. After defining the settings click on the Test Settings dialog to verify the connection to the AD server. If your tests are successful, you may save your settings. Once the settings are saved, your Egnyte account is enabled and ready for authenticating designated users against the AD server.

(7)

7

Migrating Your Users

After testing your settings successfully, you are ready to migrate users to your Egnyte domain. You have several options:

 Manually add (or edit) users one at a time via the web interface.

 Migrate users in bulk with a CSV file.

 Synchronize users from your existing AD directory using our AD Integration kit.

Manually Adding or Editing Users with the Web Interface

After you have successfully verified and saved your directory server settings, in addition to using the kit to import users, you can… Create new users and designate them to be Egnyte or Active Directory authenticated. LDAP Username will be used to match users created in Egnyte with user accounts in Active Directory server.

Note: Users that are created manually on the Egnyte server will not automatically use Active Directory authentication. This gives you the flexibility for mixed-mode authentication. For example, if you create a username for one of your clients, that user will

(8)

8

Synchronize Users with the AD Integration Kit

Egnyte Directory Service Integration Kit synchronizes user records and related metadata from your directory service into Egnyte. You can automatically add subset or all users into Egnyte from your directory service. Further, when new users are added or deactivated in your directory service you can use this kit to keep your Egnyte users up to date with your directory service records. These instructions assume that you have already completed a successful connection to the customer's AD/LDAP Server using the account's web interface.

The kit can be installed directly on your AD server or on another machine on the same network. After installing, you must set the Authentication Key as the value for client_m_version parameter in the directory_service.ini file. The Authentication Key can be found within the Applications section of your Egnyte cloud configuration.

To ensure active updates of your directory changes, configure the Egnyte Directory Services Integration job to execute on a schedule (e.g. every 24 hours) using Windows Task Scheduler.

(9)

9

AD Extraction Kit

A. AD Kit Download and System Setup

1. Download the Egnyte AD Extract Kit on your machine to test out the user extraction and build the kit. The kit can be downloaded from the Active Directory under the Apps section.

2. From the main page click on the App link on the upper right hand side of the website

3. Scroll down and under the Enterprise Apps and Integrations, please click and download the Egnyte Active Directory Connector.

4. Extract the zip file on any Windows machine that is on the same network as the AD Server 5. Browse to that directory through Windows Explorer

6. Use wordpad or textpad to edit the configuration file, directory_service.ini B. Initial Configuration and Test

The following steps configure the directory_service.ini file to extract users from your AD to an output file named data.tsv. Verify that the desired users are listed in the output file before continuing to the next step.

1. Use wordpad or textpad to edit the directory_service.ini file; set the following parameters for the first pass of the AD Extract Kit Parameter Value

action_list extract_users

(10)

10

Parameter Value

egnyte_domain Your domain name in Egnyte

Example: use “acme" if your domain is acme.egnyte.com

client_m_version Use the unique token string that was generated when you activate Active Directory in Settings/Configuration/Applications

service_type AD or OL (AD is default when commented out) host Internal IP address of Directory Service host

port Port number to connect to the Directory service of the above host *Port 636 is default when the flag “secure=True” is set

secure True if using ldaps (port 636), False with ldap (port 389) bind_dn Bind DN (user) used to bind to your active directory

Note – does not need to be a domain admin account, may need the full UPN of the user Example: [email protected]

passwd Password for above username

base_dn Base DN in your directory service from where to search

Example: base_dn=dc=acme,dc=com if the base DN is acme.com

Optionally – an “ou_inclusion_filter” can be used to identify the OUs that are part of the search path of the directory service Parameter Value

ou_inclusion_filter See section D 2. Save the directory_service.ini file

3. Open a command prompt to execute the Extract Kit

4. Change directory to the location that the AD Extract Kit was extracted 5. Execute 'run.bat' to run the script

6. The recommended method to review the output file is with MS Excel. Import the data.tsv file into Excel with “Import from a text file” to confirm that correct users were extracted. If the users were not extracted successfully, check the

(11)

11

a. Based on the error details, modification or changes to the directory_service.ini file may be required

7. If the generated user list is successful and the users that are to be pushed to the cloud are listed in the data.tsv file, you are ready to import the users to Egnyte with the sync_users action

C. Adding Users into Egnyte

The following steps configure the directory_service.ini file to extract users from your AD to an output file (data.tsv) and then add the users into the Egnyte Cloud. Verify that the desired users were extracted and added into the Egnyte cloud before continuing to the next step.

1. Use wordpad or textpad to edit the directory_service.ini file; set the following parameters for the first pass run of the AD Extract Kit

action_list add_users - add users to your Egnyte domain

sync_users – adds and updates users to the Egnyte domain

Note - when using the “sync_users, the “allow_create” flag must be set to True to push the list of users into the cloud

user_inclusion_by_group_filter= Only users within the specified security group(s) will be added 2. Save the directory_service.ini file

a. Depending on Security Policies, you may need to run the command prompt as an Administrator

b. To run command prompt as administrator click on Start/All Programs and locate the command prompt icon c. Right click on Command Prompt and left click on “Run as Administrator”

6. If the script finishes without any errors, login to your Egnyte account via the UI and select settings and then select Users and Groups. Browse within Power Users and Standard Users Interface confirming that the new users are now in Egnyte

a. If there are errors during the AD Extract Kit run, search through the directory_service.log file for more details regarding the error

(12)

12

8. Confirm that the users that are added into Egnyte via the AD Extract Kit are able to connect via the Egnyte web UI using their AD credentials

D. Working with multiple OUs in AD

These steps we will configure the directory_service.ini file to pull users from multiple organizational units (OU) within AD. Once the changes are made the script will add users into a file named users.csv. Verify that the desired users were listed correctly in the output file.

1. Use wordpad or textpad to edit the directory_service.ini file set the following parameters Parameter Value

action_list any action

ou_inclusion_filter Use a “,” to dig down the OU structure and a “;” to include additional OU’s. To pull users from qa.egnytead.com and us.sales.egnytead.com and europe.sales.egnytead.com

OU=qa;OU=europe,OU=sales;OU=us,OU=sales

2. Save the directory_service.ini file

(13)

13

6. Check the users.csv file to confirm that users were extracted. If users are not extracted successfully, review the directory_service.log file for error details

7. Based on the error details, changes to the directory_service.ini file could be required

8. If user extraction is successful and you have the correct users to in the users.csv file, you are now ready to import the users into Egnyte

9. Run the steps laid out in Section C of this guide to ADD the imported users into Egnyte. E. Working with Child and Multi Domains in AD

For these steps we will make a simple change to configure the directory_service.ini file to pull users from multiple child domains within AD. An example of a child Domain is: Primary domain name is [email protected], child domain would be

[email protected]. Once the changes are made the script will add users into a file named data.tsv. We will then verify that the desired users were extracted correctly by looking at the data.tsv file.

Adding Authentication Policies

action_list add_auth_policy – run this action once to add the additional directory service policies 2. Save the directory_service.ini file

3. Use wordpad or textpad to edit the authpolicies.ini file; set the following parameters for each child domain adding into Egnyte Parameter Value

ldapURL External IP address of the LDAP server and port. Example: ldapURL=ldap://270.135.59.71:3268 The port can be 636, 389, 3268

bindDN Change the name to reflect the correct domain Example: {username}@nyc.acme.com

(14)

14

baseDN dc=acme,dc=com

searchFilter (userPrincipalName={username}@nyc.acme.com) serviceType EXTERNAL_ADS or EXTERNAL_LDAP

4. Open a command prompt to execute the AD Kit

7. Check the directory_service.log file for errors, should any occur.

8. If child domain authentication was successful, you are now ready to extract and import the users into Egnyte. 9. Run the steps laid out in Section B and then section C of this guide to extract and import the users into Egnyte. List Existing Authentication Policies

This option lists existing authentication policies within the command window.

action_list list_auth_policy – allows to list child policies for given domain in the command line 2. Save the directory_service.ini file

(15)

15

5. Execute 'run.bat' to run the script

6. The command window will display existing authentication policies. Example:

INFO AD Kit 4.8.0 revision 136910 INFO list auth_policy: start

5dce62fe-bf91-454a-a878-249e24ccfef8 | dc=example,dc=co | {username}@example.com | ldap://270.135.59.71:3268 | userprincipalname={[email protected] | EXTERNAL_ADS

INFO list auth_policy: finished Extracting Existing Authentication Policies

This option extracts existing authentication policies into the authpolicies.ini file. NOTE: This action will overwrite any existing authpolicies.ini file.

action_list extract_auth_policy – allows to download all child policies and store them in authpolicies.ini file. 2. Save the directory_service.ini file

(16)

16

Example:

# Authentication policies applied to your domain. # Please do not alter the authPolicyId field.

# When finished editing please run update_auth_policy command # to apply the changes.

# If you want to delete any policy from CFS, please use 'Delete this policy' # marker, setting it's value from No to Yes (Delete this policy=Yes).

---

authPolicyId=5dce62fe-bf91-454a-a878-249e24ccfef8 ldapURL=ldap://270.135.59.71:3268

bindDN={username}@example.com baseDN=dc=example,dc=com

searchFilter=userprincipalname={username}@example.com serviceType=EXTERNAL_ADS

Delete this policy=No

Update Existing Authentication Policies

This option allows you to update existing authentication policies. To perform an update you will first need to run an extract. 1. Perform the steps above to Extract Existing Authentication Policies

2. Locate the authpolicies.ini file and open in wordpad or textpad. 3. Make necessary changes to the authpolicies.ini file

4. Save the authpolicies.ini file

action_list update_auth_policy – updates the existing child policies with the content of authpolicies.ini file. 6. Save the directory_service.ini file

(17)

17

c. Right click on Command Prompt and left click on “Run as Administrator” 8. Change directory to the location that the AD Extract Kit was extracted

9. Execute 'run.bat' to run the script

10. Perform another extract_auth_policy action and verify that the auth policies were updated properly. Deleting an Authentication Policy

You have the ability to delete existing authentication policy.

1. Perform the steps above to Extract Existing Authentication Policies 2. Locate the authpolicies.ini file and open in wordpad or textpad.

3. Locate the policy you wish to delete and change Delete this policy action to YES.

NOTE: Please be sure to set the delete action for the correct authentication policy. The delete action should be located directly below the authentication policy you wish to delete.

Example:

# Authentication policies applied to your domain. # Please do not alter the authPolicyId field.

# When finished editing please run update_auth_policy command # to apply the changes.

# If you want to delete any policy from CFS, please use 'Delete this policy' # marker, setting it's value from No to Yes (Delete this policy=Yes).

---

authPolicyId=5dce62fe-bf91-454a-a878-249e24ccfef8 ldapURL=ldap://270.135.59.71:3268

bindDN={username}@example.com baseDN=dc=example,dc=com

searchFilter=userprincipalname={username}@example.com serviceType=EXTERNAL_ADS

Delete this policy=YES 4. Save the authpolicies.ini file

(18)

18

action_list update_auth_policy – updates the existing child policies with the content of authpolicies.ini file. 6. Save the directory_service.ini file

10. Perform another extract_auth_policy action and verify that the auth policies were updated properly. F. Adding Groups into Egnyte

Adding groups is similar to the user process. However since some groups may not reside in the same OUs as the users, it may be helpful to include the OUs that contain all your security groups in the “ou_inclusion_filter”. Additionally, if this spans too many users and/or groups, we can further restrict the users/groups with the group_exclusion_filter and the users_inclusion_by_group_filter. To add any users and security groups to Egnyte, the same OU Inclusion string (ou_inclusion_filter) must contain the OUs in which the users and groups reside.

Similarly to Section B where users are extracted, run the extract_groups to obtain a listing of the groups that Egnyte can read from AD. The groups will be compiled in the output file (data.tsv). Next verify that the groups listed are indeed the groups that are to be added to the Egnyte Cloud.

1. Use wordpad or textpad to edit the directory_service.ini file; set the following parameters for the first pass run of the AD Extract Kit

action_list extract_groups

group_exclusion_filter The defined security groups will be excluded from Egnyte Example: group_exclusion_filter=group1,group2,group3 2. Save the directory_service.ini file

a. Open a command prompt to execute the Extract Kit Depending on Security Policies, you may need to run the command prompt as an Administrator

(19)

19

5. The recommended tool to review the groups again is MS Excel. Import the data.tsv file into Excel with “Import from a text file” to confirm that correct users were extracted. If the users were not extracted successfully, check the directory_service.log file for errors

6. Based on the error details, modification or changes to the directory_service.ini file could be required

7. If the generated group list is successful and you have the groups that are to be pushed to the cloud listed in the data.tsv file, you are now ready to import the groups into Egnyte

Again, like in Section C, groups can be added to Egnyte by changing the action_list flag, this time using “sync_groups”.

action_list sync_groups

confirm that “allow_create=True” in the .ini file Note - using sync_groups will invoke sync_users

G. Sustaining and Syncing User and Groups

Once the desired filtering is configured, a scheduled job can be used to periodically run the user and group sync scripts. This way any additional users and groups can be read from AD and be pushed to the cloud.

 Egnyte recommends adding a “Scheduled Task” on a Windows system to be initiated every 24 hours to ensure that Egnyte Cloud File Server continues to have updated AD information.

(20)

20

Install Process Summary

1. Enable and Configure AD in Egnyte 2. Download the AD Kit

3. Configure the directory_service.ini

a. Define the following parameters – (these parameters will generally be static): i. host

ii. secure

iii. client_m_version iv. egnyte_domain

v. bind_DN vi. passwd vii. base_dn

b. Use filtering as necessary (tailor to the AD architecture): i. user_exclusion_filter

ii. group_exclusion_filter iii. ou_inclusions_filter

iv. user_inclusion_by_group_filter

4. Run action_list=extract_users to get a list of users to be added to the cloud 5. Import the data.tsv as a text file in Excel to review the users

6. Modify the directory_service.ini configuration as needed to achieve the correct list of users. For troubleshooting purposes, review the directory_service.log for details of the AD Kit run results.

7. Once the config is finalized, set action_list=sync_users (with the allow_create=True flag uncommented) to push the users to the cloud

8. Repeat the process for groups by setting action_list=extract_groups, reviewing the data.tsv output file, and then setting action_list=sync_groups to push the groups to the cloud

9. Lastly, if the filtering is complete, nothing needs to be changed. Run the script (with action_list= sync_groups) via a scheduled job based on the frequency required

(21)

21

Configuration Parameters

The following is how to use each of the configuration parameters in the directory_service.ini & authpolicies.ini files: directory_service.ini

Parameter Options Description

action_list extract_users Extract users from your directory service add_users Add users to your domain in Egnyte

add_auth_policy Add an authentication policy to your domain in Egnyte update_users Update user attributes (such as first/last name) in your Egnyte

domain

list_users List all users from your Egnyte domain

sync_users One-way syncing of users from your AD/OpenLDAP to your Egnyte domain – equivalent of extract, add, and update.

*Note - when using this action, the “allow_create” flag must be set to True

extract_groups Extract groups from your directory service. add_groups Add groups to your Egnyte domain

update_groups Update groups attributes in your Egnyte domain list_groups List all groups from your Egnyte domain

sync_groups One-way syncing of groups and users from your AD/OpenLDAP to your Egnyte domain – equivalent of extract, add, and update. *Note - when using this action, the “allow_create” flag must be set to True

allow_create True or False Default is False - allows adding of new users or groups to Egnyte during sync_users and sync_groups actions. If set to True, then any user or group that exists in your directory service but not in your Egnyte domain will be created.

(22)

22

allow_delete True or False Default is False - allow_create parameter allows deleting of users or groups from Egnyte during sync_users and sync_groups actions. If set to True, then any user or group that exists in your Egnyte domain but not in your directory service will be deleted

seed_file data.tsv Output file that is created when extract_users or extract_groups is run. It is best to review this file to ensure that correct users are added to your Egnyte account

egnyte_domain Your domain name in Egnyte, if domain name is “acme.egnyte.com”

only “acme” is needed

client_m_version Unique authentication key generated in the Egnyte UI settings

webpage when enabling AD

email_suffix When defined, this overrides the domain controller’s domain

group_mapping inherit, noinherit, or flatten

inherit (default) - add all users listed within all subgroups. Create separate groups for each subgroup

noinherit - ignore subgroups, only add users explicitly listed as group members

flatten - add all users listed within all subgroups. Do not create separate groups for subgroups

service_type AD or OL External Directory service AD = Active Directory (default when commented out) or OL = OpenLDAP

host The directory service host IP address. If you are running this from

inside your firewall will be the internal IP of the directory service host

port Port number is 389 for ldap and 636 for ldaps

secure true or false If using ldap then this parameter is False if using ldaps then Set this to True

*Note - when secure=True the port is assumed to be 636

bind_dn Bind DN (user) used to bind to your active directory

Note – does not need to be a domain admin account, may need the full UPN of the user

Example: [email protected]

passwd Password for the bind_dn user

base_dn Base DN in your directory service from where to search

(23)

23

ou_inclusion_filter Define specific OUs to be included in the action list user_inclusion_by_group_filte

r

Only users within the specified security group(s) will be added Example: user_inclusion_by_group_filter=group1,group2

import_dist_groups By default only AD security groups are imported.

Setting this flag [true] allows import of all groups.

user_exclusion_filter Define specific users to exclude from the action list Example: user_exclusion_filter=user1,user2,user3

group_search_filter If using universal groups in the directory service, uncomment the “group_search_filter” to include universal and global groups

authpolicies.ini

Parameter Options Description

ldapURL External URL of the ldap server

bindDN Domain Name of child domain

baseDN Base Domain name

searchFilter Search filter of child domain

serviceType Service Type EXTERNAL_ADS or EXTERNAL_LDAP

Active Directory Service. Integration Parameters and Implementation