Tokens#

Types#

ID token#

The Skalio ID service issues a long-lived ID token after successful authentication of a person. The token is in the format of a JSON Web Token. There is no limit on the number of ID tokens that can be issued for one person.

The ID token has scope idtoken.

Example:

{
  "iss": "http://skalio.com",
  "sub": "ftv_lknlywsmmmfn",
  "aud": [
    "http://skalio.com/id",
    "http://skalio.com/skp",
    "http://skalio.com/drive"
  ],
  "iat": 1700745292,
  "jti": "z-qigy1kl9xygu8l",
  "ver": "3.0",
  "scope": "idtoken",
  "locale": "de-DE",
  "zoneinfo": "Europe/Berlin",
  "roles": [
    "Organization.Admin"
  ],
  "http://skalio.com/org_id": ".mzlig7-009iduhl",
  "email": "b9307fef-709e-4d6b-94bf-a5d7ae44d119@example.org",
  "amr": [
    "pwd"
  ],
  "email_verified": true,
  "http://skalio.com/auth_level": 1,
  "exp": 1703337292
}

An ID token from an interactive login is valid for 30 days, and lists all services in the aud claim. If the person has not yet verified their email address, the ID token is valid for one day only.

Note: older versions of the API may issue ID tokens with slightly different format. Example, older API version 2:

{
  "iss": "http://skalio.com",
  "sub": "9zpwrohd45ljlqy0",
  "aud": "http://skalio.com/id",
  "iat": 1693564174,
  "jti": "ds6kdg7xa316pgvc",
  "ver": "2.0",
  "scope": [
    "idtoken"
  ],
  "http://skalio.com/org_units": "[ {\n  \"uid\" : \"desc754-xc863v6y\",\n  \"privilege\" : \"admin\"\n} ]",
  "locale": "de-DE",
  "zoneinfo": "Europe/Berlin",
  "email_verified": true,
  "roles": [
    "desc754-xc863v6y:Organization.Admin",
    "desc754-xc863v6y:Service.Transfer.Use"
  ],
  "http://skalio.com/auth_level": 1,
  "exp": 1696156174,
  "email": "hank+novospace@pray4snow.de"
}

ID tokens from non-interactive authentication#

Skalio ID also issues ID tokens in exchange for a personal API token or a delegation grant, see non-interactive authentication. These ID tokens differ from interactively obtained ones:

  • They are valid for 24 hours.
  • The aud claim lists only the audiences of the personal API token or grant.
  • The amr claim names the credential: http://skalio.com/pat or http://skalio.com/grant. It contains mfa only if a second factor was provided when the personal API token was created; never for a grant.
  • ID tokens minted from a grant contain the claims http://skalio.com/purpose and, if set, http://skalio.com/target_ref.

Example, minted from a delegation grant:

{
  "iss": "http://skalio.com",
  "sub": "ftv_lknlywsmmmfn",
  "aud": [
    "http://skalio.com/drive"
  ],
  "iat": 1793956801,
  "jti": "k2c9-xw0q7a1lmz4",
  "ver": "3.0",
  "scope": "idtoken",
  "locale": "de-DE",
  "zoneinfo": "Europe/Berlin",
  "roles": [
    "Service.Transfer.Use"
  ],
  "http://skalio.com/org_id": ".mzlig7-009iduhl",
  "email": "b9307fef-709e-4d6b-94bf-a5d7ae44d119@example.org",
  "http://skalio.com/purpose": "forwardMailboxToSpace",
  "http://skalio.com/target_ref": "rn0bx8vdw4k1h6q2tmc9",
  "amr": [
    "http://skalio.com/grant"
  ],
  "email_verified": true,
  "http://skalio.com/auth_level": 1,
  "exp": 1794043201
}

Access token#

In order to use a service, the client must provide the ID token and request an access token. The ID token contains sufficient information about the person and its privileges in order for the remote service to make its grant-decision.

