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.

json
Copy to clipboard.
1{
2
3  "name": "Verify React OIDC Sample App",
4
5  "redirectUris": [
6
7    "https://localhost:3000/signin-callback.html"
8
9  ],
10
11  "responseTypes": [
12
13    "code"
14
15  ],
16
17  "grantTypes": [
18
19    "authorization_code"
20
21  ],
22
23  "tokenEndpointAuthMethod": "none",
24
25  "idTokenSignedResponseAlg": "ES256",
26
27  "applicationType": "native",
28
29  "logoUri": "https://learn.mattr.global/MATTR-logo_light-full.svg"
30
31}

These 2 values are key:

json
Copy to clipboard.
1{
2
3    "tokenEndpointAuthMethod": "none",
4
5  "applicationType": "native",
6
7}

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

shell
Copy to clipboard.
1git clone https://github.com/mattrglobal/sample-apps

Change to the dir and install dependencies

- Install dependencies

shell
Copy to clipboard.
1cd react-oidc-client
2
3yarn install

Update the .env file

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

Copy to clipboard.
1REACT_APP_STSAUTHORITY=https://<your-tenant>.vii.mattr.global/ext/oidc/v1/verifiers/<verifier-id>
2
3REACT_APP_CLIENTID=<client-id>
4
5REACT_APP_CLIENTROOT=https://localhost:3000/
6
7REACT_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:

https://www.datocms-assets.com/38428/1621284506-mattr-oidc-reactapp.webp?auto=format

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.

http
Copy to clipboard.
1https://tenant.vii.mattr.global/ext/oidc/v1/verifiers/dd6e3caa-7b41-4b95-afca-4dc1c41295f7/authorizehttps://tenant.vii.mattr.global/ext/oidc/v1/verifiers/dd6e3caa-7b41-4b95-afca-4dc1c41295f7/authorize
2
3?client_id=7fa513fa-0c5b-448b-b61e-0e33e4823012
4
5&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fsignin-callback.html
6
7&response_type=code
8
9&scope=openid%20openid_credential_presentation
10
11&state=66a8fe1fdca84d978edc9f1ec99c78d6
12
13&prompt=login
14
15&code_challenge=9U3GmYdjm8z3tZKS8VIxmhhRqPYA8b3JzKRiFMOglX0
16
17&code_challenge_method=S256