Authentication#

A person can provide valid credentials to authenticate themselves. In return he receives an ID token.

Description#

A person that has identified itself towards the service is called a principal. This is achieved by providing valid credentials:

Since a person can register multiple email addresses, any of them can be used to identify the person, as long as they have been verified.

The password is compared against the stored hash value.

Successful authentication results in an issued ID token. The ID token holds, cryptographically secured, the lifetime, the principal's ID and possibly other metadata about the person. It has a long lifetime. The ID token grants access privileges to the Skalio ID service. To access other service, it must be exchanged for a service-specific access token.

Image

ID tokens can be blacklisted, rendering them unusable before their actual expiration time (API endpoint).

ID tokens can also be refreshed, whereby the existing ID token is replaced by a new ID token (API endpoint). This is useful when the context of the person has changed, such as organizational membership, and an updated ID token is required reflecting the changes. The expiration time of the original ID token is transferred to the refreshed token, unless the token is upgraded reflecting the account verification status.

Access token#

Most requests must be authenticated with an access token. These are short-lived JWTs, typically with an expiration time of 10 minutes. A valid ID token must be presented to obtain an access token, see the API endpoint.

Access tokens cannot be revoked.

Two-step login#

In order to streamline the authentication process, a two-step login flow is suggested:

  1. A person enters his email address.
  2. The client queries the API if the email address belongs to a user (API endpoint). The response contains two pieces of information:
    • The user is known by Skalio ID, or not.
    • If known, it names the identity provider that can authenticate the person.
  3. Depending on the response, the client offers different screens:
    • Email address does not exist: show sign-up screen, where the person can register his credentials (API endpoint).
    • Email address is known, account is managed by Skalio ID: show password & 2FA screens, authenticate person with credentials.
    • Email address is known, account is managed externally: inform user to authenticate via the external identity provider, e.g. Google or Apple.

Organization membership#

Organizations represent the contractual partners of Skalio. They own and are responsible for all data of their users. Before a person can use a product or service, he must join an organization.

In order to join an organization, a person has different options:

  • Create their own organization (API endpoint), implicitly making them a member of it with admin privileges.
  • Accept an invitation to join an organization.

Skalio provides a dedicated organization to host all users of the free service offering. After signup, a person can join the organization using a static invitation.

List of issued tokens#

An authenticated person can request the list of ID tokens that have previously been issued. Skalio ID tracks these tokens for informational purposes and provides the following metadata:

  • unique transaction id (jti), used to identify a token
  • timestamp of creation and expiration
  • useragent and public IP address of client that created the token

This list allows a person to get an overview of ongoing "sessions", and to deauthenticate a specific token.

The actual token itself is not recorded, and as such this list is not used for token verification. Also, it does not pose a security risk, since this information cannot be used to gain access.

Password recovery#

In order to recover a lost password, a person can request a password reset:

  1. User provides email address.
  2. Service looks up person by email address. If the address is not found, or has not been verified, the request is rejected.
  3. Service sends an email message to the requested address, containing a link to complete the password reset. The link is only valid for a short timeframe.
  4. User opens link and enters a new password.
  5. Service sends an email message to all registered verified addresses, informing them of the password change.

The service does not store passwords in a recoverable form.

Two-factor authentication (2FA)#

A person has the option of registering multiple two-factor authentication methods. Once successfully registered, authentication must include 2FA.

Supported 2FA methods:

  • TOTP based "authenticator apps"
  • Recovery code

Not yet supported methods:

  • One-time keys, delivered via SMS
  • FIDO U2F hardware authenticator
  • App-based authenticator

Deauthentication#

An authenticated person can choose to terminate the validity of an ID token by de-authenticating. This is commonly called "user logout".

The request for deauthentication itself must be authenticated with a valid ID token. The person can choose to deauthenticate the current session ("self logout"), or blacklist another token that had been issued for him in the past, by referencing its unique jti transaction id.

The jti of the token is recorded in a blacklist. Future attempts to use the token will be rejected. This action is distributed across all remote services.

Image

Transfer token between hostnames#

An application that runs within the constraints of a web-browser is restricted by the browser's sandbox and cross-domain protections. The LocalStorage is domain-bound; read- or write-access from a different domain is prohibited, even if it is a subdomain.

If the same web-application is available across multiple domains (for example to provide different styling/branding), a person may attempt to login at the "wrong" location and needs to be relocated to the "correct" domain. In order to transfer the ID token to the new domain, it can be "parked":

  1. example.org: park ID token at Skalio ID, receive a single-use pickup-token (API)
  2. example.org: redirect to domain "customer.org" including the pickup token in the URL
  3. customer.net: pickup parked ID token from Skalio ID, authenticating with the pickup token (API)
  4. customer.net: persist ID token in LocalStorage

This protects the powerful ID token from being exposed in an HTTP redirect. Note:

  • The original ID token is blacklisted and can no longer be used, once it has been parked.
  • The pickup token has a very short validity of one minute. It can only be used once.
  • During pickup, a new ID token is created, and if circumstances have changed in the meantime, this will be reflected in the values of the token claims. Only the validity is transferred from the original ID token; it is not possible to extend the validity of a token by parking/retrieving it.

Image

UID token#

A valid ID token can be used to request an uid token. This token has a long lifetime, cannot be revoked, and is used only to detect a user at otherwise unauthenticated requests. The uid token can be provided as a cookie or a URL query parameter.