How Affinidi Iota Framework Works

The Affinidi Iota Framework uses OpenID for Verifiable Presentation (OID4VP) - a standard built on OAuth 2.0 - to request and receive data from Affinidi Vault. OID4VP enables secure and simple credential presentation.

Through the OID4VP standard, the request includes a query based on 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.

Once the user consents to share their data, Affinidi Vault generates the Verifiable Presentation token (VP token) containing the requested VCs.

Data-Sharing Flow Overview

Enabling your website to request user data begins with creating an Affinidi Iota Framework configuration. This setup defines the signing wallet, sets the request token expiration, and specifies the presentation definitions needed to query data from the user’s Affinidi Vault.

Once the configuration is in place, you can integrate the Affinidi Iota Framework into your website using the Affinidi TDK. This integration allows your site to request and receive user data with consent.

The diagram below illustrates how WebSocket mode is used to handle data-sharing requests in this flow.

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 define the wallet responsible for signing the request token, set the token’s expiration to enhance security, and specify the presentation definitions used to query data from the user’s Affinidi Vault.

You also need to select a data-sharing flow mode which determines how the request will be handled.

Optionally, you can enable verification of the credentials shared by the user. You can also store the user’s consent for future reference.

Data-Sharing Mode

To integrate with the Affinidi Iota Framework, your app must define how to handle the data-sharing request, including how the response is returned to your website.

The framework supports two modes: WebSocket and Redirect.

WebSocket

In this mode, your app opens a WebSocket channel to handle the data-sharing request. The channel listens for a callback from the Affinidi Iota Framework and parses either a Verifiable Presentation token (VP token) or an error message.

WebSocket mode requires Affinidi Login, as the user’s Decentralised Identifier (DID) is needed to generate an Iota Credential to sign the request token. It supports both Popup and NewTab options when opening Affinidi Vault - a secure store for user credentials.

Redirect

Redirect mode doesn’t require Affinidi Login. Instead, it uses the redirect URL to sign the request token. After the user responds to the Affinidi Vault consent screen, they are redirected to the specified URL with a response code. Your app uses this code to fetch the callback response, which contains either the VP token or an error message.

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

The Affinidi Iota Framework allows you to enable credential verification, sending a VP token shared by the user to the credential verification service. This service checks the digital signature to confirm the credential is authentic and tamper-evident.

Consent Logs

You can enable Consent Logging to store the consent given by the user in Affinidi Vault when they agree to share their data. When enabled, it records the user’s Decentralised Identifier (DID), the type of Verifiable Credential shared, the date of consent, and the consent status.

This feature gives you proof that the user has agreed to share their data. It also provides an overview of how many consents have been given and which credentials were shared.

You can view Consent Logs on the Affinidi Iota Configuration page of Affinidi Portal . This page lets you download and filter logs by the user’s DID.

To access the logs, scroll to the bottom of the page and open the Consents panel.

What’s Next