Domains and Services

As of Registration Server version 4.5.1 it is possible to reserve email domains and specify named external authentication services.

The information is stored globally on the TeamDrive Name Server (TDNS), and requires a Registration Server connected to TDNS in order to manage the domains and services.

Domains and Services can be managed by providers using the Admin Console. Registered domains and services belong to a provider, however, a domain can be assigned to an account (see below).

Domains

Domains are valid internet web addresses. In an email address it is the part following the “@” sign.

The purpose of registering a domain is to reserve the domain for a particular provider or account. Once a domain has been registered and activated only users of the associated provider (or account) can use email address with the domain.

By reserving their own domains, companies can control the usage of company email addresses with regard to TeamDrive. Reserving a domain, ensures that users of these email address are managed by a particular Registration Server (TeamDrive is a distributed system consisting of enterprise customer and TeamDrive hosted registration servers), Provider and Account as required.

In particular, reserving a domain, prevents a company email address from being used for a personal TeamDrive account. Conversely, this ensures that companies are able to manage any TeamDrive user’s that are registered with a company email address.

Domain Activation

Providers can register new domains, however, they can only be activated by TeamDrive support. Please contact TeamDrive support to have the domains you have registered activate. TeamDrive support will only activate domains that actually belong to the requesting user. In particular, the domains of email service providers, such as “gmail.com”, “aol.com, “gmx.de”, etc. cannot be reserved, of course.

If you are an account manager, then you can request a domain be reserved from you provider (or Registration Server manager), who will then request activation by TeamDrive.

Registration using a reserved Email Address

A reserved email address is an email address with a reserved domain.

As before, a user can be registered using the TeamDrive client, or the Admin Console. On registration an email and optional username must be provided.

A manager on the Admin Console may not create a user with a reserved email address unless they are a manager of the account or provider that owns the domain. This ensures that users registered on the Admin Console that use a reserved email address will be associated with the correct provider and account.

Changing the email of a user is subject to the same restriction.

When registering with a reserved email, using the TeamDrive client, users no longer need to enter a provider code. This means that they can use the regular TeamDrive client (instead of the Enterprise TeamDrive client which requires a provider code be entered) in order to register.

In the current release version of the TeamDrive client, on initial startup, the program requires users to enter their email address (if the user is already registered they can enter their username instead). If the client recognises the email as a reserved email it automatically directs the TeamDrive client to the required Registration Server.

Registration then proceeds as normal, and the user is added to the associated provider and account if necessary. The license and default depot of the new user are then determined by the policies specified by the provider and/or the account manager.

Services

Services are a new way to manage external authentication services. As soon as more than one external authentication service is to be used per provider you need to used named services.

The names of the services must be globally unique for then entire TeamDrive network. This is ensured by the fact that the details of services is stored on the TeamDrive Name Server.

Services should be associated with one or more domains. This ensures that users that login for the first time, are directed to the correct external authentication service. This authentication service takes priority over an external authentication service that may be specified as the default for all users of the provider (by setting the AUTH_LOGIN_URL, VERIFY_AUTH_TOKEN_URL and appropriate PRE_LOGIN_SETTINGS provider settings).

Whether using named authentication services or a global authentication service, you must set AUTHSERVICE/USE_AUTH_SERVICE to True. However, when using named authentication services you do not have to specify any other global provider settings. In particular, you do not have to set the client settings: enable-login=false and enable-web-login=true (for example) using the PRE_LOGIN_SETTINGS provider setting (as described here: TeamDrive Client Configuration). In order to ensure that the client uses external authentication, these settings are automatically sent to the client.

Service Details

When you create a service you must specify a “Login URL and a “Verify URL”.

These are references to the Web-pages that handle the user login, and the token verification respectively.

TeamDrive provides standard external authentication implementations for: LDAP, Microsoft AD, Vasco IDENTIKEY Authentication, Google Auth2 and Microsoft Azure.

Services such as LDAP and AD access company resources and therefore must be deployed within the corporate network. This is the case, even when the associated Registration Server may be located elsewhere. Security is ensured by exposing on 2 access points: the login and verify URLs. This also allows external authentication services to be customise with the “Corporate Identity” (CI).

Contact TeamDrive support in order to receive assistance in setting up your own an external authentication service.

Upgrading External Services

Existing “unnamed” external authentication services can be upgraded to a named authentication services. This is required if you want to add additional authentication services to a provider.

After installing the PHP code of the authentication service, rename the configuration file: *_config.php.example to *_config.php. All changes you make to the configuration must be made to this file.

In order to upgrade you must use the latest version of the various external authentication implementations. This code has been refactored to make upgrade easier in the future. In particular, code and customised pages have been separated so that future upgrades can be performed easily.

The upgrade procedure is as follows:

  • Configuration: Install the latest version and copy over configuration parameters to the new configuration file. Besides the configuration parameters that are specific to the service, you must ensure that the values $user_secret_salt and $token_encryption_key are correctly copied over to the new configuration file.

  • Encryption Version: The $prev_user_secret_ver parameters needs to be set to v2, unless you are upgrading from a very old version of the external authentication service, in which case this parameter needs to be set to v1. Contact TeamDrive support for assistance if necessary.

    Before deployment the new authentication service must be tested. In particular, you must compare the values returned after successful login with those returned by the current external authentication service. See below for more details on testing.

  • Service Name: Set the $service_name to the new name of the service. This must correspond to the name of service created on the Registration Server.

    When you access the “Login URL” for the first time, then service will check that the $reg_server_name and $provider_code correspond to the actual values of the service.

    You may need to set $tdns_proxy to make it possible for the external authentication service to contact the TeamDrive Name Server.

  • Customise Templates: Customise the *_login.php and *_verify.php pages for you purposes. Be careful to maintain the <?php ... ?> and <?= ... ?> elements in the pages.

Finally you need to add the name of your service to the PREVIOUSLY_UNNAMED_SERVICES provider setting (see PREVIOUSLY_UNNAMED_SERVICES for details).

Once this is done, test the external authentication service in a browser before trying with a TeamDrive client. Setting the parameter $enable_debug to true can help with testing, but be sure to set this back to false before deployment.

You need to verify that the new implementation of the external authentication service returns the same “user secret” value as the previous version.

To do this, compare the result page after login of both versions. Significant are the values of the hidden fields in the page named td_user_secret and td_alt_user_secret. If there is no td_alt_user_secret value in any of the pages, then the td_user_secret must match for all user’s tested.

If there is an td_alt_user_secret value in the page returned by the new version, then this must match with the td_user_secret in the current implementation. In this case td_user_secret in the new page is the new secret which uses v3 encryption.

If there is a match, then the TeamDrive client will be able to access the user’s key repository on the Registration Server. If not, then check the $user_secret_salt and $prev_user_secret_ver configuration parameters. These are the only settings that affect the user secret values returned.