Permalink: https://doc.oneportal.fi/x/E4A8

Introduction

The Authorisations API can be used to manage entity relations regarding to different types of permissions granted to a subject by an object.

The Authorisation entity maps an object entity to a subject entity and adds in an Authentication Type to tell the nature of the permission given. Additionally the authorisation can be defined externally, and in such cases the authorisation entry will have to have the Authorisation Source set to map the authorisation to a specific entity endorsing the authorisation. Authorisation Type could be for example "manage", which could mean that the subject is allowed to manage some things related to the object. The actual, concrete meaning of these types is fully application specific and it is up to the client applications' to interpret them. The same goes for the Authorisation Sources. The description of each Authorisation Type should be detailed enough to avoid any confusion on what the authorisation is about.

The Authorisation objects, types, and sources can be managed via the Management API. The Management API support basic CRUD operations for each of the items.For all three item types, the requested JSON objects can be filtered by issuing a "filter" query parameter along with the HTTP GET request.
The filter string uses the SCIM filtering syntax specified in RFC 7644. The available filterable criteria will be given for each of the entity types in question along with examples of filter usage.

Up-to-date API description can always be found in the onePortal instance's /apidoc endpoint. The reader is advised to take a look at the documentation. Also note that in the example code listings below, the variables "client_id", "client_secret" and "host" have to be changed to reflect your own setup.

Authorisation Grant Rights

The authorisation grant rights are a newer concept added to onePortal. Basically the authorisation grant rights limit what kind of authorisations can be created when the object type is a User. The user is required to grant the right for authorisation entry creation. This is done via the authorisation_grant_right api endpoint. The endpoint has to be accessed by an OAuth 2.0 client with end-user's authorisation. The required scope is https://oneportal.trivore.com/scope/authorisation.grant.rights. The final scope should always be verified from the OpenID configuration at /.well-known/openid-configuration or at the Swagger documentation at /apidoc3.

All endpoints managing the authorisation grant rights are accessed via OAuth 2.0 only. The use of Management API Client is prohibited.  For more information on how to use OAuth 2.0 clients, see the Implementing an OAuth 2.0 client and an OpenID Connect Relaying Party (RP) document or RFC 6749.

Restricted and relaxed authorisations modes

Each namespace has a setting, which defines whether the authorisation mode is either restricted or relaxed. The restricted mode is enabled for new namespaces by default and cannot be switched to relaxed mode. For existing namespaces, the authorisation mode is relaxed, but can be manually switched to restricted mode in the Web UI. When the namespace has enabled the restricted mode, it cannot be changed back to the relaxed mode due to security reasons.

The most important change in the restricted mode in contrast to the relaxed mode is that when the object of the authorisation is a onePortal user and the namespace where the user belongs to has enabled the restricted authorisations mode, the right to create authorisation will have to be granted by the user or onePortal will not allow the authorisation to be created. Additionally, the restricted mode enforces that authorisation entries can only be altered by the User or Management API Client, which created the authorisation entry.

Creating an authorisation grant right

The OAuth 2.0 client has to grant an authorisation from the end-user. After that the authorisation_grant_right endpoint (at /api/rest/v1/authorisation_grant_right) can be accessed with the access_token as the Authorisation Bearer in the HTTP header.

A well behaved client will clearly display the end-user the authorisation grant they are giving before creating the entry. Each authorisation grant right entry has in store the id of the OAuth 2.0 client, which created the entry.

Viewing authorisation grant rights

There are who endpoints, which can be used to view authorisation grant rights. One returns all of the grant rights and the other returns a single item with the specific id.

The endpoints to list all grant rights is /api/rest/v1/authorisation_grant_right and it has to be requested with the GET method. The other one is /api/rest/v1/authorisation_grant_right/{id}, where the id is the id of the authorisation grant right to be fetched.

Revoking authorisation grant right

Authorisation grant rights can be revoked by the user. To revoke an authorisation grant right, issue an HTTP POST request to the revoke endpoint at /api/rest/v1/authorisation_grant_right/revoke.

Managing Authorisations

The Authotisations can be managed via the authorisation REST API endpoint. The API contains methods for viewing authorisations, creating new authorisations as well as modifying and removing existing authorisations.
However, it should be noted that If the Authorisation is managed by an external source, which means that, it has the Authorisation Source defined, it cannot be modified by the onePortal platform. Externally managed Authorisations can still be removed, however.

Fetching Authorisations

