Learn how to build an iOS application that can claim an mDoc via OID4VCI

Create a new project

Please follow the detailed instructions to Create a new Xcode project and add your organisation’s identifier.

Unzip the dependencies file

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

See Add existing files and folders for detailed instructions.

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

Configure required resources

1. Create a new file named Constants.swift within your project.

2. Add the following string resources to represent the Authentication provider we will use for this tutorial:

   Swift

   enum Constants {
   	static let redirectUri: String = "io.mattrlabs.sample.mobilecredentialholderapp://credentials/callback"
   	static let clientId: String = "ios-sample-mobile-credential-holder-app"
   }
   • redirectUri : This is the path the SDK will redirect to once the user completes Authentication with the issuer. Our best practice recommendation is to configure this to be {redirect.scheme}://credentials/callback as shown in the example above. However, it can be any path as long as it is handled by your application and registered with the issuer against the corresponding clientId.
   • clientId : This is the identifier that is used by the issuer to recognize the wallet application. This is only used internally in the interaction between the wallet and the issuer and can be any string as long as it is registered with the issuer as a trusted wallet application.

Add Bluetooth and biometric permissions

The SDK requires access to the mobile device Bluetooth and biometric capabilities for the different workflows built in this tutorial. Configure these permissions in the Info tab of the Application target:

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:

Initialize the SDK

The first capability you will build into your app is to initialize the SDK so that your app can use SDK methods and classes. To achieve this, we need to import the MobilecredentialHolderSDK framework and then initialize the MobileCredentialHolder class:

1. Open the ContentView class in your new app project and replace any existing code with the following:

   ContentView

   import SwiftUI
   // Claim Credential - Step 1.2: Import MobileCredentialHolderSDK
    
    
   struct ContentView: View {
       @ObservedObject var viewModel: ViewModel = ViewModel()
       var body: some View {
           NavigationStack(path: $viewModel.navigationPath) {
               VStack {
                   Button("Scan Credential Offer") {
                       viewModel.navigationPath.append(NavigationState.qrScan)
    
                   }
                   .padding()
                   createQRCodeButton
                   if viewModel.shouldDisplayOnlinePresentation {
                       Button("View Online Presentation Session") {
                           viewModel.navigationPath.append(NavigationState.onlinePresentation)
                       }
                       .padding()
    
                   }
                   Spacer()
               }
               .padding()
               .navigationDestination(for: NavigationState.self) { destination in
                   switch destination {
                   case .qrScan:
                       codeScannerView
                   case .credentialOffer:
                       credentialOfferView
                   case .retrievedCredentials:
                       retrievedCredentialsView
                   case .onlinePresentation:
                       // Online Presentation - Step 3.3: Display online presentation view
                       EmptyView()
                   case .presentCredentials:
                       qrCodeView
                   case .proximityPresentation:
                       // Proximity Presentation - Step 2.5: Display proximity presentation view
                       EmptyView()
                   }
               }
               // Online Presentation - Step 2.4: Create session from request URI
           }
       }
    
       // MARK: - Credential Retrieval Views
    
       var codeScannerView: some View {
           // Claim Credential - Step 2.4 Create QRScannerView
           EmptyView()
       }
    
       var credentialOfferView: some View {
           // Claim Credential - Step 3.3: Display Credential offer
           EmptyView()
       }
    
       var retrievedCredentialsView: some View {
           // Claim Credential - Step 4.4: Display retrieved credentials
           EmptyView()
       }
    
       // MARK: - Proximity Presentation Views
    
       var createQRCodeButton: some View {
           // Proximity Presentation - Step 1.5: Add button to generate QR code
           EmptyView()
       }
    
       func generateQRCode(data: Data) -> Data? {
           // Proximity Presentation - Step 1.6: Generate QR code
           return nil
       }
    
       var qrCodeView: some View {
           // Proximity Presentation - Step 1.7: Create QR code view
           EmptyView()
       }
   }
    
   class ViewModel: ObservableObject {
       @Published var navigationPath = NavigationPath()
       // Claim Credential - Step 1.3: Add MobileCredentialHolder var
    
       // Claim Credential - Step 3.1: Add DiscoveredCredentialOffer var
    
       // Claim Credential - Step 4.1: Add retrievedCredentials var
    
    
       // Proximity Presentation - Step 1.2: Create deviceEngagementString and proximityPresentationSession variables
    
    
       // Proximity and Online Presentation: Create variables for credential presentations
    
    
       // Online Presentation - Step 2.1: Create a variable to hold the online presentation session object
    
    
       var shouldDisplayOnlinePresentation: Bool {
           // Online Presentation - Step 3.4: View Online Presentation
           return false
       }
    
       // Claim Credential - Step 1.4: Initialize MobileCredentialHolder SDK
    
    
       @MainActor
       func getCredential(id: String) {
           // Proximity and Online Presentation: Retrieve a credential from storage
           print("This method will get a credential from storage and update the viewModel")
       }
   }
    
   // MARK: - Credential Retrieval
    
   extension ViewModel {
       @MainActor
       func discoverCredentialOffer(_ offer: String) {
           // Claim Credential - Step 3.2: Add discover credential offer logic
           print("This method will discover a credentials offer and update viewModel")
    
       }
    
       @MainActor
       func retrieveCredential() {
           // // Claim Credential - Step 4.2: Call retrieveCredential method
           print("This method will save a credential from offer and store it in the application's storage ")
       }
   }
    
   // MARK: - Online Presentation
    
   extension ViewModel {
       @MainActor
       func createOnlinePresentationSession(authorizationRequestURI: String) async {
           // Online Presentation - Step 2.3: Create online presentation session
           print("This method will create an online presentation session and update viewModel")
       }
    
       @MainActor
       func sendOnlinePresentationSessionResponse(id: String) {
           // Online Presentation - Step 4.1: Send online presentation response
           print("This method will be passed to a view and send a response with selected credentials")
       }
   }
    
   // MARK: - Proximity Presentation
    
   extension ViewModel {
       func createDeviceEngagementString() {
           // Proximity Presentation - Step 1.3: Create function to create a proximity presentation session and generate QR code
           print("This method will create a device engagement string that will be converted to a QR code")
       }
    
       // Proximity Presentation - Step 1.4: Update function signature
       func onRequestReceived() {
           // Proximity Presentation - Step 2.1: Store credential requests and matched credentials
           print("The signature of this method will need to be updated to include the correct parameters")
           print("This is a method that will be called when a proximity presentation request is received")
       }
    
       @MainActor
       func sendProximityPresentationResponse(id: String) {
           // Proximity Presentation - Step 3.1: Send a credential response
           print("This method will be passed to a view and send a response with selected credentials")
    
       }
   }
    
   // MARK: - Navigation
    
   enum NavigationState: Hashable {
       case qrScan
       case credentialOffer
       case retrievedCredentials
       case onlinePresentation
       case presentCredentials
       case proximityPresentation
   }

