Learn how to build an application that can verify an mDoc from another app on the same device

Create a verifier application configuration

Each MATTR VII tenant can interact with multiple verifier applications, and can handle requests differently for each application. This means you must create a verifier application configuration that defines how to handle verification requests from your mobile application.

POST /v2/presentations/applications

{
  "name": "Verify with Wallet Application",
  "type": "ios",
  "teamId": "A2B3C4D5E6",
  "bundleId": "io.mattrlabs.dev.sampleApp.MdocSampleApp",
  "resultAvailableInFrontChannel": true
}

{
  "id": "0eaa8074-8cc4-41ec-9e42-072d36e2acb0"
  //... rest of application configuration
}

Configure a trusted issuer

You must configure trusted issuers on your MATTR VII verifier tenant, as presented mDocs will only be verified if they had been issued by a trusted issuer. This is achieved by providing the PEM certificate of the IACA used by these issuers to sign mDocs.

POST /v2/credentials/mobile/trusted-issuers

{
  "certificatePem": "-----BEGIN CERTIFICATE-----\nMIICYzCCAgmgAwIBAgIKXhjLoCkLWBxREDAKBggqhkjOPQQDAjA4MQswCQYDVQQG\nEwJBVTEpMCcGA1UEAwwgbW9udGNsaWZmLWRtdi5tYXR0cmxhYnMuY29tIElBQ0Ew\nHhcNMjQwMTE4MjMxNDE4WhcNMzQwMTE1MjMxNDE4WjA4MQswCQYDVQQGEwJBVTEp\nMCcGA1UEAwwgbW9udGNsaWZmLWRtdi5tYXR0cmxhYnMuY29tIElBQ0EwWTATBgcq\nhkjOPQIBBggqhkjOPQMBBwNCAASBnqobOh8baMW7mpSZaQMawj6wgM5e5nPd6HXp\ndB8eUVPlCMKribQ7XiiLU96rib/yQLH2k1CUeZmEjxoEi42xo4H6MIH3MBIGA1Ud\nEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMB0GA1UdDgQWBBRFZwEOI9yq\n232NG+OzNQzFKa/LxDAuBgNVHRIEJzAlhiNodHRwczovL21vbnRjbGlmZi1kbXYu\nbWF0dHJsYWJzLmNvbTCBgQYDVR0fBHoweDB2oHSgcoZwaHR0cHM6Ly9tb250Y2xp\nZmYtZG12LnZpaS5hdTAxLm1hdHRyLmdsb2JhbC92Mi9jcmVkZW50aWFscy9tb2Jp\nbGUvaWFjYXMvMjk0YmExYmMtOTFhMS00MjJmLThhMTctY2IwODU0NWY0ODYwL2Ny\nbDAKBggqhkjOPQQDAgNIADBFAiAlZYQP95lGzVJfCykhcpCzpQ2LWE/AbjTGkcGI\nSNsu7gIhAJfP54a2hXz4YiQN4qJERlORjyL1Ru9M0/dtQppohFm6\n-----END CERTIFICATE-----"
}

Create an Apple Identity Access certificate

To enable your MATTR VII tenant to interact with Apple Wallet as part of a remote verification workflow, you must create an Apple Identity Access certificate. This certificate is used to sign requests sent to the Verify with Wallet API.

Currently this action is not available in the MATTR Portal and can only be performed via an API request.

Make the following request to your MATTR VII tenant to create an Apple Identity Access certificate:

POST /v2/presentations/certificates/apple-identity-access-certificates

{
  "teamId": "A2B3C4D5E6",
  "merchantId": "com.domain.subdomain"
}

• teamId : Replace with your Apple Developer Team ID associated with your iOS application. You can find it in the Membership details section of your Apple Developer account.
• merchantId : Replace with the merchant ID you created as part of your Verify with Apple Wallet entitlement request.

Response

A successful 201 response indicates that the Apple Identity Access certificate was created successfully:

{
  "id": "fd44e792-45ac-11f0-bef8-bb24f133065e",
  "teamId": "A2B3C4D5E6",
  "merchantId": "com.domain.subdomain",
  "csrPem": "string"
}

Make note of the csrPem value, as you will need it in the next part to create a matching Apple Identity Access certificate in your Apple Developer account.

Environment setup

Create a new project

Follow the detailed instructions to Create a new Xcode Project and add your organization's identifier.

Unzip the dependencies file

