AURORAL

In this article we will explain how to get access to information about the permissions to see AURORAL data. We will provide a way to link an external identity with certain access rights defined in AURORAL. This will be specially useful for Horizontal Services providers, which will implement their own authentication, however will still need a way to match their users with what these users can see from AURORAL.

---

Background

Inside AURORAL platform there is an authorisation system that is based on three levels of granularity:

• Organisation level: Everything under a CID (Organisation ID), meaning all their Nodes and all their Items.

• Node level: Everything under certain AGID (Node ID)

• Item level: One or more items with their OIDs (Object IDs)

While working inside the AURORAL realm, this is exchanging data Node to Node or using the AURORAL Neighbourhood Manager, accessing this permission rules is easy. AURORAL can match your AURORAL identity, from the Node or User browsing the Neighbourhood Manager, and filter only the things that you can see.

Now, what happens if you want to integrate a Horizontal Service. You will likely have your own Authentication method for users, and this users will or will not match one to one with AURORAL users, however they must have some relation to any AURORAL organisation.

The idea of using API Tokens is to provide a way to create anonymous keys in AURORAL that can enhance the Authorisation flow of third party services and let them connect with AURORAL to get access permissions information.

Next we will provide an example to illustrate how this functionality works.

Example

For our example we will have two users, Bob and Alice. Bob is the administrator of the AURORAL Organisation 'GoodFarms', they are using the Horizontal Service 'MyFarmMonitor'. Bob asked Alice to register an account in 'MyFarmMonitor' so she can access the dashboards that the service generates with their farm data.

Within AURORAL, 'GoodFarms' has several Nodes generating data, those Nodes can be monitored by a Node of the organisation that owns the 'MyFarmMonitor' service. Therefore, there is a data sharing agreement or contract between 'GoodFarms' and 'MyFarmMonitor', and 'MyFarmMonitor' is collecting and aggregating some data from 'GoodFarms' to generate their dashboards. At the same time 'MyFarmMonitor' has got data from 5 other farms that want to also use their service.

So, how can 'MyFarmMonitor' show the right dashboards to Alice?

When receiving data Node to Node in AURORAL, you receive enriched data, not only with semantic fields but also with IDs that can be used to identify to which object, Node or Organisation inside AURORAL these data belong.

So Alice needs a secure way to provide which IDs, and at which level can she access the data.

Let's imagine that 'MyFarmMonitor' aggregates dashboards based on the Organisation ID, so if 'GoodFarms' is providing data from 20 objects allocated under 3 different Nodes, all this data will be grouped by its CID, which will be the same as they belong to the same AURORAL Organisation. Hence, in order to access this data, Alice needs an API Token to link her identity with permission to read 'GoodFarms' data at organisation level.

How can we create such token?

In the AURORAL Neighbourhood Manager there is a new tab in the left sidebar called API Tokens. In there we can generate this new type of credential.

To generate a token with organisation permission level, we need an AURORAL user with admin role for 'GoodFarms' organisation, luckily Bob is an Admin. So he generates a token for Alice.

Now Alice has her token, that entitles her to read organisation level data.

But how do we use this token?

The AURORAL Horizontal Service providers have the possibility to integrate with an external authorisation endpoint.

https://auroral.dev.bavenir.eu/api/external/v1/auth

This endpoint will accept API Key + API Secret credentials...

{
    "keyid": "f8337b80-c0d9-4177-bb00-9ba5a9b8447c",
    "secret": "Hbda/2pxqg/QFMcpQK+Syg=="
}

...and return ACL information, which can in return be used to map the user that provides this information with the data stored in their databases.

{
    "error": null,
    "message": {
        "ACL": {
            "cid": [
              "your-org-cid"
             ],
            "agid": [],
            "oid": []
        },
        "grantType": [
                "dataAccess"
            ]
    }
}

Now Alice can access 'GoodFarms' dashboards and make use of the service!

Closing Up

In general how to integrate and use the information provided by these tokens is up to the Service provider. Whether to use organisation or node level granularity, or how to manage the API Key and secret information is something that AURORAL will not be responsible for.

Of course there are some guidelines that must be followed to protect the security of the information:

• It is recommended to not just get once the ACL information and store it, however regularly refresh this information to be up to date. The API Tokens can be revoked and regenerated with new rights by the AURORAL Organisation Admin.

• The API Secret is effectively a password, therefore should be managed with caution.

• The API Tokens are anonymous as long as they are not match to a real person identity, so if you plan to store them is recommended to store them separated from the actual identities.

We hope this new feature is helpful for you and we will keep working to improve the Service integration experience in AURORAL.

---

Brought to you by the AURORAL community, keep posted! 💪