Learn how to build an iOS application that can present an mDoc online
Introduction
In this tutorial we will use the iOS native mDoc Holder SDK to build an iOS application that can present a claimed mDoc to a verifier remotely via an online presentation workflow as per ISO/IEC 18013-7:2024 and OID4VP.
This app will support both same-device and cross-device workflows to accommodate flexible user journeys.
Same-device workflow
- The user interacts with a website on their mobile device browser.
- The user is asked to present information as part of the interaction.
- The user is redirected to the application we will build in this tutorial.
- The application authenticates the user.
- The user is informed of what information they are about to share and provide their consent.
- The user is redirected back to the browser where verification results are displayed, enabling them to continue with the interaction.
The result will look something like this:
Cross-device workflow
- The user interacts with a website on their desktop browser.
- The user is asked to present information as part of the interaction.
- The user scans a QR code using a mobile device where the tutorial application is installed.
- The tutorial application is launched on the mobile device.
- The tutorial application authenticates the user.
- The user is informed of what information they are about to share and provide their consent.
- Verification results are displayed in the user’s desktop browser, enabling them to continue with the interaction.
The result will look something like this:
Prerequisites
Before we get started, let’s make sure you have everything you need.
Prior knowledge
-
The verification workflow described in this tutorial is based on ISO/IEC 18013-7:2024 and OID4VP. If you are unfamiliar with these technical specifications, refer to our Docs section for more information:
- What are mDocs?
- What is credential verification?
- Breakdown of the online presentation workflow.
-
We assume you have experience developing iOS native apps in Swift.
If you need to get a holding solution up and running quickly with minimal development resources and in-house domain expertise, talk to us about our white-label MATTR GO Hold app which might be a good fit for you.
Assets
- As part of your onboarding process you should have been provided with access to the following
assets:
- ZIP file which includes the required framework:
(
MobileCredentialHolderSDK-*version*.xcframework.zip
). - Sample Wallet app: You can use this app for reference as we work through this tutorial.
- ZIP file which includes the required framework:
(
This tutorial is only meant to be used with the most recent version of the iOS mDocs Holder SDK.
Development environment
- Xcode setup with either:
- Local build settings if you are developing locally.
- iOS developer account if you intend to publish your app.
Prerequisite tutorial
- You must complete the Claim a credential tutorial and claim the mDoc provided in the tutorial.
- This application is used as the base for the current tutorial.
Testing devices
- Supported iOS device to run the built application on, setup with:
- Biometric authentication (Face ID, Touch ID).
- Bluetooth access and Bluetooth turned on.
- Available internet connection.
Tutorial steps
To enable a user to present a stored mDoc to a verifier via an online presentation workflow, you will build the following capabilities into your application:
- Register the verifier’s Authorization endpoint.
- Create an online presentation session.
- Handle a presentation request.
- Send a presentation response.
Register the verifier’s Authorization endpoint
The Authorization endpoint is a URI associated with an application identifier in the MATTR VII tenant configuration. It is used to invoke an application that will handle the presentation request. The application then uses the URI to retrieve a request object, which details what information is required for verification.
Online verifiers are recommended to generate this URI as a Universal link, as this enables them to explicitly define and validate applications that can respond to their verification requests.
However, for simplicity reasons in this tutorial our verifier is using the default
custom URI scheme
defined by the OID4VP specification (mdoc-openid4vp
). This means that we need to configure the
application to be able to handle this custom URI scheme.
- Open the Xcode project with the application built in the Claim a credential tutorial.
- Register
mdoc-openid4vp
as a recognized URL scheme:- Open the project view and select your application target.
- Select the Info tab.
- Scroll down and expand the URL Types area.
- Select the plus button.
- Insert
mdoc-openid4vp
in both the Identifier and URL Schemes fields.
-
Run the app and then close it (this updates the app on your testing device) and perform the following instructions:
- Use a desktop browser to navigate to the MATTR Labs Maggie’s Groceries demo, where you must provide proof for purchasing an age restricted item.
- In the checkout area, use the dropdown list to select Generic Wallet.
- Select Share from wallet.
- Open the camera on your testing mobile device and scan the QR code.
- Confirm opening the QR code with your tutorial application.
- The tutorial application should be launched on your testing mobile device.
Create an online presentation session
Now that the application can handle an OID4VP custom URI scheme, the next step is build the capability to use the request URI to retrieve the request object. This object details:
- What credentials are required.
- What specific claims are required from these credentials.
- What MATTR VII tenant to interact with.
-
In your project’s
ContentView
file, add the following code under the// Online Presentation - Step 2.1: Create a variable to hold the online presentation session object
comment to create a variable that will hold the online presentation session:ContentView@Published var onlinePresentationSession: OnlinePresentationSession?
The following step is also included in the Proximity presentation tutorial. If you had already completed this tutorial you may skip to step 3.
-
Add the following code under the
// Proximity and Online Presentation: Create variables for credential presentations
comment to create the following variables:ContentView@Published var matchedCredentials: [MobileCredential] = [] @Published var matchedMetadata: [MobileCredentialMetadata] = [] @Published var credentialRequest: [MobileCredentialRequest] = []
matchedCredentials
: Holds stored credentials that match the credential request.matchedMetadata
: Holds metadata of credentials that match the credential request.credentialRequest
: Holds the credentials that were requested for verification.
-
Replace the
print
statement under the// Online Presentation - Step 2.3: Create online presentation session
comment with the following code to create a function that calls the SDK’screateOnlinePresentationSession
method with theauthorizationRequestURI
parameter (the request URI retrieved from the link/QR code):ContentViewTask { do { onlinePresentationSession = try await mobileCredentialHolder.createOnlinePresentationSession(authorisationRequestUri: authorizationRequestURI, requireTrustedVerifier: false) matchedMetadata = onlinePresentationSession?.matchedCredentials? .flatMap { $0.matchedMobileCredentials } .compactMap { $0 } ?? [] credentialRequest = onlinePresentationSession?.matchedCredentials? .compactMap { $0.request } .compactMap { $0 } ?? [] } catch { print(error.localizedDescription) } }
This function:
- Creates an
OnlinePresentationSession
instance and assigns it to theonlinePresentationSession
variable. - Stores matched
MobileCredentialMetadata
in thematchedMetadata
variable and theMobileCredentialRequest
in thecredentialRequest
variable in ourViewModel
to enable displaying these values to the user.
- Creates an
We chose to set requireTrustedVerifier
parameter to false
because we want the SDK to trust
all verifiers by default. If you require to limit the verifiers a user can interact with, you
may want to manually add trusted verifier certificates and set the parameter to true
. You can
learn more about certificate management in our SDK
docs.
-
Add the following code under the
// Online Presentation - Step 2.4: Create session from request URI
comment to add an onOpenURL modifier that will call thecreateOnlinePresentationSession
function when the application is launched following selecting a link (same-device flow) or scanning a QR code (cross-device flow) that includes a registered URI:ContentView.onOpenURL { url in Task { await viewModel.createOnlinePresentationSession(authorizationRequestURI: url.absoluteString) } // Navigate to online presentation view viewModel.navigationPath.append(NavigationState.onlinePresentation) }
Now, once a user opens an online presentation link on their device, an online presentation session will be created the user will be navigated to a new view, which we will implement in the next step.
Handle a presentation request
We will now build the capability to use information retrieved by the
createOnlinePresentationSession
function to handle the presentation request. This includes:
- Displaying what information is requested.
- Displaying what existing credentials match the requested information.
- Displaying what information from these existing claims will be shared with the verifier.
- Asking for the user’s consent to share requested information from matching credentials.
The following two steps are also included in the Proximity presentation tutorial. If you had already completed this tutorial you may skip to step 3.
-
Replace the
print
statement under the// Proximity and Online Presentation: Retrieve a credential from storage
comment with the following code create a function that uses the SDK’s getCredential method to retrieve a credential from the application storage:ContentViewTask { do { let credential = try await mobileCredentialHolder.getCredential(credentialId: id) matchedCredentials.append(credential) } catch { print(error) } }
The MobileCredentialMetadata object does not include the values of claims included in the credential. To display these values, the above function calls the SDK’s getCredential method with the
id
property of the MobileCredentialMetadata. -
Create a new file called
PresentCredentialsView.swift
and paste the following code to create a view to display credential requests and matching credentials stored in the application:PresentCredentialsViewimport MobileCredentialHolderSDK import SwiftUI struct PresentCredentialsView: View { @ObservedObject var viewModel: PresentCredentialsViewModel @State var selectedID: String? init(viewModel: PresentCredentialsViewModel) { self.viewModel = viewModel } var body: some View { ScrollView { VStack(alignment: .leading, spacing: 20) { Text("Requested Documents") .font(.headline) .padding(.leading) ForEach(viewModel.requestedDocuments, id: \.docType) { requestedDocument in DocumentView(viewModel: DocumentViewModel(from: requestedDocument)) } Text("Matched Credentials") .font(.headline) .padding(.leading) ForEach(viewModel.matchedMetadata, id: \.id) { matchedMetadata in VStack(alignment: .leading, spacing: 10) { if let matchedCredential = viewModel.matchedMobileCredential(id: matchedMetadata.id) { DocumentView(viewModel: DocumentViewModel(from: matchedCredential)) .padding(.vertical) .background(selectedID == matchedMetadata.id ? Color.blue.opacity(0.2) : Color.clear) .onTapGesture { guard selectedID != matchedMetadata.id else { selectedID = nil return } selectedID = matchedMetadata.id } Button("Hide claim values") { viewModel.matchedCredentials.removeAll(where: { $0.id == matchedMetadata.id }) } .frame(maxWidth: .infinity, alignment: .center) } else { DocumentView(viewModel: DocumentViewModel(from: matchedMetadata)) .padding(.vertical) .background(selectedID == matchedMetadata.id ? Color.blue.opacity(0.2) : Color.clear) .onTapGesture { guard selectedID != matchedMetadata.id else { selectedID = nil return } selectedID = matchedMetadata.id } Button("Show claim values") { viewModel.getCredentialAction(matchedMetadata.id) } .frame(maxWidth: .infinity, alignment: .center) } } } } } if selectedID != nil { Button("Send Response") { viewModel.sendCredentialAction(selectedID!) } .buttonStyle(.borderedProminent) .clipShape(Capsule()) .frame(maxWidth: .infinity, alignment: .center) } } } // MARK: PresentCredentialsViewModel class PresentCredentialsViewModel: ObservableObject { @Binding var requestedDocuments: [MobileCredentialRequest] @Binding var matchedCredentials: [MobileCredential] @Binding var matchedMetadata: [MobileCredentialMetadata] var getCredentialAction: (String) -> Void var sendCredentialAction: (String) -> Void init( requestedDocuments: Binding<[MobileCredentialRequest]>, matchedCredentials: Binding<[MobileCredential]>, matchedMetadata: Binding<[MobileCredentialMetadata]>, sendCredentialAction: @escaping (String) -> Void, getCredentialAction: @escaping (String) -> Void ) { self._requestedDocuments = requestedDocuments self._matchedCredentials = matchedCredentials self._matchedMetadata = matchedMetadata self.sendCredentialAction = sendCredentialAction self.getCredentialAction = getCredentialAction } func matchedMobileCredential(id: String) -> MobileCredential? { matchedCredentials.first(where: { $0.id == id }) } }
The
PresentCredentialsView
view is used to:- Display requested information.
- Display stored credentials that include the requested information.
- Enable the user to provide consent to sharing the requested information with the verifier.
The
PresentCredentialsViewModel
object is used to reference values from a credential request. It takes two closures in its initializer:getCredentialAction: (String) -> Void
is used to display claim values.sendCredentialAction: (String) -> Void
is used to send a credential response to the verifier once the user selected a credential and provided consent by selecting the Send Response button.
-
Replace
EmptyView
under the// Online Presentation - Step 3.3: Display online presentation view
comment with the new view that we created:
PresentCredentialsView(
viewModel: PresentCredentialsViewModel(
requestedDocuments: $viewModel.credentialRequest,
matchedCredentials: $viewModel.matchedCredentials,
matchedMetadata: $viewModel.matchedMetadata,
sendCredentialAction: viewModel.sendOnlinePresentationSessionResponse(id:),
getCredentialAction: viewModel.getCredential(id:)
)
)
- Replace the
return false
statement under the// Online Presentation - Step 3.4: View Online Presentation
comment with the following code to enable the user to manually navigate to the presentation session view if required:
onlinePresentationSession != nil
-
Run the app and then close it (this updates the app on your testing device) and perform the following instructions:
- Use a desktop browser to navigate to the MATTR Labs Maggie’s Groceries demo, where you must provide proof for purchasing an age restricted item.
- In the checkout area, use the dropdown list to select Generic Wallet.
- Select Share from wallet.
- Open the camera on your testing mobile device and scan the QR code.
- Confirm opening the QR code with your tutorial application.
- The tutorial application should be launched on your testing mobile device, displaying the verification request and any matching credentials.
- When a credential is selected, it will be highlighted and a Send Response button will appear (the logic associated with the button will be implemented in the next step).
The result will look something like this:
Send response
After displaying matching credentials to the user and enabling them to select what credential to share, the last thing we need to do is build the capability to share the selected credential with the verifier.
- Replace the
print
statement under the// Online Presentation - Step 4.1: Send online presentation response
comment with the following code to call thesendResponse
method when the user selects the Send Response button:
Task {
do {
_ = try await onlinePresentationSession?.sendResponse(credentialIds: [id])
// set presentation session to nil after sending a response
onlinePresentationSession = nil
// Return to root view after the response is sent
navigationPath = NavigationPath()
} catch {
print(error)
}
}
Test the application
Let’s test that the application is working as expected in both workflows.
Same-device workflow
- Run the app and then close it (this updates the app on your testing device).
- Use a browser on your testing mobile device to navigate to the MATTR Labs Maggie’s Groceries demo, where you must provide proof for purchasing an age restricted item.
- In the checkout area, use the dropdown list to select Generic Wallet.
- Select Share from wallet.
- Select Allow to open the tutorial application.
- The tutorial application should be launched on your testing mobile device.
- Select the credential you wish to send to the verifier from the list of matched credentials.
- Select Send Response.
- You should be redirected back to Maggie’s online store and see a Over 18 years old verified indication.
- You can now proceed with the interaction (don’t expect any items to be shipped to you by Maggie’s though).
The result will look something like this:
Cross-device workflow
- Run the app and then close it (this updates the app on your testing device).
- Use a desktop browser to navigate to the MATTR Labs Maggie’s Groceries demo, where you must provide proof for purchasing an age restricted item.
- In the checkout area, use the dropdown list to select Generic Wallet.
- Select Share from wallet.
- Open the camera on your testing mobile device and scan the QR code.
- Confirm opening the QR code with your tutorial application.
- The tutorial application should be launched on your testing mobile device.
- Select the credential you wish to send to the verifier from the list of matched credentials.
- Select Send Response.
- Back on your desktop browser, you should see a Over 18 years old verified indication.
- You can proceed with the interaction (don’t expect any items to be shipped to you by Maggie’s though).
The result will look something like this:
Summary
You have just used the iOS native mDoc Holder SDK to build an iOS application that can present a claimed mDoc to a verifier remotely via an online presentation workflow as per ISO/IEC 18013-7:2024 and OID4VP.
This was achieved by building the following capabilities into the application:
- Handle an OID4VP request URI.
- Create an online presentation session.
- Handle a presentation request.
- Send a presentation response.
What’s next?
- You can build additional capabilities into your new application:
- Present a claimed mDoc for verification via a proximity presentation workflow.
- You can check out the iOS mDoc holder SDK Docs to learn more about available functions and classes.