Configure Native Passkeys for Mobile Logins

Mobile apps can use the Hypermedia Authentication API (HAAPI) to run an OpenID Connect login in an API driven manner. Passkey logins then run with purely native screens, without invoking the system browser. The client side work is done by the HAAPI SDK, which calls native passkey APIs provided by the mobile operating system. Further background on passkeys is provided in the What are Passkeys? article.

Configure Associated Domains

During native passkeys authentication, the HAAPI SDK calls iOS Native Passkey APIs. The Apple docs describe how a mobile app must first be assigned the Associated Domains capability for the domain where webcredentials are sent for cryptographic verification. This is the domain of the Curity Identity Server, so the app must add that domain under its entitlements:

Next, the Curity Identity Server must host an assets file with the name apple-app-site-association at a well-known URL. This must be an HTTPS URL that is accessible over the internet, and use a server certificate from a trusted authority. Apple servers call this URL to verify the app to domain association.

https://login.example.com/.well-known/apple-app-site-association

The file registers one or more mobile apps. Its content is similar to the following, where each entry consists of the Apple team ID followed by a bundle ID, in the form com.mycompany.myapp:

{
  "webcredentials": {
    "apps": [
      "[TEAM PREFIX].[BUNDLE ID]"
    ]
  }
}

Use the Admin UI of the Curity Identity Server to register all mobile apps that use native passkeys. Navigate to System -> Deployment -> Zones. The apple-app-site-association document is then generated for you:

It is also possible to deploy this file directly, within the webroot folder of the Curity Identity Server. For Docker based deployments, you can place the file at the following location:

/opt/idsvr/usr/share/webroot/.well-known/apple-app-site-association

Support for generating the equivalent Android configuration, and exposing an assetlinks.json document, is also available in the Curity Identity Server. Once the HAAPI Android SDK is updated to support native passkeys, the same mechanism will therefore work for the Android platform.

Apple Document Caching

When your iOS app is launched, the operating system contacts Apple servers. As part of this process the apple-app-site-association document is retrieved from the Curity Identity Server and cached on Apple servers. If you edit the document, such as to add a new mobile app, it may take a number of hours before iOS loads the latest version during the verification process. During development, you can ensure immediate feedback by using developer mode:

webcredentials:login.example.com?mode=developer

Add the Passkeys Authenticator

Once you have a compliant device, and the associated domains are registered, simply create a Passkeys Authenticator and configure the app to use it:

Test Native Passkeys

Developers can test native passkeys using a purely local setup, by running the HAAPI iOS Code Example on a simulator. When doing so, enable options to simulate biometrics, e.g. by selecting Features / FaceID / Enrolled from the simulator menu.

To enable a working end-to-end setup, first open the app in Xcode, and update its bundle identifier to a unique value, such as com.mycompany.demoapp under Signing & Capabilities. Then configure associated domains for that bundle identifier.

Ensure that you run the example deployment using the USE_NGROK=true option. The ngrok tool creates an HTTP tunnel that is used to expose the Curity Identity Server over an internet HTTPS URL, as described in the Mobile Setup with ngrok tutorial. This provides the publicly available URL that is a prerequisite for native passkeys authentication on mobile devices.

Passkey Logins Video

Once the technical setup is complete, you can run the example application and authenticate with passkeys. The following video shows the passkey flow on a simulator, for both registration and authentication flows:

Manage Device Compatibility

You may need to support customers with iOS devices on versions below 15, for which native passkeys are not supported. To do so, integrate code similar to that in the Demo/Classes/FlowViewModel.swift class of the HAAPI Model SDK Code Example, for both registration and authentication. Older versions will then present a fallback view that triggers opening of the system browser:

private func prepareWebAuthnRegistration(operationStep: WebAuthnRegistrationClientOperationStep) {

    if #available(iOS 15.0, *) {
        self.doWebauthnRegistration()
    } else {
        showFallbackView()
    }
}

If a user with an old device attempts to use passkeys, the HAAPI flow will present the following screen, to prompt the user to switch to the system browser:

Conclusion

When using the Hypermedia Authentication API in a mobile app, you get built-in support for strong user authentication using passkeys, with a purely native login user experience. This tutorial explained the configuration steps. By implementing an OAuth flow in this manner, you don't need to write any code, and your apps will receive tokens with which to call APIs, for an end-to-end security solution.