Authorization#

This chapter deals with the concept of identifying a person using the service, and granting it access to parts of the managed data.

Authentication#

Spaces relies on Skalio ID for authentication purposes. After successful authentication, Skalio ID issues the user a long-lived ID token. This token is accepted by Spaces for authorization purposes.

Authorization#

Providing a valid ID token, a person can request an access token for different parts of the service. An access token is short-lived (10 minutes) and must be refreshed as necessary. It holds everything that is necessary for the (part of the) service to evaluate the authorization of the request.

Access tokens are issued per space.

Creation of a new space is authorized with the ID token.

Fetching the list of spaces a person can access is authorized with the ID token.

Secure spaces#

An individual space can be marked as secure, which affects who can access it. In order to access a secure space, the ID token of the person must have an authLevel claim with a value higher than 1.

This value is set by the identity provider based on the authentication methods. For example, using multi-factor authentication will result in authlevel: 2.

The authLevel is required when creating a secure space as well as enabling or disabling the flag on an existing space.

Token submission#

Unless explicitly stated, every request to the server requires the access token to be provided. The server expects the token in the Authorization header as a bearer token. Example:

> GET /spaces/v2/58zsr0j5-_lt_xjc HTTP/1.1
> Host: spaces.skalio.net
> Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJzdWIiOiI1MzNoMTgueWdndXZfYl8wIiwiYXVkIjoiaHR0cDovL3NrYWxpby5jb20vc3BhY2VzIiwiaXNzIjoiaHR0cHM6Ly9za2FsaW8uY29tIiwiaHR0cDovL3NrYWxpby5jb20vc3BhY2VJZCI6IjU4enNyMGo1LV9sdF94amMiLCJleHAiOjE1ODgwODI3MDcsImh0dHA6Ly9za2FsaW8uY29tL3ByaXZpbGVnZSI6ImFkbWluIn0.fzWxzset4EXCvLxlKa9nRrMDYQjc_kBCp_ejLX3LeQon31d3gT3W2O_a7_hnpD0j9as0xGyob-7NefE0mvWTjA
> Accept: */*

In specific cases, the access token may be accepted as a query parameter or as a cookie. Check the API documentation for more information.

Flow#

Image

JSON Web Tokens#

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

Access tokens for Spaces must address the audience (aud claim) http://skalio.com/spaces.

Access tokens for spaces contain additional information in public claims:

  • http://skalio.com/spaceId: The public ID of the project space that the token refers to.
  • http://skalio.com/privilege (read, write, admin): The privilege with which the principal can access data in the space. Higher privileges include lower privileges.