Each service issues their own access tokens, and access tokens can only be used with the service that issued them.

Access tokens typically have a much shorter live time, and clients should automatically refresh tokens on demand.

Web-applications can benefit from having access tokens delivered as a cookie.

The token has scope access.

Access tokens issued by Skalio ID are valid for 10 minutes. They carry over the aud, roles and amr claims of the ID token they were issued for, as well as http://skalio.com/purpose, http://skalio.com/target_ref and http://skalio.com/set_password, if present. A restriction of the ID token therefore applies to the access token as well.

Example:

{
  "iss": "http://skalio.com",
  "sub": "ftv_lknlywsmmmfn",
  "aud": [
    "http://skalio.com/id",
    "http://skalio.com/skp",
    "http://skalio.com/drive"
  ],
  "exp": 1700745892,
  "auth_time": 1700745292,
  "sid": "z-qigy1kl9xygu8l",
  "scope": "access",
  "roles": [
    "Organization.Admin"
  ],
  "amr": [
    "pwd"
  ]
}

UID token#

Skalio ID also issues a shorter uid token, which contains only the unique identifier (UID) of the person. This token has a long lifetime, but very limited authority. To obtain it, a valid ID token must be used. The uid token can be used as an identifier of a person when making otherwise unauthenticated requests. It can be used to track a person across multiple requests, even when the ID token has expired. It can be used as a key for throttling requests per person. It does not authorize requests that modify data, or grant access secure resources.

The token has scope uidtoken.

A uid token is valid for 90 days. It lists all services in the aud claim, and a service accepts it only if its own audience is listed. Unlike other tokens, uid tokens are signed with HMAC-SHA256 (HS256) rather than with the asymmetric key of Skalio ID, which is why they are only used for identification.

Example:

{
  "iss": "http://skalio.com",
  "aud": [
    "http://skalio.com/id",
    "http://skalio.com/skp",
    "http://skalio.com/drive"
  ],
  "exp": 1801732801,
  "sub": "4wly0wmk1.y9e0sy",
  "scope": "uidtoken"
}

Note: uid tokens issued before Skalio ID 5.1 have the audience http://skalio.com/uid and no scope claim. Services continue to accept them until they have expired.

Pickup tokens#

In the context of the OpenID Connect Form-post flow, Skalio ID issues a short-lived pickup-token. It is valid for 5 minutes, and can be used once to complete the flow and obtain the ID token for the authenticated person.

The token has scope preflight.

Example:

{
  "aud": "http://skalio.com/id",
  "sub": "b867_9c_lhdahdx-",
  "scope": "preflight",
  "iss": "http://skalio.com",
  "exp": 1652953134
}

It is also possible to park an ID token temporarily. To retrieve the parked token again, Skalio ID issues a very short-lived, single-use pickup-token with scope park. It is valid for one minute. If the client provided a state when parking the token, it is returned in the nonce claim.

Example:

{
  "aud": "http://skalio.com/id",
  "sub": "rcc5zshe6o3zwl2_",
  "scope": "park",
  "iss": "http://skalio.com",
  "exp": 1652953134,
  "nonce": "25C6BA9C2F87"
}

Checkout token#

When a person purchases a subscription using a Stripe checkout, Skalio ID issues a checkout token. It is valid for 24 hours and authenticates the request that completes the checkout.

The token has scope checkout.

Guest token#

TeamBeam Drive issues a guest token for public access to a Space via a share-link. The token does not identify a person: its subject is a random session ID with the prefix share.. It is issued by TeamBeam Drive, is valid for 10 minutes, and can only be used with TeamBeam Drive. It grants read access to the Space referenced by http://skalio.com/space_id, through the share-link referenced by http://skalio.com/share_id.

The token has scope guest.

Example:

