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
| Term | Description |
|---|---|
| User | The user of the IOTICSpace, that authorises an agent to interact with the space on its behalf. We use a delegation model whereby the authority to act on the user’s behalf is delegated to the agent. The delegation permission is granted by the user itself and the delegation record is written in the agent DID. |
| Agent | Any application that interacts with the IOTICSpace on behalf of a user. Each agent must have its own identity and be authorised to act on behalf of the user and to control one or more twins. |
| Twin | An IOTICS Digital Twin is a virtual representation of a real entity. A real entity can be a physical asset, a sensor or device, a person, a concept, a data source or data consumer, or anything else that you'd like it to represent. |
| Access token | The IOTICS API uses JWT tokens to authenticate any of the requests that the agent makes to the IOTICSpace web layer. The token is essentially a signed payload containing the agent DID and the DID of the user the agent is acting on behalf of. IOTICSpace backend will verify the signature and the user claim and authorise the request. |
| DID Subject | The subject of a DID is, by definition, the entity identified by the DID. In IOTICS there are 3 types of identity documents: user, agent and twin. All real subjects must be mapped into one of these identity types. |
| DID | Decentralised Identity. It identifies any entity - agent, user or twin. A DID is always stored within a DID Document. |
| DID Document | A DID Document is immutable and stores crypto materials such as keys, endpoints and other material necessary to prove ownership or validate and authorise identities. It enables the 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 anyone or anything in need of identity verification. |
| Seed | Combined with a Key Name, a random string of characters is used to generate private keys for users, agents and twins. You can create and manage keys manually but this increases the complexity. If you lose the Seed and the Key Name, 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. |
| Public/Private Keys | Public-key cryptography is used to securely encrypt data or securely verify digital signatures. It is based on the concept of a key pair, a public key and a private key. Both keys are linked - the public key is generated from the private key. Data that has been encrypted with a public key can be decrypted only with the corresponding private key. Conversely, data that has been encrypted with a private key can be decrypted only with the corresponding public key. The public key can be shared publicly and the private one must be kept secret. The IOTICS DID specification allows the usage of multiple key pairs linked to an identity via the DDO. This allows a higher degree of flexibility because users and agents can choose different keys to perform different identity-related operations. The keys can be added, revoked and removed from the DDO. |
| Delegation | Delegation is a statement of consent from an entity to an agent. A user delegates authority to an agent to authenticate on its behalf and a twin delegates control to an agent to authorise control over itself. The agent identity is stored in the user or twin DDO and the delegation links the user or twin identity with the delegated agent's identity and a public key. |
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.
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.
- The user informs the agents of its DID.
- The agent offers a signed proof, indicating its wish to authenticate on behalf of the user.
- 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.
- The twin informs the agent of its DID.
- The agent offers a signed proof.
- The twin updates its DDO.
Verification Process
This is how the overall verification between the user, agent, twin and the Host happens.
-
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.
-
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.
-
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 using the Identity Library, click here.
Creating these credentials is a prerequisite to work with the IOTICS API. For more information on the Identity Library, specifically, click here.
Updated 7 months ago