Configure an OIDC Client

Introduction

In order to verify a credential using OpenID Connect Authorization Code Flow, we need to set up an OIDC Client application. There is a list of OIDC Client apps, also known as ‘Relying Party’ libraries, on the OpenID website Certified OpenID Connect Implementations. These are generally easy to use, pick one which you feel comfortable with.

Prerequisites

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

• Administrator access to an OIDC-capable client application, see above for an example list.

• You will need to know the exact redirect_uri of your OIDC Client, this can be on localhost or hosted, and the path to the call back e.g. https://localhost:9090/callback.

• Access to the MATTR Platform APIs. If you’re experiencing difficulty, contact us.

• Know the DID (decentralided identifier) to use for receiving credentials, take a look at tenant setup.

• Created an OIDC Verifer and have the verifierId.

• Download the MATTR Wallet app and have it set up with a PIN.

Create a client on the platform

Use the /oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients endpoint to create an OIDC Client on the platform.

There are just two key pieces of information you need to provide;

• First give the setup a meaningful client name

• The redirectUris can accept a list of URLs, one in that list must match exactly with the callback to your OIDC Client that is made in the Authorization Request, including https, fqdn and path to the callback.

For testing, it’s okay to add a localhost uri like https://localhost:9090/callback

We’re sticking with the OIDC Authorization Code flow, so we will keep the responseTypes, grantTypes, tokenEndpointAuthMethod and idTokenSignedResponseAlg all at their default values as per the example below:

Create a Client Request

1POST https://YOUR_TENANT_URL/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients

1{
2    "name": "Verify_Credential_Demo",
3    "redirectUris": [
4        "https://localhost:9090/callback"
5    ],
6    "responseTypes": [
7        "code"
8    ],
9    "grantTypes": [
10      "authorization_code"
11    ],
12    "tokenEndpointAuthMethod": "client_secret_post",
13    "idTokenSignedResponseAlg": "ES256",
14    "applicationType": "web"
15}

There are other settings available for this endpoint like logoUri used to enhance the UI.

The platform will create a new Client and provide a response:

Client-generated response

1{
2    "name": "Verify_Credential_Demo",
3    "redirectUris": [
4        "https://localhost:9090/callback"
5    ],
6    "responseTypes": [
7        "code"
8    ],
9    "grantTypes": [
10      "authorization_code"
11    ],
12    "tokenEndpointAuthMethod": "client_secret_post",
13    "idTokenSignedResponseAlg": "ES256",
14    "applicationType": "web",
15    "id": "ukM3NWLFZJFSxh6DN2lg6",
16    "secret": "XDW7vuJ2Q6w9uPKUa8djN2Fz03YjKMIaGAQ6REeXhp2LgUfXTvNMgd7orvfrhwYQJAtMksypRVMvdy7MZUTAA",
17}

There are some key pieces of information but critically take note of these 4 values and copy them somewhere safe:

1{
2    "id": "ukM3NWLFZJFSxh6DN2lg6",
3    "secret": "XDW7vuJ2Q6w9uPKUa8djN2Fz03YjKMIaGAQ6REeXhp2LgUfXTvNMgd7orvfrhwYQJAtMksypRVMvdy7MZUTAA",
4}

You now have an OIDC Credential Verifier configured for Verifiable Credential presentation requests using an OpenID Connect Client application.

Try it out

OIDC Clients start the Authorization Code Flow with the Authorization Request.

First, go to your tenant OIDC Well Known metadata config endpoint.

1GET https://YOUR_TENANT_URL/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/.well-known/openid-configuration

There you will see the Authorization endpoint value:

1{
2    "authorization_endpoint": "https://YOUR_TENANT_URL/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/authorize",
3}

Construct your request like this:

1https://YOUR_TENANT_URL/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/authorize
2?response_type=code
3&client_id=ukM3NWLFZJFSxh6DN2lg6
4&redirect_uri=https://localhost:9090/callback
5&scope=openid+profile
6&state=abc
7&nonce=123

All OIDC requests must contain scope value of openid as the first scope. For the purpose of this test, state and nonce can be placeholder values, however normally your OIDC Client would generate those automatically.

Copy the whole request with all the query parameters and paste it into your browser.

If your Client is configured correctly you should see a page showing a QR code and the associated redirect URL.

Note on mobile screen-sizes the QR code is collapsed by default and a deeplink is shown.

What just happened?

By navigating to the Authorization endpoint, you have initiated an OIDC Authorization Code Flow. The platform has generated a QR code that can be used to point a device at your tenant.

The QR code (or deep link) will contain a link that can be opened by the MATTR Mobile Wallet App.