Introduction

This guide will step through how to issue a Web Credential to a supporting digital wallet – such as the MATTR Wallet – once your MATTR VII tenant has been configured for credential issuance using the OpenID Credential Provisioning capability. As a reminder, OpenID Credential Provisioning is based on the OpenID4VCI protocol and conforms to the necessary requirements.

Prerequisites

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

• The ID of a credential configuration you'd like to issue.

• Ensure that you have set up any necessary interaction hooks and data sources.

• Download the MATTR Wallet and have it set up.

If you’re experiencing any difficulties with any of the above, please contact us.

Create a credential offer

To issue a credential using the OpenID Credential Provisioning capability, a credential offer first needs to be set up.

The credential offer specifies the details of the credentials that will be created, including the issuer URL; authorisation and token endpoints; and the format, type and scope of the credentials. 

The information to construct an OpenID4CVI credential offer is exposed by the OpenID Provider via a well-known endpoint (eg. GET /.well-known/openid-credential-issuer).

The credential offer can be generated using the following request.

Request

1POST https://YOUR_TENANT_URL/v1/openid/offers

1{
2  "credentials": ["20d6bbe6-a978-447c-b5bd-f33b6dca19e2"],
3  "request_parameters": {
4    "login_hint": "user@example.com",
5    "prompt": "login"
6  }
7}

• credentials is a list of credential id(s) which be obtained when you setup the credential configuration.

• requestparameters is optional but if included contains the login_hint and prompt. request_parameters used to specify a list of additional request parameters that the wallet client would include in the authorisation request to MATTR VII.

An Issuer must use the same DID to issue all credentials offered as part of the configured issuance flow. Using different DIDs to offer different credentials is not currently supported by MATTR VII.

Response

1{
2  "uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Ftenant.vii.mattr.global%22%2C%22credentials%22%3A%5B%2220d6bbe6-a978-447c-b5bd-f33b6dca19e2%22%5D%2C%22request_parameters%22%3A%7B%22login_hint%22%3A%22user%40example.com%22%2C%22prompt%22%3A%22login%22%7D%7D"
3}

The credential offer URI generated is provided in response and can be shared with users by encoding in a QR code, creating a deep link or sending a secure DID message.

Embed in a QR Code

A common way to allow a mobile wallet user to reference the issuer is to encode the offer URI retrieved from the above endpoint into a QR code.

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/

• http://goqr.me/api/

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

Make sure the QR code is large enough in size to be resolvable by a phone camera; 200px square is generally fine.

Here's an example of using an API service to generate the QR code:

https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Ftenant.vii.mattr.global%22%2C%22credentials%22%3A%5B%2220d6bbe6-a978-447c-b5bd-f33b6dca19e2%22%5D%7D

Create a deep link to the Open ID endpoint

Alternatively, you can open the OpenID credential offer 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-credential-offer://...)}

For example:

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

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 the 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

After the end-user accepts the offer:

• The MATTR Wallet retrieves the /.well-known/openid-credential-issuer metadata values from the OpenID provider.

• The MATTR Wallet opens a WebView and performs an authorisation request with the credential issuer.

• The user is then redirected to any interaction hooks that are configured.

Having login_hint  as request_parameters pre-populates the username in your authentication provider's login screen and prompts users to log in even if they’re logged in already. Any other request parameters are not currently supported by the MATTR Wallet and SDK. 

Credential issuance

Following successful end user authentication via the authentication provider:

• The access token from the credential issuer is passed to the wallet.

• The wallet will use the access token to request credentials from the credential issuer. Also, the wallet creates a unique DID for each credential it requests and binds it to the credential subject.

• 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 can 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 userId.

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

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

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 (e.g., 300 x 300 px).