External Authentication¶

Authentication Service Installation¶

An authentication service can be deployed on most Linux systems that supports Apache and PHP 7.3 or later. All TeamDrive implementations have been tested on CentOS 7/8 and therefore this is the recommended system.

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.

Install the External Authentication Service package as described in Installing the Registration Server External Authentication (optional). This package is also installed on the TeamDrive Registration Server Virtual Appliance (in directory /var/www/html/authservice), however, for security reasons, an authentication service should not be run on the same host as the Registration Server.

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.

Configuration and Setup¶

After installation duplicate the “*_config.php.example” file of the service you wish to use, and rename it to “*_config.php”.

You must set the following configuration parameters: $service_name, $reg_server_name, $provider_code and $allowed_origins that are common to all authentication service (see below for details of these settings).

Below these settings you will find a section of settings that are specific to the type of service, LDAP, OAUTH2, etc. Set these parameters as required by your service. Detailed comments in the config file describe what is required for each parameter. For AD/LDAP setup, see :ref:ldap_parameters for further details.

When the service name has been determined, and other settings such as Registration Server and Provider, you must register the Authentication Service on the Registration Server. This must be done before you can test the service because when called for the first time the authentication service will attempt to verify the existence of the service on TDNS (the TeamDrive Name Server).

To register an authentication service you must enter 2 URLs: the Login URL and the Verify URL. The Login URL must reference the “_login.php” page of your service, and the **Verify URL* must reference the “*_verify.php” page of your service. See Services for more details on how to registered an authentication service.

The Login URL is the start page or user’s using the authentication service. For testing purposes you can call this page directly from the browser. During TeamDrive login the page will either by embedded in the TeamDrive client or, the user will be redirected to this page from the Web Portal (for example).

On successful login, this page issue an “Authentication Token” which can be verified by the Registration Server using the Verify URL. For testing purpose, set $enable_debug = true in the configuration file, and you will then be able to check the verification page, ater login. But, remember to remove this debug before you system goes live!

Standard Configuration Parameters¶

There are a number of configuration parameters that are common to all authentication services:

• $service_name: This must be set name of the Authentication Service as described in Services.

• $enable_debug: Places links in the login page which allow you to retry login and provide a link to test the authentication token generated.

• $reg_server_name: Set this parameter to the name of your Registration Server.

• $provider_code: This is the Provider code of the Provider associated with this external login service.

• $allowed_origins: This setting is an array of URLs, that are the permitted origins for calls to the External Authentication Service. In other words, this is a list of URLs of all systems that call the service.

  The TeamDrive client or Web Portal (or other system) which calls the authentication service must specify a “referer” URL, which is checked against this list. If it is not in the list, an error will occur. After login, the browser is re-directed back to the referer page.

  Note that older version of the Web Portal did not provide this information. In this case, the first URL in the $allowed_origins list will be assumed to be the origin of login requests from the Web Portal, and after login the browser will be re-directed back to this URL.

• $webportal_domain: This setting is deprecated, and is no longer used. When upgrading to the latest version of the LDAP authentication service, copy the value of this variable to the position of the first URL in $allowed_origins (see above) array.

• $prev_user_secret_ver: This variable need only be set when upgrading from a previous version of the LDAP authentication service. In this case, you need to maintain compatibility with previously used versions of the user secret. In order to do this, set the variable to one of the following:

  • “v2”: user secret generation v3 will be used, and clients that previously used v2 will be ugraded.

  • “v1”: user secret generation v3 will be used, and clients that previously

    v1 will be ugraded.

  • “v2,v1”: user secret generation v2 will be used, and clients that previously

    v1 will be ugraded.

  Please call TeamDrive for support for advice when upgrade you LDAP external service, if you are unsure which value to use.

  If this is a new installation, then leave this value empty, and user secret generation v3 will be used. This is the most secure version of user secret generation which uses the SHA256 HMAC algorithm.

