Authentication#

A person can provide valid credentials to authenticate themselves. In return, they receives an ID token. Skalio ID differentiates between local accounts, where the credentials are stored here, and federated accounts, where a trusted external identity provider ensures authenticity of the person.

This page describes local accounts.

Description#

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

• email address
• password
• a second factor, if available

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.

Successful authentication results in an issued ID token. The ID token holds, cryptographically secured, the lifetime, the principal's ID, their organization membership & privileges and some other metadata about the person. It has a long lifetime and must be protected by the holder.

To access services, the ID token is used to obtain short-lived access tokens, which are used to authenticate each API request. Access-tokens are specific to each backend-service.

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.

Session comparison#

TeamBeam no longer uses session-based authentication. Instead, stateless token-based authentication is used.

Feature	Session‑Cookie (stateful)	ID/Access Tokens (stateless)
Where the state lives	Server stores a session record keyed by a cookie sent from the browser.	All authentication info is encoded in the token (e.g., JWT) that the client stores and sends with each request.
Typical flow	Client logs in → server creates session → sends session ID cookie → browser includes cookie on subsequent requests.	Client logs in → server issues short‑lived access token + long‑lived ID token → client stores tokens (access token: in memory; ID token: secure storage).
Session duration vs. token lifespan	Session can be long‑lived (until logout/timeout) and is refreshed on activity. Max duration: 24h Max idle-time: 1h	Access token is short‑lived (10 minutes). ID token is long‑lived (30 days) but used only to obtain new access tokens.
Logout	Server deletes session record from database.	Server adds ID token to revocation blacklist. ID token is barred from future use. Previously issued access tokens remain valid for their short lifetime.
Browser vs. Mobile	Cookies are automatically sent by browsers, but can be vulnerable to CSRF unless protected.	Tokens are explicitly attached (e.g., Authorization: Bearer <token>) to each request, removing CSRF risk but needing careful storage (e.g., secure keychain).
Security concerns	Session hijacking (cookie theft) can give an attacker the entire session for the maximum session duration.	Token misuse (e.g., leaked JWT) is mitigated by short expiry. The signature validation ensures integrity.

Bottom line:
Session cookies keep state on the server and rely on a cookie for identification; they’re simple but need shared storage for scaling, and CSRF can expose the session cookie to bad actors.

ID/Access tokens securely encode state in the client and allow stateless verification, giving better scalability and security at the cost of more complex token handling and revocation strategies.

Passwords#

Passwords are stored in the Skalio ID database as an individually salted bcrypt-hash.

When a person provides a new password during signup or when changing an existing password, the clear-text must fulfill requirements of password complexity in order to be accepted. Using the zxcvbn mechanism, the complexity is calculated and scored from 0 (risky password) to 4 (very unguessable). A password must have a score of 2 or higher to be accepted.

Where available, the mechanism is seeded with contextual information about the person, such as their name and the name of their organization. This can help identify passwords that have a low entropic distance from the person's public details.

The zxcvbn mechanism is a powerful replacement for old-fashioned password complexity rules by testing how easily a password can actually be guessed. As an example, the word Passw0rd! fulfills typical complexity rules, whereas 5fa83b7e1r39xfa8hmiz0 does not. However, it would be hard to argue that the first word provides more security over the second.

While entering a new password, the frontends are guiding the person by showing the password strength live.

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#

To streamline the authentication process, a two-step login flow is suggested:

1. A person enters their 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 their 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, they must join an organization.

Skalio provides a dedicated organization to host all users of the FREE service offering.

To join an organization, a person has different options:

• Sign a contract with Skalio, which will create the new organization and make the person the organization administrator automatically.
• Get invited to an organization, then accept the invitation.
• Join the FREE organization.

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#

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 them 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.

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. 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 client must specify the URL where the token will be posted to. This is intended to protect clients from leaking tokens unexpectedly to insecure locations.
• Unless specified, 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.

Transfer authentication to native app#

Expanding on the concept of transferring a token between hostnames, the pickup-token can be used to transfer authentication to a native app. In this case, the web-application parks the ID token, then redirects the user to a custom scheme which is registered by the native app. The native app then uses the pickup-token to fetch a new ID token for itself.

In this scenario the web-application may choose to keep its session and not blacklist the original ID token. However, the second ID token will have the same expiration time as the original ID token.

It is recommended to secure the token-exchange with the "Proof Key for Code Exchange" protocol (RFC7636).

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.