Configure an OIDC Client

In order to verify a credential using an OpenID Connect Authorization Code Flow, you need to set up an OIDC Client application. This is the client that will engage with your configured OIDC Verifier to inititate the verification workflow.

There is a list of OIDC Client apps, also known as Relying Party Libraries, on the OpenID website. Pick one which you feel comfortable with.

For a hands-on approach to running an OIDC Client in a local development environment go to Set up an OpenID Client App.

Prerequisites

  • Access to MATTR VII APIs. If you’re experiencing any difficulties, contact us.

  • Administrator access to an OIDC Client application.

  • The path to your OIDC Client redirect_uri. This can be on localhost or hosted.

  • The id of an OIDC Verifer setup on your MATTR VII tenant.

Request

Make a request of the following structure to create an OIDC Client:

http
Copy to clipboard.
1POST https://YOUR_TENANT_URL/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients
json
Copy to clipboard.
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    "logoUri": "https://example.com/logo.png"
16}
  • name: Insert a meaningful name for your OIDC Client.

  • redirectUris: This array can include a list of URLs. One of the URIs in that list must match the callback URI configured for your OIDC Client for the Authorization Request:

    • Must be a valid URL.

    • Must use the HTTPS protocol.

    • Must not be an IP address.

    • Must not include query parameters.

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

  • We will keep the responseTypes,  grantTypes,  tokenEndpointAuthMethod  and  idTokenSignedResponseAlg all at their default values as per the example above.

  • logoUri: Insert a publicly available and valid URI to an image that will be displayed above the QR code during verification workflows.

Response

json
Copy to clipboard.
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}
  • id: Make note of your id with this OIDC Client.

  • secret: Make note of your secret with this OIDC Client.

Try it out

1. Go to your tenant OIDC Well Known metadata config endpoint:

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

2. Look up the authorization_endpoint value:

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

3. Construct a request of the following structure:

http
Copy to clipboard.
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 these automatically.

Copy the whole request with all the query parameters and paste it into your browser. This will initiate an OIDC Authorization Code Flow and generate a QR code that can be used to point a device at your tenant:

https://www.datocms-assets.com/38428/1628127346-1627947081-verify-setup-client-qr-demo.png?auto=format

On mobile devices the QR code is collapsed by default and a deeplink is shown.

What's next?

Once an OIDC Client is configured, you can manually create a presentation request.