{
  "iss": "http://skalio.com/drive",
  "sub": "share.x7k2m9p4q1w8z3n6v5b0",
  "exp": 1793957490,
  "aud": "http://skalio.com/drive",
  "scope": "guest",
  "http://skalio.com/space_id": "n0vq3k8z1m5x7c2b9w4t",
  "http://skalio.com/share_id": "p6r1y8u3i0o5a2s7d4f9",
  "http://skalio.com/privilege": "read"
}

Note: access to a published Space works differently. TeamBeam Drive issues an access token with scope access and privilege guest, whose subject is guest. followed by the UID of the Space.

Delay token#

This type of token is deprecated and no longer in use.

The token has scope delay.

Multi-Factor Authentication token#

When a person requires multi-factor authentication, a mfa token is issued after successful first-factor authentication. The short-lived token contains scope mfa and a list of available factors the person can use to complete authentication. The subject contains the person's unique id. It is valid for 5 minutes.

The mfa token is used to authenticate the second-factor authentication request.

The token has scope mfa.

Example:

{
  "aud": "http://skalio.com/id",
  "sub": "k7apfcpb.sgz2sb6",
  "scope": "mfa",
  "iss": "http://skalio.com",
  "exp": 1666259895,
  "locale": "en-US",
  "http://skalio.com/authenticators": [
    "totp"
  ]
}

Principal#

An ID token authenticates a specific person. This is called the principal. The token references a principal by his unique identifier.

Token verification#

The tokens are cryptographically signed. The recipient of a token can verify the signature and thus chose to trust the encoded information. Tokens that are used across multiple services employ asymmetric cryptography:

  • An ECDSA private key is used to create the signature. The private key is protected, and only accessible to the service issuing tokens.
  • The matching public key is widely available. The remote service, consuming the token, can use it to verify the signature.

Uid tokens are the exception: they are signed symmetrically, see uid token.

Besides the signature, a service verifies that the token was issued by Skalio ID (iss), and that the aud claim lists its own audience. A token that does not name the service is rejected, as is a token with a missing or malformed aud claim.

Token expiration#

Every token contains an expiration timestamp. When an ID token expires, the person must go through the authentication process again to receive a new token. When access or uid tokens expire, they must be obtained again, using the ID token for authentication.

An expired pickup-token cannot be refreshed. Instead, the client has to initiate the authentication flow again from the beginning.

Tokens issued by Skalio ID have the following lifetimes:

Token Lifetime
ID token, interactive login 30 days
ID token, person has not verified their email address 1 day
ID token, minted from a personal API token or grant 24 hours
Access token 10 minutes
Uid token 90 days
Multi-factor authentication token 5 minutes
Pickup token, scope preflight 5 minutes
Pickup token, scope park 1 minute
Checkout token 24 hours

Scope#

Tokens describe their purpose using a scope claim. Over time, the use of this claim will be extended.

Available scopes:

  • idtoken: The token describes the verified identity of a person and can be used to authenticate against Skalio ID.
  • uidtoken: The token describes the unique ID of a person. Used for identification only, not used for authentication.
  • preflight: The token covers the OpenID Connect authentication and can be used to fetch a Skalio ID token.
  • mfa: The token can be used to authenticate the submission of a second factor during multi-factor authentication.
  • access: The token grants access to resources. It is derived from an ID token.
  • park: The token can be used to retrieve a previously parked ID token.
  • checkout: The token authenticates the completion of a Stripe checkout.
  • guest: The token grants public read access to a Space in TeamBeam Drive via a share-link. It is issued by TeamBeam Drive and does not identify a person.

Deprecated scopes:

  • delay: The token is used in an attempt to rate-limit requests.

Roles & organization membership#

An ID token contains the roles claim, describing the privileges the person has in an organization. A person can have none, one or multiple (distinct) roles in an organization. The claim contains an array of strings.

