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 further down.
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 the “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 check 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 “External Authentication” in the TeamDrive Registration Server Reference Guide for more details.
The TeamDrive Registration Server installation ships with a PHP-based example on how to set up authentication against an LDAP or 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 Configuration¶
Sample code to interface between an Active Directory or LDAP Server and the Registration Server is included in the TeamDrive Registration Server installation package (subdirectory authservice and is also installed on the TeamDrive Registration Server Virtual Appliance (in directory /var/www/html/authservice).
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 sample 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 Auth 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 6 or a derivative like CentOS 6, Oracle Linux 6 or Scientific Linux 6. 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 with yum: httpd, php, php-pear, php-ldap, php-mcrypt, openldap-clients.
The following PEAR modules should be installed using pear install: Log, Auth
The two pages for authentication and token-verification need to be placed in the web server’s document root directory, e.g. /var/www/html.
For testing purposes, it’s possible to simply open the login PHP page in a regular web browser.
The ldap_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.
For querying LDAP/AD, this implementation uses the PEAR “Auth” object. More information can be found at the URL http://pear.php.net/package/Auth/docs.
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, (which can also be found in the “RegServerSetup.xml”) are entered.
<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="RegServerName" /> <input type="hidden" id="td_distributor_code" value="DIST" />
The file’s PHP code needs to be edited as to adjust the PEAR Authentication fields, as described by the following example. This example uses attributes for the Active Directory query.
$options = array( 'enableLogging' => true, 'host' => 'localhost', 'port' => '389', 'version' => 3, 'referrals' => false, 'basedn' => 'dc=tdad,dc=teamdrive,dc=net', 'binddn' => 'cn=TDAdmin,ou=teamdrive,dc=tdad,dc=teamdrive,dc=net', 'bindpw' => 'password', 'userattr' => 'mail', // attribute will be search 'userfilter' => '(objectClass=user)', // added to the search filter 'attributes' => array('sAMAccountName', 'mail', 'cn', 'homePhone'), //additional attributes to fetch from entry. These will added to auth data and can be retrieved via Auth::getAuthData(). An empty array will fetch all attributes, array('') will fetch no attributes at all (default). If you add 'dn' as a value to this array, the user's DN that was used for binding will be added to auth data as well. 'groupdn' => 'OU=teamdrive', // added to the beginning of the basedn - searching for group 'groupscope' => 'one', // Scope for group searching:one, sub (default), or base. 'groupfilter' => '(objectClass=group)', // be added to the search filter when searching for a group: 'group' => 'gp_teamdrive', //name of the group users have to be a member of 'groupattr' => 'samAccountName', // The group attribute to search for "cn" 'memberattr' => 'member', //The attribute of the group object where the user dn may be found. 'memberisdn' => true //Whether the memberattr is the dn of the user (default) or the value of userattr (usually uid).
Note that 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 private key. The highlighted shared key must be changed in both the login and verification page to some arbitrary other value. It is used as input for the MD5 encryption.
For the verification page:
For debugging the generated query for the Active Directory, it is helpful to have the debugging information display in the browser. To enable debugging, uncomment the follow section:
To disable debugging, simply “comment” the section out again.
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 VERIFY_AUTH_TOKEN_URL setting (see VERIFY_AUTH_TOKEN_URL (<VerifyAuthTokenURL> tag) in the Settings chapter of the Reference Guide). 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 starting with 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 SSL certificate problem: self signed certificate or other SSL-related problems when opening the URL.
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.
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 “Edit Provider Settings” the following parameters need to be set. Add the setting AUTHSERVICE/USE_AUTH_SERVICE and set USE_AUTH_SERVICE to True.
The 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.
Set AUTH_LOGIN_URL to the Auth Server’s login URL, e.g. http://authserver.yourdomain.com/ldap_login.php.
Set VERIFY_AUTH_TOKEN_URL to the Auth Server’s token verification URL, e.g. http://authserver.yourdomain.com/ldap_verify.php.
Now the TeamDrive Client needs to be informed to use external authentication 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 “default” (see 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.
Finally, set CLIENT/USE_EMAIL_AS_REFERENCE to True, so API requests to the Registration Server can be performed using the e-mail address instead of the (dynmically generated) username. (see USE_EMAIL_AS_REFERENCE (<UseEmailAsReference> tag) in the Reference Guide)
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 Managing Users.