Page Comparison

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.

...

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 HTTPheader.

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

...

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".

GET Authorisations

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.

...

GET Single Authorisation

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())

...

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".

POST Authorisation

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())

...

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.

DELETE Authorisation

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)

...

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.

...

GET Authorisation Type

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())

...

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.

...

POST Authorisation Type

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())

...

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.

...

PUT Authorisation Type

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())

...

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.

...

DELETE 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))

...

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.

...

...

GET 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

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

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

...

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.

...

POST 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())

...

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.

...

PUT 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 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())

...

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.

...

DELETE 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)