Configure an OIDC Client on the Platform

Introduction

In order to verify a Credential using Authorization Code Flow, we need to set up an OIDC Client application. There is a list of Clients 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.

Pre-Requisites

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.

Subscription to MATTR Platform & OIDC Bridge service

  • The Subdomain URL of your MATTR service e.g. https://tenant.platform.mattr.global.

A compatible Android (6+) or iOS (iPhone 7+) device

Create a client on the platform

Use the /v1/oauth/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 redirect_uri 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 response_types, grant_types, token_endpoint_auth_method and id_token_signed_response_alg all at their default values as per the example below:

Create a Client Request

POST https://tenant.platform.mattr.global/v1/oauth/clients
{
"client_name": "Verify_Credential_Demo",
"redirect_uris": [
"https://localhost:9090/callback"
],
"response_types": [
"code"
],
"grant_types": [
"authorization_code"
],
"token_endpoint_auth_method": "client_secret_post",
"id_token_signed_response_alg": "ES256"
}

There are other settings available for this endpoint like client_uri and logo_uri used to enhance the login screen.

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

Client-generated response

{
"application_type": "web",
"grant_types": [
"authorization_code"
],
"id_token_signed_response_alg": "ES256",
"post_logout_redirect_uris": [],
"require_auth_time": false,
"response_types": [
"code"
],
"subject_type": "public",
"token_endpoint_auth_method": "client_secret_post",
"request_uris": [],
"client_id_issued_at": 1590282969,
"client_id": "ukM3NWLFZJFSxh6DN2lg6",
"client_name": "Verify_Credential_Demo",
"client_secret_expires_at": 0,
"client_secret": "XDW7vuJ2Q6w9uPKUa8djN2Fz03YjKMIaGAQ6REeXhp2LgUfXTvNMgd7orvfrhwYQJAtMksypRVMvdy7MZUTAA",
"redirect_uris": [
"https://localhost:9090/callback"
],
"registration_client_uri": "https://tenant.platform.mattr.global/v1/oauth/clients/ukM3NWLFZJFSx3M8IHug6",
"registration_access_token": "nUSAZIlFe03bZ3Dj-rqtDT6nRmq6AluL-duyB6A0lp1"
}

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

{
"client_id": "ukM3NWLFZJFSxh6DN2lg6",
"client_secret": "XDW7vuJ2Q6w9uPKUa8djN2Fz03YjKMIaGAQ6REeXhp2LgUfXTvNMgd7orvfrhwYQJAtMksypRVMvdy7MZUTAA",
...
"registration_client_uri": "https://tenant.platform.mattr.global/v1/oauth/clients/ukM3NWLFZJFSxh6DN2lg6",
"registration_access_token": "nUSAZIlFe03bZ3Dj-rqtDT6nRmq6AluL-duyB6A0lp1"
}

The only way to retrieve the information on the Client is to call the registration_client_uri with the registration_access_token as the bearer token.

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.

GET https://tenant.platform.mattr.global/.well-known/openid-configuration

There you will see the Authorization endpoint value:

{
"authorization_endpoint": "https://tenant.platform.mattr.global/v1/oauth/authorize",
}

Construct your request like this:

https://tenant.platform.mattr.global/v1/oauth/authorize
?response_type=code
&client_id=ukM3NWLFZJFSxh6DN2lg6
&redirect_uri=https://localhost:9090/callback
&scope=openid+profile
&state=abc
&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 dummy 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 this:

Successful Auth screen loading on desktop

Verify Setup Client

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's Identity Agent.

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