Authentication

The TeamBeam server has builtin support for user management and authentication. For corporate customers, TeamBeam can relay verification of credentials to an external LDAP directory. In addition, TeamBeam accepts pre-authenticate tokens from Skalio ID. Handling of the different concepts is described below.

Built-in Authentication

Users are identified by their registered email address. TeamBeam stores a password hash for each internally authenticated user. Users provide credentials, consisting of email and cleartext password, to the Auth-Login resource. If the credentials are verified, the resource creates a new HTTP session and assiociates it with the user. The response instructs the client to store a session cookie, which is to be sent by the client with each HTTP request.

A session is valid for a specific amount of time, after which it expires, and authentication must be re-established. Sessions may also be dropped server-side prior to this. Clients are invited to implement graceful re-authentication.

LDAP Authentication

The flow is identical to the built-in Authentication, with the following difference:

  • Users are searched by their email address, but identified by their distinguished name (DN), a text-based, hierarchical unique identifier used in LDAP directories. The DN is obtained by searching the remote LDAP directory for the given email address. Both email and DN are stored in the TeamBeam database.
  • Using the DN and the cleartext password, authentication is forwarded to the remote LDAP directory. An LDAP Bind operation is attempted. If it succeeds, the given credentials are considered valid, and the session is established like above.

Skalio ID

This flow requires the person to have signed up at Skalio ID TODO: clarify teambeam subscriptions and possibly have a subscription for TeamBeam. Skalio ID identifies users by a alphanumerical unique ID. Users can register multiple email addresses via which their account can be found. Users can register multiple authenticators, such as password, TOTP, SMS, etc. Skalio ID also supports delegating the authentication to established external identity providers such as Apple and Google.

Users provide credentials to Skalio ID and, if verified, receive in return a JSON Web Token, called ID token. The token contains clear-text readable elements that describe the user, but are tamperproof thanks to a cryptographic signature. ID tokens are valid for a relatively long time and must be stored in a secure manner. The token contains:

  • unique ID
  • primary email address
  • locale
  • timezone
  • validity of the token

This ID token is accepted at TeamBeam at the Auth-Access resource. Once validated, TeamBeam will issue a short lived JSON Web Token, called access token. This represents the previously used session. Clients are to send the access token in the Authorization header with each request. An access token describes its own expiration time, but cannot be blocked or expired server-side.

When using access-token based authentication on the web-browser platform, it is recommended to request the access token as a cookie (API, with cookie=true). As a result, the web browser will automatically send the cookie when making the download-request. This authenticates the GET request without having to insert a Authorization header.

Image

Internal implementation

The TeamBeam server implements authentication checks using a series of filters that each request goes through. They support both optional and mandatory authentication.

  1. BlockDuringMaintenanceFilter: Terminates request early, if the server is set into administrative or forced maintenance.
  2. BlockBadStoragehostFilter: Matches the HTTP request host against a TeamBeam storagehost. If none is found, or it is disabled, the request is terminated.
  3. AuthenticationByTokenFilter: If an access token is found (header or cookie), it is validated and the SecurityContext of the request is populated with a SkpPrincipal representing the user of the access token.
  4. AuthenticationBySessionFilter: If the SecurityContext contains a SkpPrincipal, the filter lets the request pass through. Otherwise it searches for a session cookie and the matching session. From the session data it extracts the authenticated user and populates the SecurityContext with a matching SkpPrincipal.
  5. AssertValidUserFilter: This filter is activated by the @RequireValidUser annotation and enforces mandatory authentication. If active, it aborts requests whose SecurityContext does not contain a SkpPrincipal.
  6. AuthenticatedUserRateLimitFilter: If the SecurityContext contains a SkpPrincipal, a rate-limit bucket for the referenced user is fetched (created if necessary) and a drop is added. If the bucket flows over, the request is aborted with a rate-limit exception.

API endpoints can use the injectable CurrentUserProvider to obtain an instance of the UserDAO representing the authenticated user. Note that the response may be null, if the request is not authenticated.