2. Add the following code after the // Claim Credential - Step 1.2: Import MobileCredentialHolderSDK comment to import MobileCredentialHolderSDK and enable using its capabilities in your application:

   ContentView

    import MobileCredentialHolderSDK

3. Add the following code after the // Claim Credential - Step 1.3: Add MobileCredentialHolder var comment to create a variable that holds the mobileCredentialHolder instance:

   ContentView

       var mobileCredentialHolder: MobileCredentialHolder

4. Add the following code after the // Claim Credential - Step 1.4: Initialize MobileCredentialHolder SDK comment to initialize the SDK and make it available for your application:

   ContentView

       init() {
           do {
               mobileCredentialHolder = MobileCredentialHolder.shared
               try mobileCredentialHolder.initialise(userAuthRequiredOnInitialise: false)
           } catch {
               print(error)
           }
       }

5. Run the app to make sure it compiles properly.

Interact with a Credential offer

Once the SDK is initialized, the next step is to build the capability to handle a Credential offer, which can be received as deep-links or QR codes. As this tutorial uses an offer formatted as a QR code, your application needs to be able to scan and process it.

For ease of implementation, we will use a third party framework to achieve this:

1. Add camera usage permissions to the app target:

2. Add the CodeScanner library via Swift Package Manager.

3. Create a new swift file named QRScannerView and add the following code into it to implement the QR scanning capability:

   QRScannerView

       import SwiftUI
       import CodeScanner
    
       struct QRScannerView: View {
    
           private let completionHandler: (String) -> Void
    
           init(completion: @escaping (String) -> Void) {
               completionHandler = completion
           }
    
           var body: some View {
               CodeScannerView(codeTypes: [.qr]) { result in
                   switch result {
                   case .failure(let error):
                       print(error.localizedDescription)
                   case .success(let result):
                       print(result.string)
                       completionHandler(result.string)
                   }
               }
           }
   }

