Authenticate using a DID

Introduction

In order to obtain a Decentralized Identifier that’s being held in a Mobile Wallet, the MATTR VII platform 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.

This can be achieved using either of the verification methods:

Authenticate using a Callback URL
Authenticate using an OIDC Bridge Verifier

Both methods first require you to create a simple Presentation Template, and you must have the MATTR mobile wallet installed and set up.

Pre-Requisites

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

Access to the MATTR VII APIs. If you’re experiencing difficulty, contact us.
A verifier DID (Decentralized ID) to use for signing messages (this must include a non-BLS key type), take a look at Tenant Setup
Download the MATTR Mobile Wallet App and have it set up with a PIN.

In order to present a DID using the OIDC Bridge, 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:

httpCopy to clipboard. 
POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/presentations/templates

Request

jsonCopy to clipboard. 
{
    "name":"did-presentation",
    "domain": "YOUR_TENANT_SUBDOMAIN.vii.mattr.global",
    "query": [
        {
            "type": "DIDAuth"
        }
    ]
}

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

jsonCopy to clipboard. 
{
  "id": "aee61692-3568-484a-8eda-e150c48ec9e6",
  "name": "did-presentation",
  "domain": "YOUR_TENANT_SUBDOMAIN.vii.mattr.global",
  "query": [
    {
      "type": "DIDAuth"
    }
  ]
}

Authenticate using a Callback

In order to start a verification flow using a callback, you will need to set up your local environment to be able to receive HTTP requests as well as calling a number of APIs to generate the required messages.

Either follow the tutorial Setup your local environment or use the verify-callback-express ExpressJs app in the MATTR Sample Apps repo. This will orchestrate a number of the calls for you and even generate a QR code making it simple for the MATTR mobile wallet to interact with your MATTR VII tenant.

Once you have installed dependencies and provided the configuration from your MATTR VII tenant in the .env file and run the ExpressJs app, you will see a QR code in the console. Scanning the QR code will prompt the mobile wallet to show a 'New request' consent screen. Once this is agreed to the platform will receive the authenticated DID response and present this in the Callback specified.

You will see the result in the terminal:

jsonCopy to clipboard. 
{
  presentationType: 'DIDAuth',
  challengeId: 'GW8FGpP6jhFrl37yQZIM6w',
  claims: {},
  verified: true,
  holder: 'did:key:z6MkkxU8iVDyXW1GgQdURDxS7SGsvzPhyDqz82XhL3sSJUs8'
}

The DID specified in the holder parameter is the fully authenticated DID from the mobile wallet.

Authenticate using an OIDC Bridge 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:

httpCopy to clipboard. 
POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/ext/oidc/v1/verifiers

Request

jsonCopy to clipboard. 
{
  "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  "presentationTemplateId": "aee61692-3568-484a-8eda-e150c48ec9e6",
  "claimMappings": []
}

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

jsonCopy to clipboard. 
{
  "id": "41458e5a-9092-40b7-9a26-d4eb43c5792f",
  "verifierDid": "did:key:z6MkrYVmyqSA93o4B1GwERM8kaQDMAUKAFV2TC3weQKeg9Gq",
  "presentationTemplateId": "aee61692-3568-484a-8eda-e150c48ec9e6",
  "claimMappings": []
}

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

httpCopy to clipboard. 
GET https://YOUR_TENANT_SUBDOMAIN.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

httpCopy to clipboard. 
POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients

jsonCopy to clipboard. 
{
    "name": "DID_Auth_Demo",
    "redirectUris": [
        "https://localhost:9090/callback"
    ],
    "responseTypes": [
        "code"
    ],
    "grantTypes": [
      "authorization_code"
    ],
    "tokenEndpointAuthMethod": "client_secret_post",
    "idTokenSignedResponseAlg": "ES256",
    "applicationType": "web"
}

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

jsonCopy to clipboard. 
{
    "name": "DID_Auth_Demo",
    "redirectUris": [
        "https://localhost:9090/callback"
    ],
    "responseTypes": [
        "code"
    ],
    "grantTypes": [
      "authorization_code"
    ],
    "tokenEndpointAuthMethod": "client_secret_post",
    "idTokenSignedResponseAlg": "ES256",
    "applicationType": "web",
    "id": "ukM3NWLFZJFSxh6DN2lg6",
    "secret": "XDW7vuJ2Q6w9uPKUa8djN2Fz03YjKMIaGAQ6REeXhp2LgUfXTvNMgd7orvfrhwYQJAtMksypRVMvdy7MZUTAA",
}

There are some key pieces of information, take note of the Client ID and Client Secret:

jsonCopy to clipboard. 
{
    "id": "ukM3NWLFZJFSxh6DN2lg6",
    "secret": "XDW7vuJ2Q6w9uPKUa8djN2Fz03YjKMIaGAQ6REeXhp2LgUfXTvNMgd7orvfrhwYQJAtMksypRVMvdy7MZUTAA",
}

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:

httpCopy to clipboard. 
https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/ext/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/authorize
?response_type=code
&client_id=ukM3NWLFZJFSxh6DN2lg6
&redirect_uri=https://localhost:9090/callback
&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.

^PrevCreate an ION DID