Authenticate a DID using OIDC Bridge

Table of Contents

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 Request 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 Request Template by providing a payload:

POST https://tenant.platform.mattr.global/v1/presentations/templates

Request

{
    "name":"did-presentation",
    "challenge": "99612b24-63d9-11ea-b99f-4f66f3e4f81a",
    "domain": "tenant.platform.mattr.global",
    "query": [
        {
            "type": "DIDAuth"
        }
    ]
}

The challenge can be used to identify which request the response is for.

The domain shows to the Mobile Wallet user which domain is asking for information. Based on who is asking for credentials, the holder may agree to send their DID to the relying party or verifier.

type is the request type of DID Auth.

Response

{
  "id": "aee61692-3568-484a-8eda-e150c48ec9e6",
  "name": "did-presentation",
  "domain": "tenant.platform.mattr.global",
  "query": [
    {
      "type": "DIDAuth"
    }
  ]
}

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:

POST https://tenant.platform.mattr.global/oidc/v1/verifiers

Request

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

The verifierDid specifies the DID where the Verifiable Presentation will be send to.

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

Response

{
  "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.

GET https://tenant.platform.mattr.global/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 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

POST https://tenant.platform.mattr.global/oidc/v1/verifiers/41458e5a-9092-40b7-9a26-d4eb43c5792f/clients
{
    "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 platform will create a new Client and provide a response:

Client-generated response

{
    "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:

{
    "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:

https://tenant.platform.mattr.global/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 platform has generated a QR code that can be used to point a device at your tenant.

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

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.

Prev

Create a Sovrin DID

Next

Issue a basic Credential