The following role types are defined:

  • Organization.Admin: can manage details of the organization and its subscriptions
  • Contract.Admin: can manage the subscriptions
  • Contract.Read: can view details of the subscriptions, such as invoices
  • Service.Transfer.Use: can use TeamBeam Transfer, implies Service.Transfer.Create and Service.Transfer.Mailbox
  • Service.Transfer.Create: can send P2P- or Drop-Transfers in TeamBeam Transfer
  • Service.Transfer.Mailbox: can receive Mailbox-Transfers in TeamBeam Transfer
  • Service.Transfer.Archive.CreateRoot: can create root-folders in TeamBeam Archive
  • Service.Drive.CreateSpace: can create new Spaces in TeamBeam Drive
  • Service.All.Use: deprecated, implies all Service.* roles
  • Service.Spaces.Use: deprecated, use Service.Drive.CreateSpace instead

Services may choose to transfer the roles claim into their access token or encode the associated permissions in any other way that the service itself understands.

Version 3.0#

A person can be member of none or one organization. The claim http://skalio.com/org_id contains the UID of the organization the person is a member of, or null if the person is not a member anywhere.

The roles claim contains a list of role types that have been assigned to the person. If the person is not a member anywhere, or if simply no roles got assigned, the claim contains an empty list.

Example:

{
  "http://skalio.com/org_id": "desc754-xc863v6y",
  "roles": [
    "Organization.Admin",
    "Service.Transfer.Use"
  ]
}

Version 2.0#

Each entry consists of the organization UID and the role identifier, separated by a colon.

Example:

{
  "roles": [
    "desc754-xc863v6y:Organization.Admin",
    "desc754-xc863v6y:Service.Transfer.Use"
  ]
}

Token blacklisting#

A person can choose to terminate the validity of an unexpired ID token. This action is commonly called "user logout". As a result of this action, the unique transaction ID of the ID token is blacklisted until the natural expiration time of the token. This information is replicated to all known remote services. See deauthentication for details.

ID tokens may get blacklisted for other reasons as well:

  • Since ID tokens encode privileges of organization members, these tokens need to be blacklisted, whenever the organization membership or assigned privileges change. Examples:
  • A person can selectively refresh or park individual ID tokens, which blacklists them. However, in this process, new ID tokens are issued.
  • For persons authenticating via Microsoft Entra, logging out of a Microsoft session is propagated to Skalio ID. This will blacklist all ID tokens issued from within that Microsoft session.
  • Other federated identity providers, such as Apple or Google, may consider a user's session as compromised, triggering the blacklisting of all sessions of the person.
  • Revoking a personal API token or delegation grant blacklists all ID tokens minted from it. The expiration of a personal API token does not blacklist them.

A blacklisted token must be rejected by all services. Once blacklisted, an ID token can no longer be used to request a service access token.

However, this does not affect the validity of a previously issued access or uid token. It remains valid until its expiration time has passed. Therefore, it is important to balance comfort versus security when choosing the live-time of access tokens.

After an ID token has been blacklisted, the person can obtain a new token through authentication. In some cases, the Skalio ID backend returns an updated ID token directly within the response, using the HTTP header AUTHORIZATION (example: joining an organization).

Authentication levels#

An ID token contains an auth_level claim, indicating the levels of trust a token provides. The auth level is expressed as a numeric integer. The following values exist:

Level Description Purpose
0 Unverified The principal has signed up to Skalio ID, but has not yet verified his initial email address. The token is short lived. The principal is not allowed to interact with other persons.
1 Verified The principal has one or more verified email address. The principal was authenticated using a single factor (typically password).
2 multi-factor authenticated The person has used multi-factor authentication to establish the session.

Note: raising the authentication level does not blacklist the ID token. The weaker ID token remains valid, although a client has an interest to upgrade it as soon as possible.

For ID tokens minted from a personal API token, the level reflects whether a second factor was provided when the personal API token was created, not the current state of the account. ID tokens minted from a delegation grant have level 1 at most.

JSON Web Token#

ID and access tokens are following the JSON Web Token format, as defined in RFC 7519. See jwt.io for more information.

