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 serverAuth_Container_KADM5
– Authenticate against a Kerberos 5 serverAuth_Container_POP3
– Authenticate against a POP3 serverAuth_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 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”.