MATTR

MATTR is building tools and working alongside communities who want to transform the internet into a web of trust and restore trust and confidence in digital interactions.

With MATTR and Auth0, you can issue verifiable credentials to end-users from data stored about them in Auth0, enabling decentralized identity use cases from your existing Auth0 setup. Verifiable credentials are reusable, portable and can cross different domains, decoupling a user’s identity from their provider. Users can manage their credentials in a digital wallet under their control and choose how and when they want to share information with relying parties.

Learn more with the following videos

Introduction to The Decentralized Identity Ecosystem
MATTR's Luke McIntyre (Chief Product Officer) and John Thompson (Product Manager) gives us an introduction to the world of digital trust and decentralized identity. This video will take you from the current state of managing multiple digital identities right through to unlocking the business value from verifiable credential ecosystems.

Issuing Verifiable Credentials with OpenID Connect Bridge
MATTR's Preet Patel (Developer Advocate) demos how you can issue credentials with an existing OpenID Connect provider and MATTR's OIDC Bridge Extension. Preet takes you through the steps of how to setup an issuer, a verifier and what you will see once the setup is successful.

By leveraging the MATTR VII OIDC Bridge this integration provides the ability to create client-bound verifiable credentials using user metadata from the Auth0 user store.

Once configured you’ll be able to offer verifiable credentials to end-users with compatible digital wallets, e.g. the MATTR Mobile Wallet App, so they can hold and control their own credentials.

MATTR VII and Auth0 working together

MATTR VII provides an extensible platform capable of managing decentralized identifiers, the creation of as well as verification of standard-based verifiable credentials and by using the OIDC Bridge, can map existing identity protocols with decentralized identity methods.

This integration enables the following process flow:

1. Display a QR code or send a deep link to present a credential offer
2. A User scans the QR code using their Digital Wallet Mobile App
3. The wallet creates an authorization request to the OIDC Bridge and invokes a web-view
4. The OIDC Bridge redirects the request to your Auth0 tenant application
5. The User can authenticate directly on your Auth0 tenant login screen
6. Using Rules configured in Auth0, data from the the authenticated user’s user_metadata is included in the ID token
7. The resulting ID token is passed to the OIDC Bridge
8. The OIDC Bridge uses configuration along with a signed Request token from the auth and the claims from the ID token to issue a Verifiable Credential, signed by a Decentralized Identifier.
9. The resulting credential is passed to the Digital Wallet Mobile App, where the user can hold it

Prerequisites

You will need a MATTR VII account with API credentials and a decentralized identifier (DID) established using a DID method that meets your requirements as an Issuer. A DID with a bls key type is recommended as it will result in the more privacy-preserving ZKP-enabled credential based on BBS+ signatures.

This integration will also use the OIDC Bridge extension, so ensure this is included as part of your account setup.

Contact MATTR if you need help with any of the steps in this integration.

In order to test the end-to-end integration, you will need to download the MATTR Wallet Mobile App for either iOS or Android.

Configure Auth0

Create a new Application

1. Go to Auth0 Dashboard > Applications > Applications.
2. Add a meaningful name like "MATTR Verified Credentials Issuer".
3. Select Regular Web Application, then Create.
4. Select the Settings tab and make note of the Domain, Client ID, and Client Secret.
5. Add https://example.com/callback to the Allowed Callback URLs field; this will be updated with a value from the Issuer later.

Create a test User

1. Go to Auth0 Dashboard > User Management > Users.
2. Select Create User.
3. Enter an Email and Password.
4. Select the Database Connection that is active for the Application created above.
5. Select Create.
6. Scroll to Metadata > user_metadata and add additional information that will ultimately appear in the issued Verifiable Credential.

{
     "educationalCredentialAwarded": "Certificate Name",
    // ...
}

Create an OIDC Credential Issuer in MATTR VII

Obtain a valid access token using your MATTR VII API credentials and lookup or create a valid DID that exists on your MATTR VII tenant that can be used as the IssuerDid to issue credentials.

Next, create an OIDC Credential Issuer using the following payload with a few replacements:

• Replace AUTH0_TENANT_DOMAIN with the Domain from above
• Replace AUTH0_CLIENT_ID with the Client ID from above
• Replace AUTH0_CLIENT_SECRET with the Client Secret from above

{
    "credential": {
        "issuerDid": "MATTR_DID_IDENTIFIER",
        "name": "Educational Credential Awarded",
        "context": [ "https://schema.org" ],
        "type": [ "Course" ]
    },
    "federatedProvider": {
        "url": "AUTH0_TENANT_DOMAIN",
        "clientId": "AUTH0_CLIENT_ID",
        "clientSecret": "AUTH0_CLIENT_SECRET",
        "scope": [ "openid", "profile", "email" ],
    },
    "claimMappings": [
        {
            "jsonLdTerm": "givenName",
            "oidcClaim": "given_name"
        },
        {
            "jsonLdTerm": "familyName",
            "oidcClaim": "family_name"
        },
        {
            "jsonLdTerm": "educationalCredentialAwarded",
            "oidcClaim": "https://vii.mattr.global/educationalCredentialAwarded"
        }
    ]
}

