Sample App with WebSocket Implementation

WebSocket mode enables a consent-driven data-sharing flow where requests and responses are processed through a WebSocket channel created when the Iota Session is initialised.

Applications using WebSocket mode must implement Affinidi Login to parse the user’s Decentralised Identifier (DID). This DID is required to generate the signed request token and ensure only the authenticated user can access Iota Credentials, protecting against phishing and forwarding attacks.

Before you begin

Ensure you have:

1. Set up Affinidi Vault account. Follow the guide below if you haven’t set it up.

Set up Affinidi Vault

Set up an Affinidi Vault account using the Web Vault or install the Mobile Vault (for Android).

The same setup steps for Mobile Vault.

1. Click on Get started if you are creating a new account, or click on Restore from Backup if you have an existing backup of your Affinidi Vault. Provide the passphrase to secure your Affinidi Vault.

   You have the option to enable Biometrics to unlock your Affinidi Vault easily instead of using passphrase.

GIF

2. Enter your email address to register with the Affinidi Vault. An OTP will be sent to this email for verification.

GIF

3. Enter the OTP sent to the email you have provided for verification to complete the setup.

GIF

After successfully providing the OTP, you are redirected to the Affinidi Vault dashboard.

Important Note

Remember to keep your passphrase in a secure location. Use the Passphrase Reset feature in Affinidi Vault settings to generate the PDF files and keep them safe, which you can use to recover access to your Affinidi Vault if you forget your passphrase.

2. Affinidi CLI installed. Follow the guide below if not installed.

Set up Affinidi CLI

1. Download and install NodeJS on your machine if you haven’t set it up yet.

Node Version

Affinidi CLI requires Node version 18 and above.

2. Install Affinidi CLI using Node Package Manager (npm).

        
npm install -g @affinidi/cli

3. Verify that the installation is successful.

        
affinidi --version

3. Git installed on your machine. Follow this guide on how to install Git.

4. NodeJS installed on your machine.

Download the Application

Download the sample code as a ZIP from the GitHub Repo or generate it using Affinidi CLI:

        
affinidi generate app --provider=affinidi --framework=nextjs --library=nextauthjs --path=affinidi-sample-app

Select n when prompted to Automatically configure sample app environment, we will configure it later.

The above command will generate the code sample in the affinidi-sample-app directory.

Install App Dependencies

After successfully generating the sample app, n avigate to the affinidi-sample-app directory and install dependencies using the following commands:

        
npm install

Run the Application

Start the app locally:

        
npm run dev

Once it is successfully started, visit the app in your browser using the link http://localhost:3000.

Integrate Affinidi Login

Affinidi Iota Framework requires the user’s DID to:

• Generate Iota Credentials
• Sign the Request Token
• Ensure only the authenticated user can access credentials

Implement Affinidi Login for authentication and authorisation.

Create Login Configuration

Name: Affinidi Sample App

Redirect URIs: http://localhost:3000/api/auth/callback/affinidi

        
affinidi start

        
affinidi login create-config --name='Affinidi Sample App' --redirect-uris='http://localhost:3000/api/auth/callback/affinidi'

Using Affinidi Portal

1. Go to Affinidi Login under the Services section.

2. Click on the Create Login Configuration and provide the required details.

• Name is the string that describes your login configuration.
• Redirect URIs is the URL on your application where the user gets redirected after the successful authentication.

3. Click on create and confirm if all the details are correct.

4. After confirming the details, another popup shows the Client ID and Client Secret for your Login Configuration. Copy the generated Client Credentials and use them to integrate with Affinidi Login.

5. After copying the Client ID and Client Secret and closing the popup, you are redirected back to the Affinidi Login page.

Login configuration uses:

• Default Presentation Definition (presentationDefinition)
• Default ID Token Mapping (idTokenMapping) to request the user’s email during authentication

Learn more about customising the Presentation Definition and ID Token using this guide.

Configure the App to Enable Affinidi Login

Once the Login Configuration is created, set up the client credentials provided to integrate Affinidi Login.

Copy and set up the environment variables:

        
cp .env.example .env

Set the following variables with the values provided by the Login Configuration:

        
PROVIDER_CLIENT_ID="<LoginConfig.auth.ClientID>"
PROVIDER_CLIENT_SECRET="<LoginConfig.auth.ClientSecret>"
PROVIDER_ISSUER="<LoginConfig.auth.Issuer>"

The <LoginConfig.auth.*> are values from Login Configuration.

