Decentralised Identity

On this page, you'll find a high-level introduction to how IOTICS handles Identity.
For further information check out our Identity Specification.

Overview

The IOTICS decentralised platform model works with an equally decentralised identity system.

Decentralised Identities are an emerging effort for establishing a standard for self-sovereign digital identities. They provide entities - users, agents and twins - with the ability to self-manage cryptographic key material and other metadata to prove ownership of their identity. This data can be used to authenticate an entity to third parties or to request authorisation for access to a given resource.

IOTICS' Decentralised Identities are built on the W3C Proposed Recommendation, click here to read it.

How Identity works

The root of each identity is a cryptographic key pair, made of a private and a public key, both created from a Seed and a Key Name.

The public part of the key pair is hashed to produce a public identifier - which we'll be referring to as DID Identifier or simply, DID. The DID usually looks like this did:iotics:iotLPFgE1Q5x31dpUAKUWemywwttHmC6Zzfs.

The DID Document (DDO) contains the DID and the necessary data to prove and verify ownership of identity. It also contains the data used to prove ownership of the DID Document.
DDO's are stored in a Resolver system - a database of DID Documents - which is global to all participants of the network.

Before we move forward to the authentication and control flows, have a look at our Terminology.

Terminology

Authentication and control delegation flows

The entities within the IOTICSpace are:

• Users
• Agents
• Twins

In IOTICS, we'll always talk about delegation. A delegation is a statement of consent from a user or a twin towards an agent.

Authentication Delegation

The user delegates its authority to the agents so they can authenticate requests against an application or against the IOTICS host on its behalf.
The delegation is recorded in the DDO and managed by the user. A user can temporarily revoke or entirely remove the delegation.

Control Delegation

The twin delegates its control to the agents so they can create and update their metadata in IOTICSpace and publish data over the twins' feed. We call this action control delegation.

Delegation Proof for the IOTICS User Interface (UI)

For the IOTICS UI Agent to control your Twin created through your external Agent, the Twin's control has to be delegated to it. This control delegation will require the Delegation Proof from the IOTICS UI Agent.

{
  "content": "",
  "issuer": {
    "did": "did:iotics:iotabcdefghikjlmnopqrstuvwxyz",
    "name": "#agent-007"
  },
  "signature": "MEUCIQDRTZpzYw8uywLdn10oxsBNqCLCShZE+rPDRInx/2JwKAIgffVUrrviAKCoAHjMFuROEaP4X5YuNnBChqANSZu+994="
}

from iotics.lib.identity.api.advanced_api import APIGenericDelegationProof
from iotics.lib.identity.api.regular_api import (
    KeyPairSecretsHelper,
    get_rest_identity_api,
)
from iotics.lib.identity.crypto.issuer import Issuer


regular_api = get_rest_identity_api(resolver_url=RESOLVER_URL)  # The resolver URL of your Space

portal_issuer = Issuer(
    did="",  # As specified in the JSON
    name="",  # As specified in the JSON
)

regular_api.advanced_api.add_control_delegation_proof_to_document(
    proof=APIGenericDelegationProof(
        issuer=portal_issuer,
        content=f"",  # As specified in the JSON
        signature="",  # As specified in the JSON
    ),
    subject_issuer=portal_issuer,
    delegation_name="#portalDeleg",
    doc_owner_issuer=twin_identity.issuer,  # The Twin Identity you want to delegate the UI's Agent the control of
    doc_owner_key_pair=KeyPairSecretsHelper.get_key_pair(
        key_pair_secrets=twin_identity.key_pair_secrets  # The Twin Identity you want to delegate the UI's Agent the control of
    ),
)

Quick summary

A user delegates an agent to consent the agent to authenticate on its behalf.
A twin delegates an agent to consent the agent to control the twin.

🚧

Note:

Controlling a twin means the ability to manage its metadata, publish feed data or subscribe to inputs. This is different from sending a control command to a device by its twin to actuate a function. This is implemented with the Input interface and is contextual to the use case.

Delegation Flows

Below you'll find the authentication and the control delegation steps.

+---------+                       +-------+                          +-------+      
| user    |--- auth delegation -->| agent |<--- control delegation---| twin  |
+---------+                       +-------+                          +-------+

The user authentication delegation flow.

1. The user informs the agents of its DID.
2. The agent offers a signed proof, indicating its wish to authenticate on behalf of the user.
3. The user updates their DDO. The user delegates authority to the agent by adding an entry to their identity document with the signed proof of the agent received in step 2. As soon as its identity is updated the agent can work on the user's behalf.

The twin control delegation flow.

1. The twin informs the agent of its DID.
2. The agent offers a signed proof.
3. The twin updates its DDO.

Verification Process

This is how the overall verification between the user, agent, twin and the Host happens.

1. The agent makes an API request to a Host in the IOTICSpace, and supplies the request with a JWT token containing a claim that states what user it wants to act on behalf of.

2. The claim is then verified in the Host by accessing the nominated user’s DDO and verifying the presence of a valid and active delegation.

3. Each specific request - involving changes to the metadata or publishing and subscribing to inputs - is then checked against the twin DDO to check whether the agent has the corresponding control delegation.

To see how to create User and Agent decentralised identities, click here.
Creating these credentials is a prerequisite to work with the IOTICS API. For more information on the Identity Library, specifically, click here.