Verifiable Credential based Authentication via OpenID Connect

At MATTR, we’ve been working hard on an exciting opportunity with the Government of British Columbia (BC Gov) in Canada. In June 2019, the BC Gov Verifiable Organisations Network team put out a “Code With Us” development bounty to integrate KeyCloak, their chosen enterprise Identity and Access Management (IAM) solution, with a new W3C standard called Verifiable Credentials. This work led to a solution that enables the use of Verifiable Credentials (VC) as a means of authentication that is interoperable with OpenID Connect (OIDC). We call this work VC-AuthN-OIDC. The output is an adapter that bridges these standards and enables a whole new set of capabilities through a simple extension of most modern IAM solutions.

Understanding Verifiable Credentials

Verifiable credentials are a new W3C standard that defines a data model for expressing credentials in a digitally verifiable way.

A verifiable credential ecosystem is commonly described using the following model:

A verifiable credential is essentially a set of one or more attributes of data (aka ‘claims’) that are issued by some authority who is known as the ‘issuer’. These claims are made about a subject (such as a person) in a way that, when presented to a verifier, their authenticity can be ‘verified’ cryptographically.

For example, a driver’s license is a traditional ‘credential’ that is quite common to everyone. In this case, the Department of Motor Vehicles (DMV) is the issuer of the credential, the subject is you, and the claims include first name, last name and D.O.B. (date of birth) that are listed on the license. When the DMV provides you with the license, it can be used in a variety of ways to assert claims to a variety of verifiers. For example, a driver’s license can be presented to a police officer to prove your eligibility to drive. It can also be presented at a store to meet the minimum age requirement to purchase alcohol.

The idea behind verifiable credentials is to take physical credentials like a driver’s license and others and convert them to a digital format. In this form, rather than verifiers trusting security ink and paper documents for proof of authenticity, cryptography is used instead. Most commonly, the storage and exchange of these ‘credentials’ for individuals are achieved via a mobile app called a digital identity wallet.

Understanding OpenID Connect

OpenID Connect is an authentication protocol built on top of OAuth2.0. In a standard OpenID Connect implementation, a relying party will form an authentication request and send it to a trusted OpenID provider who will handle authenticating the user on the relying party’s behalf. Relying parties, like verifiers, are typically trying to verify a user’s identity in order to grant the user access to some service or application. OpenID providers, on the other hand, manage and maintain the actual user identities and how to authenticate them. Popular OpenID Connect providers include Twitter, Facebook, and Github — the familiar options users see when logging in. To authenticate and identify a user, the OpenID provider will most commonly ask the user for a username and password as the challenge. Upon authentication, the OpenID provider constructs an identity token with the requested information on the authenticated user (similar to the ‘claims’ on a driver’s license) and returns this back to the relying party (either directly or indirectly).

What problem does VC-AuthN-OIDC solve?

With OpenID Connect, a user can leverage an account they hold with an OpenID provider to authenticate to another website/service. However, in this process, the user often unknowingly reveals important information to the provider like what online services they use, how often they use them and what they use them for. This model also puts an OpenID provider at the centre of these digital relationships, effectively handing over much of the control of the relationship to the provider.

The ability within OpenID Connect to leverage an account held at one provider to authenticate with another website/service is often referred to as identity federation and because of this model, many use cases are difficult to support. Take the example of proving to a website your first and last name from your passport and your address verified by your utility provider. Using OpenID Connect would first require you to have an active account with both the passport authority and your utility provider. The website you are trying to disclose this information to must also support connecting to these two particular OpenID providers and finally you would have to login to both of these services separately when you want to disclose this information. This mix of having to support a delicate federation model and tricky user experience is at odds with how we use credentials in the physical world. Here, we are issued credentials such as a passport that we are free to combine with other credentials and present wherever, without further involvement from the issuer(s).

VC-AuthN-OIDC leans on the standardisation that OpenID Connect has defined in order to create an easy integration mechanism to existing systems that use OpenID Connect while also achieving a new way for users to authenticate using verifiable credentials. The approach removes the dependency on any single OpenID provider, shifts greater control back to the user, strengthens privacy and simplifies the user experience.


Our solution builds on the existing OpenID Connect authentication flow making one subtle but important change to the authentication request made by the relying party to a supporting OpenID provider. Rather than the relying party asking the general question of, can you authenticate this user? the question asked by the relying party is, *can you challenge this user to present verifiable credentials that satisfy these given constraints? *Importantly as this question changes, the control that an OpenID provider previously had over a user’s identity in conventional OpenID Connect disappears, as any OpenID provider supporting VC-AuthN can now perform the same authentication for a relying party.

When the relying party asks for this method of authentication, they can impose a set of constraints, examples of the types of these are:

  • Credential Issuer — Who the credential was issued by?
  • Credential Schema — What type of credential is it?
  • Credential Attributes — Which attributes (pieces of data) are of interest?

The end result for a relying party is the same as in traditional OpenID Connect in the sense that they obtain what is referred to as an Identity Token, the only real difference is how this token is constructed. Rather than it being populated based on user information held by the OpenID provider, it is constructed using the claims in Verifiable Credentials that a user presents.

Use Cases

Below are a few example use cases we describe that are enabled by the VC-AuthN-OIDC work.

British Columbia Government Access to Legal Services

John’s a lawyer in the province of British Columbia and has been issued with a verifiable credential proving this. The Government of British Columbia has several digital services that are available to lawyers within the province. Leveraging VC-AuthN-OIDC, John is able to authenticate into and gain access to these digital services by presenting his Verifiable Credential proving he is a lawyer.

Opening a new bank account

Jennifer wishes to open a bank account with Faber Bank digitally, in order to do this she must prove certain things about herself, such as:

  • Her name
  • Her address
  • Her current employment status

Using a combination of credentials she has previously obtained such as her driver’s license, address credential from her utility provider, and an employment credential issued by her employer, leveraging VC-AuthN-OIDC she can present these to the Faber Bank website in a single interaction in order to complete the account creation.

Obtaining a public transport discount

Dave is a student at a University and he wishes to get a public transport discount based on the fact he is currently studying. To apply for this discount Dave will be asked to prove to the public transport provider via their website that he is a student. The University in which Dave attends issues Dave with a verifiable credential confirming he is a student. To get the public transport discount, leveraging VC-AuthN-OIDC, Dave can present this credential to the public transport provider to redeem the discount.

Get in touch

If you’re interested in understanding more about this solution or believe this is a solution you’d like to implement, reach out at support@mattr.global or check out the open-source repository where documentation along with a reference implementation can be found. The work was also recently presented at the Internet Identity Workshop, for a link to the presentation see here.