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 functions 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:

   Swift

   import SwiftUI
   import MobileCredentialHolderSDK
    
   struct ContentView: View {
       @ObservedObject var viewModel: ViewModel = ViewModel()
       // Online Presentation - Step 3.1: Create variable to store selected credential
       // Online Presentation - Step 3.3: Add isPresentingOnlinePresentation variable
       // Proximity Presentation - Step 1.2: Add isPresentingPresentCredentialsView variable
       // Claim Credential - Step 2.5: Add isPresentingQRScanButton variable
       // Claim Credential - Step 2.6: Add QR scan button
       var body: some View {
           VStack {
               Text("Hello, world!")
           }
           .padding()
       }
    
       // Claim Credential - Step 2.4: Create QRScannerView
    
   	// Proximity Presentation - Step 1.4: Create PresentCredentialsView
       // Online Presentation - Step 3.2: Create PresentCredentialsView
   }
    
   class ViewModel: ObservableObject {
       // Claim Credential - Step 1.2: Add MobileCredentialHolder var
       // Claim Credential - Step 3.1: Add DiscoveredCredentialOffer var
       // Claim Credential - Step 4.1: Add retrieveCredentialResult var
       // Claim Credential - Step 4.5: Add credential var
       // Online Presentation - Step 2.1: Create a variable to hold the online presentation session object
       init() {
           do {
               // Claim Credential - Step 1.3: initialize MobileCredentialHolder SDK
           }
           catch {
               print(error.localizedDescription)
           }
       }
    
       // Claim Credential - Step 3.2: Add discover credential offer logic
    
   // Claim Credential - Step 4.2: Create retrieveCredential function
   // Online Presentation - Step 2.2: Create createOnlinePresentationSession function
   // Online Presentation - Step 4.1: Create send response function
   }

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

   Swift

       var mobileCredentialHolder: MobileCredentialHolder

3. Add the following code after the // Claim Credential - Step 1.3: initialize MobileCredentialHolder SDK comment to initialise the SDK by creating a new instance of the MobileCredentialHolder class:

   Swift

   	mobileCredentialHolder = MobileCredentialHolder.shared
   	try mobileCredentialHolder.initialize(userAuthRequiredOnInitialize: false)

   This will initialize the SDK, making it available for your wallet application.

4. 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.

Users can receive OID4VCI Credential offers as deep-links or QR codes. In this tutorial we will use the following QR code, which is a MATTR Labs example of an OID4VCI Credential offer:

