...

Authorisation

What is an Authorisation?

Authorisations are relations between an object, and a subject. The relation is called Authorisation.

State of Finland has a nice public domain tutorial for this subject on their corresponding service description. They call the service "e-Authorization". You can find the documents here: <https://palveluhallinta.suomi.fi/en/sivut/valtuudet/tekninen-yleiskuvaus>.

The concept

Conceptually authorisations are very simple relations. This simplicity has built-in flexibility and extensibility, which makes authorisations a powerful asset.

The relationship triples is as follows:

The Subject (delegate) is authorised to act on the Object's (principals) behalf or allowed to interact with the Object in some specific way.

Object gives to Subject a right or a permission which the Subject may use to act on behalf of the Object.

The actual meaning for the authorisations are given in the utilising application or service. Below are few simple examples:

  UserAccount-A => Is_parent_of => UserAccount-Z
  UserAccount-B => Is_employee_of => UserAccount-Y
  UserAccount-C => May_sign_for => UserAccount-X
  UserAccount-D => May_represent => UserAccount-W 

Object and Subject types

It is important to note, the Object type may be of type:

• a user account – it is strongly recommended to use users directly as objects,

• a group (with user accounts as members in the group),

• a contact,

• a target, or

• an arbitrary string.

Almost equally Subject type may be of type:

• a user account – it is strongly recommended to use users directly as subjects,

• a group (with user accounts as members), or

• an arbitrary string.

How Authorisations are accessed and used by applications and services?

Authorisations have their dedicated REST end-point. They can be used:

• with Access Token by the signed-in user account (recommended), and

• by Management API Client via the Management API.

There is also a Management UI interface for Authorisations for mostly administrative use.

REST API end-points

The REST API end-points are available on service Swagger at /apidoc3/#/Authorisation

As the API subject for improvements, the above may not be up to dateAuthorisation is a record of someone (the Principal) giving another (the Delegate) the authorisation to perform actions of certain type for a limited time. The ID service serves as a trusted storage of these records.

Type

The authorised action type is defined with a text (String). The content of that text can be anything. The meaning must be agreed between the creator of the Authorisation and the consumers of the Authorisation information.

Principal

Principal is the entity whose authority to perform actions is given to the Delegate. The Delegate will therefore perform the actions on behalf of the Principal.

In the Authorisation API the Principal is also called the Object of the Authorisation.

The Principal can be one of:

• An User account - identified by the User account’s ID

• An arbitrary String - meaning is defined by creator of the Authorisation

• An User Group - identified by the Group’s ID

• A Contact - identifed by the Contact’s ID

• A Target - identified by the Target’s ID

Delegate

Delegate is the entity to whom authority to perform actions is given by the Principal.

In the Authorisation API the Delegate is also called the Subject of the Authorisation.

The Delegate can be one of:

• An User account - identified by the User account’s ID

• An User Group - identified by the Group’s ID

• An arbitrary String - meaning is defined by creator of the Authorisation

Time limitation

Authorisations have a limited lifetime. They come into effect at a specified start time, and remain in effect until another specified end time.

The start time must be specified when creating an Authorisation, or the current time will be used.

The end time can be specified when creating an Authorisation, or alternatively a default time, configured in the Namespace settings of the Delegate, may be used.

The Authorisation is not active until the start time has passed, and ceases to be active when the end time has passed.

Revocation

Authorisations can be revoked before they have expired. They can be revoked either by the creator of the Authorisation, or the Principal of it.

Access

The creator of an Authorisation (an User or a Management API Client) has access to Authorisations they have created. The Principal and the Delegate also have access to Authorisations they are connected to.

Authorisations are connected to a selected namespace upon creation. Often it is the namespace of the Authorisation creator, or the Delegate. This has effect mostly as a restriction to administrator access to the Authorisations.

After expiration or revocation

Authorisations which are no longer in effect will stay in the system until a configured amount of time has passed. After that time they will be purged from the system permanently by an automated system.

Modification (restricted)

Authorisations should not be modified after creation. Instead they should be revoked and another Authorisation be created.

Previously entities with a special permission were allowed to modify Authorisation records, currently only the time limit modification is permitted for such entities.

Deletion (restricted)

Authorisations can be “soft deleted” by entities with a special permission. Such Authorisations are not effective any more, but they remain in the system for auditing. The recommendation is to revoke Authorisations instead.

Sources of Authorisations

The Authorisation system stores Authorisations from different sources.

Authorisations created through our APIs and user interfaces are completely managed by our systems and support all the features.

Some Authorisations may come from external sources and are only partially imported to our system. They may lack some data and actions such as revocation may be ineffective through our APIs. Such authorisations must be managed through the original service.

Authorisation system configuration

Some Authorisation features are adjustable in Namespace settings.

Default validity time

Authorisations without a specific end time will stay in effect from the start time for the length of this duration.

Purge delay time

This configuration controls how long Authorisations are kept in the system after they have expired or been revoked.