This article provides Installation Instructions for Active Directory (AD)
Before you begin the installation please make sure that the following is satisfied:
- You have read the document titled “Active Directory Integration”.
- You have an Active Directory / Domain Controller installation on your LAN.
- You have a machine that you are going to install the Echoshare Agent on, that will be integration agent for the AD.
- NOTE: This machine may NOT be the domain controller itself.
- NOTE: Ideally it could be a file server or similar that is guaranteed to be running all the time. The agent will be installed as a system service to ensure that there is a permanent connection to AD.
- NOTE: The machine must be Windows 7 or later – Windows XP is currently not supported.
- The best is a dedicated machine that is newly installed that is on the domain.
- You have a team already created in Echoshare with at least one admin account.
- .NET 3.5 is installed
- Windows 8 & Windows Server 2008 and later
- The agent must run as Administrator
1) Installing the basic agent
- Log into the computer on which you want to install the AD Integration agent.
- Download and install the agent from the official Echoshare site:
- Login to ECHOshare
- Click the Devices tab.
- Click + Install ECHOshare on this computer
- Connect the agent to your Echoshare Admin account.
- Verify that it is correctly installed and connected by finding it online in your account.
2) Switching into Service mode for AD access
- Shutdown the agent by right clicking on the tray menu and selecting Shutdown.
- Download and install the AD Service installer from:
- Restart the agent.
- Wait until the agent is online again.
- Switch the agent to run as system service.
- Right click on the tray menu and select Settings / Run as Service.
- Enter your Echoshare Admin account password to complete the Service switch.
- Verify that the agent is now running as system service.
- Right click on the tray menu and bring up the About box.
- It should say “Run Mode: System Service”.
- Verify that the agent is connected to the service by finding it in the web portal again.
3) Configure the AD setup
- Click on the Team Tab / Active Directory.
- Click Configure and add the agent to the setup.
- Configure the search path as described in the “Active Directory Integration” document.
- Try the “Test Authentication” to verify the link is working.
- Try the “Synchronize” button to verify that the AD integration is fully working.
- For reliability you may want to install an extra AD Integration agent. It is possible to have multiple AD Integration Agents connected to your team – if one is unavailable then the other one is used.
- Since the agent is running as system service unmaintained on a server you will need to check that it is the latest version from time to time. The team overview in the regular web portal allows viewing agents that need an upgrade.
The typical error conditions that can be experienced are:
- The AD Integration agent is not installed on a machine that has permission to perform authentications for all users on the domain. The typical cause for this is that the agent is installed on a domain controller but there can also be other domain policies that restrict this.
- The AD Integration agent is not installed as a system service and is therefore not always available when required – this means that users will not be able to log into the service when the AD Integration Agent is not running.
- The LDAP search path is incorrect. This results in the AD Sync operation not finding the expected users from AD.
Result when the LDAP path finds no accounts:
Recommended procedure for putting Active Directory into Production
Since connecting your Echoshare team to your Active Directory servers is a multi-step process where several things can go wrong, we suggest paying close attention to these instructions and the entire process.
Many teams that did not start using AD initially find themselves with quite a few existing user accounts by the time they decide to use AD. The team may originally have been set up as a trial, or as a smaller production team which has reached the point where integration with AD becomes necessary.
The Echoshare accounts are assumed to be using the same email addresses as the accounts that exist in AD. Echoshare AD integration maps accounts together based on email addresses.
1) Getting the AD Integration Agent installed
First get the agent installed that is to function as the AD Integration Agent following the procedures above in steps 1, 2, and 3. Verify that you have a reliable setup with an agent running as a Windows System Service.
We recommend configuring the AD Integration Agent on a dedicated server if possible that is directly connected (wired Ethernet) to your LAN. If a dedicated server is not available, configure the agent in such a way so that heavy backup and sync operations are not required by the agent to minimize any performance impacts.
Leave the agent running for a few days or longer to verify that it stays online all of the time and that there are no network connectivity or firewall issues, or other types of problems.
2) Prepare your AD for integration
Before you turn on AD for all team members you should perform a test integration. This test will involve getting a few accounts setup under AD management and becoming familiar with the integration.
The following setup is recommended:
- Create a new OU (Organizational Unit) in AD called “Test” which is at the same level as your main OU that you will be using. We will use this as a test container for integration.
- Provision a test account in your Echoshare Team called “Test User A <test-user-A@company.com>” – replace company.com with your own company domain and preferably use an email address where you can receive e-mails.
- Verify that your “Test User A” account is fully functional in Echoshare by logging in a few times through the web portal using the assigned password, in this example “user-A-psw”.
- Create two user accounts in your AD under the “Test” OU. They should be called “Test User A <email@example.com>” and “Test User B <firstname.lastname@example.org>” and have two new unique passwords (user-A-ad-psw and user-B-ad-psw).
You now have:
- Existing accounts in Echoshare that should not be affected when you connect AD to Echoshare (your current Echoshare users).
- A new user that is in both Echoshare and AD (Test User A).
- And a new user that exists in AD (Test User B) but not yet in Echoshare.
3) Next, connect AD to Echoshare
- Go into the Team / Active Directory setup and follow the instruction on the top of the page setting up the domain name, the LDAP search path, and an integration agent.
- Save the Settings.
- Click Configure again and test the authentication link by clicking on “Test Authentication for Active Directory”.
- Click on the “Synchronize” button – this runs your first query against AD and merges the data into your Echoshare team.
- Accounts with the same email address are linked to accounts in your Echoshare team. In our case this is “Test User A”.
- Accounts that exist only in AD are imported as being available for provisioning in the Echoshare team. In our case that will be “Test User B”.
- Accounts that exist only in the Echoshare team are unaffected. This would be the rest of your team members already provisioned.
- Run through the process of:
- Verify that the “Test User A” user is now linked to the AD record, that the password used to log into the Echoshare account is the user’s AD password and that user is shown in the team members list with the Windows icon on it (indicating it is linked to the AD account).
- Verify that the “Test User B” user is now picked up and placed on the list of available accounts that can be provisioned from AD.
- Confirm that AD Sync occurred as expected in the pop-up:
- Verify the Sync Log. The Sync log shows the details of actions that have occurred during an AD Sync operation.
- Verify the Active Directory Overview for new and deleted accounts. This page shows all accumulated changes from AD:
- Complete Admin Action on recently imported users:
Admin may at this time do either of the following:
- Do nothing – the entries will stay on the list and accumulate as more changes are picked up from AD. The admin should take this action if he has not yet decided if an account should or should not be provisioned for this new user.
- “Provision” which will create a new Echoshare account for the user found in AD – “Test User B”.
- “Ignore” – the admin takes this action if no Echoshare account is to be provisioned. The admin can always find this user later and provision the account by filtering for “Available in Active Directory” from the Team / Members tab:
- Verify that “Test User A” which was defined in both systems is now linked to the AD. You can see this by the small Windows icon on the team member:
4) Integrate the rest of your AD users
After you have become familiar with the workings of AD integration in Step 3, you are now ready to integrate and import the rest of the user information from your AD. Start this by changing the LDAP search path to include the main OU where you keep your users, and proceed as described in Step 3 above.