External Authentication

TeamDrive supports external authentication. If used, the authentication data is not located on the Registration Server. The TeamDrive Client, version 3.1.1 or later, provides an alternative login window in the form of an embedded browser. This embedded browser-based login window resides in a different panel than the standard login dialogue. By default, this panel is disabled, and must be enabled explicitly by the Client Settings sent from the Registration Server. This procedure is described in detail below.

External authentication is performed by a Web-site, possibly just a single page. This Web-site is called an “Authentication Service”. Upon a successful login, the Authentication Service returns a page containing an “Authentication Token”. This token is received by the TeamDrive Client and sent to the Registration Server. The Registration Server then uses a pre-defined URL to verify the Authentication Token. Upon successful verification the login will be completed.

External User Data

In order to complete the login of an externally authenticated user, the Registration Server requires a user ID and the email address of the user.

User ID

A vital prerequisite for the external authentication is a unique fixed user ID. The Authentication Service must provide a unique ID for every user that can be authenticated by the service. Furthermore, the user ID must be fixed (always remain associated with that user) the moment it is first used to identify a user.

The user ID may be any character sequence up to 100 unicode characters (or 300 ascii characters) in length. The character sequence used as the user ID is an internal reference which will not be exposed to the user. This means the character sequence can be cryptic (i.e. it does not need to make sense to the user). The most important characteristics of the user ID is that it’s unique and fixed.

Most systems to do not have a problem providing a unique identifier for a user. For example, the email address of the user is globally unique, and can used as the user ID. Many authentication systems, such as LDAP, store a “username”, which uniquely identifies the user.

However, some systems have a problem with the “fixed” property of the user ID. For example, the email address of a user can be used as the user ID, but there are situations in which a company may want to change a user’s email address.

In general, if the user ID of a user changes, the Registration Server will not recognize a user as the same user when the user logs in for a second time. For example, if a user owns two devices, and the user’s ID changes after login on the first device, the Registration Server will consider the login on the second device to be from a different user, even though the user used the same credentials to login on both devices.

Email Address

Users that have been externally authenticated will be identified in the TeamDrive Client by their email address. Invitations sent to externally authenticated users must also use the users email address.

The user’s email address may change if it is not used as the user ID. In this case, TeamDrive will only discover the change when the user logs in again. It is possible to force the user to re-login, however this cannot be done automatically since the Registration Server has no way of knowing that a user’s email was changed within the Authentication Service.

Re-login is described in Compelling Re-login.

The user’s profile name can be used as an alternative to displaying the user’s email address in the TeamDrive Client (see display-full-name=true/false (default: false)).

If the username is hidden, we recommend setting the user’s profile information during the external login process, if possible. This is described in Authentication Examples.

Compelling Re-login

You may need to compel the user to re-login for a number of reasons:

  • Updating user information (email address and other profile information) stored by the TeamDrive Client or the Registration Server. Currently, re-logging is the only way to update this information.
  • The user’s password has changed.
  • Confirming the user’s identity for security reasons (usually done periodically)

Forcing the user to re-login is currently a manual process. It is done by generating a random MD5 value and updating the column MD5Password in the table TD2Device (see TD2Device table) and TD2User (see TD2User table), in the td2reg database. All devices and the user row must be set to the same MD5 value.

A random MD5 value is generated by applying the MD5 hash to a randomly generated character sequence. A different random MD5 value should be used for each user.

The result of this update is that the TeamDrive Client on all devices of the user will automatically request login.

Login Configuration

Login is configured by the client-side settings. The settings that can be used are described in Login and Registration Client Settings. Since the user is in the pre-login phase, the settings used are determined by the Candidate Provider (see Network Allocation).

If external authentication is required then the embedded browser-based login panel must be enabled. This is done by setting the enable-web-login setting (see enable-web-login=true/false/default (default: false)) to “true” or “default”. If the standard login panel is not disabled (see enable-login=true/false/default (default: true)) then enable-web-login should be set to “default”. This will ensure that the user is presented with the web login panel when the TeamDrive Client is started.

