Configuring External Authentication using Microsoft Active Directory / LDAP¶
TeamDrive supports “External Authentication”, where the authentication data is not stored on the Registration Server.
TeamDrive Client versions 3.1.1 and higher offer an alternative login window in an embedded browser, which resides in a different panel than the standard login dialogue. By default this window is disabled. It must be explicitly activated in the Client settings of the Registration Server. This process is described in detail below.
External Authentication is performed by an external web service, hosted on a web server separate from the TeamDrive Registration Server. This instance and the related web pages are referred to as an “Authentication Service”.
Below is a general overview of the TeamDrive Client login process.
If a sign-in attempt was successful, the Authentication Service will return an “Authentication Token” which is received by the client and sent to the Registration Server. The Registration Server then uses a pre-defined URL to verify the token. If the token is valid, the login phase ends successfully and the TeamDrive Client is registered.
This service can be configured to work with various authentication mechanisms, such as NIS, LDAP, Active Directory, Shibboleth and others. Only the Authentication Service needs to contact your directory server in order to verify the user names and passwords provided. The Registration Server has no knowledge of these values. See the chapter see External Authentication for more details.
The TeamDrive Registration Server installation ships with a PHP-based implementation of an Authentication Service for LDAP and Microsoft Active Directory Server.
This section covers the Authentication of a TeamDrive Client using the Active Directory directory service offered by Microsoft Windows Servers. Since Windows Server 2008, this is also referred to as ADDS. ADDS manages various objects on a network such as users, groups, computers, services, servers, and shared folders. With the help of Active Directory, an administrator can organize, deploy, and monitor the information of these objects.
Configuring Microsoft Active Directory Server¶
In the Server Manager, in the “Active Directory User and Computer” branch, create a new Organizational Unit with a meaningful name (“TeamDrive” for example). Select this newly created Organizational Unit and right click the middle panel to create a new user.
All users require an email address and need to be part of the group “gp_teamdrive”.
In this picture it can be seen that the user is a member of the group “gp_teamdrive”.
Authentication Service Installation¶
Reference code to interface between an Active Directory or LDAP Server and the
Registration Server is included in the TeamDrive Registration Server
installation package (see Installing the Registration Server External Authentication (optional)) and is also installed on the TeamDrive Registration Server
Virtual Appliance (in directory
However, for security reasons, we strongly recommend to set up a dedicated system for the Authentication Service and to not use the Registration Server’s web server for this.
The Authentication Service code can be deployed on any Linux system that supports running an HTTP Server (e.g. Apache) with the PHP scripting language and the PEAR extension enabled. It is strongly recommended to enable SSL for accessing the authentication web service, to protect the transmission of usernames and passwords from the TeamDrive Client to the Authentication Service.
The host providing the Authentication Service needs to be reachable by the TeamDrive Clients via HTTPS (TCP Port 443) as well as by your Registration Server via HTTP (TCP Port 80, if both systems are in a trusted environment) or HTTPS (TCP Port 443). Additionally, the Authentication Service needs to be able to access your directory service in order to verify usernames and passwords.
The detailed setup and configuration of this framework is out of the scope of this document; please refer to the installation instructions of your operating system and your local environment.
The following example assumes Red Hat Enterprise Linux 7 or a derivative like CentOS 7, Oracle Linux 7 or Scientific Linux 7. The names of packages or directories might differ on other Linux distributions.
On a minimal system, make sure that the following packages have been installed
The “Log” PEAR module must be installed using
For installation details see chapter Installing the Registration Server External Authentication (optional)
For testing purposes, it’s possible to simply open the login PHP page (“/authservice/ldap_login.php”) in a regular web browser.
Authentication Service Customisation¶
You may change the user interface and behaviour of the LDAP Authentication Service by modifying the layout and content of the following files:
/authservice/ldap/index.html: This is the default page, which redirects to
/authservice/ldap/ldap_login.php: You can change this page to present a login page that would be recognised by your users. For example, change the page to conform to you companies CI (Corporate Identity).
/authservice/ldap/ldap_verify.php: The only reason to change this file is to change the data returned to the Registration Server when an authentication token has been verified.
For example, returning the email address is optional. If you do not return an email address, the Registration Server will return an error if a user with the specified “User ID” does not already exist.
If an email address is returned, a user will be automatically created with the given User ID.
/authservice/ldap/ldap_web_login.php: This page is identical to the
ldap_login.phppage, but is is used as target login page for the Web Portal. In other words the
AuthLoginPageURLsetting must be set to reference this page, not the ldap_login.php` page.
ldap_login.phppage is used as the target page for the TeamDrive Client embedded browser. This page must be reference by the
All changes you make to other files under the
directory will be overwritten when you update to the latest
Authentication Service Configuration¶
Once you have installed the external Authentication Service code, you
must duplicate the file
ldap_config.php.example, and rename it to
ldap_config.php. The settings in this file must then be edited to
access your LDAP or AD service.
Optional parameters may be set to “”.
During testing of the LDAP connection, set the variable
ldap_config.php. When set to
true a trace of the
LDAP/AD login attempt will be printed to the HTML page. In production this
variable should be set to
Registration Server Parameters¶
The Registration Paramaters are required.
$reg_server_name: Set this parameter to the name of your Registration Server. On successful login, the TeamDrive Client is passed this value in the
$provider_code: This is the Provider Code of the Provider associated with this external login service.
Web Portal Parameters¶
$webportal_domain: When using the LDAP/AD Authentication Service in conjunction with a TeamDrive Web Portal, set this variable to the value of the
WebPortalDomainWeb Portal setting.
The encryption parameters are random sequences that must be changed for every new installation. Failure to do this results in a major security failure.
This random sequence of character must be unique for each installation. After setting this value at installation, it should never be changed again. It is important that this value must remain secret at all times as it is used to generate the, so-called, “user secret” value.
Any sequence of strings, of any length (preferably at least 50 characters) may be used.
Changing the value will result in the user not being able to access his/her key repository stored on the Registration Server, after TeamDrive is installed on a new device. This will mean the user does not have automatic access to all his/her Spaces created on other devices.
However, access can be restored for the new device if the user has an old device and performs a re-login (for example, after the password is reset on the Registration Server). Re-login forces the TeamDrive Client to re-encrypt the data in the Key Repository which will then make the Space keys available to new devices.
This random sequence is used as a key to encrypt token sent to the client. The value must be unique for every installation. This string may be changed at any time since tokens are only valid of a short time.
Any sequence of strings, of any length (preferably at least 50 characters) may be used.
For querying LDAP/AD, this implementation uses the LDAP functionality of the PEAR “Auth” module. Since this module is no longer externally maintained, an updated version (compatible with PHP 7.2) is included directly in the TeamDrive distribution. More information can be found at the URL http://pear.php.net/package/Auth/docs.
The configuration file contains parameters which the set the PEAR Authentication fields. The examples use values for an Active Directory query.
These parameters are required.
This is domain name of the host on which the LDAP server is running.
This is the port on which the LDAP server is listening. The default port for LDAP is 389.
Please check if the LDAP server can be reached from the Apache Web Server. The access might be blocked if SELinux is enabled. You can check this:
[root@authserver ~]# getsebool -a | grep http | grep ldap If you get ``httpd_can_connect_ldap --> off`` you have to allow the communication or disable SELinux as described in :ref:`disable-selinux`.
This is the base “distinguished name” of the part of the Directory that will be searched. Examples: “dc=teamdrive,dc=com”, “dc=egco,dc=teamdrive,dc=net”
If the LDAP server does not allow anonymous connections then you must provide credentials for the connection here.
This is the name of the user that has access to the part of the directory that is to be searched. For example: “cn=Manager,dc=teamdrive,dc=com”, “cn=TDAdmin,ou=global,ou=kkh,egco=tdad,dc=teamdrive,dc=net”,
The password of the user.
A number of user attributes can be sent to the TeamDrive Client after successful authentication. The user_id and email are required.
This is the name of the attribute which contains a unique identifier of the user. Usually this value is “uid”.
In order for external authentication to work the LDAP/AD server must store a unique, unchanging, identifier for each user. Note that if the identifier changes TeamDrive will fail to recognise The user, and assume the user is new. For this reason the email address is not a choice.
The name of the attribute that contains the user’s email address. Note that this email address is used within TeamDrive in order to invite users to a Space.
This is the name of the attribute that contains the user’s common name. If provided, TeamDrive will display this name, instead of the email address in the user interface.
This attribute contains the user’s home or work telephone number.
This attribute contains the user’s mobile telephone number.
These parameters are required. They are used to locate a user in the directory.
This specifies the user distinguished name to be searched.
$ldap_userdnis added to
$ldap_basednwhen performing the search.
This parameter specifies the attribute that will be searched for the user’s “login name”. Any parameter that uniquely identifies the user may be used.
This is added to the search filter when searching. It is usually used to specify the object type of the users, for example: “(objectClass=inetOrgPerson)” or “(objectClass=posixAccount)”
By specifying a group you can ensure that only users of a particular group are authorised to access TeamDrive.
Use the parameters below to to determine how to check whether a user is a member of a group.
If this variable is empty, then no group check will be performed. The value of
$ldap_groupdnis added to
$ldap_basednwhen searching for a group.
The scope for group search, either
subis the default.
This is added to the search filter when searching for a group. It usually identifies the group object type, for example: “(objectClass=groupOfUniqueNames)”.
This is the name of the group to be searched. User’s that wish to Login to TeamDrive must be members of this group.
This variable specifies the group attribute to searched forto find the group name:
This is the attribute in the group object that specifies the names of the members.
Set this variable to
$ldap_memberattris the complete distinguished name (dn) of the user. If not, it is assumed to be just the value of the the memberattr is the dn of the user (default) or the value
ldap_web_login.php) page generates an HTML form
with standard fields to collect the user’s credentials and generate the required
query with it. If the authentication was successful, the PHP code of the login
page generates the authentication token based on information returned from the
directory server (Active Directory) and returns it to the client.
The HTML form also includes some hidden fields, which are evaluated by the TeamDrive Client. In these fields the Registration Server’s name and the Provider Code are included.
The values are taken from the
<div id="loginFormWrapper"> <form id="loginForm" action="ldap_login.php" method="post" enctype="multipart/form-data"> <input type="hidden" id="td_login_page" value="login" /> <input type="hidden" id="td_registration_server" value="TeamDriveMaster" /> <input type="hidden" id="td_distributor_code" value="EGCO" />
The communication between the Authentication Service and the directory service (e.g. LDAP or Active Directory) is performed without encryption by default. If these services communicate via an untrusted network, we strongly advise to enable some form of encryption, to protect against the potential eavesdropping of usernames and passwords. For example, LDAP supports encryption via SSL (LDAPS), other alternatives would be using a VPN or an SSH tunnel.
The content of the authentication token that is returned to the client is
encrypted with a secret key. This key is stored in the
For debugging the generated query for the Active Directory, it is helpful to
have the debugging information display in the browser, by setting
Output is written to the login page, for example:
After the Authentication Service has confirmed the credentials of a user, an authentication token is passed to the TeamDrive client. The client then sends the token on to the registration server to complete the registration. Before the login process can be successfully completed, the registration server then verifies the authentication token by sending it to the Authentication Service.
This is done via the URL specified in the
The page referenced by the URL is referred to as the “verification page.”
If you use SSL to encrypt the token verification communication between the
Registration Server and the Authentication Service (by providing an URL
https:// in the
VERIFY_AUTH_TOKEN_URL), you must
install properly signed SSL certificates on the Auth Service’s web server
— using self-signed certificates will result in an authentication
failure, displaying the error message
REG SERVER EXCEPTION "-24918" ( "0"
) "Verify authentication failed: result file not found" in the Client log
file. You can use the command line tool
curl on the Registration Server
to test opening the verification page. It should not complain about
certificate problem: self signed certificate or other SSL-related problems
when opening the URL. Check your SSL configuration using the service from
https://www.ssllabs.com/ssltest/analyze.html and make sure that
the “Handshake Simulation” is working for current platforms and browser. The
following ssl parameters for the apache web server will create an A-rating
and make sure that the handshake is working for current platforms and browser:
SSLProtocol all -SSLv2 -SSLv3 SSLHonorCipherOrder on SSLCipherSuite ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS
To complete the registration process, the registration server requires the user’s ID and e-mail address. If the validation is successful, this information is sent back from the site as confirmation.
Web Portal Configuration¶
How to configure the TeamDrive Web Portal to use an external Authentication Service is described in the TeamDrive Web Portal Administration Guide.
When an Authentication Service is used by the Web Portal, the authentication token will be verified twice: once by the Web Portal and once by the TeamDrive Agent (running in the Docker container).
TeamDrive Client Configuration¶
Enabling external authentication requires various settings to be adjusted using the Registration Server’s Admin Console. For more information, see External Authentication and/or Settings in the Reference Guide.
Log in as the user that has the privileges to modify your provider settings.
Under “Providers/Provider Settings” the following parameters need to be set.
Add the setting
AUTHSERVICE/USE_AUTH_SERVICE and set
AUTH_LOGIN_URL must hold the URL of the webpage that handles
Authentication. This page is the so called “Web-Login-Panel” and will
be displayed to the user in the TeamDrive Client.
AUTH_LOGIN_URL to the Authentication Service’s login URL, e.g.
VERIFY_AUTH_TOKEN_URL to the Authentication Service’s token
Now the TeamDrive Client needs to be informed to use external Authentication
Service for this Provider. In the Provider Settings, set
CLIENT/PRE_LOGIN_SETTINGS as follows:
enable-login=false enable-lost-password=false enable-registration=false enable-web-login=true
The web-login-panel will be displayed if the “
enable-web-login” setting is
set to “
true” or “
enable-web-login=true/false/default (default: false)
in the Reference Guide).
If the standard-login panel is also activated (see
enable-login=true/false/default (default: true)
in the Reference Guide),
enable-web-login should be set to
default. This ensures that when the
client is started, the Web-Login-Panel is shown to the user
(as opposed to the Standard-login-panel).
The TeamDrive Client now calls the alternative login page within an embedded browser.
When logging in, AD users must enter their e-mail address (as opposed to their username) into the username field.
You can use the email address to reference users when making API calls. But, it
is also possible to use the
authid, which is set to the value specified by the
Upon successful first authentication, the user will be automatically created on the Registration Server. The user can then be managed through the Registration Server’s Management Console under the “Manage Users” tab.
For more information about managing users, see Manage Users.