Your application must provide a way for the user to interact with Credential offers. 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:

   Swift

   import SwiftUI
   import CodeScanner
    
   struct QRScannerView: View {
    
       private let completionHandler: (String) -> Void
    
       init(completion: @escaping (String) -> Void) {
           completionHandler = completion
       }
    
       @Environment(\.presentationMode) var presentationMode: Binding<PresentationMode>
    
       var body: some View {
           CodeScannerView(codeTypes: [.qr]) { result in
               presentationMode.wrappedValue.dismiss()
               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 add the following code under the // Claim Credential - Step 2.4 Create QRScannerView comment to create a new view in the application for the QR scanning capability:

   Swift

   var codeScannerView: some View {
       QRScannerView(
           // Claim Credential - Step 3.3 Update completion object
           completion: { _ in
           }
       )
   }

5. Add the following code under the // Claim Credential - Step 2.5: Add isPresentingQRScanButton variable comment add to add a new variable to manage navigation to the QRScannerView:

   Swift

   @State var isPresentingQRScanButton = false

6. Replace the var body object under the // Claim Credential - Step 2.6: Add QR scan button comment with the following code to create a new button to trigger the QR scanning functionality:

   Swift

   var body: some View {
       NavigationStack {
           VStack {
               Button("Scan Credential Offer") {
                   isPresentingQRScanButton = true
               }
               .padding()
               // Online Presentation - Step 3.4: View Online Presentation Session
               // Proximity Presentation Step 1.3: Add button to navigate to present credential view
               // Claim Credential - Step 3.4: Display Credential Offer
               // Claim Credential - Step 4.7: Display Retrieved Credential
               Spacer()
           }
           .navigationDestination(isPresented: $isPresentingQRScanButton) {
               codeScannerView
           }
           // Online Presentation - Step 3.5: Add navigation to presentCredentialsView
           // Proximity Presentation Step 1.5: Add navigation to presentCredentialsView
       }
       .padding()
       // Online Presentation - Step 2.3: Create session from request URI
   }

   This will navigate to the app QRScannerView screen when the user selects the Scan Credential Offer button, enabling them to use their device camera and scan a QR code.

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

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

Retrieve offer details and present them to the user

The next capability to build is for the user to be able to review the Credential offer details before agreeing 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 wallet application should call the discoverCredentialOffer function. 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:

   Swift

   @Published var discoveredCredentialOffer: DiscoveredCredentialOffer?

2. Add the following code under the // Claim Credential - Step 3.2: Add discover credential offer logic comment to define the discoverCredentialOffer function that is called from within our QRScannerView callback:

   Swift

   func discoverCredentialOffer(_ offer: String) {
       Task { @MainActor in
           do {
               discoveredCredentialOffer = nil
               discoveredCredentialOffer = try await mobileCredentialHolder.discoverCredentialOffer(offer)
           } catch {
           }
       }
   }

3. Replace the completion object under the // Claim Credential - Step 3.3: Update completion object comment with the following code to handle the credential offer upon scanning a QR code:

   Swift

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

   Now, once the user scans a QR Code that includes a credential offer, the discoverCredentialOffer function is called and accepts the returned credentialOffer string as its offer parameter.

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

   The discoverCredentialOffer function makes a request to the offer URL to retrieve the offer information 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.

4. Add the following code under // Claim Credential - Step 3.4: Display Credential offer to achieve this:

   Swift

   // Claim Credential - Step 4.4: Update if statement
   if viewModel.discoveredCredentialOffer != nil {
       let offer = viewModel.discoveredCredentialOffer!
       Text("Received \(offer.credentials.count) Credential Offer from \(offer.issuer)")
       List(offer.credentials, id: \.docType) { credential in
           HStack {
               VStack {
                   Text("name: \(credential.name ?? "")")
                   Text("doctype: \(credential.docType)")
               }
               Spacer()
               Text("No. of claims: \(credential.claims.count)")
           }
       }
       Button {
       // Claim Credential - Step 4.3: Call retrieveCredential function when button is selected
       } label: {
           Text("Consent and retrieve Credential(s)")
       }
   }

5. Run the app, select the Scan Credential Offer button and scan the following QR code (also provided at the top of this tutorial):

You should see a result similar to the following:

As the user scans the QR code, the wallet displays the Credential offer details.

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 based on the displayed information. This should then trigger issuing the credential and storing it in the wallet.

In our example this is achieved by selecting a Consent and retrieve Credential(s) button. Once the user provides their consent by selecting this button, your application must call the retrieveCredentials function to trigger the credential issuance.

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

   Swift

   @Published var retrievedCredentialResults: [RetrieveCredentialResult]?

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

   Swift

   func retrieveCredential() {
       Task { @MainActor in
           do {
               retrievedCredentialResults = try await mobileCredentialHolder.retrieveCredentials(
                   credentialOffer: discoveredCredentialOffer!,
                   clientId: Constants.clientId,
                   redirectUri: Constants.redirectUri,
                   autoTrustMobileCredentialIaca: true)
              // Claim Credential - Step 4.6: add getCredential function
           } catch {
               print(error.localizedDescription)
           }
       }
   }

3. Add the following code under the // Claim Credential - Step 4.3: Call retrieveCredential function when button is selected comment so that the new retrieveCredential function is called when the user selects the Consent and retrieve Credential(s) button:

   Swift

     viewModel.retrieveCredential()

4. Update the if statement under the // Claim Credential - Step 4.4: Update if statement comment to the following:

   Swift

   if viewModel.discoveredCredentialOffer != nil && viewModel.retrievedCredentialResults == nil

Let’s review where we got all the parameters’ values from:

• credentialOffer: This is the DiscoveredCredentialOffer object returned by the discoverCredentialOffer function in step 3.
• 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 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 references all retrieved credentials:

[RetrieveCredentialResult]
 
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 : Unique identifier (UUID) of this credential.

Your application can now retrieve specific credentials by calling the getCredential function with the credentialId of any of the retrieved credentials.

The getCredential function returns a MobileCredential object which represents the issued mDoc, and your application can now introduce UI elements to enable the user to view the credential.

5. Add the following code under the // Claim Credential - Step 4.5: Create credential var comment to create a new variable that will hold the retrieved credential:

   Swift

   @Published var credential: MobileCredential?

6. Add the following code under the // Claim Credential - Step 4.6: add getCredential function comment to call the getCredential function and retrieve the first credential from the RetrieveCredentialResult array:

   Swift

   credential = try await mobileCredentialHolder.getCredential(credentialId: retrievedCredentialResults![0].credentialId!)

7. Add the following code under the // Claim Credential - Step 4.7: Display retrieved credential comment to display the retrieved credential to the user:

   Swift

   if viewModel.credential != nil {
       let credential = viewModel.credential!
       VStack {
           Text("Retrieved Credential")
           Text("doctype: \(credential.docType)")
           Text("Credential info: \(String(describing: credential.claims!))")
       }
   }

8. 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, they are then provided with the offer details by the wallet. The user then provides consent to retrieving the credentials to which the wallet responds by initiating the issuance workflow and displaying the retrieved credentials to the user.