The following information is encoded in the token (called claims in the JWT domain). Every token contains the following information:

  • iss (issuer): A string identifying the operator of the service.
  • sub (subject): A string containing the unique ID of the principal. This is not a human-readable id.
  • exp (expiration): The point in time until the token is valid.
  • aud (audience): The services the token may be used with. A service rejects a token that does not list its own audience. ID, access and uid tokens list one or more of:

    • http://skalio.com/id: the Skalio ID service
    • http://skalio.com/skp: the TeamBeam Transfer service
    • http://skalio.com/drive: the TeamBeam Drive service

    Tokens that are only used within Skalio ID, such as pickup and mfa tokens, list http://skalio.com/id only. Deprecated values:

    • http://skalio.com/uid: uid tokens issued before Skalio ID 5.1
    • http://skalio.com/spaces: access tokens for the Novospace service

ID tokens might contain additional information, see all standard claims here. The following are claims supported by Skalio ID tokens:

  • iat (issued at): The point in time when the token was issued. Fights replay attacks.
  • jti (transaction ID): A unique string used to ward off replay attacks and support blacklisting (aka server-side-session-end).
  • ver (String): The version of the ID token. Valid values are: "3.0" (current), "2.0".
  • locale (String): The chosen locale of the person, separated by a dash, e.g. "en-US".
  • zoneinfo (String): The chosen timezone of the person.
  • name (String): The persons name. Optional; not present if the person did not specify their name.
  • email (String): The primary email address of the person.
  • email_verified (boolean): True if the person's e-mail address has been verified; otherwise false.
  • scope (String): The scope associated with the token. See scopes.
  • amr (Array of String): How the person authenticated, as defined in RFC 8176. Values:
    • pwd: interactive login with a password
    • mfa: a second factor was used
    • http://skalio.com/pat: minted from a personal API token
    • http://skalio.com/grant: minted from a delegation grant
  • http://skalio.com/auth_level (number, >=0): Indicates the level of authentication reached. Higher numbers indicate higher degree of account security.
  • http://skalio.com/set_password (boolean, default false): If present and set to true, the token authorizes the client to set a new user password without providing the current valid password (bypassing the safety check).
  • http://skalio.com/org_units Deprecated (JSON): A list of organizational units, and the privileges that the person has in them.
  • http://skalio.com/oidc_provider (String): Only present, when the account is externally managed. The claim contains the name of the external identity provider.
  • http://skalio.com/org_id (String): Contains the UID of the organization the person is a member of; null if the person is not a member anywhere.
  • roles (Array of string): List of roles the person has been granted. See roles. May be empty, but not null.
  • http://skalio.com/purpose (String): Only present in tokens minted from a delegation grant. Contains the purpose of the grant, e.g. forwardMailboxToSpace.
  • http://skalio.com/target_ref (String): Only present in tokens minted from a delegation grant that is limited to a target, e.g. the UID of a Drive Space. Skalio ID does not interpret it; enforcing it is up to the consuming service.

Access tokens issued by Skalio ID contain additional information:

  • auth_time (number): The point in time when the ID token, which the access token was issued for, was issued.
  • sid (String): The jti of the ID token, which the access token was issued for.

Access and guest tokens for Spaces contain additional information:

  • http://skalio.com/space_id (String): The public ID of the project space that the token refers to.
  • http://skalio.com/privilege (guest, read, write, admin): The privilege with which the principal can access data in the space. Higher privileges include lower privileges.
  • http://skalio.com/share_id (String): Only present in guest tokens. The UID of the share-link through which the space is accessed.

Multi-factor authentication tokens use the following claims:

  • http://skalio.com/authenticators (Array of String): List of authenticator types that are available for the person as a second factor.

Pickup tokens with scope park may contain:

  • nonce (String): The state that the client provided when parking the ID token.

Access tokens for TeamBeam contain additional information:

  • http://skalio.com/hostname (String): The token is tied to a specific hostname.