How Affinidi Login Works

Affinidi Login lets your app offer passwordless authentication using decentralised identity. Users control their identity through the Affinidi Vault, a secure credential store.

Affinidi Login integrates with apps that support OIDC (OpenID Connect - a standard authentication protocol). It also uses OpenID for Verifiable Presentation (OID4VP) to let users prove their identity during login.

Core Components

• Affinidi Vault: Stores user credentials securely and privately.
• OIDC Integration: Connects with your app’s existing authentication flow.
• OID4VP Support: Enables users to present verified credentials during login.

Affinidi Vault acts as the identity provider in the OIDC flow.

This gives your users full control over their data while ensuring strong security and privacy.

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

Affinidi Login Authentication Flow

Integrate Affinidi Login into your app to enable secure, passwordless authentication. Once configured as the default login method, your app follows this flow:

1. User Sign-In:

   • The user initiates sign-in from your app.

2. Redirect to Affinidi Login

   • The service validates your app’s credentials: Client ID and Client Secret.
   • The application initiates authentication and redirects users to the Affinidi Login service frontend page.

3. Data Request via Affinidi Vault

   • On successful validation, the user is redirected to the Affinidi Vault.
   • The Vault queries user data using a Presentation Exchange (PEX) definition and requests user consent.

4. Verifiable Presentation Token Generation

   • After consent, the Vault creates a Verifiable Presentation token (vp_token) containing the shared data.
   • This token is sent back to the Affinidi Login service.

5. Identity Token Creation

   • The service verifies the vp_token.
   • It then maps it to an identity token (id_token) using your app’s ID Token Mapping configuration.

6. Redirect Back to Your App

   • The user is redirected to your app using the configured redirect URI.

7. Access Granted

   • Your app receives the id_token.
   • If valid, the app grants access based on the user’s identity claims.

What You Need to Do

• Ensure your app is configured with valid Client ID, Client Secret, and redirect URIs.
• Define your PEX query and ID Token Mapping in the Login Configuration.
• Handle the id_token securely to authenticate users and manage sessions.

Affinidi Login Key Components

Below are the key components that power Affinidi Login:

Login Configuration

To integrate Affinidi Login into your app, start by creating a Login Configuration. This setup generates the OAuth client credentials -Client ID and Client Secret- used to initiate the OIDC flow (OIDC: a standard authentication protocol).

It also defines what user data your app requests (e.g. Email Address VC) and how to extract identity information from the VP token (a Verifiable Presentation token) issued by the Affinidi Vault (a secure data wallet for users).

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

1. Name: The unique identifier of the Login Configuration (for reference).

2. Redirect URIs: After users consent to share their data, Affinidi Login redirects them to this URI. Your app then fetches the generated ID token (id_token).

3. Presentation Definition: Specifies what data to query from the user’s Affinidi Vault to verify identity. By default, it requests the Email Address VC.

4. ID Token Mapping: Maps identity data from the VP token into the ID token (id_token). This allows your app to use the extracted data directly. This field is optional.

OpenID Connect (OIDC)

OpenID Connect (OIDC) is a widely used protocol for handling authentication and authorization. It allows users to log in securely using trusted identity providers (IdPs), such as Google or Facebook. This approach is known as federated identity, where users authenticate through external services.

In Affinidi Login, the Identity Provider is the Affinidi Vault - a secure wallet that verifies user data. Instead of relying on traditional IdPs, your app uses the Vault to confirm ownership of specific credentials, like a verified email address.

Here’s how the flow works:

• The user logs in and consents to share data.
• The Affinidi Vault issues a VP token (vp_token) (Verifiable Presentation).
• This token is converted into an ID token (id_token), which your app fetches.
• Your app uses the ID token to grant access to protected resources.

OpenID for Verifiable Presentation (OID4VP)

