Requesting User Data

The Presentation Exchange (PEX) Protocol defined by Presentation Exchange Standard 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.

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.

Key takeaways to note in the above flow:

1. Website to initiate the data request to the Affinidi Vault once the user triggers an action.

2. Affinidi Vault evaluates the Presentation Definition defined by the website and identify the data requirements that must be satisfied by the user.

3. Once the user consents to sharing the data, Affinidi Vault generates the Verifiable Presentations (VPs) based on the requested Verifiable Credentials and sends the user back to the website.

4. The Affinidi Verifier is called to verify the authenticity of the Verifiable Presentations (VPs) the user shares.

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:

"presentationDefinition": {
    "id": "vp_combined_email_user_profile_combined",
    "submission_requirements": [
      {
        "rule": "pick",
        "min": 1,
        "from": "A"
      }
    ],
    "input_descriptors": [
      {
        "id": "email_vc",
        "name": "Email VC",
        "purpose": "Check if data contains necessary fields",
        "group": ["A"],
        "constraints": {
          "fields": [
            {
              "path": [
                "$.type"
              ],
              "purpose": "Check if VC type is correct",
              "filter": {
                "type": "array",
                "contains": {
                  "type": "string",
                  "pattern": "Email"
                }
              }
            },
            {
              "path": [
                "$.credentialSubject.email"
              ],
              "purpose": "Check if VC contains email field",
              "filter": {
                "type": "string"
              }
            },
            {
              "path": [
                "$.issuer"
              ],
              "purpose": "Check if VC Issuer is Trusted",
              "filter": {
                "type": "string",
                "pattern": "^did:key:zQ3shtMGCU89kb2RMknNZcYGUcHW8P6Cq3CoQyvoDs7Qqh33N"
              }
            }
          ]
        }
      },
      {
        "id": "profile_vc",
        "name": "Profile VC",
        "purpose": "Check if data contains necessary fields",
        "group": ["A"],
        "constraints": {
          "fields": [
            {
              "path": [
                "$.type"
              ],
              "purpose": "Check if VC type is correct",
              "filter": {
                "type": "array",
                "pattern": "HITFullName"
              }
            },
            {
              "path": ["$.credentialSubject.familyName"],
              "purpose": "Check if VC contains last name",
              "filter": {
                "type": "string"
              }
            },
            {
              "path": ["$.credentialSubject.givenName"],
              "purpose": "Check if VC contains first name",
              "filter": {
                "type": "string"
              }
            },
            {
              "path": ["$.credentialSubject.middleName"],
              "purpose": "Check if VC contains middle name",
              "filter": {
                "type": "string"
              }
            }
          ]
        }
      }
    ]
}

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

1. 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.

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

• The type of the VC is FullName.
• 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) issued by the Affinidi Vault for the PEX query to be valid.

Learn how to customise the Presentation Definition and ID Token Mapping in the Login Configuration of 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.

Consent Screen with Additional Data

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.

In summary, it is necessary to use a PEX query to request data from the Affinidi Vault to validate the authenticity of the Verifiable Presentations (VPs) the user shares. Upon verification, you can parse the JSON data based on the application’s business requirements.