• $user_secret_salt: This random sequence of characters must be unique for each installation. Once set, this value may never be changed again. It is also important that this value remain secret at all times as it is used to generate the, so-called, “user secret” value, which is used to encrypt the user’s key repository stored on the Registration Server.

  On installation, leave this value blank, as found in the *_config.php.example file. The value will then be automatically set to a 54 character random sequence when first used.

  Changing the value will result in the user not being able to access their key repository, which means that the user will not have access to their spaces after a new TeamDrive installation.

  However, access can be restored for the new device if the user has an old device and performs a re-login (which can be initiated from the Admin Console for a user). 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 of characters is used as a key to encrypt the authentication token sent to the client. The value must be unique for every installation.

  On installation, leave this value blank, as found in the *_config.php.example file. The value will then be automatically set to a 54 character random sequence when first used.

  This string may be changed at any time since authentication tokens are only valid of a short time.

Authentication Service Customisation¶

You may change the user interface of the authentication services provided by TeamDrive by modifying the layout and content of the following files:

• /authservice/*/index.html: This is the default page, which redirects to *_login.php by default.
• /authservice/*/*_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).

Note that 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. As a result, make sure that you make a backup of these files before performing an upgrade.

Example Template Authentication¶

The “example authentication service” implementation provided can be used as a template to create your own External Authentication Service.

The example implementation stores the login names and email address of user in a text file. A page, “eg_register.php” may be used to create example users for testing the implementation.

Before beginning your customisation, make a copy of the “eg” directory, and replace the prefix for all files, for example, change “eg_* to “myco_*” to create an Authentication Services for “My Company”. Internal reference to pages like <form action="eg_login.php" method="post" enctype="multipart/form-data"> must also be changed accordingly.

The functions in “eg_functions.php” must be customised for your system. For example, replace the implementation of getUserByLoginName() with code that retrieves users of your authentication system.

The file “eg_config.php”, contains the configuration parameters that are required by all External Authentication Services. This file is created by duplicating the “eg_config.php.example” file and renaming it to “eg_config.php”.

Configuration parameters include “$service_name” which must be set to the name of the service. The other parameters are documented in detail in the file “eg_config.php.example” file.

Add your service specific parameters to your own “myco_config.php.example” file, and set them as required in your services “myco_config.php” file. You should do this by replacing the “EXAMPLE PARAMETERS” section in the config file.

Ext Auth ID¶

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

The Ext Auth ID may be any character sequence up to 100 characters in length. The character sequence used as the Ext Auth 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 Ext Auth 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 Ext Auth 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 Ext Auth ID, but there are situations in which a company may want to change a user’s email address.

In general, if the Ext Auth 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 Ext Auth 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 below.

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 Service Implementations.

TeamDrive Client: Enter Username/Email¶

The user enters there their username or email address in the first pannel of the login dialog. The client send this information in the “prelogin” call to the Registration Server.

Registration Server: Re-direct to Login URL¶

The Registration Server looks up the user and determines if external authentication is required. If so, the server returns the Login URL of the service to the client.

Authentication Service: Generate Login Page¶

The HTML of the login page is generated and returned to the client by the Authentication Service. 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 Service Implementations), 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 must be prefixed by the authentication service name as follows:

<auth-service_name>~<encrypted_token_data>

• 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 Ext Auth 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 Verify URL of the authentication service, 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 authentication service Verify URL page verifies the Authentication Token sent by the Registration Server. Further details on how the verification page works are provided in Configuration and Setup.

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>
        <service>SERVICE_NAME</service>
        <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, and SERVICE_NAME is the name of the external authentication service.

Registration Server: Complete Login¶

The Registration Server evaluates the XML result sent by the verification page. In general, an error is not expected unless there is an error in the implementation or configuration.

The Ext Auth ID returned by a successful verification is used to find the associated TeamDrive user.

If the user is found then login is successful. The email address stored by the Registration Server for the user is update if necessary.

If the user is not found, then the Registration Server searches for a user with the email address provided. If a user is found, then the server checks that the authentication service associated with the user, matches the authentication service being used. If so, the server stores the Ext Auth ID is the user record and login is successful.

If no user is found then a user is created automatically. In this case, the email address provided for the user may not already be in use.