Implementation considerations

This document provides an overview of key product and user experience (UX) considerations for organizations designing and implementing digital credential solutions using MATTR issuance capabilities.

It outlines decisions to make across the credential lifecycle, from data modeling and issuance through status management, and describes how current and upcoming MATTR capabilities can support these choices.

At a high level, credential issuance involves three steps:

1. The issuer offers a credential.
2. The holder accepts the offer, collects the credential and stores it in a digital wallet application.
3. The holder later presents it to a verifier when required.

Within this lifecycle, there are several key decisions to make that will shape the user experience and technical implementation.

How will you structure your credential?

Credential data and structure

Before issuing credentials, define what data will be included and how it will be structured to ensure interoperability and compliance.

• Credential Data Mapping: Map existing data models (e.g., from legacy digital credentials or other data sources) to the relevant ISO/IEC 18013-5 (or equivalent) schema.
• Custom Namespaces: Use custom namespaces to represent organization-specific claims that are not part of the ISO/IEC 18013-5 (or equivalent) schema.

This structure is manifested in the credential configuration within the MATTR issuance platform. Refer to the Credential Configuration Overview for more details.

Integrating external data sources

Consider whether to integrate external data sources (e.g., government databases, organizational records) to enrich credential data or validate information during issuance. This is referred to as a Claims Source in the MATTR issuance platform.

• The claim source should expose required data in the format expected by MATTR VII.
• All claim mapping logic, including translation of custom or legacy fields, should occur in the claim source.
• Non-standard claims can be expressed using custom namespaces.

Refer to the Claims Source Overview for more details.

How will you offer the credentials to the user?

Consider how users will discover and access the credentials you issue. MATTR VII supports multiple methods for offering credentials, each suited to different user experiences and contexts:

• QR Code: Generate a QR code that users can scan with their mobile device to initiate the issuance process.
• Deep Link: Provide a deep link (URL) that users can click to start the credential issuance flow.
• Deep Link: Provide a clickable URL that users can access from an email, mobile browser, or mobile app to start the credential issuance flow.
• Silent Push: Credentials can be issued silently to authenticated users within an existing app session, requiring no user interaction.

How will you issue credentials to users?

Consider how to issue the credentials to your users. MATTR VII supports two main issuance workflows, each suited to different use cases and user experiences:

• Authorization Code Flow: In this flow users must authenticate before they can claim the credential. It is typically used when credentials are offered publicly (e.g., via QR code or website).

  • Supports integration with authentication providers (to authenticate the user) and claim sources (to populate credential data).
  • Interaction hooks allow additional steps like biometric or liveness verification.
  • Refer to the Authorization Code Overview for more details.

• Pre-Authorized Code Flow: In this flow users are not required to authenticate before they can claim the credential. For high assurance credentials, the assumption is that the issuer has already authenticated and authorized the user through other means before sharing the credential offer with them.

  • Supports issuing credentials to known users through secure channels (e.g., inside an existing app session).
  • Suitable for silent issuance or updates to existing credentials.
  • Claims source integration not required if systems of record can provide credential data when creating the credential offer.
  • Optional transaction codes can add 2-factor security.
  • Refer to the Pre-Authorized Code Overview for more details.

How will the user collect the credential?

When generating a credential offer, issuers can influence which wallet applications are able to claim the offer and how the user experience flows. This involves both user experience considerations and security, privacy, or commercial requirements where you want a specific app to claim the credential:

• Open model: Users can use any compatible app to claim the credential.
• Restricted model: Users can only use specific apps to claim the credential using unique custom schemes or app links/universal links.

This will also affect, for example, whether the user is prompted to select an app when they scan a QR code or click a link, or whether they are taken directly to a specific app.

Refer to Claiming credential offers for more details.

How will you manage credential status?

Credentials may need to be revoked or suspended after issuance. MATTR provides a status list mechanism to manage credential states (valid, suspended, revoked, etc.).

The issuer configures and publishes a status list that verifiers can retrieve to determine the current status of a credential. Consider how you will implement this in your solution:

• Define how often apps should fetch updated status lists using the Time to Live (ttl) and Expiry (exp) parameters:
  • ttl: Recommended duration for using a retrieved copy of a status list before retrieving the latest one. This guides best practices to ensure relying parties are using the most up-to-date mDocs status in their verification workflows. This is set to one day by default but can be adjusted based on your use case.
  • exp: Retrieved status lists cannot be used after this time. This ensures relying parties do not use stale status lists beyond a certain point. This is set to seven days by default but can be adjusted based on your use case.
• Apps can rely on cached statuses between TTL and expiry to maintain offline usability. Setting appropriate values balances up-to-date status checking with user experience and app performance.
• Consider how to notify users if their credentials are revoked or suspended.

Refer to Credential revocation for more information.

How will you manage your issuer keys and certificates?

Secure key management is critical for maintaining the integrity and trustworthiness of issued credentials, and issuers must securely manage private keys and certificates used to sign credentials using one of the methods supported by MATTR issuance capabilities:

• MATTR managed Key Management Service (KMS): Key management solutions provided by MATTR for secure key storage and management. Refer to the PKI Spec sheet for more information.
  • Software Security Module (SSM): MATTR’s default storage option for managing issuer certificates.
  • Hardware Security Module (HSM): Available for issuers requiring hardware-based key protection (online and offline HSM options available).
• External KMS: MATTR supports integration with third-party KMS providers for organizations with existing key management solutions. Refer to external certificates for more information.