How Affinidi Login Works

Learn how Affinidi Login works and its components.

Affinidi Login enables developers to adopt password-less authentication flows for their applications with decentralised identity controlled by the user. Affinidi Login can be integrated with applications that support OIDC flow.

Based on the diagram above, let’s do a deep dive on how each component works to enable the passwordless login experience for the end-users.

When integrating Affinidi Login into your application and setting it as the default login method, the usual customer journey unfolds as follows:

The customer clicks the login button in your application. This initiates the OIDC authentication flow within your application and redirects users to the Affinidi Login Service frontend. At this stage, the Login Configuration credentials (Client ID and Client Secret) configured in your app is validated.
The Affinidi Login Service validates these Login Configuration credentials. Upon successful validation, it triggers the PEX query based on the presentationDefinition set in your Login Configuration used to request specific data from the Affinidi Vault.
The Affinidi Login Service sends a data request to the user’s Affinidi Vault. In response, if the Verifiable Credentials (VCs) exist, the Affinidi Vault prompts the user for consent, notifying that an application seeks their approval to access the specified data.
If the user agrees to share the data, the Affinidi Vault generates the Verifiable Presentation (VP) containing the requested VCs and transmits it to the Affinidi Login Service.
Subsequently, the Affinidi Login Service calls the Affinidi Verifier service to ascertain the authenticity and validity of the shared VP.
After verifying the VP, the Affinidi Login Service processes the mapped data extracted from the VP. This extraction is based on the idTokenMapping in your Login Configuration and converting this data into an idToken.
Finally, having created the idToken, the Affinidi Login Service redirects the user back to your application. This redirection is determined by the redirectURIs in your Login Configuration. The application then processes the idToken as the user’s identity claim.

Below are the key components that power Affinidi Login:

The first step to integrate Affinidi Login involves creating a Login Configuration. This configuration generates the OAuth client credentails (Client ID and Client Secret) required to initiate OAuth flow and specifies the data users need to share (e.g., Email Address VC) and the method of extracting the identity token from the VP Token, generated by the Affinidi Vault.

When setting up a Login Configuration, developers should provide the following information:

Name: The unique identifier or title of the Login Configuration.
Redirect URIs: After users consent to share their Email Address VC as their identity, the Affinidi Login Service redirects them to this specified URL. The Affinidi Login then includes the idToken (user’s claim) data, facilitating its processing by the application or IDP platform.
Presentation Definition: This defines the PEX query, indicating which Verifiable Credentials (VCs) are needed to verify the user’s identity. By default, when creating a Login Configuration with Affinidi Login, a presentationDefinition is available that lets developers query the user’s Email Address VC from the Affinidi Vault. This field is optional.
ID Token Mapping: This dictates how to extract details from the user claim. The extracted data is transformed into the idToken, which is subsequently sent to the address specified in the Redirect URIs. This field, too, is optional.

Below is the sample request and response from the Login Configuration using CLI:

CLI Request:

affinidi login create-config \
--name='Login Config Name' \
--redirect-uris='https://example.com/authCallback'

CLI Response:

{
  "ari": "ari:identity:ap-southeast-1:98ec70d5-hjiy-0987-8uy7-d7ee2b120e20:login_configuration/11bcee19144bc7f323f0d1cef0hygf54",
  "projectId": "98ec70d5-2e0c-huy6-jh76-d7ee2b120e20",
  "configurationId": "11bcee19144bc7f323f0d1cef0hygf54",
  "name": "Login Config Name",
  "auth": {
    "clientId": "<AUTH.CLIENT_ID>",
    "clientSecret": "<AUTH.CLIENT_SECRET>",
    "issuer": "https://<PROJECT_ID>.apse1.login.affinidi.io"
  },
  "redirectUris": [
    "https://example.com/authCallback"
  ],
  "clientMetadata": {
    "name": "Login Config Name",
    "logo": "https://login.affinidi.com/default-client-logo.svg",
    "origin": "https://example.com"
  },
  "creationDate": "2023-08-22T06:51:59Z",
  "tokenEndpointAuthMethod": "client_secret_post"
}

Learn more about Login Configuration and how you can manage them using Affinidi CLI.

Presentation Exchange (PEX)

Affinidi Login uses the Presentation Exchange (PEX) protocol to request the user’s identity, like the Affinidi Vault email address, to provide your consumers with a passwordless login experience.

Through the Presentation Definition defined in the Login Configuration, Affinidi Login queries the user’s Affinidi Vault to request specific data to generate a Verifiable Presentation (VP). It converts it into an idToken as a user claim and sends it to your application.

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

OIDC and OpenID for VP (OID4VP)

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. Your users can choose IdPs like Facebook and Google to login to 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, and returns with the VP Token (vpToken) and converted into an ID Token (idToken) and sent back to the application process the user Claim and grant access to secured resources.

OpenID for Verifiable Presentation (OID4VP)

It is an OpenID Connect standard flow extension that turns the user into the independent identity provider and implements the Presentation Exchange Protocol.

OpenID for Verifiable Presentations (OID4VP) extends OpenID Connect with the ability to request and present verifiable credentials. It introduces the new “VP Token” to convey Verifiable Presentations (VPs). It integrates the Decentralised Identity Foundation (DIF) Presentation Exchange Protocol into the “claims” request parameter to specify the application requirements regarding the credentials to be presented and to help the verifier process the result.

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 does and enables user-defined claims and verified data.

Affinidi Login Service is designed to make the information the developer can request and validate flexible. Leveraging OID4VP standard, Affinidi Login Service provides maximum flexibility, privacy, and security during the authentication flow.

Under the hood, Affinidi Login implements a Verifiable Presentation Adapter (VPA), exposed as the Affinidi Login Service, that connects to the Affinidi Vault to provide consumers with a seamless passwordless login experience.

Below is how the request flows from a website to Affinidi Login and Affinidi Vault to authenticate and authorise user:

Session Initialisation

The first step of an 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 initialise 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

Once the session and authorisation request are completed, Affinidi Login Service initiates the OID4VP flow with the Affinidi Vault.

The user is then prompted 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 (VP) for the requested VCs and sends it back to the Affinidi Login Service.

The VP Token response is parsable through the direct_post method, depending on how you initialised the Authentication request.

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

After receiving the VP Token response, the Affinidi Login Service calls the Affinidi Verifier service to validate the validity and authenticity of the VP Token.

Once the verification is complete, Affinidi Login Service extracts the information from the VP based on idTokenMapping and returns the user’s claim to the website as an idToken.

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.

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 Consumer Flow

Affinidi Login Key Components

Login Configuration

Presentation Exchange (PEX)

OIDC and OpenID for VP (OID4VP)

OpenID for Verifiable Presentation (OID4VP)

Benefits of using OID4VP

Affinidi Login Service

Session Initialisation

Affinidi Login Service - Affinidi Vault - OID4VP

Affinidi Login Service Response Handling