How to build mDocs claiming capabilities into my iOS application
This guide offers step-by-step instructions for using the iOS mDocs holder SDK to build the capability to claim an mDoc into an iOS wallet application via an OID4VCI workflow.
If you are unfamiliar with this workflow, the corresponding tutorial might be a better starting point as it offers more context and a high level overview of the user experience.
Prerequisites
- The
clientId
used to identify your wallet application by the issuer you are going to claim credentials from. - Access to the SDK’s GitHub distribution repository. Refer to the getting started guide for more information.
Access requires an SSH key associated with the GitHub user who has access to the distribution repo. Please contact us if you are having trouble with setting this up.
Overview
This guide comprises the following steps:
- Setup your project.
- Initialize the SDK.
- Discover a credential offer.
- Present offer to user.
- Initiate issuance workflow.
Setup your project
- Install the SDK.
- Create a new file named Constants.swift and define the following resources:
redirectUri
: The path the SDK will redirect to once the user completes Authentication with the issuer.clientId
: The identifier used by the issuer to recognize your wallet application.
Resource definition
enum Constants {
static let redirectUri: String = "io.mattrlabs.sample.mobilecredentialholderapp://credentials/callback"
static let clientId: String = "ios-sample-mobile-credential-holder-app"
}
- Add Bluetooth and Biometric permissions to your application.
Initialize the SDK
- Create a new variable:
Creating a new variable
var mobileCredentialHolder: MobileCredentialHolder
- Initialize the SDK by creating a new instance of the
MobileCredentialHolder
class and calling itsinitialize
function:
Initializing the SDK
mobileCredentialHolder = MobileCredentialHolder.shared
try mobileCredentialHolder.initialize()
Discover a credential offer
- Call the
discoverCredentialOffer
function with aString
parameter to discover the credential offer:
Discovering the Credential offer
func discoverCredentialOffer(_ offer: String) {
Task { @MainActor in
do {
discoveredCredentialOffer = nil
discoveredCredentialOffer = try await mobileCredentialHolder.discoverCredentialOffer(offer)
} catch {
}
}
}
- The
String
parameter is a URL-encoded Credential offer which your application must extract from a received Credential offer. Based on your implementation, this offer might be formatted as a QR code, deep-link or app notification. Refer to the tutorial for an example of extracting the URL from a QR code.
- The function will return a
DiscoveredCredentialOffer
object, which we will use in the next step.
Display offer to user
- Extract the
issuer
andcredentials
elements from theDiscoveredCredentialOffer
object and present this information to the user for review, alongside any other information you might think is relevant.
Initiate the issuance workflow
- Create a UI element that enables the user to consent to claiming the credentials included in the Credential offer.
- Once the user provides consent, your application must call the
retrieveCredentials
function to trigger the credential issuance.
Retrieving the offered credentials
func retrieveCredential() {
Task { @MainActor in
do {
retrievedCredentialResults = try await mobileCredentialHolder.retrieveCredentials(
credentialOffer: discoveredCredentialOffer!,
clientId: Constants.clientId,
redirectUri: Constants.redirectUri,
autoTrustMobileCredentialIaca: true)
} catch {
print(error.localizedDescription)
}
}
}
credentialOffer
: This is theDiscoveredCredentialOffer
object returned by thediscoverCredentialOffer
function.clientId
: This was configured when setting up your project. It is used by the issuer to identify the wallet application that is making a request to claim credentials.redirectUri
: This was configured when setting up your project. It is used by the SDK to redirect the user back to a specific wallet application view after completing authentication.
The function returns a
RetrieveCredentialResult
array.
- Call the
getCredential
function with acredentialId
parameter (extracted from theRetrieveCredentialResult
array).
The function returns a
MobileCredentialResponse
object.
- Create a new variable to hold the
MobileCredentialResponse
object and add a UI element to display it to the user.
@Published var credential: MobileCredential?
...
credential = try await mobileCredentialHolder.getCredential(credentialId: retrievedCredentialResults![0].credentialId!)