Implement a Seamless Data Sharing Flow with Affinidi Iota Framework
Enable your website to request and receive user data with Affinidi Iota Framework securely.
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.
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.
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.
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 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:
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 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
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 tampered-evident and authentic based on the digital signature.
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.
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.
Learn how to integrate with Affinidi Iota Framework to enable secure data sharing flow on your website.
Enable your website to request and receive user data with Affinidi Iota Framework securely.
Use this guide to setup and run the sample application using NextJS that integrates with Affinidi Iota Framework using the Redirect mode to get you started quickly.
Use this guide to setup and run the sample application using NextJS that integrates with Affinidi Iota Framework using the WebSocket mode to get you started quickly.
Get the consent logs from the Affinidi Iota Framework stored on your project from your application.
Glad to hear it! Please tell us how we can improve more.
Sorry to hear that. Please tell us how we can improve.
Thank you for sharing your feedback so we can improve your experience.