Issuing and verifying verifiable credentials with MATTR utilizing Asgardeo

The Verifiable Credentials concept is becoming exponentially widespread in diverse industries all around the world, with growing use cases …

Verifiable credentials can be depicted as a digitalized representation of paper-based credentials and can be stored in a digital wallet. Those credentials can be cryptographically verified, providing more tamper-evident and security than in their physical forms. It offers the holder to have ownership and control to manage the credentials and address many more issues in traditional verification systems.

If you/your organization are already managing user accounts in an OpenID Connect provider, you can use the OpenID Connect login to share user attributes to offer verifiable credentials.

This blog illustrates how to conduct the following flows using MATTR and Asgardeo, where MATTR furnishes as a decentralized identifiers managing platform for verifiable credentials issuing, management, and verification, while Asgardeo is acting as the OpenID Connect Identity Provider.

1. Configuring MATTR to connect to Asgardeo with OpenID Connect.
2. Issuing verifiable credentials to MATTR Wallet.
3. Verifying credentials presented by the Wallet holder.

Configuring MATTR to connect to Asgardeo with OpenID Connect

Issuing Verifiable Credentials with MATTR utilizing Asgardeo

Follow the below instructions to issue verifiable credentials using MATTR with Asgardeo.

Configuring Asgardeo

1. Sign up to Asgardeo https://wso2.com/asgardeo/ and create a tenant.
2. Next, create a OIDC application in Asgardeo. Navigate to Deploy > Application , click on +New Application , and select Traditional Web Application . Select OpenID Connect protocol and click Register to complete the registration. Refer Asgardeo official documents on registering OIDC application for any clarification.
   Take note of the Client ID and Client secret, you need them to configure the MATTR credential issuer later.
3. Go to Info tab and take a note of the token URL which will be needed later.
4. Go to the User Attributes tab, and click Add User Attribute . Add user attributes that you need to offer as verifiable credentials and make them mandatory. Eg: Email , First Name , Last Name, Birth Date attributes. Click on Update button.
   Refer enable-attributes-for-oidc-app for more details.

Next, only if you do not have any user account in Asgardeo, follow the below instructions to create a new user.

Creating user

1. Go to Manage >Users and click on +customer button. Create a user by filling required fields. Refer the Asgardeo official documentation for user account management.
   Later, the user is required to log in to the Asgardeo with user credentials to obtain verifiable credentials from MATTR Wallet.

Configuring MATTR and create a credential issuer

1. Visit https://mattr.global/ and create a MATTR account. Keep safe Client ID , Client Secret , and Tenant Domain .

Here onward, MATTR client id will refer as <MATTR_CLIENT_ID>, client secret as <MATTR_CLIENT_SECRET> and tenant domain as {tenant-subdomain} or <TENENT_DOMAIN>.

2. Get an access token for the MATTR tenant with below cURL command.

curl -i -X POST "https://auth.mattr.global/oauth/token" \
-H "Content-Type: application/json" \
-d '{ 
     "client_id": "<MATTR_CLIENT_ID>",
     "client_secret": "<MATTR_CLIENT_SECRET>",
     "audience": "https://vii.mattr.global", 
     "grant_type": "client_credentials" 
   }'

Value of access_token parameter in the response body will refer as <BEARER_TOKEN> here onward.

3. Create a MATTR DID with a BLS key type which supports BBS+ signatures.

curl -i -X POST "https://{tenant-subdomain}.vii.mattr.global/core/v1/dids" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{ 
     "method": "key",
     "options": {
       "keyType": "bls12381g2"
     }
   }'

The value of did parameter in the response body will refer as <DID_ID>.

4. Next, create a MATTR credential issuer. Provide <ISSUER_NAME> and <CREDENTIAL_TYPE> with a meaningful values. Replace <TOKEN_ENDPOINT_URL>with Asgardeo token endpoint URL, <OIDC_APP_CLIENT_ID> with OIDC application ID, and <OIDC_APP_CLIENT_SECRET> with the OIDC application secret which you take configured under Configuring Asgardeo section.

curl -i -X POST "https://{tenant-subdomain}.vii.mattr.global/ext/oidc/v1/issuers" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
     "credential": {
       "issuerDid": "<DID_ID>",
       "name": "<ISSUER_NAME>",
       "context": [
         "https://schema.org"
       ],
       "type": [
         "VerifiableCredential",
         "<CREDENTIAL_TYPE>"
       ]
     },
     "federatedProvider": {
       "url": "<TOKEN_ENDPOINT_URL>",
       "scope": [
         "openid",
         "profile",
         "email"
       ],
       "clientId": "<OIDC_APP_CLIENT_ID>",
       "clientSecret": "<OIDC_APP_CLIENT_SECRET>"
     },
     "claimMappings": [
       {
         "oidcClaim": "email",
         "jsonLdTerm": "email"
       },
       {
         "oidcClaim": "given_name",
         "jsonLdTerm": "given_name"
       },
       {
         "oidcClaim": "birthdate",
         "jsonLdTerm": "birthdate"
       },
       {
         "oidcClaim": "family_name",
         "jsonLdTerm": "familyName"
       }
     ]
   }'

You can configure the credential claims that you need offer as verifiable credentials for Wallet holder by adding them in the claimMappings paramter in the request payload. MATTR supporting Credential Claims Mappings can be found from https://learn.mattr.global/tutorials/web-credentials/issue/oidc-bridge/common-mappings

