
HAAPI WebAuthn Native Mobile Configuration
On this page
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.
Mobile Supported Platforms
At the time of writing, use of native WebAuthn APIs is only supported in the iOS HAAPI SDK. In addition, these APIs are only supported on devices running iOS 15 or higher. Android support will be included in an upcoming release of the Curity Identity Server and client side SDKs.
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.
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial