OpenID4VCI Tutorial

Configure an Auth0 application

Let’s start by configuring an Auth0 application. This application will be used to authenticate the user as part of the OID4VCI workflow.

Create a new Auth0 application

1. Log into Auth0.
2. Skip the Auth0 onboarding tutorials and go straight to your Dashboard.
3. Select Create Application.
4. Insert a Name for your application.
5. Select Regular Web Application.
6. Select Create.
7. Select Skip Integration.

Your application is created and you will be redirected to the Settings tab under the Applications section.

8. Record your application Domain, Client ID and Client Secret.
9. Add a simple Description.
10. Scroll down to the Application URIs area, locate the Allowed Callback URLs textbox and insert the following URL: https://{your_tenant_url}/core/v1/oauth/authentication/callback (make sure you replace {your_tenant_url} with the tenant_url provided with your MATTR VII access credentials.)
11. Select the Connections tab.
12. Enable Username-Password-Authentication under Database.
13. Disable everything under Social.

Create a User

1. Select the User Management menu on the left hand side navigation panel and select Users.
2. Select the Create User button.
3. Add an Email. This must be different to the one you use to sign up to your Auth0 account.
4. Add a password.
5. Select Username-Password-Authentication from the Connection dropdown list.
6. Select Create. You will be redirected to the new user’s Details tab.
7. Select Edit under Name and replace the value (Auth0 uses the email by default) with the full user name.

Obtain a MATTR VII access token

Now that we have an Auth0 application set up, we continue the rest of the workflow configuration on your MATTR VII tenant. All of the MATTR VII endpoints we will use in this tutorial are protected, so you will first need to use your login credentials to make a request of the following structure and obtain an access token:

Request

POST https://{auth_server}/oauth/token

• auth_server : Replace with the auth_url value from your login credentials.

Request body

{
    "client_id": "F5qaeLDdbvnU9zhA0j4eHUGCHwC1bKtt",
    "client_secret": "Wzc8J**********************************************************",
    "audience": "learn.vii.au01.mattr.global",
    "grant_type": "client_credentials"
}

• Replace client_id, client_secret and audience with your own login credentials.
• Keep grant_type as client_credentials.

Response

{
    "access_token": "eyJhb********************************************************************",
    "expires_in": 14400,
    "token_type": "Bearer"
}

Use the returned access_token value as a bearer token for all requests to your MATTR VII tenant in the next steps of this tutorial.

Configure a MATTR VII Authentication provider

Now that you have an access token, we can make a request to create an Authentication provider configuration based on the details of your Auth0 application. This will be used to authenticate users as part of the OID4VCI workflow.

Request

Make the following API request to your MATTR VII tenant:

POST /v1/users/authentication-providers

Request body

{
    "url": "https://example.us.auth0.com/",
    "scope": ["openid"],
    "clientId": "zH1IGGkRo6q0ofwiNJnlY0bg9fchw3s0",
    "clientSecret": "***********************************************************LFRrZ",
    "tokenEndpointAuthMethod": "client_secret_post",
    "staticRequestParameters": {
        "prompt": "login",
        "maxAge": 10000
    }
}

• url: Replace with your Auth0 application Domain. Make sure you prefix it with https.
• clientId: Replace with your Auth0 application Client ID.
• clientSecret: Replace with your Auth0 application Client Secret.

Create issuer certificates

In this tutorial we are going to issue an mDoc, so we need to have valid IACA and DSC certificates.

Create an IACA

Make the following request to your MATTR VII tenant to create an IACA:

POST /v2/credentials/mobile/iacas

Create a DSC

Make the following request to your MATTR VII tenant to create a DSC:

POST /v2/credentials/mobile/documentsigners

Request body

{
    "active": true
}

Create a MATTR VII mDocs credentials configuration

Now that we have valid certificates in place, the next component we need is a Credential configuration to define the structure and branding of the issued credential.

Request

Make the following request to create a simple mDoc credential configuration that includes the holder’s first name, last name and e-mail:

POST /v2/credentials/mobile/configurations

Request body

{
    "type": "com.example.myfirstcredential",
    "expiresIn": {
        "months": 1
    },
    "claimMappings": {
        "com.example.personaldetails.1": {
            "first_name": {
                "mapFrom": "claims.first_name",
                "type": "string"
            },
            "last_name": {
                "mapFrom": "claims.last_name",
                "type": "string"
            },
            "date_of_birth": {
                "mapFrom": "claims.date_of_birth",
                "type": "date"
            }
        }
    },
    "branding": {
        "name": "My First Credential",
        "description": "For High Assurance Interactions",
        "backgroundColor": "#2d46d8"
    }
}

Response

The response will include an id element. You will use it to create a Credential offer in the next step.

Create a Credential offer

We now have all the pieces in place and we can wrap them all together to generate a Credential offer and share it with the intended holder so that they know what credentials are being offered and by whom.

Request

Make the following request to generate a new Credential offer:

POST /v1/openid/offers

Request body

{
    "credentials": ["945214ad-3635-4aff-b51d-61d69a3c8eee"]
}

• 945214ad-3635-4aff-b51d-61d69a3c8eee: Replace with the id element returned in the response when you created an mDocs credentials configuration in the previous step.

Response

The response will include a uri element which can be used by a digital wallet to trigger the OID4VCI workflow. Use one of the following tools to convert the uri value to a QR code (make sure you use the Plain text option where available):

• https://www.the-qrcode-generator.com/
• http://goqr.me/api/
• https://www.qr-code-generator.com/

Save the generated QR code on your computer.

Use the MATTR Showcase Wallet to claim the credential

1. Open the MATTR Showcase wallet app.
2. Select Scan.
3. Scan the QR code generated in the previous step.
4. Review the credential offer and select Accept.
5. Follow the issuance workflow instructions to claim the credential.

Congratulations, you just configured an end-to-end OID4VCI workflow to issue an mDoc into a digital wallet!!!