Passkeys on iOS
Introduction
This guide explains how to implement passkey registration and authentication workflow on iOS applications.
| The following code samples and screenshots are issued from our example application using our SDK. Feel free to check out the Github project. |
Passkeys prerequisites
To successfully enable passkeys for iOS:
-
Enable the WebAuthn feature on your ReachFive account.
You may need to contact support to have this enabled if you do not see it on your ReachFive Console.
You’ll also need:
-
An iOS device that supports passkeys.
-
iOS OS 16 or later.
-
To install our SDK Core which exposes all of the passkey methods.
-
End users and those testing the setup need an iCloud account with 2-step authentication enabled. iCloud Keychain must be activated.
Get started
This section describes important terms and concepts as well the steps needed to get started with passkeys for iOS with ReachFive.
Relying Party ID
The Relying Party ID is the domain to which passkeys are bound. Once bound to a domain, it can be used on subdomains but not other full domains.
Using the Relying Party ID of boulangerie.com allows the use of credentials on help.boulangerie.com for example, but not on a different full domain like boulangerie.fr.
Also, if the Relying Part ID is bound to a subdomain such as login.boulangerie.com, then it cannot be used on the root domain, another full root domain, or another subdomain of boulangerie.com such as help.boulangerie.com.
In this case, customers would need a common login page for passkeys for varying full domains like the stated example here.
Discoverable login
With discoverable logins, the passkey manager presents the user with all the stored credentials for this app or website meaning that the user does not have to manually enter his or her identifier.
Discoverable logins aren’t restricted to passkeys. This is also applicable to passwords. See login(withRequest) for more details.
Non-discoverable login
With non-discoverable login, the user must manually enter his or her username before the passkey manager can find a credential.
apple-app-site-association
You need to host a apple-app-site-association file on https://<your_domain>/.well-known/apple-app-site-association to allow the application to register and authenticate with credentials associated with the Relying Party ID <your_domain>.
{
"webcredentials": {"apps": ["ABCDE12345.com.example.app"]} (1)
}| 1 | A value of the following format: <Application Identifier Prefix>.<Bundle Identifier>. |
Hosted pages
If you are using’s ReachFive’s Hosted Pages and need the apple-app-site-association file hosted on your domain at ReachFive, you should input the content of your apple-app-site-association file into the text area called apple-app-site-association in the section of the ReachFive Console.
| We do not perform any validation on the file. |
If you do not use a custom domain, the Relying Party ID associated to credentials created on Hosted Pages is <account>.reach5.net.
Your apple-app-site-association file is served at https://<account>.reach5.net/.well-known/apple-app-site-association.
If you do use a custom domain, your Relying Party ID is https://<custom_domain>.
Your apple-app-site-association file is served at https://<custom_domain>/.well-known/apple-app-site-association.
You could also choose to host the apple-app-site-association file on your root domain.
Hosted Pages are accessible via auth.example.com.
You could then host the apple-app-site-association file at example.com.
This is a viable long-term option in the case you may not use Hosted Pages in the future.