4. Return to the ContentView file and replace the EmptyView() under the // Claim Credential - Step 2.4 Create QRScannerView comment with the following code to create a new QRScannerView view in the application for scanning QR codes:

   ContentView

           QRScannerView(
               completion: { credentialOffer in
                   viewModel.discoverCredentialOffer(credentialOffer)
               }
           )

5. Run the app and select the Scan Credential Offer button.

You should see a result similar to the following:

As the user selects the Scan Credential Offer button, the app launches the device camera to enable the user to scan a QR code.

You might notice that nothing happens after scanning a QR code - this is expected. In the next step we will implement the logic that retrieves the credential offer details from the QR code and presents them to the user.

Retrieve offer details and present them to the user

The next capability to build is to display the Credential offer details to the user before they agree to claim any credentials. Credential discovery is the process in which a wallet application retrieves the offer details, including:

• What Issuer is offering the credentials?
• What credentials are being offered, in what format and what claims do they include?

To display this information to the user, your application should call the SDK’s discoverCredentialOffer method. We are going to implement this within the ViewModel class.

1. Add the following code under the // Claim Credential - Step 3.1: Add DiscoveredCredentialOffer var comment to add a new variable that will hold the credential offer details:

   ContentView

   @Published var discoveredCredentialOffer: DiscoveredCredentialOffer?

2. Replace the print statement under the // Claim Credential - Step 3.2: Add discover credential offer logic comment with the following code to create a function that calls the SDK’s discoverCredentialOffer method:

   ContentView

       Task {
           do {
               discoveredCredentialOffer = try await mobileCredentialHolder.discoverCredentialOffer(offer)
               // present credential offer screen, as soon as credential offer is discovered
               navigationPath.append(NavigationState.credentialOffer)
           } catch {
               print(error)
           }
       }

   This function is called from our QRScannerView callback, so that when the user scans a QR Code that includes a credential offer, the discoverCredentialOffer method is called and accepts the returned credentialOffer string as its offer parameter.

   This is a URL-encoded Credential offer which in our example is embedded in a QR code. In other implementations you might have to retrieve this parameter from a deep-link.

   The discoverCredentialOffer method makes a request to the offer URL to retrieve the offer details and returns it as a DiscoveredCredentialOffer object:

   Swift

   struct DiscoveredCredentialOffer {
       let issuer: URL
       let authorizeEndpoint: URL
       let tokenEndpoint: URL
       let credentialEndpoint: URL
       let credentials: [OfferedCredential]
       let mdocIacasUri: URL?
   }

   The application can now use the issuer and credentials properties and present this information for the user to review. Once an application has discovered a credential offer, the user is navigated to the credentialOfferView view, which we are going to implement next.

3. Replace EmptyView under the // Claim Credential - Step 3.3: Display Credential offer comment with the following code to navigate the user to the credentialOfferView view when a credential offer is discovered:

   ContentView

       VStack {
           Text("Received \(viewModel.discoveredCredentialOffer?.credentials.count ?? 0) Credential Offer(s)")
               .font(.headline)
           Text("from \(viewModel.discoveredCredentialOffer?.issuer.absoluteString ?? "unknown issuer")")
               .font(.subheadline)
           List(viewModel.discoveredCredentialOffer?.credentials ?? [], id: \.docType) { credential in
               Section {
                   HStack {
                       Text("Name:")
                           .bold()
                       Spacer()
                       Text("\(credential.name ?? "")")
                   }
                   HStack {
                       Text("Doctype:")
                           .bold()
                       Spacer()
                       Text("\(credential.docType)")
                   }
                   HStack {
                       Text("No. of claims:")
                           .bold()
                       Spacer()
                       Text("\(credential.claims.count)")
                   }
               }
           }
           Button {
               viewModel.retrieveCredential()
           } label: {
               Text("Consent and retrieve Credential(s)")
                   .font(.title3)
           }
           .buttonStyle(.borderedProminent)
           .clipShape(Capsule())
       }

4. Run the app, select the Scan Credential Offer button and scan the following QR code:

You should see a result similar to the following:

As the user scans the QR code, the application displays the credential offer details.

You might notice that nothing happens if you select the Consent and retrieve Credential(s) button. This is expected - in the next step we will implement the logic that initiates the credential issuance once the user provides their consent.

