Set up an OpenID Connect Client App

Introduction

Most verifiers or relying parties will want to request information from a user’s Verifiable Credential during a particular workflow, perhaps as an onboarding step or a confirmation before proceeding to do something with the information.

Exactly how and when to achieve this is going to depend on your existing systems or external processes you need to integrate with. For the purpose of this tutorial we will demonstrate a basic user journey, so we’re going to use a simple standards-based OpenID Connect Client application that you can configure and run locally.

Pre-requisites

You need the following in order to proceed with this tutorial:

You’ll also need a development environment setup with:

  • Node.js
  • NPM or Yarn

Set up a Client to use PKCE

Because we will be running the OIDC Client as a native-like app (also known as a Single-Page-App) you will need to setup the Client on the Verifier in a certain way:

PKCE is not a requirement for using the OIDC Credential Verifier, if you were to run a more traditional server based authorization flow then the client app can be configured in a similar way to how you Configure an OIDC Client.

{
"name": "Verify React OIDC Sample App",
"redirectUris": [
"https://localhost:3000/signin-callback.html"
],
"responseTypes": [
"code"
],
"grantTypes": [
"authorization_code"
],
"tokenEndpointAuthMethod": "none",
"idTokenSignedResponseAlg": "ES256",
"applicationType": "native",
"logoUri": "https://learn.mattr.global/MATTR-logo_light-full.svg"
}

These 2 values are key:

{
"tokenEndpointAuthMethod": "none",
"applicationType": "native",
}

You technically will not be requiring a secret on the Token endpoint and the application type can be considered as native. This will setup your client to accept a Proof Key Code Exchange or ‘PKCE’ often referred to as ‘Pixie’.

There are lots of good guides about why PKCE is the preferred method of using OIDC with clients and how the ‘implicit’ flow is strongly not recommended when transferring sensitive data, such as often found in Credentials.

Get the sample app

Go to the MATTR Github account: https://github.com/mattrglobal/sample-apps

Clone the sample-apps repo

git clone https://github.com/mattrglobal/sample-apps

Change to the dir and install dependencies

  • Install dependencies
cd react-oidc-client
yarn install

Update the .env file

Rename the .env-template file to .env and add your variables

REACT_APP_STSAUTHORITY=https://<your-tenant>.platform.mattr.global/oidc/v1/verifiers/<verifier-id>
REACT_APP_CLIENTID=<client-id>
REACT_APP_CLIENTROOT=https://localhost:3000/
REACT_APP_CLIENTSCOPE=openid_credential_presentation

Note the mandatory openid scope is always automatically added to the Authorization Request in the first position as per OpenID Connect Core spec.

Try it out

If you have everything configured correctly, then go ahead and start the demo app in a development server on your local machine.

Start the app

yarn start

The app should open a browser window, if not navigate to https://localhost:3000 and you should see the MATTR OIDC Client Demo App home screen:

demo app

Click on the ‘Verify’ button to start the Verify Credential via OIDC flow!

Its a good idea to have your browser dev-tools open at this point, switch on ‘preserve log’ so you can follow the redirect requests across sites.

Tip: If the redirect fails with ‘oops! something went wrong’ screen — check that the redirect Uri configured in the Client exactly matches the value configured in your .env file, and that the React app started on the port specified e.g. https://localhost:3000.

The app will construct the OAuth2/OIDC Authorization Request and navigate you to the OIDC Credential Verifier instance configured in the REACT_APP_STSAUTHORITY variable, it will contain the REACT_APP_CLIENTID as a query parameter, along with the required OAuth2 parameters state, login and scope (containing both openid and the opendID_credential_presentation values) as well as the PKCE code_challenge and code_challenge_method parameters, which trigger the PKCE flow.

https://tenant.platform.mattr.global/oidc/v1/verifiers/dd6e3caa-7b41-4b95-afca-4dc1c41295f7/authorize
?client_id=7fa513fa-0c5b-448b-b61e-0e33e4823012
&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fsignin-callback.html
&response_type=code
&scope=openid%20openid_credential_presentation
&state=66a8fe1fdca84d978edc9f1ec99c78d6
&prompt=login
&code_challenge=9U3GmYdjm8z3tZKS8VIxmhhRqPYA8b3JzKRiFMOglX0
&code_challenge_method=S256

The response from this authorization request is a 302 redirect to the authorization screen, on desktop you will see a QR code presented.

OIDC Verifier QR Code

If you access the demo app on a mobile browser sized viewport (less than 725px width) then the QR code is hidden by default and a Deeplink is shown. If the device you are on has the MATTR Mobile Wallet App then use the Deeplink or just expand the QR code.

This QR code contains a link to the Presentation Request generated by the platform using the Presentation Request Template ID you had configured in your OIDC Credential Verifier

Send presentation

Use the MATTR Wallet App on your phone to scan the QR code, you will then be presented with screens to guide you through selecting a valid Credential.

On final consent, the information from the Credential (the Presentation) is securely sent to the Platform, this is then decrypted, verified and mapped to claims in an OIDC ID Token, based on the claims mapping you have configured in your OIDC Credential Verifier.

The redirect back to the demo app should contain the OAuth2/OIDC auth code, the demo app uses this against the /token endpoint along with the PKCE challenge to fetch the ID token. The result is the Verified Credential information being displayed on-screen.

React App User Profile

Conclusion

By successfully capturing credential information (like given name, last name and award etc) from a Credential securely held on a mobile wallet and then consuming it inside a totally separate app running locally, you can highlight the power this flow has to offer.

This OIDC client app is entirely OpenID Connect standards based, the only details entered to get it running is standard configuration. Any number of other OIDC Relying Party clients will work in a similar manor and you may find other services or libraries are more suitable to your needs or programming experience.