Skip to main content
European CommissionEBSI European Blockchain

How to authenticate users

Last updated on

Context

This document aims to enhance current user authentication capabilities by integrating hybrid approaches, such as classic OpenID Connect (OIDC), Self-Issued OpenID Provider (SIOP) v2, and Verifiable Presentation (VP) Exchange. The goal is to re-use existing protocols and patterns to improve efficiency and interoperability.

Generic communication pattern

OpenID for Verifiable Credential Issuance (OID4VCI) employs a Credential Offer mechanism, where the Issuer initiates a cross- or same-device request for a credential. This approach allows the Holder Wallet to control the process, whitelist Issuers and perform background validations and configurations through /.well-known discovery. The main benefit of this offer is to enable the Issuer to introduce itself and allow the Wallet to initiate the underlying sequence. Wallets can use client_metadata in the initial Authorisation Request, giving them full control over how the Authorisation Request is constructed.

Simarly, OID4VP can use Verification Offer, where the Verifier initiates a cross- or same-device request for verification, offering the same benefits.

Verification Offer

The Verification Offer must contain the Verifier's client_id. It should also contain information of the possible authentication schemes, including classical OIDC, ID Token and VP Exchange, as well as the required scopes and optional scopes. Optionally, the VP Token section could list supported VC types, which may also be defined in the /.well-known configuration.

The Wallet must respond via the initial Authorisation Request's client_metadata to indicate support for the proposed authentication schemes. For example, not all End-Users may prefer classic OIDC, prompting the Authorisation Server to use a credential instead.

Well-known metadata

The Verifier should expose ./well-known/openid-verifier. If the Issuer acts as a Verifier, it should also contain the configuration alongside /.well-known/openid-credential-issue. Depending on the Client Identifier Scheme used, the ./well-known configuration may be located via client_id. The Verifier may also provide the metadata in the Verification Offer through client_metadata or the client_metadata_uri property.

If the Verifier is not an Authorisation Server, it must include the authorization_server in the configuration, similar to the Issuer's case.

Flow

  1. Verifier creates a Verification Offer specific to their needs.
  2. Holder Wallet receives the Verification Offer (via redirect or QR Code).
  3. Holder Wallet reads the /.well-known configuration and optionally the AS configuration.
  4. Holder Wallet optionally requests consent from the End-User and any potential scope extensions.
  5. Holder Wallet sends an /authorize request to the designated AS, with client_metadata describing the Wallet's capabilities.
  6. AS redirects back, either through a classic OIDC redirection or an Authorisation Request with response_type=id_token or response_type=vp_token, where both also contains the response_mode=direct_post.
  7. Holder Wallet will create the direct post response accordingly, or follow redirect for classical OIDC.
  8. After one to many authentications are completed, the AS should return to the initial response_type. In case of code, it will return redirect into RP with code.

To enable device-specific redirections, the Verifier should always use a Signed Request Object as request or request_uri, which can also be achieved with JWT-Secured Authorisation Request (JAR).

Verifying the Verifier

The Verifier may store credentials in any public place, such as /.well-known/verifiable-credentials/xyz-jwt or in a public Credential Registry. These credentials should be referenced in the Verifier's /.well-known/openid-verifier configuration.

Each Verifiable Credential should be issued for the client_id, which is automatically proven through Transport Layer Security (TLS) if the client_id matches the prefix of the /.well-known endpoint. In other cases, the Verification Offer should be signed as a JWT with keys located through the Client Identifier Scheme.

Benefits

  • The Verifier can operate within a 3-legged model.
  • ID Token, VP Token and classic OIDC can all be used for authentication.
  • Builds on existing protocols and patterns.
  • SIOP can be used as two-factor authentication (2FA) in normal OIDC.
  • Enables Decentralised Access Management through VCs holding proofs of access.

Known issues

openid-credential-offer:// is specific to VCI, while Verification Offer would introduce another endpoint (openid-verification-offer://). On End-User devices, these two endpoints may be bound to different applications, which may cause confusion and support issues. It would be better to unify these two endpoints into a single one: openid-offer://.