How Affinidi Login Works

Learn how Affinidi Login works and its components.

Affinidi Login enables you to adopt passwordless login for your applications with a decentralised identity controlled by your users. Affinidi Login integrates with applications that support the OpenID Connect (OIDC) authentication protocol.

Affinidi Login leverages the OpenID for Verifiable Presentation (OID4VP) standard to enable your users to verify their identity using their Affinidi Vault, making it the identity provider in the OIDC flow, providing maximum flexibility, privacy, and security during the authentication flow.

Based on the diagram above, let’s examine how each component works to enable the passwordless login experience for end users.

Once you integrate Affinidi Login into your application and set it as the default authentication for passwordless login, the following actions happen within the authentication flow:

The customer signs in to your application.
The application initiates authentication and redirects users to the Affinidi Login service frontend page. At this stage, the login configuration credentials (Client ID and Client Secret) configured in your app are validated.
Upon successful credential validation, the user is redirected to the Affinidi Vault to query the user’s data using the configured presentation definition (PEX query) and request consent.
After the user consents to share their data, the Affinidi Vault generates a Verifiable Presentation token (vp_token) containing the user’s shared data and sends it back to the Affinidi Login service.
The Affinidi Login service verifies the vp_token and converts it into an identity token (id_token) based on the ID Token Mapping configuration from the Login Configuration.
Finally, the Affinidi Login service redirects the user to your application based on the redirect URIs in your Login Configuration.
The application then fetches the id_token containing the user’s identity claim and grants access to the application when valid.

Below are the key components that power Affinidi Login:

The first step to integrating Affinidi Login involves creating a Login Configuration. This configuration generates the OAuth client credentials (Client ID and Client Secret) required to initiate the OIDC flow. It specifies the data users must share (e.g., Email Address VC) and extracts the user’s identity from the VP token generated by the Affinidi Vault.

When setting up a Login Configuration, you must provide the following information:

Name: The unique identifier of the Login Configuration for reference.
Redirect URIs: After users consent to share their data as their identity, the Affinidi Login redirects them to this specified URL that fetches the generated id_token.
Presentation Definition: To query the data from the user’s Affinidi Vault to verify the user’s identity. By default, when creating a Login Configuration, a default presentation definition that queries the user’s Email Address VC from their Affinidi Vault.
ID Token Mapping: To map the user’s identity from the VP token. It transforms the extracted data into the id_token, which the application fetches. This field is optional.

OpenID Connect (OIDC)

OpenID Connect (OIDC) has been a popular way for websites to handle their Authentication and Authorisation requirements. Many existing products use these technologies in their stack to provide a secure way for users to authenticate themselves in the application.

One part of OIDC is leveraging different Identity Providers (IdPs) to provide other login mechanisms to users. Users can choose IdPs like Facebook and Google to log into websites and have a federated identity.

In the context of Affinidi Login, the Identity Provider is the Affinidi Vault that attests to the user’s ownership of specific information, like the verified email address. It returns with the VP Token (vp_token), which is converted into an ID Token (id_token), which the application fetches and grants access to secured resources.

OpenID for Verifiable Presentation (OID4VP)

OpenID for Verifiable Presentations (OID4VP) extends OpenID Connect with the ability to request and present verifiable credentials. It introduces the “VP Token” to convey Verifiable Presentations (VPs) that contain the data shared by the user from their Affinidi Vault with their consent to verify their identity.

To query the user’s identity, it leverages the Presentation Exchange protocol, which introduces the presentation definition in the request parameter to enable applications to specify requirements regarding the credentials that users consent to share to verify their identity.

Benefits of using OID4VP

Interoperability and open standards.
Verifiable Presentation (VP) allows building data and attribute-based authentication and authorisation flows with flexible data schema.
OID4VP aligns with the meta-identity system and Privacy by Design principles.
It allows basic cryptography-based authentication like FIDO2 and enables user-defined claims and verified data.

Presentation Exchange (PEX)