Obtain user consent and initiate credential issuance

The next (and final!) step is to build the capability for the user to accept the credential offer. This should then trigger issuing the credential and storing it in the application storage.

Once the user provides their consent by selecting the Consent and retrieve Credential(s) button, your application must call the SDK’s retrieveCredentials function to trigger the credential issuance and store the issued credential in the application storage.

1. Add the following code under the // Claim Credential - Step 4.1: Add retrievedCredentials var comment to add a new variable that will hold the result returned by the SDK’s retrieveCredentials method:

   ContentView

   @Published var retrievedCredentials: [MobileCredential] = []

2. Replace the print statement under the // Claim Credential - Step 4.2: Call retrieveCredential method comment with the following code to create a new function that will call the SDK’s retrieveCredentials method:

   ContentView

       Task {
           do {
               let retrievedCredentialResults = try await mobileCredentialHolder.retrieveCredentials(
                   credentialOffer: discoveredCredentialOffer!,
                   clientId: Constants.clientId,
                   redirectUri: Constants.redirectUri,
                   autoTrustMobileCredentialIaca: true)
               Task {
                   var credentials: [MobileCredential] = []
                   for result in retrievedCredentialResults {
                       if let credentialId = result.credentialId {
                           if let credential = try? await mobileCredentialHolder.getCredential(credentialId: credentialId) {
                               credentials.append(credential)
                           }
                       }
                   }
                   self.retrievedCredentials = credentials
                   // Clear navigation stack and display retrievedCredentials view
                   navigationPath = NavigationPath()
                   navigationPath.append(NavigationState.retrievedCredentials)
               }
           } catch {
               print(error.localizedDescription)
           }
       }

Let’s review where we got all the parameters’ mobileCredentialHolder.retrieveCredentials from:

• credentialOffer: This is the DiscoveredCredentialOffer object returned by the discoverCredentialOffer method in step 3 above.
• clientId: This was configured when setting up your development environment. 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 development environment. It is used by the SDK to redirect the user back to a specific wallet application view after completing authentication.

Once the function is called, it will redirect the user to authenticate with the configured Authentication provider defined in the authorizeEndpoint element of the DiscoveredCredentialOffer object.

Upon successful authentication, the user can proceed to complete the OID4VCI workflow configured by the issuer. This workflow can include different steps based on the issuer’s configuration, but eventually the user is redirected to the configured redirectUri which should be handled by your wallet application.

As the user is redirected to the configured redirectUri, the issuer sends the issued mDocs to your wallet application. The SDK then processes the received credentials and validates them against the ISO/IEC 18013-5:2021 standard. Credentials who meet validation rules are stored in the application internal data storage.

The retrieveCredentials function then returns a RetrieveCredentialResult array, which includes metadata of all retrieved credentials:

struct RetrieveCredentialResult {
    let docType: String
    let credentialId: String?
    let error: RetrieveCredentialError?
}
 
[
   {
      "docType":"org.iso.18013.5.1.mDL",
      "credentialId":"F52084CF-8270-4577-8EDD-23149639D985"
   }
]

• docType : Identifies the credential type.
• credentialId : Internal unique identifier of this credential.

After the result is received, your application can retrieve specific credentials by calling the SDK’s getCredential method with the credentialId of any retrieved credential.

The SDK’s getCredential method returns a MobileCredential object which can be used to display the retrieved credential, its claims and verification status to the user.

Since this object can be used across multiple views, it will make sense to create one view that will represent it. We will use this view in both the Proximity and Online presentation tutorials.

