Active Directory Service Integration s and Implementation Revised January, 2014
Table of Contents Overview... 3 Getting Started... 3 Migrating Your Users... 7 Manually Adding or Editing Users with the Web Interface... 7 Synchronize Users with the AD Integration Kit... 8 AD Extraction Kit... 9 Install Process Summary... 20 Configuration s... 21 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 US East Coast Data Center 208.83.111.2 208.83.111.131 EU Data Center 173.245.120.83 173.245.120.48 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. 3
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 You will be presented with the following fields as detailed below. 4
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) Note: The above examples are for domain acme.com. You only need to replace text in bold with your domain name. 5
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. 6
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 authenticate against Egnyte while your employees are authenticating against your Active Directory Service. 7
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. 8
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 action_list extract_users Note this will only list out the users from active directory that have not been added to the cloud 9
egnyte_domain client_m_version service_type host port Your domain name in Egnyte Example: use acme" if your domain is acme.egnyte.com Use the unique token string that was generated when you activate Active Directory in Settings/Configuration/Applications AD or OL (AD is default when commented out) Internal IP address of Directory Service host 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 passwd base_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: egnyteuser@acme.com Password for above username 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 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 directory_service.log file for errors 10
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 user_inclusion_by_group_filter= 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 Only users within the specified security group(s) will be added 2. Save the directory_service.ini file 3. Open a command prompt to execute the Extract Kit 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 4. Change directory to the location that the AD Extract Kit was extracted 5. Execute 'run.bat' to run the script 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 7. Based on the error changes to the directory_service.ini file may be required to be re-run 11
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 action_list ou_inclusion_filter any action 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 3. Open a command prompt to execute the Extract Kit a. Depending on Security Policies, you may need to run the command prompt as an Administrator 12
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 4. Change directory to the location that the AD Extract Kit was extracted 5. Execute 'run.bat' to run the script 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 username@acme.com, child domain would be username@nyc.acme.com. 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 1. Use wordpad or textpad to edit the directory_service.ini file set the following parameters 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 ldapurl binddn External IP address of the LDAP server and port. Example: ldapurl=ldap://270.135.59.71:3268 The port can be 636, 389, 3268 Change the name to reflect the correct domain Example: {username}@nyc.acme.com 13
basedn searchfilter servicetype dc=acme,dc=com (userprincipalname={username}@nyc.acme.com) EXTERNAL_ADS or EXTERNAL_LDAP 4. Open a command prompt to execute the AD Kit 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 5. Change directory to the location that the AD Extract Kit was extracted 6. Execute 'run.bat' to run the script 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. 1. Use wordpad or textpad to edit the directory_service.ini file set the following parameters action_list list_auth_policy allows to list child policies for given domain in the command line 2. Save the directory_service.ini file 3. Open a command prompt to execute the AD Kit 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 4. Change directory to the location that the AD Extract Kit was extracted 14
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 Policy ID Base DN Bind DN LDAP URL Search Filter Service Type 5dce62fe-bf91-454a-a878-249e24ccfef8 dc=example,dc=co {username}@example.com ldap://270.135.59.71:3268 userprincipalname={username@example.com 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. 1. Use wordpad or textpad to edit the directory_service.ini file set the following parameters 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 3. Open a command prompt to execute the AD Kit 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 4. Change directory to the location that the AD Extract Kit was extracted 5. Execute 'run.bat' to run the script 6. Locate the authpolicies.ini file and open in wordpad or textpad. 15
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 5. Use wordpad or textpad to edit the directory_service.ini file set the following parameters action_list update_auth_policy updates the existing child policies with the content of authpolicies.ini file. 6. Save the directory_service.ini file 7. Open a command prompt to execute the AD Kit 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 16
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 5. Use wordpad or textpad to edit the directory_service.ini file set the following parameters 17
action_list update_auth_policy updates the existing child policies with the content of authpolicies.ini file. 6. Save the directory_service.ini file 7. Open a command prompt to execute the AD Kit 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 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. 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 group_exclusion_filter extract_groups 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 18
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 3. Change directory to the location that the AD Extract Kit was extracted 4. Execute 'run.bat' to run the script 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. 19
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. iii. iv. secure client_m_version egnyte_domain v. bind_dn vi. vii. passwd base_dn b. Use filtering as necessary (tailor to the AD architecture): i. user_exclusion_filter ii. iii. iv. group_exclusion_filter ou_inclusions_filter 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 20
Configuration s The following is how to use each of the configuration parameters in the directory_service.ini & authpolicies.ini files: directory_service.ini Options Description action_list extract_users Extract users from your directory service add_users add_auth_policy update_users list_users sync_users extract_groups add_groups update_groups list_groups sync_groups Add users to your domain in Egnyte Add an authentication policy to your domain in Egnyte Update user attributes (such as first/last name) in your Egnyte domain List all users from your Egnyte domain 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 from your directory service. Add groups to your Egnyte domain Update groups attributes in your Egnyte domain List all groups from your Egnyte domain 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. 21
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 client_m_version email_suffix group_mapping inherit, noinherit, or flatten Your domain name in Egnyte, if domain name is acme.egnyte.com only acme is needed Unique authentication key generated in the Egnyte UI settings webpage when enabling AD When defined, this overrides the domain controller s domain 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 port 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 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 passwd base_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: egnyteuser@acme.com Password for the bind_dn user Base DN in your directory service from where to search Example: base_dn=dc=acme,dc=com if base DN is acme.com 22
ou_inclusion_filter user_inclusion_by_group_filte r import_dist_groups Define specific OUs to be included in the action list Only users within the specified security group(s) will be added Example: user_inclusion_by_group_filter=group1,group2 By default only AD security groups are imported. Setting this flag [true] allows import of all groups. user_exclusion_filter group_search_filter Define specific users to exclude from the action list Example: user_exclusion_filter=user1,user2,user3 If using universal groups in the directory service, uncomment the group_search_filter to include universal and global groups authpolicies.ini Options Description ldapurl binddn basedn searchfilter servicetype External URL of the ldap server Domain Name of child domain Base Domain name Search filter of child domain Service Type EXTERNAL_ADS or EXTERNAL_LDAP 23