OpenID for Verifiable Presentations (OID4VP) extends OIDC (OpenID Connect – a standard authentication protocol) to support verifiable credentials. It enables your app to request and receive Verifiable Presentations (VPs) - structured data that users share from their Affinidi Vault (a secure wallet for verified credentials).

This protocol introduces the VP token, which carries the user’s shared data. With user consent, your app can verify identity based on this data.

How It Works

OID4VP uses the Presentation Exchange protocol to query user credentials. Your app defines a presentation definitionin the request. This tells the Affinidi Vault what data to share - such as a verified email address - to confirm the user’s identity.

Key Benefits

• Interoperability: Built on open standards, OID4VP works across platforms and systems.
• Flexible Authentication: Supports data - and attribute-based login flows using custom schemas.
• Privacy by Design: Aligns with meta-identity principles and gives users control over shared data.
• Cryptographic Security: Enables secure authentication methods like FIDO2 and supports verified claims.

Presentation Exchange (PEX)

Presentation Exchange (PEX) is part of the OID4VP standard, which extends OIDC (OpenID Connect – a standard authentication protocol). It allows your app to request specific user data from the Affinidi Vault - a secure wallet for verified credentials.

How PEX Works in Affinidi Login

Affinidi Login uses PEX to query user identity data. You define a Presentation Definition in your Login Configuration, which tells the Affinidi Vault what credentials to share. With user consent, the Vault returns a Verifiable Presentation token (vp_token) containing the requested data.

Example Pex Query
To request a user’s verified email address from Affindi Vault, your app sends a PEX query like the one below:

        

{
  "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"
            }
          }
        ]
      }
    }
  ]
}

Affinidi Login Service

The Affinidi Login service uses a Verifiable Presentation Adapter (VPA) to handle authentication. This adapter powers both the frontend and backend components of Affinidi Login. It connects to the Affinidi Vault - a secure wallet for verified credentials - to query user data and verify identity.

How Authentication Works

During login, your app sends a request to Affinidi Login. The service:

• Connects to the user’s Affinidi Vault
• Requests identity data based on the configured Presentation Definition
• Receives a VP token (Verifiable Presentation)
• Converts the VP token into an ID token
• Returns the ID token to your app to grant access

Session Initialisation

The authentication flow begins when your website redirects the user to the Affinidi Login frontend. This redirect includes a login challenge, which starts the session.

Once the user lands on the Affinidi Login page, the service:

• Initialises a login session
• Collects the required parameters
• Prepares to start the OIDC flow (OpenID Connect – a standard authentication protocol)

This setup allows your app to securely request and verify user identity using data from the Affinidi Vault.

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 the login session is initialised and the user authorises the request, the Affinidi Login service begins the OID4VPflow.

OID4VP (OpenID for Verifiable Presentation) extends OIDC - a standard authentication protocol - to support verified credentials.

How It Works

• The service sends a request to the Affinidi Vault (a secure wallet for user credentials).
• The Vault prompts the user to review and consent to share specific Verifiable Credentials (VCs).
• These credentials are defined in the Presentation Definition configured in your app.
• Once the user consents, the Vault generates a Verifiable Presentation token (vp_token).
• The VP token (vp_token)*is returned to the Affinidi Login service for identity verification.

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 your app receives the VP token (Verifiable Presentation), the Affinidi Login service validates it using the Affinidi Verifier.

How It Works

• The VP token (vp_token) is sent to the Affinidi Verifier.
• The Verifier checks the token’s validity and authenticity.
• Once verified, Affinidi Login extracts the user data from the token.
• It then applies the idTokenMapping (idTokenMapping) configuration.
• This mapping transforms the data into an ID token (id_token) (compatible with OIDC, a standard authentication protocol).
• The ID token is returned to your app, allowing secure access control.

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.

Affinidi Login Benefits

• Passwordless login using verified credentials
• Secure identity verification via cryptographic validation
• Privacy-preserving by design - users control what they share
• Flexible integration with any OIDC-compatible system

What’s next