Configuring External Authentication using Microsoft Active Directory / LDAP

Overview

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.

Login_Flow_png

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.

Active Directory

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

Managing Users

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.

New_User_Menu_Sel_png

All users require an email address and need to be part of the group “gp_teamdrive”.

ServerManager_View_png

User_Properties_png

In this picture it can be seen that the user is a member of the group “gp_teamdrive”.

gp_teamdrive_properties_png

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 /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 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 with yum: httpd, php, php-pear, php-ldap, php-mcrypt, openldap-clients.

The “Log” PEAR module must be installed using pear install.

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 ldap_login.php by default.

  • /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.php page, but is is used as target login page for the Web Portal. In other words the AuthLoginPageURL setting must be set to reference this page, not the ldap_login.php` page.

    The ldap_login.php page is used as the target page for the TeamDrive Client embedded browser. This page must be reference by the AUTH_LOGIN_URL Provider setting.

Note

All changes you make to other files under the authservice directory will be overwritten when you update to the latest td-regserver-ext-auth RPM.

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_enable_debug to true, in 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 false.

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 td_registration_server hidden field.
  • $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 WebPortalDomain Web Portal setting.

Encryption Parameters

Note

The encryption parameters are random sequences that must be changed for every new installation. Failure to do this results in a major security failure.

  • $user_secret_salt:

    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.

  • $token_encryption_key:

    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.

LDAP/AD Parameters

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.

Connection Parameters

These parameters are required.

  • $ldap_server_domain:

    This is domain name of the host on which the LDAP server is running.

  • $ldap_server_port:

    This is the port on which the LDAP server is listening. The default port for LDAP is 389.

Note

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`.
  • $ldap_basedn:

    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”

Authentication

If the LDAP server does not allow anonymous connections then you must provide credentials for the connection here.

  • $ldap_binddn:

    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”,

  • $ldap_bindpw:

    The password of the user.

User Attributes

A number of user attributes can be sent to the TeamDrive Client after successful authentication. The user_id and email are required.

  • $ldap_user_id_attr:

    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.

  • $ldap_email_attr:

    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.

  • $ldap_common_name_attr:

    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.

  • $ldap_telephone_attr:

    This attribute contains the user’s home or work telephone number.

  • $ldap_mobile_attr:

    This attribute contains the user’s mobile telephone number.

User Identification

These parameters are required. They are used to locate a user in the directory.

  • $ldap_userdn:

    This specifies the user distinguished name to be searched. $ldap_userdn is added to $ldap_basedn when performing the search.

  • $ldap_userattr:

    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.

  • $ldap_userfilter:

    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)”

Group Specification

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.

  • $ldap_groupdn:

    If this variable is empty, then no group check will be performed. The value of $ldap_groupdn is added to $ldap_basedn when searching for a group.

  • $ldap_groupscope:

    The scope for group search, either one, sub, or base. sub is the default.

  • $ldap_groupfilter:

    This is added to the search filter when searching for a group. It usually identifies the group object type, for example: “(objectClass=groupOfUniqueNames)”.

  • $ldap_group:

    This is the name of the group to be searched. User’s that wish to Login to TeamDrive must be members of this group.

  • $ldap_groupattr:

    This variable specifies the group attribute to searched forto find the group name: $ldap_group.

  • $ldap_memberattr:

    This is the attribute in the group object that specifies the names of the members.

  • $ldap_memberisdn:

    Set this variable to true if the $ldap_memberattr is 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_userattr attribute.

Authentication Procedure

The ldap_login.php (or 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 $reg_server_name and $provider_code settings.

<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" />

Note

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 $token_encryption_key parameter.

For debugging the generated query for the Active Directory, it is helpful to have the debugging information display in the browser, by setting $ldap_enable_debug to true.

Output is written to the login page, for example:

Logging_Output_png

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). The page referenced by the URL is referred to as the “verification page.”

Note

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. Check your SSL configuration using the service from SSL Labs: 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.

Note

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 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 Authentication Service’s login URL, e.g. http://authserver.yourdomain.com/authservice/ldap/ldap_login.php.

Set VERIFY_AUTH_TOKEN_URL to the Authentication Service’s token verification URL, e.g. http://authserver.yourdomain.com/authservice/ldap/ldap_verify.php.

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

AuthService_Settings_png

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.

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 $ldap_user_id_attr setting.

Embedded_browser_login_png

AdminConsole_Client_Settings_png

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.

AdminConsole_ListUsers_png

For more information about managing users, see Manage Users.