Issue a credential using OIDC Bridge

Introduction

This guide will step through how to issue a credential to the MATTR Wallet once the MATTR tenant has been configured for Verifiable Credential issuance using an OpenID Connect Provider.

Prerequisites

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

• Access to MATTR VII APIs. If you’re experiencing difficulty, contact us.

• The DID (Decentralized ID) to use for issuing credentials. Take a look at Tenant Setup for more information.

• A correctly-configured OpenID Provider (OP). Have the client_id and client_secret close at hand.

• Set up an OIDC Credential Issuer and have the id.

• Download the MATTR Wallet and have it set up with a PIN.

If you’re experiencing any difficulties please contact us.

Configure Auth0 OIDC Provider

Open your Auth0 application and navigate to the ‘Settings’ tab.

Update the ‘Allowed Callback URLs’ to include the callbackUrl from the OIDC Credential Issuer you have created.

1https://YOUR_TENANT_URL/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599/federated/callback

Embed in a QR Code

A common way to allow a mobile wallet user to reference the issuer is to encode the openid:// URL within a QR code.

1openid://discovery?issuer=https://YOUR_TENANT_URL/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599&request_parameters={UrlEncoded({"login_hint": "xxx"})}

Remember the issuer is long-lived and can be referenced by many clients. You could even print out the QR code.

• https://www.the-qrcode-generator.com/

• https://www.qr-code-generator.com/

• http://goqr.me/api/

MATTR is not affiliated with any of these service providers and cannot vouch for their offerings.

Make sure to make the QR a decent size to be resolvable by a phone camera, 200px square is a fine.

Let’s use an API service to generate the QR code:

https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=openid://discovery?issuer=https://tenant.vii.mattr.global/ext/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599&request_parameters={UrlEncoded({"login_hint": "xxx"})}

Create a deep link to the Open ID endpoint

Alternatively, you can open the OIDC Credential Provider link directly from a mobile device by creating a Deep Link to the OpenID endpoint for the MATTR Wallet. This can be achieved using the MATTR Wallet bundle ID, along with the accept path and Base64Url encoding of the string.

1global.mattr.wallet://accept/{base64Url(openid://...)}

For example:

1global.mattr.wallet://accept/b3BlbmlkOi8vZGlzY292ZXJ5P2lzc3Vlcj1odHRwczovL1lPVVJfVEVOQU5UX1NVQkRPTUFJTi52aWkubWF0dHIuZ2xvYmFsL2V4dC9vaWRjL3YxL2lzc3VlcnMvOTgzYzBhODYtMjA0Zi00NDMxLTkzNzEtZjVhMjJlNTA2NTk5

Try it out

At this stage, you should be able to open the MATTR Wallet, either tap ‘Scan’, and point the camera at the QR code, or tap the deep link.

You will now see the Credential Offer on screen.

• You should see that the offer has been sent from a verified domain (your MATTR tenant).

• Tap ‘View’ to see the particulars of the offer.

• Tap ‘Proceed’ to move to the next step.

End-user authentication

Upon end-user acceptance of the offer:

• The MATTR Wallet retrieves the /.well-known/openid-configuration metadata values from the OIDC Issuer you configured.

• The MATTR Wallet creates a unique DID to be used for this interaction.

• The MATTR Wallet opens a WebView and navigate to the /authorize endpoint for the OIDC Issuer (the unique DID is included in this request).

• The OIDC Issuer redirects the end user to the configured federated provider within the WebView.

• The Federated Provider presents a login screen.

Having login_hint as request_parameters pre-populates the username in your Federated Provider's login screen. Any other request parameters are not supported by MATTR Wallet and SDK at the moment.

Credential issuance

Following successful end-user authentication via the federated provider:

• The ID Token from the federated provider is passed to the OIDC Issuer.

• The claims provided within the ID Token are used to create the credential (including the unique subject DID created above).

• Finally, the credential is passed to the MATTR Wallet wherein you can tap ‘View’ to inspect its contents.

This subject-bound Verifiable Credential is now saved in the MATTR Wallet and able to be presented to any requesting party. Such a presentation will usually also evidence ownership of the DID named as subject.

The issued credential will support revocation. For more information please see the credential revocation overview.

The metadata for the issued credential is held in a registry and can be retrieved via the list credentials endpoint. The tag in the credential metadata will be set to the sub value of the ID token of the federated provider.

For more information on holding the credential in a registry, please see Hold a Credential in a Registry.

Troubleshooting

You may encounter some technical difficulties while running this tutorial. Below are a few common problems and their solutions.

The app opens but refuses to show the credential being offered

• Check that you have encoded the Issuer Id correctly in the QR code

• Your phone will need public internet access. Check it can access common websites.

• Check that you can open the exact URL embedded in the code

Scanning the QR code using the phone’s camera doesn’t open the app (opens Google search or tries to load in the browser and fails)

• Make sure you have the MATTR Wallet set up with a PIN

• Make sure the QR is large enough to be read by your phone; try creating a larger QR Code (say 300 x 300 px)