Requesting User Data

Learn how to use PEX queries to request data from Affinidi Vault.

The Presentation Exchange (PEX) Protocol defined by Decentralized Identity Foundation allows the exchange of Verifiable Credentials and other JSON format claims between parties, enabling data interoperability.

PEX aims to standardise the exchange of information between two parties (Verifier and Holder) to describe proof requirements as Verifier and for Holder to submit their proof per the needs to attest their claim. It introduces Presentation Definition parameter used to define the data requirements that must be satisfied by the user.

They are designed to deliver the data between parties in a serialised JSON format that is both Claim format and transport envelope agnostic.

Request Data Flow

The diagram below shows how a user initiates the action into a particular call-to-action of a website that requests specific data and how Affinidi Vault provides the mechanism to securely share the data to the website with the user’s consent.

The example shows the flow of Affinidi Login that requests specific data from the user’s Affinidi Vault to authenticate the user.

sequenceDiagram
    actor User
    participant Website
    participant Affinidi Login
    participant Affinidi Vault

    User->>Website: Click on Affinidi Login button
    Website->>Affinidi Login: Authenticate to the Affinidi Login via Client Credentials
    Affinidi Login->>Affinidi Login: Retrieve the Login Configuration and Presentation Definition
    Affinidi Login->>Affinidi Vault: Queries Affinidi Vault based on Presentation Definition
    Affinidi Vault->>User: Request for consent to share data
    User->>Affinidi Vault: Consent given to share data
    Affinidi Vault->>Affinidi Vault: Generates Verifiable Presentation from shared data (VCs)
    Affinidi Vault->>Affinidi Login: Return the Verifiable Presentation
    Affinidi Login->>Affinidi Login: Validates the Verifiable Presentation
    Affinidi Login->>Affinidi Login: Generates ID Token from Verifiable Presentation
    Affinidi Login->>Website: Return ID Token containing user data
    Website->>User: Provides access to the user

Key takeaways to note in the above flow:

Website to initiate the data request to the Affinidi Vault once the user triggers an action.
Affinidi Vault evaluates the Presentation Definition defined by the website and identify the data requirements that must be satisfied by the user.
Once the user consents to sharing the data, Affinidi Vault generates the Verifiable Presentations (VPs) based on the requested Verifiable Credentials.
The Credential Verification service is called to verify the authenticity of the Verifiable Presentations (VPs) the user shares and sends the user back to the website.

Presentation Definition

When requesting data from the user through Affinidi Vault, the website defines the Presentation Definition of what proofs the website requires from the user to allow them to participate or access specific resources. It usually comprises inputs and constraints to describe the data the user must share to satisfy the website’s requirements.

Presentation Definition is usually consisting of:

Unique ID
Name and Purpose to explain the expectations and needs of the Verifier
List of Input Descriptors to query the holder’s data based on the requirements of the Verifier

In the context of requesting the user’s profile data from the Affinidi Vault through Affinidi Login to simplify the onboarding or registration of the user into the website, the developer has to redefine the default presentation definition of the Login Configuration. Consider the Presentation Exchange query below:

{
  "id": "token_with_identity_fullname_vc",
  "input_descriptors": [
    {
      "id": "email_vc",
      "name": "Email VC",
      "purpose": "VC Data Check",
      "constraints": {
        "fields": [
          {
            "path": [
              "$.type"
            ],
            "purpose": "Verify VC Type",
            "filter": {
              "type": "array",
              "contains": {
                "type": "string",
                "pattern": "^Email$"
              }
            }
          },
          {
            "path": [
              "$.credentialSubject.email"
            ],
            "purpose": "Check email field",
            "filter": {
              "type": "string"
            }
          },
          {
            "path": [
              "$.issuer"
            ],
            "purpose": "Check if VC Issuer is Trusted",
            "filter": {
              "type": "string",
              "pattern": "^did:key:zQ3shtMGCU89kb2RMknNZcYGUcHW8P6Cq3CoQyvoDs7Qqh33N"
            }
          }
        ]
      }
    },
    {
      "id": "profile_name",
      "name": "Profile Name",
      "purpose": "VC Data Check",
      "constraints": {
        "fields": [
          {
            "path": [
              "$.type"
            ],
            "purpose": "Verify VC Type",
            "filter": {
              "type": "array",
              "contains": {
                "type": "string",
                "pattern": "^HITFullName$"
              }
            }
          },
          {
            "path": [
              "$.credentialSubject.familyName"
            ]
          },
          {
            "path": [
              "$.credentialSubject.givenName"
            ]
          },
          {
            "path": [
              "$.credentialSubject.middleName"
            ]
          }
        ]
      }
    },
    {
      "id": "profile_identity_birthdate",
      "name": "Profile Identity",
      "purpose": "VC Data Check",
      "constraints": {
        "fields": [
          {
            "path": [
              "$.type"
            ],
            "purpose": "Verify VC Type",
            "filter": {
              "type": "array",
              "contains": {
                "type": "string",
                "pattern": "^HITBirthdate$"
              }
            }
          },
          {
            "path": [
              "$.credentialSubject.birthdate"
            ]
          }
        ]
      }
    }
  ]
}

In the above presentation definition, we are defining the following data points that are required from the user to share:

First, we defined that we require Email VC, and it should contain the following constraints:

The type of the VC is Email.
It should contains the email field.
It should be issued by a trusted issuer, in this case Affinidi.

Lastly, we defined additional requested data from the user, and it should contain the following constraints:

The type of the VC is HITFullName and HITBirthdate.
It should have the fields requested based on the path.

It is important to note that defining individual fields in the input_descriptors must match the structure and field names of the Verifiable Credential (VC) stored in the user’s Affinidi Vault for the PEX query to be valid.

Learn how to customise the Presentation Definition and ID Token Mapping of the Affinidi Login based on the available user data from Affinidi Vault to extend its capability and provide a better user experience and learn how to define PEX query with specific requirements to ensure the data is trusted.

Best Practices for Creating Presentation Definitions

When creating Presentation Definitions to query data from Affinidi Vault, we recommend following some of these best practices to avoid unexpected issues, like URL length limits, when requesting data either through Affinidi Login or Affinidi Iota Framework.

Avoid Special Characters

Special characters often require additional encoding, which increases the URL length when added as a query string. URL encoding is done to prevent any conflict or mistranslation of the data by the web platforms receiving the request.

To minimise the URL length and prevent any unexpected issue when processing the request, avoid using special characters such as +, ?, &, etc., when defining the id, name, and purpose in the Presentation Definitions. For example:

A space ( ) encoded as a plus sign (+) or %20.
A plus sign (+) encoded as %2B.
An ampersand (&) encoded as %26.

Such encodings can significantly increase the URL length, leading to potential failures when processing the query.

Keep String Short

When possible, keep the text in the id, name, and purpose short while still keeping the meaning of the text as it contributes to the length and size of the query string in the URL. For example:

id: Instead of “extract_birthdate_for_verification”, use “verify_birthdate”.
name: Instead of “Check if VC data contains necessary fields”, use “VC Data Check”.
purpose: Instead of “Ensure the VC type is correct”, use “Verify VC Type”.

Below is an example of Presentation Definition applying the best practices:


{
  "id": "verify_birthdate",
  "input_descriptors": [
    {
      "id": "bdate_vc",
      "name": "Birthdate",
      "purpose": "VC Data Check",
      "constraints": {
        "fields": [
          {
            "path": [
              "$.type"
            ],
            "purpose": "Verify VC Type",
            "filter": {
              "type": "array",
              "contains": {
                "type": "string",
                "pattern": "^HITBirthdate$"
              }
            }
          },
          {
            "path": [
              "$.credentialSubject.birthdate"
            ],
            "purpose": "Get birthdate field",
            "filter": {
              "type": "string"
            }
          }
        ]
      }
    }
  ]
}

Use Exact Match on Filter

Use the filter available in the Presentation Definition to ensure that you request only the data you require the user to provide. The filter property in the Presentation Definition supports using a RegEx to query the data to satisfy your requirements from the user.

When using the RegEx pattern to filter the data being requested from the user’s Affinidi Vault, it is recommended to use exact match to avoid conflict on other Verifiable Credentials that might match the condition. For example:

Request the Personal Email of the user from a specific Verifiable Credential:


{
  "id": "verify_email",
  "input_descriptors": [
    {
      "id": "email_vc",
      "name": "Email",
      "purpose": "VC Data Check",
      "constraints": {
        "fields": [
          {
            "path": [
              "$.type"
            ],
            "purpose": "Verify VC Type",
            "filter": {
              "type": "array",
              "contains": {
                "type": "string",
                "pattern": "Email"
              }
            }
          },
          {
            "path": [
              "$.credentialSubject.email"
            ],
            "purpose": "Get email field",
            "filter": {
              "type": "string"
            }
          }
        ]
      }
    }
  ]
}

Although the Presentation Definition is correct, using this approach can result in requesting a wrong credential with a different structure or format in the data, which may cause unexpected behaviour on your application. For example, another Issuer might issue a credential to the user with the type set to AlternateEmail, which also matches the pattern provided in the example.

Instead of just using the Email pattern in the filter, we will use an exact match for the type of credential your application requires.


{
  "id": "verify_email",
  "input_descriptors": [
    {
      "id": "email_vc",
      "name": "Email",
      "purpose": "VC Data Check",
      "constraints": {
        "fields": [
          {
            "path": [
              "$.type"
            ],
            "purpose": "Verify VC Type",
            "filter": {
              "type": "array",
              "contains": {
                "type": "string",
                "pattern": "^Email$"
              }
            }
          },
          {
            "path": [
              "$.credentialSubject.email"
            ],
            "purpose": "Get email field",
            "filter": {
              "type": "string"
            }
          }
        ]
      }
    }
  ]
}

Using the exact match on the filter ^Email$ ensures that you request data from the specific credential type with the expected structure and format of data your application can understand.

By following these recommendations, you can ensure that your Presentation Definitions are concise and efficient, preventing unexpected issues with your application when requesting data from Affinidi Vault.

Once you define and update the presentation definition, below is the sample screen of how it looks for the end-user with the additional data points requiring the user’s consent to share the data.

Note on Shared Data

It is important to note that the data requested from the Affinidi Vault and shared by the user is a snapshot of the data available at the time of request. The user may update the data anytime, and as a developer, you must initiate another request to get the latest snapshot.

Was this page helpful?

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.