These docs are for v1.0.1. Click to read the latest docs for v1.0.11.

Decentralized Identity Documents

Suggest Edits

This page provides a high level introduction to the way IOTICS handles Identity.

If you're interested in a deeper understanding of the IOTICS Identity management and delegation model then take a look at our full specification.

Overview

The IOTICS decentralised operating platform identity system builds upon decentralised ID (W3C).

DIDs are an emerging effort for establishing a standard for self-sovereign digital identities from the W3C Credentials Community Group. They provide entities with a means to self-manage cryptographic key material and other metadata about their identity. This data can be used to authenticate an entity to third parties or to request authorisation for access to a given resource.

You can read more about DIDs here.

Summary of the identity functions

The root of each identity is an cryptographic key pair. The public part of the key pair is hashed to produce a public identifier (DID or DID Identifier) which takes the form (for example) did:iotics:iotLPFgE1Q5x31dpUAKUWemywwttHmC6Zzfs.

The identifier leads to a DID Document (DDO) stored in a resolver system which is global to all participants of the network. The DDO can contain multiple keys allowing the owner(s) of the document to rotate their keys and have backup keys. All participants in the network are expected to be responsible for their own cryptographic keys. All entities make their own identity and register it with the resolver system.

Entities with an IOTICS identity are:

  • Users
  • Twins
  • Agents

Users delegate their authority to Agents to act on their behalf or to manage the their DDOs. Agents create Twins so can act on user’s behalf. Twins can delegate to other Agents and the creating key can be removed. An example of a Twin delegating authority to an Agent could be for data storage.

Terminology

TermDescription
Access token The IOTICS API uses JWT tokens to authenticate the agent over the web layer. The token must contain the necessary parts to allow the backend to verify the ID of the agent making the incoming request and to check whether that agent is allowed to access the user's resources.
Agent Any application that interacts with the IOTICSpace on behalf of a user. Each agent must have its own keys and DIDs and be authorised to act on behalf of the user.
DID Decentralized Identifier Document that enables verifiable and decentralized identity. It identifies any entity (an application/agent, a user, a twin). A DID is always associated to a DID document. A DID Document is immutable and stores crypto materials (keys, endpoints, etc) that enable a DID controller to verify the identity of the DID owner. DID documents must be globally resolved.
Resolver A database of DID documents. It must be accessible by any controller who wants to verify the identity of a DID owner.
Seed A random string of characters that is used to generate set of keys for entities like users and agents. The seed is secret because the seed can recreate the keys and therefore impersonate the entity who is associated to the private key.

You can create and manage keys manually but this increases complexity

If you lose the seed you lose your identity - in practice, the ability to control your resources (agents and twins). This may be acceptable whilst developing. Less so in production. See below how to mitigate this.
User A user of HOST. We use a delegation model whereby Agents are delegated to act on behalf of users. The delegation permission is granted by the user itself and the delegation record is written in the Agent DID.

Authentication and control delegation flows

A delegation is a statement of consent that a user or a twin make for an agent. Users delegate an agent to consent the agent to authenticate on behalf of the user; a twin delegates an agent to consent the agent to control the twin.

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

The flow for User’s authentication delegation is?:

  1. User informs Agent of their DiD
  2. Agent offers signed request
  3. User updates their DDO
    The user delegates authority to the Agent by adding an entry to their identity with the signed proof of the Agent received in 2. As soon as the identity is updated the app can work on the users behalf.

The flow for twin’s control delegation is

  1. Twin informs Agent of its DiD
  2. Agent offers signed request
  3. Twin updates their DDO.

🚧

Note:

Controlling a twin means the ability to update it’s metadata, delete it, etc. This is different than sending a control command to a device by its twin to actuate a function. This is implemented with the CONTROLS interface.

Verification process

When an Agent makes a request to a HOST it supplies the request with a JWT token containing a claim that states what User it wants to act on behalf.

The claim is then verified in the HOST by accessing the nominated user’s DDO and verifying the presence of the delegation.

Each specific request is then verified on the twin DDO to check whether the agent has the corresponding control delegation.

Updated almost 3 years ago