Learn

Authenticate a DID using OIDC Bridge

Introduction

In order to obtain a Decentralized Identifier that’s being held in a Mobile Wallet, the OIDC Bridge must request this from the holder, who in turn may provide their DID in the form of a Verifiable Presentation. The short-lived presentation request itself is derived from a presentation request template, which defines that the verifier is requesting a DID.

Pre-Requisites

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

In order to present a DID using Authorization Code Flow, you need administrator access to 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.

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.

Create Presentation Template

A Presentation Request Template defines which credentials are required for presentation. The template is therefore used to create the actual Presentation Request, which is used by the Mobile Wallet to select which DID it should send.

Create a Presentation Template by providing a payload:

http
Copy to clipboard. 
1POST https://tenant.vii.mattr.global/core/v1/presentations/templates

Request

json
Copy to clipboard. 
1{
2    "name":"did-presentation",
3    "domain": "tenant.vii.mattr.global",
4    "query": [
5        {
6            "type": "DIDAuth"
7        }
8    ]
9}

The domain shows to the Mobile Wallet user which domain is asking for information. This will need to be your tenant domain or a custom domain if configured.

type is the request type so use DIDAuth.

Response

json
Copy to clipboard. 
1{
2  "id": "aee61692-3568-484a-8eda-e150c48ec9e6",
3  "name": "did-presentation",
4  "domain": "tenant.vii.mattr.global",
5  "query": [
6    {
7      "type": "DIDAuth"
8    }
9  ]
10}

Create an OIDC Credential Verifier

The OIDC Credential Verifier is designed for an OIDC Client application to request a DID. To present a DID, you need to add an OIDC Credential Verifier so that the Mobile Wallet App can present its DID to the OIDC relying party.

Create an OIDC Credential Verifier by providing a payload:

http
Copy to clipboard. 
1POST https://tenant.vii.mattr.global/ext/oidc/v1/verifiers

Request

json
Copy to clipboard. 
1{
2  "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
3  "presentationTemplateId": "aee61692-3568-484a-8eda-e150c48ec9e6",
4  "claimMappings": []
5}

The verifierDid specifies the DID the recipient of the Verifiable Presentation, so must be a valid DID on your tenant.

The presentationTemplateId references the request template that defines that a DID is being requested.

Response

json
Copy to clipboard. 
1{
2  "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
3  "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
4  "presentationTemplateId": "aee61692-3568-484a-8eda-e150c48ec9e6",
5  "claimMappings": []
6}

The Verifier can be resolved publicly from your tenant by the verifierId.

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

The Authorization header is not required as it is intended for OIDC Client applications to resolve.

Create a client

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

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

http
Copy to clipboard. 
1POST https://tenant.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients
json
Copy to clipboard. 
1{
2    "name": "DID_Auth_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 will create a new Client and provide a response:

Client-generated response

json
Copy to clipboard. 
1{
2    "name": "DID_Auth_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, take note of the Client ID and Client Secret:

json
Copy to clipboard. 
1{
2    "id": "ukM3NWLFZJFSxh6DN2lg6",
3    "secret": "XDW7vuJ2Q6w9uPKUa8djN2Fz03YjKMIaGAQ6REeXhp2LgUfXTvNMgd7orvfrhwYQJAtMksypRVMvdy7MZUTAA",
4}

You now have OIDC Bridge configured for DID Auth requests using an OpenID Connect Client application.

Try it out

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

Construct your request like this:

http
Copy to clipboard. 
1https://tenant.vii.mattr.global/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

All OIDC requests must contain scope value of openid as the first scope.

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.

By navigating to the Authorization endpoint, you have initiated an OIDC Authorization Code Flow. The OIDC Bridge extension has generated a QR code that includes a reference to a JWM message from your tenant, the payload of this message is a Presentation Request, using a DIDAuth query type, that can be interpreted by the Mobile Wallet.

By scanning the QR code (or following the deeplink) the MATTR Mobile Wallet App will create a DID for the connection and respond to the request with a proof of DID ownership.

On successful presentation, the browser will redirect to the redirect_uri provided in the authorize request, with a code query parameter added.

Your OIDC client application will obtain the DID by requesting the token from the OpenID Provider.