Authentication and Authorization module

Both SCHEMA api and TESK are capable of receiving HTTP requests that declare a task execution and perform data validation and management, schedule the task and provide handles for the different types of output. However, SCHEMA api extends this flow by introducing an Authentication and Authorization module (will be referred to as auth module for the rest of this documentation).

The main motivation behind the implementation of the auth module is the need for control on the task submission and execution workflow. This control should focus on "who wishes to execute a task?" and "what limitations may affect the task execution?". To that end, SCHEMA api specifies a set of Auth entities that can interact with it and allows for specific operations per user type. Moreover, it implements an Authentication scheme using API tokens. Finally, SCHEMA api provides the ability of defining sets of tasks with specific quotas, under which submitted tasks are grouped (see Contexts in the tasks architecture documentation)

caution

Although, the auth module is enabled by default, it can be disabled. If the auth module is disabled, SCHEMA api will operate without taking into account identities of incoming task requests and perhaps a different authentication/authorization process should be employed on top, to prevent undesired access to the API and the task execution backend.

See Settings for the available configuration variables that can be used.

Authentication

There are numerous flows that can be implemented when it comes to incorporating authentication. One of SCHEMA api's aims, is the provision of simple solutions without preventing the use of more sophisticated external applications. Following this logic, SCHEMA api currently offers authentication through API tokens, with the prospect of supporting more common authentication schemes in the future.

API token

In general, an API token is a randomly generated value that authenticates a specific resource. API tokens must have a specific value domain so that they are sufficiently secure against brute-force attacks. This is controlled by the length of potentially issued tokens, as well as any limitations on the token's dictionary. API token length is commonly expressed by the number of bytes and takes values that are powers of 2, e.g. 128-bytes token, 256-bytes token, etc.

SCHEMA api can currently issue and manage API tokens, which in essence can be random values of either 64, 128 and 256 bytes. The API token is the corresponding hexadecimal representation of any random value that can be represented with the corresponding API token length. Hence, issued SCHEMA api tokens character count is two times the length of the token. For instance, a 64-byte API token could be the following 128-character hex value:

13236ba7dcfd884d4a6c3aea981ec0bbd71e21d281e29cd011a7307b715dbd468c9e00f848ef526c6975d4461220d757e7eae53680b5365e3c1f04c798a7baf4

Auth entities

Auth entities refer to all the different types of subjects that SCHEMA api can determine their identity and enforce restrictions on the operations that they are allowed to make. These are the following:

• Superuser

  This auth entity type can perform the administrative tasks on SCHEMA api, like for example, register application services.

  Currently, no operations are exposed through the API for superusers. Future implementations will include actions that will allow to manage application services and users through the API, as well as monitor API operation.

• Application service

  An application service is a registered auth entity that can create its own users, contexts and manage context participants. In addition, an application service can also issue authentication tokens that match an incoming task request to a specific context and a specific participant.

  Application services operations are limited to managing their namespace; that is managing their users, contexts, participants and issued API tokens. Application services, currently are not modeled to submit tasks - task executions should be requested only by users.

• User

  Users are auth entities that are created, owned and namespaced by a specific application service. Users can submit tasks for execution.

• AnonymousUser

  As AnonymousUsers we refer to any entity that performs a request to the API and cannot be authenticated. This can occur mainly because the entity does not provide any proper authentication credentials, but can also be the case that the auth module is disabled and thus auth-related validation does not take place.

Authorization

Defined auth entities have a range of actions that they are allowed to perform. These are represented in the table below:

Action	Superuser (actions not implemented yet)	ApplicationService	User
Retrieve application services	✅
Create new application service	✅
Update an application service	✅
Retrieve users	✅	✅
Create new user	✅	✅
Update a user	✅	✅
Retrieve contexts	✅	✅
Create new context	✅	✅
Update a context	✅	✅
Retrieve users assigned to a context	✅	✅
Assign a user to a context	✅	✅
Unassign a user from a context	✅	✅
Retrieve context participation API tokens	✅	✅
Issue new context participation API token	✅	✅
Update context participation API token	✅	✅
Revoke context participation API token	✅	✅
Submit a task a execution request	✅		✅
Retrieve submitted tasks	✅		✅
Retrieve submitted task's standard error stream	✅		✅
Retrieve submitted task's standard output	✅		✅

Data flow

The inclusion of the auth module introduces a certain interaction with the API, prior to the submission of tasks. Typically, that is the following:

1. A superuser registers a new application service on SCHEMA api. On registration, the superuser receives an API token that authenticates the registered application service. The application service then is configured to use this API token in order to perform calls on SCHEMA api.

2. A registered application service uses its API token to manage users, contexts, context participants. Initially:

   1. The application service creates a context

   2. The application service registers a user

   3. The application service assigns the registered user to the registered context

   4. The application service issues an API token that authenticates the participation of the registered user to the registered context. The application service hands out the participation API token to the user, so that task submission calls can be performed.

      At this point, with the auth module being active and the provision of a participation API token to the user, the data flow is equivalent to the Tasks data flow.