Integrate Affinidi Iota Framework

After setting up Affinidi Login, configure the integration to enable data-sharing flow with the Affinidi Iota Framework:

• Configure integration to enable data sharing with Affinidi Iota Framework.
• Create an Affinidi Iota Framework Configuration and define a Presentation Definition for querying data from Affinidi Vault.

Follow this guide for instructions on creating the configuration.

Create a Personal Access Token

After creating the configuration and Presentation Definition, generate a Personal Access Token (PAT) using Affinidi CLI:

        

affinidi token create-token -n IotaToken --auto-generate-key --passphrase "MySecretPassphrase" --with-permissions

The PAT includes:

• Private/public keys (protected with a passphrase)
• A defined policy granting permissions to call Affinidi Iota Framework

Copy the output and configure it later in the sample app’s environment variables.

Example output of the command:

        
{
  "tokenId": "086b64ce-oau0-huy7-9876-65d76e84fa36",
  "projectId": "cba41b90-34bg-jhg9-acgf-800baa9a40a0",
  "privateKey": "...",
  "passphrase": "MySecretPassphrase"
}

Configure the App to Integrate with Affinidi TDK

Add PAT details to environment variables.

Set the following variables with the values provided by the Personal Access Token (PAT):

        
PROJECT_ID="<PAT.projectId>"
TOKEN_ID="<PAT.tokenId>"
PRIVATE_KEY="<PAT.privateKey>"
PASSPHRASE="<PAT.passphrase>"

Keep the PUBLIC_KEY and KEY_ID in env file empty.

Try the Data Sharing Flow

After setting up the Personal Access Token (PAT) and running the app:

1. Open http://localhost:3000.
2. Click Receive Credentials. You can choose:

• The page using WebSocket mode
• The page using Redirect mode

On the Receive Credentials page, you will see a dropdown field listing all the available Affinidi Iota Framework configurations created on your project.

Select the Affinidi Iota Framework configuration, including the method of opening your Affinidi Vault, whether a browser popup or a new tab if you are using WebSocket mode or select the Redirect URL if you are using Redirect mode. Also, select the Query or the Presentation Definition you defined on your configuration to query the data from the Affinidi Vault.

Once all the options are selected, click on the Share button. This will show the consent screen of the Affinidi Vault, which displays the data being requested and asks if you would like to allow access to this data.

How the Integration Works

After testing the data-sharing flow, review how the integration works.

The sample app uses Affinidi TDK modules:

• Auth Provider package to authenticate and authorise the Personal Access Token (PAT) to perform actions on your behalf.
• Iota Core library to generate the Iota Credentials for signing the Request Token.
• Iota client to call Affinidi Iota Framework service to load the configurations.
• Iota Browser library to initialise the Iota Session and prepare the Request Token to request and receive data from the Affinidi Vault.

Read more about Affinidi TDK here.

Generating Iota Credentials for Signing Request Token

The backend exposes an API endpoint to generate Iota Credentials for signing the request token. This token is used by the frontend to request and receive data from Affinidi Vault.

It uses two modules from Affinidi TDK:

• Auth Provider Authenticates and authorises the PAT and generates the Iota Token. Requires:

  • Affinidi Iota Framework Configuration ID
  • Logged-in user’s DID from Affinidi Login

• Iota Core Generates Iota Credentials to sign the request token. Takes the JWT from the Iota Token as a parameter.

Source Path: src/pages/api/iota/start.ts

        
try {
    const session = await getServerSession(req, res, authOptions);
    if (!session) {
      res.status(401).json({ message: "You must be logged in." });
      return;
    }
    const { iotaConfigurationId } = iotaStartSchema.parse(req.query);

    const authProvider = getAuthProvider();
    const iotaToken = authProvider.createIotaToken(
      iotaConfigurationId,
      session.userId,
    );
    const iotaCredentials = await Iota.limitedTokenToIotaCredentials(
      iotaToken.iotaJwt,
    );

    res.status(200).json(iotaCredentials);
} catch (error: any) {
    res.status(500).json({ message: "Unable to get Iota credentials" });
    console.log(error);
}

Initialising Affinidi Iota Framework Session

After setting up the API endpoint to generate the Iota Credentials, in the front end, we shall initialise the IotaSession using the Iota Browser package of the Affinidi TDK.

In our sample application, the IotaSession is initialised whenever you select an Affinidi Iota Framework configuration from the dropdown list.

