Affinidi Login overview

Learn how Affinidi Login works and its components.

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 Login acts as the identity provider in the OIDC flow, and the user’s Affinidi Vault supplies the credentials it signs the user in with.

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

The user clicks Sign in. The app's backend builds the authorisation URL and the frontend redirects to Affinidi Login, which requests the data its Login Configuration names from the user's Affinidi Vault. The Vault returns a vp_token once the user consents. Affinidi Login redirects back with an authorisation code, which the backend exchanges for an ID token, and the app signs the user in. The user clicks Sign in. The app's backend builds the authorisation URL and the frontend redirects to Affinidi Login, which requests the data its Login Configuration names from the user's Affinidi Vault. The Vault returns a vp_token once the user consents. Affinidi Login redirects back with an authorisation code, which the backend exchanges for an ID token, and the app signs the user in.

The sections below explain each part of this flow.

Affinidi Login authentication flow

Once Affinidi Login is your app’s sign-in method, a sign-in has three stages from your app’s side:

  1. Your app starts sign-in. It redirects the user to the authorisation endpoint of Affinidi Login (<issuer>/oauth2/auth) with its Client ID, the requested scopes and a state value. Affinidi Login shows the user its Login page.
  2. The user shares data from their Affinidi Vault. Affinidi Vault shows the user the data your Login Configuration’s presentation definition requests. When the user consents, the Vault returns that data to Affinidi Login as a Verifiable Presentation (vp_token).
  3. Your app receives the ID token. Affinidi Login verifies the presentation, maps its data into an ID token (id_token) using your ID Token Mapping, and redirects the user to your redirect URI with an authorisation code. Your app exchanges the code at the token endpoint (<issuer>/oauth2/token) for the id_token and access_token, authenticating with the method set in Auth method: a client secret, or PKCE when it’s None.

If the user declines, or the presentation fails verification, the sign-in doesn’t complete and your app receives no ID token.

What You Need to Do

  • Ensure your app is configured with a valid Client ID, its client authentication (a client secret, or PKCE when Auth method is None), 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.

  Learn more about Presentation Definition and ID Token Mapping.

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: A name for the Login Configuration, for your own reference.

  2. Redirect URIs: After users consent to share their data, Affinidi Login redirects them to this URI with an authorisation code. Your app then exchanges the code for 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.

  Read more about Login Configuration.

  Learn more about Presentation Definition and ID Token Mapping.

OpenID Connect (OIDC)

OpenID Connect (OIDC) is a widely used protocol for handling authentication and authorisation. 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, Affinidi Login is the identity provider your app connects to. Instead of checking a password, it asks the user’s Affinidi Vault, a wallet that holds the user’s credentials, for a credential such as a verified email address, and builds the ID token from it.

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 definition in 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 Affinidi 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"
            }
          }
        ]
      }
    }
  ]
}

  Learn more about Presentation Definition and ID Token Mapping.

  Request additional data from the user’s Affinidi Vault.

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

  Onboard users into your application with verified identity

  Request data from your users with their consent

Works with