Affinidi Iota Framework

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

Through the OID4VP standard, the data request is defined using 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 stored in the user’s Affinidi Vault. Once the user consents to share the requested data, the Affinidi Vault generates the Verifiable Presentation token (VP token) that contains the presentation of Verifiable Credentials.

The same standard and protocol are used in the Affinidi Login to authenticate and authorise users in the application.

Benefits of the Affinidi Iota Framework

Simplified Data Sharing: It streamlines requesting and receiving data from the Affinidi Vault, leveraging the OpenID for Verifiable Presentation (OID4VP) standard. Easily define the Presentation Definition from available templates to request relevant data from the user.

Enhanced User Experience: Simplified data sharing removes manual and repetitive form filling. It enables the reusability of attestable, accurate, and relevant data to get actionable insights about the consumer.

Improved Privacy and User Trust: Consent-driven data sharing promotes transparency and trust, increasing user engagement and loyalty.

How Affinidi Iota Framework Works

To enable your website to request data from the user, you must create an Affinidi Iota Framework configuration to set up the Signing Wallet, JWT Expiration, and the Presentation Definitions required to query the data from the Affinidi Vault.

After creating a configuration, you can integrate the Affinidi Iota Framework into your website with Affinidi TDK. This allows you to request and receive user data from their Affinidi Vault.

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

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 consumers within their website, requesting different data sets while giving users value in return. The Affinidi Iota Framework enables you to extract actionable insights and provide a better customer experience by offering calls to action at various touch points of the consumer journey.

Affinidi Iota Framework Configuration

When integrating with the Affinidi Iota Framework, developers must create a Configuration first, where they 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.

Developers must also select the Data sharing flow mode, which determines how the integration and request are handled. Two modes are supported when integrating the Affinidi Iota Framework.

• WebSocket mode that handles data-sharing requests and responses from Affinidi Vault using WebSocket communication. In this mode, Affinidi Login is required to be implemented on your application to extract the Decentralised Identifier of the current user to generate the required Iota Credentials for signing the request token.

• Redirect mode handles the data-sharing request from Affinidi Vault and sends the response using a specified redirect URL. The Redirect URL in the request must match the list of URLs defined in the configuration. In this mode, your application does not need to implement Affinidi Login.

Additionally, developers have the option to enable verification of the credentials shared by the user and store the user’s consent.

The created Configuration ID is part of the required parameters to generate the signed request token and initiate the data-sharing request.

To learn more about Affinidi Iota Framework Configuration, visit this page for details and steps to create.

Data Sharing Flow Mode

To integrate with the Affinidi Iota Framework, developers have to specify the mode in which the data-sharing request is handled, including how the response is sent to the requester.

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. With WebSocket, it 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 provides an option to enable Credential Verification that sends 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

Developers have the option to 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 developers 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.

If you wish to get the consent logs stored on your project from your application, you can use the Affinidi Iota Framework client of the Affinidi TDK. Follow this guide to learn how to integrate this.

Test Your Configuration

After creating your configuration, including the Presentation Definition to query data from the user’s Affinidi Vault, you can test your queries to see if it can request data based on your requirements and get a response. This way, even before integration, you can optimise your queries and get the sample response to parse the data correctly into your application and experience first-hand how consent-driven data sharing works with Affinidi Iota Framework.

To test your configuration, click on the Test button available on the overview page of your configuration.

Select the query you want to test and click the Send request button. It will initiate a data-sharing request to your Affinidi Vault and query the data based on the inputs of your Presentation Definition.

Integrate Affinidi Iota Framework

Learn how to integrate with Affinidi Iota Framework to enable secure data sharing flow on your website.