Tutorial: update the Host Twin AllowList

Selective data sharing can be enabled for the entire IOTICSpace by setting the Host Twin's access permissions. Follow this tutorial to guide you step by step.

This tutorial will cover:

1. Introduction to the Host Twin and its AllowList
2. How to get ownership of the Host Twin
3. How to update the Host Twin's AllowList

Introduction to the Host Twin and its Allowlist

The Host Twin controls access to the entire IOTICSpace and therefore restricts or enables access to all the Digital Twins within the IOTICSpace to all, none or a select group of other IOTICSpaces. These access permissions are set by updating the Host Twin's AllowList property.

Available access levels of the AllowList are:

• ALLOW ALL - allows access from any other IOTICSpace
• ALLOW SOME - allows access from specific IOTICSpaces only
• ALLOW NONE - denies access to any other IOTICSpace

🚧

More granular access control can be achieved by setting an individual Digital Twin's access permissions. For more information see Selective Data Sharing: Accessibility.

The AllowList property is a system property and as such it is used to describe the internal behaviour of the twin. It does not belong to the twin descriptions.

By default the AllowList of the Host Twin is set to ALLOW ALL.

The AllowList property of the Host Twin is described as follows:

key: 'http://data.iotics.com/public#hostAllowList'
uri value:
- A Host Twin DID (to allow slected hosts/twins)
- 'http://data.iotics.com/public#all' (to allow all hosts/twins)
- 'http://data.iotics.com/public#none' (to not allow any hosts/twins)

How to get ownership of the Host Twin

You can only update the Host Twin's AllowList if you have ownership of the Host Twin. For security reasons, no one user is assigned ownership automatically at set-up - this needs to be configured separately.

If you do not have ownership but should have, please ask your administrator to request ownership for you by writing an email IOTICS Support including

• your “challenge token”
• your public key

🚧

Please note that updating the Host Twin is only possible through the WebAPI at present. This functionality is not available to users of the IOTICS Host Library.

How to update the Host Twin's AllowList

This guide details how to restrict access to your Digital Twins to only some other IOTICSpaces. We therefore change the AllowList from ALLOW ALL to ALLOW SOME.

The steps to follow are:

1. Get the Host Twin DIDs of the IOTICSpaces you want to allow
2. Update the Host Twin's AllowList from ALLOW ALL to ALLOW SOME specific IOTICSpaces
   ​

1. Get the Host Twin DIDs of the IOTICSpaces you want to allow

In order to authorise an IOTICSpace, you first need to identify it by its Host Twin. The Host Twin's DID then needs to be added to the AllowList.

Ask the owner(s) of the IOTICSpace(s) for their Host Twin's DID. The DID will look similar to did:iotics:iotN5jyXWLCBDAav7YoBaHbEZM5brcHiC1Gn

2. Update the Host Twin's AllowList from ALLOW ALL to ALLOW SOME specific IOTICSpaces

Updating the AllowList property can be done by using the standard Update Twin call. For every new Host Twin you want to authorise, you need to delete the existing property and create a new property with key http://data.iotics.com/public#hostAllowList and value Host Twin DID(s).

import json
from datetime import datetime, timedelta, timezone
from typing import List
from uuid import uuid4

from requests import request

HOST = "host_url"


def get_local_host_twin_id():
    host_twin_id = None

    with request(
        method="POST",
        url=f"{HOST}/qapi/searches",
        headers=headers,
        stream=True,
        verify=False,
        params={"scope": "LOCAL"},
        json={
            "filter": {
                "properties": [
                    {
                        "key": "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
                        "uriValue": {"value": "http://data.iotics.com/public#HostTwin"},
                    }
                ]
            },
            "responseType": "MINIMAL",
        },
    ) as resp:
        # Raises HTTPError, if one occurred
        resp.raise_for_status()
        # Iterates over the response data, one line at a time
        for chunk in resp.iter_lines():
            response = json.loads(chunk)
            try:
                twin_found = next(iter(response["result"]["payload"]["twins"]))
            except KeyError:
                continue
            else:
                host_twin_id = twin_found["id"]["value"]
                break

    return host_twin_id


def update_twin_allow_list(local_host_twin_id: str, remote_host_twin_ids: List[str]):
    property_list = []

    for remote_host_twin_id in remote_host_twin_ids:
        property_list.append(
            {
                "key": "http://data.iotics.com/public#hostAllowList",
                "uriValue": {"value": remote_host_twin_id},
            }
        )

    response = request(
        method="PATCH",
        url=f"{HOST}/qapi/twins/{local_host_twin_id}",
        headers=headers,
        json={
            "properties": {"added": property_list},
            "deletedByKey": ["http://data.iotics.com/public#hostAllowList"],
        },
    )

    response.raise_for_status()


headers = {
    "accept": "application/json",
    "Iotics-ClientAppId": f"search_{uuid4()}",
    "Authorization": f"Bearer {host_twin_token}",
    "Content-Type": "application/json",
    "Iotics-RequestTimeout": (
        datetime.now(tz=timezone.utc) + timedelta(seconds=10)
    ).isoformat(),
}

local_host_twin_id = get_local_host_twin_id()
update_twin_allow_list(local_host_twin_id, remote_host_twin_ids=[remote_host_twin_id])