You may refer to the configurationsQuery query for the sample code to load the list of configurations from your project using the Iota client of the Affinidi TDK.

Source Path: src/components/iota/IotaClientPage.tsx

        
async function getIotaCredentials(configurationId: string) {
    const response = await fetch(
      "/api/iota/start?" +
      new URLSearchParams({
        iotaConfigurationId: configurationId,
      }),
      {
        method: "GET",
      },
    );
    return (await response.json()) as IotaCredentials;
}

The IotaSession is initialised through the useQuery hook that gets triggered when selecting a Configuration from the dropdown list.

        
const iotaSessionQuery = useQuery({
    queryKey: ["iotaSession", selectedConfigId],
    queryFn: async ({ queryKey }) => {
      const credentials = await getIotaCredentials(queryKey[1]);
      const iotaSession = new Session({ credentials });
      await iotaSession.initialize();
      return iotaSession;
    },
    enabled: !!selectedConfigId,
});

Before initialising:

• Call getIotaCredentials to fetch credentials from the API endpoint.
• Pass credentials to IotaSession to start the session.

The IotaSession opens a WebSocket connection and listens to the callback events.

Handling the Data Sharing Request

To trigger the flow:

• Use an async function handleTDKShare to prepare and sign the request token.
• Pass the Query ID (Presentation Definition) to request data from Affinidi Vault.

Source Path: src/components/iota/IotaClientPage.tsx

        
async function handleTDKShare(queryId: string) {
    if (!iotaSessionQuery.data) {
      throw new Error("Iota session not initialized");
    }
    try {
      setIsFormDisabled(true);
      const request = await iotaSessionQuery.data.prepareRequest({ queryId });
      setIsFormDisabled(false);
      addNewDataRequest(request);
      request.openVault({ mode: openMode });
      const response = await request.getResponse();
      updateDataRequestWithResponse(response);
    } catch (error) {
      if (error instanceof IotaError) {
        updateDataRequestWithError(error);
        console.log(error.code);
      }
    }
}

Attach handleTDKShare to the rendered button as an onClick event.

        
{iotaSessionQuery.isSuccess && selectedQuery && (
  <Button
    disabled={isFormDisabled}
    onClick={() => handleTDKShare(selectedQuery)}
  >
    Share
  </Button>
)}

After signing the request token:

• Affinidi Vault opens to query data and request user consent.
• The response returns to the WebSocket opened by IotaSession.
• Use request.getResponse() to parse the response in JSON format.

Here is an example:

        
{
  "correlationId": "b099967b-8736-44db-93fa-a741e8016848",
  "verifiablePresentation": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1"
    ],
    "id": "claimId:gpf1UbjaUwwFtgKUbu_Yj",
    "holder": {
      "id": "did:key:zQ3shPh4UnmNgNza3TB2KkhKDrcEVVnntyjdNWYqDg8jKo6Gj"
    },
    "proof": {
      ...
    },
    "type": [
      "VerifiablePresentation"
    ],
    "verifiableCredential": [
      {
        "@context": [
          "https://www.w3.org/2018/credentials/v1",
          "https://schema.affinidi.com/EmailV1-0.jsonld"
        ],
        "credentialSchema": {
          "id": "https://schema.affinidi.com/EmailV1-0.json",
          "type": "JsonSchemaValidator2018"
        },
        "credentialSubject": {
          "email": "info@affinidi.com"
        },
        "holder": {
          "id": "did:key:zQ3shPh4UnmNgNza3TB2KkhKDrcEVVnntyjdNWYqDg8jKo6Gj"
        },
        "id": "claimId:31de43221eeb658e",
        "issuanceDate": "2024-07-03T05:05:56.702Z",
        "issuer": "did:key:zQ3shtMGCU89kb2RMknNZcYGUcHW8P6Cq3CoQyvoDs7Qqh33N",
        "proof": {
          ...
        },
        "type": [
          "VerifiableCredential",
          "Email"
        ]
      }
    ]
  },
  "presentationSubmission": {
    "id": "NT080x7PwL3hG2MFxtCor",
    "definition_id": "token_with_email_vc",
    "descriptor_map": [
      {
        "id": "email_vc",
        "path": "$.verifiableCredential[0]",
        "format": "ldp_vc"
      }
    ]
  }
}

The verifiableCredential can have multiple entries depending on

• Your Presentation Definition
• Verifiable Credentials shared by the user from Affinidi Vault.