Authentication and authorisation

Authentication

Access to the API is granted with an OAuth 2.0 bearer token, a JSON Web Token, sent in the Authorization header of every request:

Authorization: Bearer {token}

Tokens are issued by the identity service, Auth0. A script or integration acting as a named user obtains one with a password sign-in:

curl https://undagrid.eu.auth0.com/oauth/token \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "http://auth0.com/oauth/grant-type/password-realm",
    "realm": "{realm}",
    "audience": "https://cumulus.undagrid.com",
    "client_id": "{clientId}",
    "username": "{username}",
    "password": "{password}",
    "scope": "openid profile email"
  }'

This is one way to obtain a token; any OAuth 2.0 flow Auth0 offers that signs in a user works the same way:

Caller	OAuth 2.0 flow
An application acting for a signed-in user	Authorization code with PKCE
A user of the customer's own identity provider	Single sign-on through an enterprise connection, with any of these flows
A script or integration acting as a named user	Resource owner password, as above

The response carries the access_token and its lifetime in expires_in: reuse the token until it expires rather than requesting one per call.

Tokens represent users

Every token represents a user, and the API takes the caller's permissions from that user. An integration therefore uses a dedicated API user, created in user management like any other user and given only the permissions it needs. Tokens issued to a client rather than a user, through the client-credentials grant, are not accepted. The clientId and realm are provided by Undagrid on request.

Users with single sign-on

With single sign-on to the customer's own identity provider, users are not created by hand. A user of the customer's directory signs in, and the account is created at the first sign-in. The roles follow from the user's group membership in the directory and are synchronised on every sign-in, so a change in the directory takes effect at the user's next sign-in. Where needed, additional rights or roles can be granted on top of the synchronised ones.

Authorisation

Each user holds permissions per tenant. A permission grants operations on an object type:

Operation	Allows
READ	Reading objects, and their history through the object type's history permission
CREATE	Creating objects
UPDATE	Updating the mutable data of objects
DELETE	Deleting objects
COMMISSION	Commissioning devices onto objects
EXECUTE	Running named views

Reading history is granted separately: a user reads the history of assets through READ on assets.history. Permissions are assigned to a user as roles, called permission sets, in user management.

A request outside the caller's permissions is answered with HTTP 403.

The caller's profile and permissions

GET /v1/userinfo

Returns the caller's profile, with the effective permissions resolved from the roles the caller holds in grants, as { "<tenant>:<objectType>": [operations] }. This is the one endpoint without a tenant in its path: it answers for every tenant the caller has access to.