Next the AUTH_LOGIN_URL setting for the Provider must be set to the URL of the page that will handle the authentication. This URL will be called as soon as the web login panel is displayed to the user.

Lost Password and Registration

Embedded browser-based panels are also available in the login dialogue to preform the “Lost Password” and “Registration” functions.

Their Configuration is similar to the configuration of the Web-based login function. The client-side settings user are enable-lost-password, enable-web-lost-password, enable-registration and enable-web-registration, as described in Login and Registration Client Settings.

If you implement these functions then you must set AUTH_LOST_PWD_URL and AUTH_REGISTER_URL to the corresponding URLs (see EMAIL Settings).

All your embedded web-pages can be linked together in way expected by the user. For example, the Login page should provide a link to the Lost Password page, if available. Hidden fields (described below) in these pages inform the TeamDrive Client that a page change has occurred, so that the page will be displayed in the correct panel.

Back buttons do not need to be provided by the web-pages. This operation can be performed by using the standard buttons available in the login dialogue.

Authentication Examples

If you plan to implement your own Authentication Service, please request the example authentication web-sites from TeamDrive Systems GmbH.

We provide two example authentication web-sites.

Demo Authentication

This is a set of PHP pages which provide a simple example of all authentication functions: login, lost password and registration. This code is provided for demonstration purpose only, and should not be used in a production environment.

LDAP Authentication