3. Create a new file named DocumentView and add the following content:

   DocumentView

   MobileCredentialHolderSDK import SwiftUI
    
       struct DocumentView: View {
    
           var viewModel: DocumentViewModel
    
           var body: some View {
               VStack(alignment: .leading, spacing: 10) {
                   Text(viewModel.docType)
                       .font(.title)
                       .fontWeight(.bold)
                       .padding(.bottom, 5)
    
                   ForEach(viewModel.namespacesAndClaims.keys.sorted(), id: \.self) { key in
                       VStack(alignment: .leading, spacing: 5) {
                           Text(key)
                               .font(.headline)
                               .padding(.vertical, 5)
                               .padding(.horizontal, 10)
                               .background(Color.gray.opacity(0.2))
                               .cornerRadius(5)
    
                           ForEach(viewModel.namespacesAndClaims[key]!.keys.sorted(), id: \.self) { claim in
                               HStack {
                                   Text(claim)
                                       .fontWeight(.semibold)
                                   Spacer()
                                   Text(viewModel.namespacesAndClaims[key]![claim]! ?? "")
                                       .fontWeight(.regular)
                               }
                               .padding(.vertical, 5)
                               .padding(.horizontal, 10)
                               .background(Color.white)
                               .cornerRadius(5)
                               .shadow(radius: 1)
                           }
                       }
                       .padding(.vertical, 5)
                   }
               }
               .padding()
               .background(RoundedRectangle(cornerRadius: 10).fill(Color.white).shadow(radius: 5))
               .padding(.horizontal)
           }
       }
    
       // MARK: DocumentViewModel
    
       class DocumentViewModel: ObservableObject {
           var docType: String
    
           var namespacesAndClaims: [String: [String: String?]]
    
           init(from credential: MobileCredential) {
               self.docType = credential.docType
               self.namespacesAndClaims = credential.claims?.reduce(into: [String: [String: String]]()) { result, outerElement in
                   let (outerKey, innerDict) = outerElement
                   result[outerKey] = innerDict.mapValues { $0.textRepresentation }
               } ?? [:]
           }
    
           init(from credentialMetadata: MobileCredentialMetadata) {
               self.docType = credentialMetadata.docType
               var result: [String: [String: String?]] = [:]
               credentialMetadata.claims?.forEach { namespace, claimIDs in
                   var transformedClaims: [String: String?] = [:]
                   claimIDs.forEach { claimID in
                       transformedClaims[claimID] = Optional<String>.none
                   }
                   result[namespace] = transformedClaims
               }
               self.namespacesAndClaims = result
           }
    
           init(from request: MobileCredentialRequest) {
               self.docType = request.docType
               self.namespacesAndClaims = request.namespaces.reduce(into: [String: [String: String?]]()) { result, outerElement in
                   let (outerKey, innerDict) = outerElement
                   result[outerKey] = innerDict.mapValues { _ in nil }
               }
           }
       }
    
       // MARK: Helper
       extension MobileCredentialElementValue {
           var textRepresentation: String {
               switch self {
               case .bool(let bool):
                   return "\(bool)"
               case .string(let string):
                   return string
               case .int(let int):
                   return "\(int)"
               case .unsigned(let uInt):
                   return "\(uInt)"
               case .float(let float):
                   return "\(float)"
               case .double(let double):
                   return "\(double)"
               case let .date(date):
                   let dateFormatter = DateFormatter()
                   dateFormatter.dateStyle = .short
                   dateFormatter.timeStyle = .none
                   return dateFormatter.string(from: date)
               case let .dateTime(date):
                   let dateFormatter = DateFormatter()
                   dateFormatter.dateStyle = .short
                   dateFormatter.timeStyle = .short
                   return dateFormatter.string(from: date)
               case .data(let data):
                   return "Data \(data.count) bytes"
               case .map(let dictionary):
                   let result = dictionary.mapValues { value in
                       value.textRepresentation
                   }
                   return "\(result)"
               case .array(let array):
                   return array.reduce("") { partialResult, element in
                       partialResult + element.textRepresentation
                   }
                   .appending("")
               @unknown default:
                   return "Unknown type"
               }
           }
       }

   The file comprises the following components:

   • DocumentViewModel: This class stores the credentials’ docType and claim values.
   • DocumentView: This view takes DocumentViewModel as a parameter and displays its content in a human-readable format.
   • MobileCredentialElementValue : This helper extension allows retrieving a MobileCredentialElementValue from a MobileCredential’s claims and present it in a human-readable format.

4. Return to ContentView and replace EmptyView under the // Claim Credential - Step 4.4: Display retrieved credentials comment with the following code to use the DocumentView structure to display retrieved credentials to the user:

   ContentView

       ScrollView {
           VStack {
               Text("Retrieved Credentials")
                   .font(.title)
               ForEach(viewModel.retrievedCredentials, id: \.id) { credential in
                   DocumentView(viewModel: DocumentViewModel(from: credential))
               }
           }
       }

5. Run the app, select the Scan Credential Offer button, scan the QR code and then select Consent and retrieve Credential(s).

You should see a result similar to the following:

As the user scans the QR code, the application displays the offer details. The user then provides consent to retrieve the credentials and the wallet responds by initiating the issuance workflow and displaying the retrieved credentials to the user.