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:
- Access to the MATTR Platform APIs. If you’re experiencing difficulty, contact us.
- Know the DID (Decentralized ID) to use for receiving Credentials, 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 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.