This is an implementation of LDAP Authentication in PHP, meant for reference. This implementation uses the PEAR “Auth” module ( http://pear.php.net/package/Auth/docs). Since this module is no longer externally maintained, an updated version (compatible with PHP 7.2) is included directly in the TeamDrive distribution. You may use these web-pages almost (see note below) without modification if you wish to provide LDAP based authentication for your TeamDrive users.

Install the code by copying it to the Apache documents folder. Before the code can be tested. duplicate the file called “ldap_config.php.example” and rename it to “ldap_config.php”. You must then alter the parameters in this file as required.

See the chapter Configuring External Authentication using Microsoft Active Directory / LDAP in the TeamDrive Registration Server Administration Guide for details.

Note

When using the LDAP reference code you must change two configuration parameters that are used for encryption. In the file “ldap_lconfig.php”, the parameters to be changed are $user_secret_salt and $token_encryption_key. Follow the detailed instructions in this file.

The Auth_Container_LDAP Auth “container” is used to access the LDAP server and verify the user’s credentials.

PEAR Auth provides other containers for many authentication methods, including:

  • Auth_Container_IMAP – Authenticate against an IMAP server
  • Auth_Container_KADM5 – Authenticate against a Kerberos 5 server
  • Auth_Container_POP3 – Authenticate against a POP3 server
  • Auth_Container_SAP – Authenticate against a SAP server

The LDAP reference code can be easily adapted to use one of these alternative authentication methods.

Authentication Tokens and Verification Pages

As mentioned above, after the Authentication Service has confirmed a user’s credentials, it returns an Authentication Token to the TeamDrive Client. The client then sends the token to the Registration Server in order to complete the login.

Before it can successfully complete the login process, the Registration Server must verify the Authentication Token. This is done using the URL stored in the VERIFY_AUTH_TOKEN_URL setting (see VERIFY_AUTH_TOKEN_URL). The page referenced by this URL is called the “verification page”.

A verification page performs two functions:

  • Validation of the Authentication Token: The verification page must confirm that the Authentication Token is valid, and was generated by the Authentication Service. Two examples of how this can be done are provided by the Authentication Examples mentioned above.
  • Return User data required to complete Login: As mentioned above, in order to complete login, the Registration Server requires the user ID and the email address of the user. This information must be returned by the verification page if validation is successful.

The verification page may be either local or remote.

Remote Verification Page

A remote verification page is located on the Authentication Service server. Verification of the Authentication Token requires the Registration Server to open a secure HTTP connection to the Authentication Service.

The Demo Authentication example described above is an example of a remote verification page. The Authentication Token used in the Demo example contains a reference to user data stored by the authentication web-site (i.e. stored by the Authentication Service).

When the verification page is requested by the Registration Server, the page extracts the reference from the Authentication Token and uses it to retrieve the user ID and email address from local storage. The verification page must be located on the Authentication Service server.

Local Verification Page

A local verification page is located in the Registration Server’s local network, possibly on the same machine. A local verification page does not require access to the user’s data repository (e.g. LDAP server) because all of the information required to verify and complete login are stored within the Authentication Token.

An example of this is provided by the LDAP Authentication example mentioned above. The Authentication Token returned by the LDAP example contains all data needed to verify and complete login in an encrypted form.

This has the advantage that the Registration Server does not have to connect to the Authentication Service to verify the Authentication Token which may not be possible due to firewalls or for performance reasons.

However, this means that each Authentication Service used must provide a corresponding verification page which can be installed in the Registration Server network. Installation is done by the Registration Server administrator.

Note that a local verification page must be implemented in PHP. Other server-side technologies are not supported in order to keep the Registration Server installation as simple as possible.

Login Procedure

The diagram below illustrates 9 steps that constitute the login procedure. Each step is described in the sections that follow.

TeamDrive_LoginProcedure_png

TeamDrive Client: Load Registration Server Redirector URL

When the embedded browser-based login panel is displayed, the TeamDrive client loads the redirector URL of the Candidate Provider with the URL parameters: page and distr. page is set to “login” and distr is set to the Candidate Provider’s Provider Code.

Registration Server: Re-direct to AUTH_LOGIN_URL

The Registration Server redirects the client’s embedded browser to the AUTH_LOGIN_URL. Access to this page must use the secure HTTP protocol (https).

Authentication Service: Generate Login Page

The HTML of the login page is generated and returned to the client by the Authentication Server. The page includes an HTML form with standard fields to gather the user’s credentials and perform login.

The HTML form must include the following hidden fields which are evaluated by the TeamDrive Client:

  • td_login_page:

    For example: <input type=”hidden” id=”td_login_page” value=”login”/>

    This field tells the client which page has been loaded. Possible values are “login”, “register” or “lostpassword”. The TeamDrive Client will switch the login panel accordingly. In this way, the correct title and buttons will be displayed in the login dialogue.

  • td_registration_server:

    For example: <input type=”hidden” id=”td_registration_server” value=”TeamDriveMaster”/>

    This field specifies the name of the Registration Server that must be called to complete the login process. This value is actually only needed if the user manually enters an URL in the embedded browser for the login dialogue. Normally this information is redundant because when the TeamDrive Client loads the page, it has already determined the Candidate Provider and hence the Registration Server.

  • td_distributor_code:

    For example: <input type=”hidden” id=”td_distributor_code” value=”EGCO”/>

    This field specifies the Provider of the Authentication Service. Just like the td_registration_server field above, this field is only required if the user manually enters a URL into the embedded browser in the login dialogue.

    It is recommended that the login page contain elements that make it identifiable as belonging to the Provider. For example by using a logo associated with the Provider.

    This is required because it may not be obvious to the user where he has landed, due to the fact that the identification of the CandidateProvider is transparent to the user. In particular, identification of the Candidate Provider using the current IP address of the client can lead to the user being presented a different login dialogue depending on where the TeamDrive Client is started.

TeamDrive Client: Display Embedded Login Page

The TeamDrive client displays the HTML page received from the Authentication Service.

When the page is loaded, the client also reads the 3 hidden fields described above: td_login_page, td_registration_server and td_distributor_code. Depending on the value of td_login_page the client will switch to the appropriate login panel.

If the td_distributor_code is set, it may change the Candidate Provider, and is used later, along with the specified Registration Server to complete the login (or registration) process.

Authentication Service: Authenticate User Credentials

When the user clicks the login button, control returns to the Authentication Service’s web-site. The target page is determined, as usual, by the page specified in the HTML <form> tag.

The Authentication Service then checks the credentials submitted by the user. If an error is encountered, the web-site should return the login page with an appropriate error message.

If the credentials are valid, the returns a page with a message indicating success. As shown in the Authentication Examples (see Authentication Examples), the result page should also indicate that login is now being processed by the Registration Server.

On success the page must include a form with the following hidden fields:

  • td_authentication_token

For example:

<input type="hidden" id="td_authentication_token" value="<?php echo $authToken; ?>"/>*

The authentication token as describe in Authentication Tokens and Verification Pages.

  • td_authentication_cookie

For example:

<input type="hidden" id="td_authentication_cookie" value="<?php echo base64_encode($authCookie); ?>"/>

The authentication cookie is stored by the client. You can store any information you like in the cookie and encrypt the data for security reasons. The cookie is returned by the client when they access the Authentication Service again.

The cookie should be used to pre-fill the username field when a user is required to re-login. For this purpose it is recommended to store information in the cookie that can be used to identify the user (for example, the user ID).

  • td_user_secret

For example:

<input type="hidden" id="td_user_secret" value="<?php echo $userSecret; ?>"/>

This field is require to support automatic distribution of Space keys to all devices of the user. In other words, when a user creates or enters a Space on one device, the “user secret” makes it possible to pass this information securely to all other devices belonging to the user. In particular the access information can be passed securely to devices that are registered later (i.e. devices unknown at the time of Space entry).

The facility used to do this is the Registration Server Key Repository. When enabled, then TeamDrive Client stores the Space keys in the Key Repository, encrypted with the user secret. This also acts as a backup for the user’s Space keys.

The user secret is optional, but without it, the Key Repository is not used and the user must explicitly invite himself to new Spaces in order that they are available on other devices of the user.

Note that the user secret is only stored on the TeamDrive Client. In particular, it is not passed to the Registration Server, as this would constituted a security risk (because both encrypted the Space keys and the means to decrypt the keys would be located in the same location).

For additional security, the client does not use the user secret as is. Instead it uses a salted SHA256 hash value of the user secret.

Changing the user secret of a user is discussed in the section below.

  • td_alt_user_secret

For example:

<input type="hidden" id="td_alt_user_secret" value="<?php echo $altUserSecret; ?>"/>

This field is optional. It is used to transition to a new method for generating the user secret. In order to do this, then original user secret value of a user should be returned as the td_alt_user_secret value, and the new user secret returned as td_user_secret.

Note that the TeamDrive Client version 4.5.5 is required for a problem free transition as this is the first version of the Client that handles the td_alt_user_secret value.

Changing the user secret for a user initially does nothing. Only when the user logs in (either by re-login on an exiting installation, or when a new TeamDrive installation is done), does the new user secret have an effect.

In the case of a re-login, the client will re-encrypt all Space keys with the new user secret and upload them to the Key Repository. In the case of a new installation, if td_alt_user_secret is available, then the Client will be able to read the Space keys from Key Repository, decrypt them using the “alt user secret” and encrypt and upload the keys using the new user secret.

If td_alt_user_secret is not specified, or the TeamDrive Client is pre version 4.5.5 then the Client will not be able to access the Key Repository and none of the user’s current Spaces will be available. In addition, Spaces created in the new installation will not be available to old installations until the old installation perform a re-login.

A re-login can be forced by the Administrator using the “Invalidate Password” button on the user details page in the Admin Console, or by providing a value for the AUTHSERVICE/AUTH_VERIFY_PWD_FREQ Provider setting (see AUTH_VERIFY_PWD_FREQ).

However, there are still cases when the user can loose access to his Space keys if the td_user_secret value is not used to transition to a new user secret.

Authentication Service: User Profile

The result page may also include the following fields which are used to set the user’s profile:

  • td_profile_name Set the actual name of the user.
  • td_profile_email Sets the email address in the user’s profile.
  • td_profile_telephone Sets the user’s telephone number.
  • td_profile_mobile Sets the user’s mobile phone number.
  • td_profile_notes Sets the notes field in the user profile. This field may contain any additional information you wish to distribute regarding the user.

TeamDrive Client: Process Result Page

The TeamDrive Client displays the result page returned by the Authentication Service. If the page contains the td_authentication_token then the client assumes that authentication was successful and sends a secure login message to the Registration Server. The login message includes the Authentication Token and the Provider Code of the Candidate Provider.

Other data returned by the Authentication Service is retrieved from the hidden fields in the page and stored locally. This includes the authentication cookie (td_authentication_cookie), the user secret (td_user_secret), and any profile data sent by the service.

The login dialogue is disabled while the TeamDrive Client waits for a reply from the Registration Server.

Registration Server: Verify Authentication Token

The Registration Server receives the login message from the TeamDrive Client. Using the URL specified by the VERIFY_AUTH_TOKEN_URL setting (see AUTH_VERIFY_PWD_FREQ) it verifies the Authentication Token. The Authentication Token is added as a parameter to the URL with the name “authentication_token”.

Authentication Service: Execute Verification Page

The page referenced by the VERIFY_AUTH_TOKEN_URL setting is called the “verification page”. This page verifies the Authentication Token sent by the Registration Server. Further details on how the verification page works are provided in Authentication Tokens and Verification Pages.

The verification page is expected to return the following XML result upon encountering an error:

<?xml version='1.0' encoding='UTF-8'?>
<teamdrive>
        <error>
                <message>ERROR_MESSAGE</message>
        </error>
</teamdrive>

The ERROR_MESSAGE text will be printed to the Registration Server log, but not returned to the client. Instead the client will display a generic message indicating that authentication failed.

On success, the verification page must send a reply of the following form:

<?xml version='1.0' encoding='UTF-8'?>
<teamdrive>
        <user>
                <id>USER_ID</id>
                <email>USER_EMAIL</email>
        </user>
</teamdrive>

Here USER_ID and USER_EMAIL are the values as described in External User Data.

Registration Server: Complete Login

The Registration Server evaluates the XML result sent by the verification page. In general, an error is not expected unless the system has been compromised somehow.

The user ID returned by a successful verification is stored in the ExtReference field in the TD2User table in the td2reg database.

Before inserting a record into the TD2User table, the Registration Server checks to see if a user with the given user ID is already present. In this case the user’s email address is updated and success is returned to the TeamDrive Client.

If the user ID is not found a new user record is created. Internally, the Registration Server generates a so-called “magic username” for the user. This username is of the form $DISTCODE-USERCOUNTER, for example: $EGCO-1234.

Magic usernames are never visible to the TeamDrive Client user. Instead, the users e-mail address is used whenever the username would otherwise be displayed or used in the client.

Note

An error will be returned to the client, and login will fail, if the user’s email address is already in use by some other user.

External Authentication for Agents with a Webinterface

A TeamDrive agent using a webinterface can be configured to use an external login page by setting the http-api-external-login-url client setting to the URL of the page.

WebInterface Login Procedure

The webinterface will embed the specified page in an <iframe>. Once the user has logged in, the login page must use a javascript postMessage() call to send the authentication token to the TeamDrive webinterface/agent (ie. the “parent” page of the iframe).

An example of how to set this up is given in “ldap_agent_login.php”.

Important

postMessage() calls must specify the exact host of the page that is expected to receive the call (<protocol>://<host>:<port>). Failing to do this can result in the authentication token being stolen. See the section below for a way to safely send the postMessage() calls.

Specifying the right host for the postMessage() call

The external login page must be set up so that postMessage() calls will only be sent to “whitelisted” hosts. The way this works:

  • The webclient, when loading the login page into the iframe, will append a URL parameter referrerUrl, which contains the base 64 encoded host of the agent (<protocol>://<host>:<port>). For example, this might be “http://localhost:45454”, “http://internalserver.net:4321” or “https://webportal.com:443
  • The external login page verifies that this parameter is included in the pre-configured whitelist set by $agent_origins in “ldap_config.php”
  • Once the user has logged in, the authentication token can be safely sent to the specified page

An example is given in “ldap_agent_login.php”.