How Affinidi Iota Framework Works

The Affinidi Iota Framework leverages the OpenID for Verifiable Presentation (OID4VP) standard to request and receive data from the Affinidi Vault. The OID4VP is built with the OAuth 2.0 authorisation framework, providing a simple and secure presentation of credentials.

Through the OID4VP standard, the request contains a query following the Presentation Exchange (PEX Query) protocol, which introduces the Presentation Definition parameter. This parameter provides a syntax for defining the required presentation of Verifiable Credentials (VCs) stored in the user’s Affinidi Vault.

As part of the OID4VP flow, the Affinidi Vault generates the Verifiable Presentation token (VP token) containing the VCs after the user consents to share their data.

Data-sharing flow overview

The first step to enable your website to request data from the user is to create an Affinidi Iota Framework configuration to set up the signing wallet, request token expiration, and the presentation definitions required to query the data from the user’s Affinidi Vault.

After creating a configuration, integrate the Affinidi Iota Framework into your website using the Affinidi TDK and enable your website to request and receive user data with consent.

The diagram below implements the WebSocket mode to handle data-sharing requests.

sequenceDiagram
    actor U as User
    participant WF as Website<br/>Frontend
    participant WB as Website<br/>Backend
    participant AV as Affinidi Vault
    participant I as Affinidi Iota Framework
    U->>WF: Login
    Note over WF, WB: Authenticates to website via Affinidi Login
    U->>WF: Visits page that requires data
    WF->>WB: Load session protected page
    WB->>WB: Get did from user's session
    WB->>WB: Generate limited token with private key and user's did<br/>[auth-provider]
    WB->>WB: Exchange limited token for Iota credentials<br/>[iota-core]
    WB-->>WF: Page with Iota credentials
    WF->>+I: Initialize Iota session with credentials<br/>[iota-browser]
    I-->>-WF: Iota session
    U->>WF: Clicks on share data button
    Note over U, WF: Triggers a request to <br/>share data from Affinidi Vault
    WF->>+I: New data sharing request<br/>[iota-browser]
    I-->>-WF: Signed request token
    WF->>AV: Open Affinidi Vault with signed request token<br/>[iota-browser]
    WF->>+I: Await data sharing response<br/>[iota-browser]
    AV->>AV: Verify the request token
    AV->>AV: Query stored Verifiable Credentials (VC) using the<br/>presentation definition defined on the Iota configuration
    AV->>+U: Request for consent to share data
    U-->>-AV: Allow access to the data
    AV->>AV: Create a Verifiable Presentation (VP)
    AV->>I: Send VP token
    I->>I: Record the consent given by the user<br/>(Optional from configuration)
    I->>I: Verify the VP token<br/>(Optional from configuration)
    I-->>AV: Ok
    AV->>AV: Window self close
    I-->>-WF: Sends response event with the VP token
    WF-->>U: Provide service

You can provide different context-based data-sharing requests for your users at every touchpoint within your website, requesting different data sets while giving users value in return.

Affinidi Iota Framework configuration

In the Affinidi Iota Framework configuration, you configure the wallet used for signing the request token, the request token expiration to enhance security, and presentation definitions to query the data from the Affinidi Vault that users will consent to share.

You must also select the data sharing flow mode to determine how to handle the request.

You also have the option to enable verification of the credentials shared by the user and store the user’s consent.

Data sharing mode

To integrate with the Affinidi Iota Framework, you must specify the mode of handling the data-sharing request, including how the response is sent to your website.

There are two supported modes in the Affinidi Iota Framework flow.

WebSocket

With WebSocket communication, the data-sharing request is handled by initialising a WebSocket channel that listens to the callback response from Affinidi Iota Framework to parse either the data shared by the user as a Verifiable Presentation token (VP token) or error messages.

This mode requires the implementation of Affinidi Login since the current user’s Decentralised Identifier (DID) is needed to generate an Iota Credential to sign the request token. WebSocket supports Popup and NewTab when opening the Affinidi Vault.

Redirect

Redirect mode eliminates the need to implement Affinidi Login to generate Iota Credential for signing the request token. Instead, it uses the redirect URL to sign the request token. In this mode, after the user responds to the consent screen of Affinidi Vault, the user is redirected to the specified redirect URL with the response code. The requester uses the response code to fetch the callback response, which can be the user’s data (VP Token) or error messages.

sequenceDiagram
    actor U as User
    participant WF as Website<br/>Frontend
    participant WB as Website<br/>Backend
    participant I as Affinidi Iota Framework
    participant AV as Affinidi Vault
    U->>WF: Visits page that requires data
    WF->>WB: Initiate data-sharing request with Nonce
    WB->>+I: Initiate data-sharing request
    I->>I: Session created
    Note over I, I: Generates Transaction ID 
    I->>I: Retrieves configuration, including redirect URL
    I->>I: Sign request token
    I->>-WF: Signed request token
    WF->>+AV: Open Affinidi Vault with signed request token
    AV->>AV: Verify the request token
    AV->>AV: Query stored Verifiable Credentials (VC) using the<br/>presentation definition defined on the configuration
    AV->>+U: Request for consent to share data
    U-->>-AV: Allow access to the data
    AV->>AV: Create a Verifiable Presentation (VP)
    AV->>I: Send VP token
    I->>I: Record the consent given by the user<br/>(Optional from configuration)
    I->>I: Verify the VP token<br/>(Optional from configuration)
    I-->>AV: Ok
    AV->>AV: Window self close
    AV-->>-WF: Redirect user with response code
    WF->>I: Fetch callback response using response code
    I->>WF: Returns Verifiable Presentation token (VP token)
    WF-->>U: Provide service

Credential Verification

Affinidi Iota Framework Configuration allows you to enable Credential Verification, sending a Verifiable Presentation token shared by the user to the Credential Verification service to cryptographically verify the credential to check it is tamper-evident and authentic based on the digital signature.

Consent Logs

You can enable Consent Logging, which stores the consent provided by the Affinidi Vault user upon consenting to share their data. If enabled, it tracks the user’s DID, including the type of Verifiable Credential they shared, the date the consent was given, and the consent status.

It provides you with proof that the Affinidi Vault user has consented to share their data aside from getting an overview of the number of consents given and what credentials are shared.

Consent Logs can be viewed in the Affinidi Iota Configuration page of the Affinidi Portal . This page provides the option to Download and filter the logs based on the Affinidi Vault user’s DID.

Scroll down to the bottom of the page to see the Consents panel.

What’s next