Build a mobile application that can verify an mDoc from an Apple Wallet installed on the same device

1. In the navigation panel on the left-hand side, expand the Credential Verification menu.
2. Select Applications.
3. Select Create new.
4. Enter a meaningful Name for your application (e.g. "Verify with Wallet Application").
5. Use the Type dropdown to select iOS as you are building an iOS application.
6. Enter your Apple Developer Team ID in the Team ID field. You can find it in the Membership details section of your Apple Developer account.
7. Enter your iOS application bundle identifier in the Bundle ID field. This is the unique identifier of your iOS application, which you can set in your Xcode project settings. This will be used by the MATTR VII tenant to validate incoming requests are from a known and trusted application.
8. Select Create.

Make the following request to your MATTR VII tenant to create a verifier application configuration:

POST /v2/presentations/applications

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

• name : You can use whatever name you'd like, as long as it is unique on your tenant.
• type : Use ios as you are building an iOS verifier application.
• 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.
• bundleId : Replace with your iOS application bundle identifier. This is the unique identifier of your iOS application, which you can set in your Xcode project settings. This must match the bundle ID you included in your Verify with Apple Wallet entitlement request.
• resultAvailableInFrontChannel : Setting this to true makes the verification results available directly to the verifier application.

Response

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

• id : You will use this value later to initialize the SDK so that requests coming from your verifier application can be recognized and trusted by the MATTR VII tenant.

1. In the navigation panel on the left-hand side, expand the Credential Verification menu.
2. Click on Trusted issuers.
3. Click on Create new.
4. In the Certificate PEM file field, paste the PEM certificate of the IACA used by the issuers you want to trust. For testing purposes, you can use the IACA of the Apple Developer Integrator profile referenced in the prerequisites section.
5. Click on Add.

Make the following request to your MATTR VII tenant to configure a trusted issuer:

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-----"
}

• certificatePem : Replace with the PEM certificate of the IACA used by the issuers you want to trust. For testing purposes, you can use the IACA of the Apple Developer Integrator profile you installed as part of the prerequisites.

Response

A successful 201 response indicates that this issuer's certificate was added to your MATTR VII tenant's trusted issuer's list. This means that mDocs that use this IACA as their root certificate can be trusted and verified.

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:

Install the SDK

Add the React Native mDocs Verifier SDK to your project:

yarn add @mattrglobal/mobile-credential-verifier-react-native

Generate the native iOS project

This guide uses Expo with development builds. Generate the native ios/ project so you can add the required capabilities in Xcode:

yarn expo prebuild

Run the application

Connect a physical iOS device and run the application on it:

yarn ios --device

Identity Presentment capabilities

Identity Presentment capabilities configuration

Once yarn expo prebuild has generated the ios/ project, open it in Xcode and add the same capabilities described above via the Signing & Capabilities tab, exactly as in the iOS steps. For detailed instructions, see Add capabilities to your app.

Identity Presentment capabilities

Identity Presentment capabilities configuration

From v6.0.0, initialize is asynchronous and requires a PlatformConfiguration with both your tenant host and Verifier Application id (this drives SDK Tethering):

let platformConfiguration = PlatformConfiguration(
    tenantHost: URL(string: "https://learn.vii.au01.mattr.global")!, 
    applicationId: "<YOUR_VERIFIER_APPLICATION_ID>"
)
try await mobileCredentialVerifier.initialize(platformConfiguration: platformConfiguration)

• tenantHost : Replace with the URL of your MATTR VII tenant.
• applicationId : The id returned when you created the verifier application.

Import the SDK and call initialize with a platformConfiguration that sets your tenant host. The function returns a neverthrow Result, so errors are surfaced via result.isErr() rather than a thrown exception:

import { initialize } from "@mattrglobal/mobile-credential-verifier-react-native";

const result = await initialize({
  platformConfiguration: { tenantHost: "https://learn.vii.au01.mattr.global" }, 
});
if (result.isErr()) {
  // handle initialization error
}

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

Call the fetchAppleWalletConfiguration method:

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

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
            ]
        ]
    )

Call fetchAppleWalletConfiguration with the request, your verifier applicationId, and the merchantId. It returns a Result<AppleWallet, FetchAppleWalletConfigurationError>:

import { fetchAppleWalletConfiguration } from "@mattrglobal/mobile-credential-verifier-react-native";

const result = await fetchAppleWalletConfiguration({
  request: mobileCredentialRequest,
  applicationId: "<your-verifier-application-id>",
  merchantId: "merchant.com.example.app",
});
if (result.isErr()) {
  // request cannot be met via Apple Wallet, do not show the button
  return;
}
const appleWallet = result.value;

• applicationId : The id returned when you created the verifier application.

MobileCredentialRequest example

const mobileCredentialRequest = {
  docType: "org.iso.18013.5.1.mDL",
  namespaces: {
    "org.iso.18013.5.1": {
      family_name: false,
      given_name: false,
      birth_date: false,
    },
  },
};

Call the requestMobileCredentials method:

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

Call requestMobileCredentials on the appleWallet instance returned by fetchAppleWalletConfiguration. It returns a Result<OnlinePresentationSessionResult, RequestMobileCredentialsWithAppleWalletError>:

const result = await appleWallet.requestMobileCredentials(challenge);
if (result.isErr()) {
  // handle error
  return;
}
const sessionResult = result.value;

The results are returned 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.

After checking result.isErr() on the value returned by requestMobileCredentials, read the OnlinePresentationSessionResult from result.value (the sessionResult in the previous step). Your app should then:

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