The id parameter in the response will refer as {issuer-id} in the QR code displaying step.

5. Next, need to configure the value of the callbackUrl parameter under federatedProvider in the above response(step 4) body as a authorized redirect URL for the OIDC application. It can be configured by login in to the Asgardeo Console https://console.asgardeo.io/, and navigating Develop > Applications and select your OIDC application, then add the URL in Authorized redirect URLs under Protocol tab.

Issuing verifiable credentials to MATTR Wallet

Display QR code to obtain verifiable credentials

Get a QR code which can be scanned to obtain verifiable credentials from the MATTR Wallet.

https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=openid://discovery?issuer=https://{tenant-subdomain}.vii.mattr.global/ext/oidc/v1/issuers/{issuer-id}

Obtaining verifiable credentials with MATTR Wallet.

1. Download the MATTR wallet to your mobile phone. see this documentation from MATTR https://learn.mattr.global/tutorials/get-started/wallet.
2. Go to the MATTR wallet and scan the QR code.
3. Click the proceed button and log into your account in the Asgardeo with user credentials.

Now you can view your credentials in your MATTR Wallet.

Verifying credentials

Verifying Verifiable Credentails

Here, the credential verification is performed using a Callback. For bellow steps, you can use previously created MATTR tenant, or new tenant. If you are using new MATTR tenant, need to obtain a new access token for the new tenant.

1. Create a credential presentation template with MATTR. Replace <TEMPLATE_NAME> with meaningful value, and <CREDENTIAL_TYPE> with same value used in the issuer creation step.

curl -i -X POST "https://{tenant-subdomain}.vii.mattr.global/core/v1/presentations/templates" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
     "domain":"<TENENT_DOMAIN>.vii.mattr.global",
     "name":"<TEMPLATE_NAME>",
     "query": [{
       "type":"QueryByFrame",
       "credentialQuery":[
         {
           "reason": "Please provide your educational award and surname from your Certificate",
           "frame":{
             "@context":[
               "https://www.w3.org/2018/credentials/v1",
               "https://w3id.org/security/bbs/v1",
               "https://mattr.global/contexts/vc-extensions/v1",
               "https://schema.org",
               "https://w3id.org/vc-revocation-list-2020/v1"
            ],
           "type": ["VerifiableCredential", "<CREDENTIAL_TYPE>"],
           "credentialSubject":{
             "@explicit":true,
             "given_name":{}
           }
         },
         "trustedIssuer":[
           {
             "issuer":"<DID>",
             "required":true
           }
         ],
         "required":true
         }
       ]
     }]
   }'

2. Next, create a Presentation Request. Note this should be performed every time a Presentation is requested. <CHALLENGE> is needs to be a unique identifier per transaction, where it can be used as an interaction id. The <CALLBACK_URL> defines the path that verification response need to be sent.

Note: The Presentation Request does not support DID with a BLS key type which we created earlier. You may need to create a new DID by removing keyTpye in options in the credential issuer creation request body.

curl -i -X POST "https://{tenant-subdomain}.vii.mattr.global/core/v1/presentations/requests" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
     "challenge": "<CHALLENGE>",
     "did": "<NON_BLS_DID>",
     "templateId": "<TEMPLATE_ID>",
     "callbackUrl": "<CALLBACK_URL>"
   }'

The request in response body will refer as <RESPONSE_PAYLOAD> .

3. The presentation request body is required to be signed with the authentication key of the Verifier DID and Encode. The authentication key can retrieve with bellow the cURL command.

curl -i -X GET "https://{tenant-subdomain}.vii.mattr.global/core/v1/dids/{MATTR-Non-BLS-DID}" \
-H "Authorization: Bearer <BEARER_TOKEN>"

The authentication parameter under didDocument in the response body will refer as <DID_URL> .

4. Next, sign the presentation request body with DID URL.

curl -i -X POST "https://{tenant-subdomain}.vii.mattr.global/core/v1/messaging/sign" \
-H "Authorization: Bearer <BEARER_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
     "didUrl": "<DID_URL>",
     "payload": <RESPONSE_PAYLOAD>
   }'

Value of the jws is refer as the {jws} in the next step.

5. Create a QR code with MATTR Wallet to request credentials.

https://api.qrserver.com/v1/create-qr-code/?size=400x400&data=didcomm://https://{mattrTenantDomain}.vii.mattr.global/?request={jws}

6. Scan the QR code with the MATTR Wallet, and click on Send button.

Callback endpoint you configured in the presentation request receives verification response and requested credentials, once the wallet holder sends them.

{
  presentationType: 'QueryByFrame',
  challengeId: 'GW8FGpP6jhFrl37yQZIM6w',
  claims: {
    id: 'did:key:z6MkisTmUeMWzqbwxTad2jrhoAXrLZN1BggiYUNsVBR7FUYW',
    'http://schema.org/birthdate': '1996-09-05'
    'http://schema.org/given_name': 'john'
  },
  verified: true,
  holder: 'did:key:z6MkisTmUeMWzqbwxTad2jrhoAXrLZN1BggiYUNsVBR7FUYW'
}

By following above instructions, verifiable credentials can be issued for wallet holders and verified them with MATTR utilizing Asgardeo.