HAAPI WebAuthn Native Mobile Configuration

For mobile apps that use the Hypermedia Authentication API (HAAPI), the app itself can act as the WebAuthn client, using native APIs, rather than needing to use the system browser. This requires version 8.0 or later of the Curity Identity Server, and version 2.5 or later of the HAAPI iOS SDK.

Native WebAuthn Requirements

The HAAPI iOS SDK uses native APIs by default, but this will fail unless the required permissions are configured, or if the iOS version is lower than 15. In this case you can fall back to a browser based flow, and the user can continue to sign in using WebAuthn. This tutorial explains the correct configuration and device prerequisites, in order to run WebAuthn flows with only native screens.

Configure WebAuthn Entitlements

The WebAuthn security overview explains how the authorization server acts as a relying party, to verify the authenticator's response, which includes signature and the expected application identity:

For this flow to work when using native APIs in a mobile app, with the Curity Identity Server providing the backend relying party role, you must update the mobile app's entitlements to grant the backend domain access to web credentials:

Configure Associated Domains

Secondly, an associated domains file must be hosted at a Curity Identity Server URL, of the following form. This must be an internet exposed URL, since it will be called by Apple servers:

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

The file will have content similar to the following, where an example bundle ID is com.mycompany.myapp:

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

This file can be deployed directly, within the webroot folder of the Curity Identity Server. For Docker based deployments this will be at the following location:

/opt/idsvr/usr/share/webroot/.well-known/openid-configuration

Rather than providing the file directly, it is instead recommended to simply register all mobile apps that use HAAPI native WebAuthn in the Curity Identity Server. When using the Admin UI, this is done at System -> Deployment -> Zones. The apple-app-site-association document is then generated for you:

Support for generating the equivalent Android configuration, and generating an assetlinks.json document, is also available in the Curity Identity Server. Once the HAAPI Android SDK is updated with native WebAuthn support, this mechanism will work equivalently for the Android platform.

iOS 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 the latest version is used in the verification process. During development, you can ensure immediate feedback by using a developer mode:

webcredentials:login.example.com?mode=developer

Manage Device Compatibility

In a real iOS app you are likely to have some customers with iOS devices on versions below 15, for which native WebAuthn is not supported. To understand how to manage device versions, clone the HAAPI iOS Code Example and see the code in the Demo/Classes/FlowViewModel module. For both registration and authentication flows you will need a logic branch similar to this, to 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()
    }
}

The code example manages this by presenting the following screen, to allow the user to switch to the system browser:

Testing Native WebAuthn

To get up and running with a mobile app that uses working native webauthn, run the above HAAPI code example by following the tutorial instructions. Next add a WebAuthn authenticator, and select a mode of passkeys-or-user-verifying-devices. This is the most secure option, to restrict authentication to multi-factor WebAuthn devices:

Then update the code example's bundle identifier under Signing & Capabilities in Xcode, to a unique value, of the form com.yourcompany.yourapp. Next, add an App ID of the form yourteamprefix.com.yourcompany.yourapp to the mobile app associations screen in the Curity Identity Server. You must also ensure that the Curity Identity Server is exposed to the internet. This can be done by pointing to a deployed system, or running a local ngrok setup. Finally, add the corresponding webcredentials entry to the mobile app's entitlements.

Video Walkthrough

Once the technical setup is complete, you can then run the following flow on an iOS simulator or device:

Multi-Factor WebAuthn

This tutorial has shown how passkeys and user verified devices can be used with iOS >= 15, in a purely native flow, with no browser screens. You can also use multi-factor WebAuthn on Android or iOS < 15, by falling back to the system browser. For further information on the general behavior, see the Using Multi-Factor WebAuthn Devices tutorial.

Conclusion

When using the hypermedia authentication API to manage mobile logins, there is built-in support for using WebAuthn APIs, providing strong authentication and also a purely native user experience. This tutorial explained the simple technical configuration steps. By implementing WebAuthn in an OAuth flow in this manner, you don't need to write any code, and your apps will also receive tokens with which to call APIs, for an end-to-end solution.