Affinidi Login leverages the Presentation Exchange (PEX) as part of the OID4VP standard to request data from the user’s Affinidi Vault. Through the Presentation Definition configured in the Login Configuration, Affinidi Login requests the user’s identity from their Affinidi Vault and generates a Verifiable Presentation token (vp_token).

Sample PEX query to request user’s email address from the Affinidi Vault:


        

{
  "id": "vp_token_with_email_vc",
  "input_descriptors": [
    {
      "id": "email_vc",
      "name": "Email VC",
      "purpose": "Check if data contains necessary fields",
      "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"
            }
          }
        ]
      }
    }
  ]
}

Under the hood, Affinidi Login implements a Verifiable Presentation Adapter (VPA) service, exposed as the Affinidi Login frontend and backend service, that connects to the Affinidi Vault to query the user’s data to verify their identity during the authentication flow.

Below is how the request flows from a website to Affinidi Login and Affinidi Vault to authenticate and grant access to the user.

Session Initialisation

The first step of the authentication flow starts with the website redirecting the consumer to the Affinidi Login service frontend page with a login challenge.

Afterwards, the Affinidi Login service initialises a login session and receives the necessary information to initiate an OIDC flow.

sequenceDiagram
    actor User
    participant Website
    participant Affinidi Login Service

    User->>Website: I want to Login
    Website->>Affinidi Login Service: Initiate OAuth2 with login credentials
    Note over Website, Affinidi Login Service:  [login_challenge] Client ID, Client Secret
    Affinidi Login Service->>Affinidi Login Service: Validate login_challenge
    Affinidi Login Service->>Affinidi Login Service: Retrieve Login Configuration
    Affinidi Login Service->>Affinidi Login Service: Create Login Session with Authorisation Request

Request User’s Identity from Affinidi Vault

After completing the session and authorisation request, the Affinidi Login service initiates the OID4VP flow with the Affinidi Vault.

Affinidi Vault prompts the user to confirm the sharing of the Verifiable Credentials (VCs) requested by the website, as specified in the presentation definition. Upon user consent, the Affinidi Vault generates the Verifiable Presentation token (vp_token) with the shared VCs and sends it back to the Affinidi Login service.

sequenceDiagram
    actor User
    participant Affinidi Login Service
    participant Affinidi Vault

    Affinidi Login Service->>Affinidi Vault: Initialise request to the Affinidi Vault with Authorisation request
    Affinidi Vault->>User: Show Consent screen to share data
    User->>Affinidi Vault: User confirm consent to share data
    Affinidi Vault->>Affinidi Vault: Generate Verifiable Presentation (VP)
    Affinidi Vault->>Affinidi Login Service: Redirect to Affinidi Login Service with the VP Token response
    Affinidi Login Service->>User: Show extension loading screen
    Affinidi Login Service->>Affinidi Login Service: Extract VP Token from the response

VP Token to ID Token Process

After receiving the VP token response, the Affinidi Login service calls the Affinidi Verifier service to validate its validity and authenticity.

Once the verification is complete, the Affinidi Login service extracts the data from the VP token and maps it based on idTokenMapping, which returns the user’s identity claim to the website in an id_token format compatible with the OIDC.

sequenceDiagram
    actor User
    participant Website
    participant Affinidi Login Service
    participant Affinidi Verifier

    Affinidi Login Service->>Affinidi Verifier: Validate VP Token
    Affinidi Login Service->>Affinidi Login Service: Calculate extra claim to add to the ID Token 
    Affinidi Login Service->>Website: Redirect to website with id_token and access_token
    Website->>Website: Process id_token as a user claim
    Website->>User: Provide access_token

Using different standards like OID4VP and Presentation Exchange protocol, the Affinidi Login enables applications that support OpenID Connect to provide a flexible, privacy-preserving, and secure way to authenticate consumers with a passwordless login experience.

What’s next

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.

How Affinidi Login Works

Affinidi Login authentication flow

Affinidi Login Key Components

Login Configuration