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://esuomi.fi/suomi-fi-services/digital-authorizations/?lang=en>.
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:
Object => (gives) => Authorisation => (is received by) => Subject
The Subject is authorised to act on the Object's 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.
For normal applications and services, it is recommended to use Object and Subject types "user" to authorise from one identified account to another identified account.
For external services integrating with onePortal more flexibly, the common use case is to use Object and/or Subject type "string". In these cases onePortal does not know, nor does not care what the strings are, and what they mean. The external service or application takes ful responsibility of this meaning.
How Authorisations are accessed and used by applications and services?
Authorisations have their dedicated REST end-point. They can be used:
- by Management API Client via the Management API, and
- with Access Token by the signed-in user account.
There is also a Management UI interface for Authorisations for mostly administrative use.
REST API end-points
The REST API end-points are as follows:
As the API subject for improvements, the above may not be up to date.