1. Unzip the MobileCredentialVerifierSDK-*version*.xcframework.zip file.
2. Drag the MobileCredentialVerifierSDK-*version*.xcframework folder into your project.
3. Configure MobileCredentialVerifierSDK.xcframework to Embed & sign.

See Add existing files and folders for detailed instructions.

This should result in the following framework being added to your project:

Run the application

Select Run and make sure the application launches with a “Hello, world!” text in the middle of the display, as shown in the following image:

Configure application entitlement files

To enable your application to interact with the Apple Wallet, you must add the required capabilities in your Xcode project (see example below):

1. Add the In App Identity Presentment capability and define the document types and elements you want to request for verification. You can find a list of supported document types and elements in the Apple Developer documentation.
2. Add the In App Identity Presentment Merchant IDs and define the merchant IDs you created as part of your Verify with Apple Wallet entitlement request.

Identity Presentment capabilities

Identity Presentment capabilities configuration

Initialize the SDK

The first capability you will build into your app is to initialize the SDK so that the app can use its functions and classes.

mobileCredentialVerifier.initialize(
    platformConfiguration: {
        tenantHost: "https://learn.vii.au01.mattr.global"
    }
)

• tenantHost : Replace with the URL of your MATTR VII tenant.

Validate verification feasibility

Before displaying a Verify with Apple Wallet button, the SDK must confirm that the request can be met using the Apple Wallet. This includes validating:

• The identity of the verifier (using the provided merchantId).
• That the verifier is entitled to verify the requested credential type (using the provided docType in the credential request and comparing it against the entitlements associated with this merchantId).
• That the user has a credential that matches the requested docType in their Apple Wallet.

This is achieved by calling the fetchAppleWalletConfiguration method and providing the following parameters:

func fetchAppleWalletConfiguration(
    request: MobileCredentialRequest,
    applicationId: String,
    merchantId: String
) async -> Result<AppleWallet, MobileCredentialVerifierError>

• request : Pass a MobileCredentialRequest instance that defines what information is requested for verification (see example below). This will be used by the Verify with Wallet API to determine whether the requested credential type is supported by the entitlements associated with your application.
• applicationId : Replace with the identifier of the MATTR VII verifier application created above. This will be used later on by MATTR VII to identify your application and ensure that requests coming from it can be trusted.
• merchantId : Replace with the merchant ID you created as part of your Verify with Apple Wallet entitlement request. This is used by the Verify with Wallet API to determine whether this specific merchant is authorized to request the specified credential type.

If all checks pass, this method returns an instance of the AppleWallet class, which includes the UI elements and methods required to request a credential from an Apple Wallet.

Your application can then present one of the returned UI elements (for example a Verify with Apple Wallet button) to the user, which when tapped would invoke the Apple Wallet to request the credential for verification.

MobileCredentialRequest example

    let mobileCredentialRequest = MobileCredentialRequest(
        docType: "org.iso.18013.5.1.mDL",
        namespaces: [
            "org.iso.18013.5.1":  [
                "family_name": false,
                "given_name": false,
                "birth_date": false
            ]
        ]
    )

This object defines what information is required for verification:

• The requested credential type (e.g. org.iso.18013.5.1.mDL).
• The claims required for verification (e.g. family_name).
• The requested namespace (e.g. org.iso.18013.5.1).
• Whether or not the verifier intends to persist the claim value (true/false).

Request a credential from an Apple Wallet

Once the user taps the Verify with Apple Wallet button, you can call the requestMobileCredentials method to invoke the Apple Wallet and request the mDoc for verification:

func requestMobileCredentials(challenge: String) async throws -> OnlinePresentationSessionResult

• challenge : Unique UUID that must be generated by the verifier app. Should be a unique, unpredictable value generated for each verification session to mitigate replay attacks by ensuring the response from the Apple Wallet is tied to the current request and cannot be reused maliciously. Always generate a new challenge for every credential request.

Once called, this method would orchestrate the interaction to request the mDoc for verification from the Apple Wallet. The user would see the Apple Wallet popup interface, where they can select the credential to present for verification and provide their consent to share the requested information.

Display verification results and continue the interaction

After the user consents, Apple Wallet sends the encrypted credential to the MATTR VII tenant. The tenant decrypts and verifies it, then returns the verification results to your app as an OnlinePresentationSessionResult.

Your app should then:

• Validate the challenge in the OnlinePresentationSessionResult matches the one you sent in the request.
• Parse the OnlinePresentationSessionResult object to extract the verification results.
• Display the results to the user and continue the interaction accordingly.