The Authorisations can be retrieved by issuing an HTTP GET request to the "authorisation" endpoint of the Management API. There are two different endpoints, one of which can be used to retrieve multiple JSON objects and another, which can be used to retrieve a single entity by issuing an id. Both of these operations require the AUTHORISATION_VIEW permission.

The Authorisations can be filtered by issuing a filter string parameter as an HTTP GET query parameter. The Authorisations can be filtered by Authorisation Type, Authorisation Source, subject value, object value and the code of the namespace owning the authorisation. The filterable parameters are "object.value", "subject.value", "auhtSource", "authType" and "nsCode".

import requests

client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint = "/api/rest/v1/authorisation"
url = host + endpoint

# look only for items that are owned by the organisation with code "root"
params = {"filter": "nsCode eq \"root\"" }

response = requests.get(url, params = params, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

 

To fetch the contents of a single Authorisation, simply append the internal id of the Authorisation to the request URL. The example below demonstrates this practice.

import requests

client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint = "/api/rest/v1/authorisation/"

# the id of the authorisation to be fetched
authz_id = "12345" 
url = host + endpoint + authz_id

response = requests.get(url, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Creating an Authorisation

To create an Authorisation, issue an HTTP POST request to the "authorisation" endpoint. The endpoint requires the client to have the AUTHORISATION_CREATE permission.

As for the parameters, the namespace code is optional, and if omitted, the Authorisation object will be created to the default namespace of the management API client. If the Authorisation should be created in some other namespace, then the nsCode parameter is required and must be the code of one of the namespaces accessible to the API client. A valid Authorisation Type is required as well as subject and an object.

Additionally, Authorizations can optionally be assigned validity time by issuing validFrom and validTo parameters. The value of these parameters should be a ISO 8061 formatted datetime. The endpoint will return code 400, if the given values cannot be parsed. The example code listing below shows how to create an Authorisation with a string object and subject. The type of the Authorisation is "employment".

import requests


client_id = "0880905547415718"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint =  "/api/rest/v1/authorisation"
url = host + endpoint

payload = {
  "nsCode": "root",
  "authType": "employment",
  "object": {
    "type": "String",
    "value": "value1"
  },
  "subject": {
    "type": "String",
    "value": "value2"
  },
  "validFrom": "2018-10-25T12:00:31Z",
  "validTo": "2019-10-25T12:00:31Z"
}

response = requests.post(url = url, json = payload, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Removing an Authorisation

Authorisations can be removed by issuing an HTTP DELETE request to the "authorisation/{id}" endpoint. The endpoint requires the client to have the AUTHORISATION_REMOVE permission and the Authorisation must exist in one of the accessible namespaces. The code listing example below shows how to remove an existing Authorisation. The authorisation entries are not deleted fully. For authorisations onePortal utilizes a concept of "soft deletion", where the authorisation entry is not really deleted but marked for deletion and then finally deleted after a certain amount of time.

import requests

client_id = "0880905547415718"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint = "/api/rest/v1/authorisation/"

# the id of the authorisation to be fetched
authz_id = "12345"
url = host + endpoint + authz_id

response = requests.delete(url, auth = (client_id, client_secret))

print(response.status_code)

Authorisation Types

An Auhtorisation Type is an entity with a set of names for different localisations, description, and a code, which is used as a technical value for the client to distinguish between types. The code is also used as a reference value when managing Authorisations. The Authorisation Type can be selected from one of the preexisting types or the Management API can be used to create new custom types. The preexisting types can also be modified to better suit the client application's needs.

Fetching Authorisation Types

The Authorisation Types can be retrieved by issuing a HTTP GET request to the authorisation_type endpoint. The endpoint requires the client to have the AUTHORISATION_TYPE_VIEW permission. The Auhtorisation Types can be filtered by the code or the owner namespace's code.

import requests

client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint =  "/api/rest/v1/authorisation_type"
url = host + endpoint

params = {"filter": "code eq \"manage\"", "count": "50"}

response = requests.get(url, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Creating an Authorisation Type

An Authorization Type can be created with the POST method sent to the authorisation_type endpoint. The only attributes required by the POST method is the code of the Authorisation Type. However, it is recommended to also include a name and a brief description of the type. The following example code listing shows how to create an Authorisation Type object using Python.

import requests


client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint =  "/api/rest/v1/authorisation_type"
url = host + endpoint

payload = {
    "code": "manage",
    "nsCode": "root",
    "description": "Manage entity",
    "names" : [
        {
            "locale": "fi",
            "value": "Hallinoi"
        },
         {
            "locale": "en",
            "value": "Manage"
        }
    ]
}

response = requests.post(url, json=payload, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Modifying existing Authorization Type

An Authorisation Type can be modified by sending an HTTP PUT request to the authorisation_type endpoint. The content of the request body is the same as in the POST method. The only difference is that since the namespace cannot be changed, the nsCode parameter should be omitted.
The example below  shows how to edit an existing Authorisation Type by using Python.

import requests


client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint =  "/api/rest/v1/authorisation_type"
url = host + endpoint

payload = {
    "code": "manage",
    # nsCode parameter not needed
    "description": "Manage entity",
    "names" : [
        {
            "locale": "fi",
            "value": "Hallinnoi"
        },
         {
            "locale": "en",
            "value": "Manage"
        }
    ]
}

response = requests.put(url, json=payload, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Removing an Authorization Type

An Authorisation Type can be deleted with the HTTP DELETE method request sent to the authorisation_type endpoint. It should be noted, however, that only types that are not in use by any Authorisations can be removed. The delete request will return an error if an Authorisation Type is attempted to be removed, when it is in use. The example code listing below shows how to remove an Authorisation Type.

import requests

client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint =  "/api/rest/v1/authorisation_type/"
authz_src_id = "123" 
url = host + endpoint + authz_src_id


response = requests.delete(url, auth = (client_id, client_secret))

Authorisation Sources

The Authorisation may optionally be associated with an Authorisation Source, which tells if the Authorisation was defined by an entity external to onePortal. An Authorisation Source consists of a code, the code of the namespace owning the Authorisation Source and optionally a description and a set of names for different locales.  The external entity could be, for instance, the suomi.fi. The API methods to create, modify and remove Authorisation Sources are quite similar to the methods in Authorization Type related endpoints.

Fetching Authorisation Sources

The Authorisation Sources can be listed by issuing an HTTP GET request to the authorisation_source endpoint. Just like the Authorisation Type API, the result set can filtered by issuing a filter query parameter. The filterable parameters are "code" and "nsCode", which are the code of the Authorisation Source and the code of the namespace owning the Authorisation Source respectively. The code listing below shows an example on how to fetch a list of Authorisation Sources by using Python.

import requests

client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint =  "/api/rest/v1/authorisation_source"
url = host + endpoint

params = {"filter": "code eq \"suomi_fi\"", "count": "50"}

response = requests.get(url, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Creating an Authorisation Source

Authorization Sources can be , issue an HTTP POST request to the authorisation_source endpoint. The only required parameter is the code of the Authorisation Source. Additionally, is is recommended to issue a human-readable name as well as a short description. The code listing below shows how to create an Authorisation Source.

import requests


client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint =  "/api/rest/v1/authorisation_source"
url = host + endpoint

payload = {
    "code": "suomi_fi",
    "nsCode": "root",
    "description": "suomi.fi managed authorisation",
    "names" : [
        {
            "locale": "fi",
            "value": "suomi.fi:n hallinnoima valtuutus"
        },
         {
            "locale": "en",
            "value": "authorisation managed by suomi.fi"
        }
    ]
}

response = requests.post(url, json=payload, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Modifying an Authorisation Source

To modify an existing Authorisation Source, issue an HTTP PUT request to the authorisation_source end point. The parameter requirements are the same as the ones in the POST request except it is recommended to not include the namespace code, nsCode parameter as the namespace cannot be changed. The code listing below shows an example on how to modify an Authorisation Source by using Python.

import requests


client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint =  "/api/rest/v1/authorisation_source"
url = host + endpoint

payload = {
    "code": "suomi_fi",
    # nsCode is omitted as it cannot be changed
    "description": "suomi.fi managed authorisation",
    "names" : [
        {
            "locale": "fi",
            "value": "suomi.fi:n hallinnoima valtuutus"
        },
         {
            "locale": "en",
            "value": "authorisation manged by suomi.fi"
        }
    ]
}

response = requests.put(url, json=payload, auth = (client_id, client_secret))
print(response.status_code)
print(response.json())

Removing an Authorisation Source

The removal process is also similar to removing authorisation types. Just like with the types, Authorisation Sources cannot be removed if they are used by an Authorisation and the endpoint will return an error. The example below shows how to remove an Authorisation Source.

import requests

client_id = "3430986450301641"
client_secret = "change_me"

host = "https://fi.trivoreid.com"
endpoint =  "/api/rest/v1/authorisation_source/"
authz_src_id = "123" 
url = host + endpoint + authz_src_id


response = requests.delete(url, auth = (client_id, client_secret))
print(response.status_code)