Credential

The credential object defines which issuerDid to use (steps to create a DID), the meaningful name of the credential that will appear in the digital wallet, the JSON-LD context and credential type, which should express type information that other systems can use to determine if the type is appropriate.

On Issue, the type verifiableCredential is always added as the first item in the array.

Note on context: this needs to be a resolvable vocabulary that describes the information used in the credential, JSON-LD is used in the issuance of credentials.

Federated provider

The federatedProvider object defines the attributes of your Auth0 tenant configuration including:

• url - set this to the Domain from the Application above
• clientId - set this to the Client ID from the Application above
• clientSecret - set this to the Secret from the Application above
• scope - required to invoke claims

Claim mappings

The claimMappings collection defines the subject claims for the credential by mapping OpenID Connect claims from the Auth0 ID token to JSON-LD terms that will be used when creating the Verifiable Credential along with the context provided in the credential object as the data vocabulary.

Currently, the platform only supports schema.org as a data vocabulary, please contact us if you wish to explore other options.

• oidcTerm is the OIDC claim name
• jsonLdTerm is the JSON-LD term name

Use the payload of your ID token to obtain the exact field name used and map the required fields to a valid JSON-LD term from schema.org.

The common OIDC claims are already mapped for you here, so you can copy and paste these into your claimMappings collection if needed.

Only claims you explicitly map to JSON-LD terms will appear in the issued credential; all other claims in the ID token will be disregarded.

The entire Schema.org list of JSON-LD terms can be accessed directly and used to look up terms. Use the rdfs:label value.

Response

The callbackUrl property in the federatedProvider object must be added to the Allowed Callback URLs field of the Auth0 Application crated above.

You now have an OIDC Credential Issuer configured for Verifiable Credential issuance.

Create a Rule in Auth0

A Rule is used to add properties from user_metadata to an ID token alongside the standard OIDC claims - given_name, family_name, etc. - so it can be consumed by the MATTR VII OIDC Bridge and used to create a verifiable credential.

Create a new Rule in Auth0 using the code below:

function mattrVerifiedCredentials(user, context, callback) {
    const metadata = user.user_metadata || {};

    if (metadata.educationalCredentialAwarded) {
        const idTokenClaim = "https://mattr.global/educationalCredentialAwarded";
        context.idToken[idTokenClaim] = metadata.educationalCredentialAwarded;
    }

    callback(null, user, context);
}

Add additional claims to the ID token based on attributes in your users' metadata but remember they also need to appear in the mapping configuration of the OIDC Issuer to ensure the claims appear in the issued verifiable credential. OIDC Issuer has an update operation that can be invoked to update the mappings or any other configuration changes as needed.

Try it out

Once your configuration is completed, you need to start the "Obtain a Credential" flow using the MATTR Wallet app

In order for a user of the app to know you can offer them a digital verifiable credential, you need to direct them towards the OIDC Bridge configured on your tenant. One of the ways to achieve this is outlined below.

Use a QR code

A common way is to create a QR code, which can be scanned by using the MATTR Wallet app. Construct the QR payload using your MATTR VII tenant url and the uuid of the Issuer you have created, like this:

openid://discovery?issuer=https://tenant.vii.mattr.global/oidc/v1/issuers/983c0a86-204f-4431-9371-f5a22e506599

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

Once the QR code is generated, open the MATTR Wallet app's Scan screen and put the QR code in frame. The app will recognise the embedded URL and fetch the OIDC Bridge Issuer information from the discovery endpoint. The wallet will then show you a screen displaying the Credential Offer. Once you provide consent that you wish to continue, a webview is opened to navigate to the OIDC Bridge. The OIDC Bridge will redirect to you Auth0 Login page to authenticate.

When authentication is complete, the webview is closed and your newly created Verifiable Credential is available to be viewed. Check to confirm all the correct attributes are shown.

Troubleshooting

I cannot access the MATTR VII APIs, I get an unauthorized

• Make sure you can obtain your access token from the https://auth.mattr.global/oauth/token endpoint.
• Check to make sure your tenant subdomain is correct in the calls you are making.

I receive a ‘callback not found’ message

• Ensure that the MATTR OIDC Bridge Issuer callback URL is added to the Auth0 application under Allowed Callback URLs.

I receive a ‘Hmm.. we cannot process this type of code’ error when scanning a QR code

Make sure you have encoded the URL correctly using the openid:// scheme and that your tenant subdomain and Issuer UUID are correct.