Contents

Requesting identity data from a Wallet pass

Initiate a request for identity information by prompting a user for permission and decrypting a response payload.

Overview

The Wallet app allows people to store an identification card, for example, a mobile driver’s license (mDL), or national identification card from a government issuing authority, or a digital ID issued by Apple.

Beginning on iPhone with iOS 16, you can request information from IDs in Wallet to verify a person’s age or identity. If a person accepts the request, the system gets the information from their issuing authority and your app receives a payload. After decryption, the payload contains data that follows the ISO 18013-5 specification. To use the elements your app requests, send the payload to your server for verification.

For design guidance, see Human Interface Guidelines > Technologies > Wallet.

Create an identity document descriptor

Before you request information from an ID in Wallet, you create an object to describe the elements you need. Your app can only request the elements your entitlement grants. There are a few identity document descriptor options:

PKIdentityDriversLicenseDescriptor

For requesting information from a person’s state or mobile driver’s license.

PKIdentityNationalIDCardDescriptor

For requesting information from their national identificaton card, and add the elements to the request.

PKIdentityPhotoIDDescriptor

For requesting information from a digital ID.

PKIdentityAnyOfDescriptor

For requesting information for more than one identity document.

For each element, you specify your intent to store the resulting data by using mayStore(days:), mayStore, or willNotStore. Upon request, the system presents the information for a person to review in a system sheet.

The framework allows for requesting the Boolean age(atLeast:) element for any age between 1 and 125 only if the issuer includes it. If an app requests age(atLeast:) and the age_over_XX element isn’t present in the mobile driver’s license, the framework falls back to a request for the age element.

An app can’t include both an age(atLeast:) element and an age element in the same request.

The following code shows how you create the different identity document descriptors:

To check whether the identity document you describe is available to request, create a PKIdentityAuthorizationController and call checkCanRequestDocument(_:completion:). If the document exists, show a PKIdentityButton to allow the user to begin the authorization request.

let controller = PKIdentityAuthorizationController()
controller.checkCanRequestDocument(descriptor) { canRequest in
    // Show or hide the identity button.
}

Create a request

To create an identity request, you need the merchant identifier you configure in the developer portal. A merchant identifier never expires, and you can use the same one that you use for Apple Pay.

A request also needs a nonce to prevent your server from using a response document more than once. Your server needs the nonce to decrypt the response document, so generate it there and associate it with the user’s session.

let request = PKIdentityRequest()
request.descriptor = descriptor
request.merchantIdentifier = // The merchant identifier.
request.nonce = // The nonce your server generates.

Your app’s Info.plist file needs to provide a message for the NSIdentityUsageDescription key. If this key is missing, any attempt to request a document fails.

Request the document

When requesting a document, the system presents a sheet to the user to confirm the request before retrieving any data. If the user rejects the request, your app receives a PKIdentityError.Code.cancelled error.

do {
    let document = try await controller.requestDocument(request)
} catch {
    // Handle the error.
}

When you receive a PKIdentityDocument, you’re ready to verify the request payload. The data in the encryptedData property isn’t readable on the device, so you need to send it to your server for verification.

The elements in the descriptors map this way in their responses:

To learn more about verifying identity requests, see Verifying Wallet identity requests.

Test the implementation

Even if you don’t live in an area that supports IDs in Wallet, you can test your implementation through the iPhone simulator or by downloading a developer profile on your local device. When you request a document, you receive a mock mDL that’s similar to a real ID. When you test with the simulator, the response doesn’t include a real issuing authority or device signature. The developer test profile produces a real device signature, but not a real issuer signature. A mock mDL isn’t visible in the Wallet app, so don’t treat it as real. To activate a mock mDL on your device, download the Wallet identity developer profile from Profiles and Logs.

See Also

Essentials