AppKey Swift Demo #

I still think that one of the finest tests of programming ability is to hand the programmer about 30 pages of code and see how quickly he can read through and understand it. – Bill Gates

Get the Swift Demo Working for you #

The first step is to clone the sample project to your local machine. You can do this with a simple Git clone command, as shown below:

git clone git@github.com:Cosync/AppKey-SwiftDemo.git

As the iOS developer evaluating the Cosync AppKey passkey authentication system, your task is to integrate the sample app using your company’s credentials as a proof of concept. This section outlines the steps required to set it up and get it running quickly and efficiently.

FIDO2 passkeys provide a highly secure, phishing-resistant authentication protocol, but implementing them requires careful configuration. As a developer, you need to lock down several key components to ensure security. While an out-of-the-box solution with minimal setup might be convenient, it wouldn’t be as secure.

Fortunately, once you understand the core concepts behind FIDO2 passkey integration on iOS, the process is straightforward. The essential components you need to configure are:

• Relying Party ID
• Apple App ID
• apple-app-site-association file
• AppKey Application
• Constants file
• Xcode App signing capabilities
• Xcode Associated Domains

With these in place, you’ll have a secure and properly functioning passkey implementation.

What is a Relying Party ID? #

According to the FIDO2 WebAuthn specification, the Relying Party (RP) is the entity whose web application uses WebAuthn for user registration and authentication. The RP controls WebAuthn API options during these processes.

If that definition didn’t help much, let’s break it down.

FIDO2 passkeys follow a client/server model:

• The client is your app, running as either a web page or a mobile application.
• The server is a cloud-based system that communicates with the client via a REST API, implementing the FIDO2 WebAuthn protocol for passkey authentication.
• The Relying Party ID is a unique URL that identifies your application on the internet. It must be an active, functioning web address that you configure.

Typically, the Relying Party ID is the root URL where the client’s WebAuthn server is hosted. If you’re using Cosync AppKey, your WebAuthn server runs at:

https://api.appkey.io

As the developer, you are responsible for registering the URL associated with your Relying Party ID, as this will likely be where a web version of your application is hosted. The passkeys generated by Cosync AppKey for your app will be tied to this Relying Party ID, ensuring a consistent and secure authentication experience.

Setting up a Relying Party ID requires two key skills:

• Using a Domain Name Registrar to secure the URL and any necessary subdomains.
• Setting up a basic hosted website under the Relying Party ID.

Apple App ID #

To get the AppKey Swift sample application working with your Relying Party ID, you need to define an Apple App ID within your Apple Developer account that corresponds to the Relying Party ID.

For example, if you have registered xyzsoft.com as your root domain and selected demo.xyzsoft.com as your Relying Party ID, you’ll need to configure your Apple App ID accordingly.

When you log into your Apple Developer account, you’ll see a 10-character alphanumeric identifier—this is your Team ID. An Apple App ID consists of this Team ID plus a unique Bundle ID.

To create an Apple App ID:

• Navigate to Certificates, Identifiers & Profiles in your Apple Developer portal.
• If your Relying Party ID is ‘demo.xyzsoft.com’, set your Bundle ID to ‘com.xyzsoft.demo’.
• When creating your Apple App ID, ensure it includes at least the following two capabilities:
  • Associated Domains
  • AutoFilll Credential Provider

The Apple App ID you just created is now ready to be used for signing your AppKey Swift sample application.

apple-app-site-association file #

The next critical step is to properly configure the ‘apple-app-site-association’ file, which must be hosted on the website linked to your Relying Party ID. This is a JSON file that specifies the Apple App ID for your Swift application, allowing it to generate and use passkeys for authentication.

Since you control the website associated with your Relying Party ID, you are also the only one who can update this file. If another application—one that isn’t yours—tries to use your users’ passkeys but its Apple App ID isn’t listed in this file, the WebAuthn server will reject the request. Only your app’s users can authenticate using the passkeys. This is what makes the FIDO2 WebAuthn protocol secure.

For example, if your Team ID is WQKLK89MX9 and your Bundle ID is ‘com.xyzsoft.demo’, your apple-app-site-association file would contain the following JSON:

{
    "webcredentials": { 
        "apps" : [
            "WQKLK89MX9.com.xyzsoft.demo"
        ]
    }
}

The app format follows the structure .. Since this is part of a JSON array, you can include multiple Apple App IDs, separated by commas.

AppKey Application #

Now you’re ready to create an application in the Cosync AppKey portal at https://appkey.io to enable passkey authentication for your Swift sample app. If your Relying Party ID is demo.xyzsoft.com, you might name your application DemoXYZSoft or something similar. Go ahead and set this up in the AppKey portal.

Once the application is created:

• Navigate to the Options tab and set your RELYING PARTY ID—be sure to include the https:// prefix, as shown below.
• Go to the Keys tab, copy the App Token to your clipboard. Your Swift application will use this token to direct Cosync AppKey’s REST API to authenticate users with this specific application.

At this stage, the Cosync AppKey WebAuthn server recognizes your application’s Relying Party ID and can verify whether the requesting application is authorized to authenticate through it.

Constants file #

Next, open the project in Xcode and update the Constants file to include your Relying Party ID and AppKey application token. If your Relying Party ID is “demo.xyzsoft.com”, modify the file as shown below.

struct Constants {
    static let RELYING_PARTY_ID = "demo.xyzsoft.com"
    static let API_URL_ADDRESS = "https://api.appkey.io"
    static let APP_TOKEN = “<your app token copied from above>“
    static let GOOGLE_CLIENT_ID = ""
}

Do not worry about the GOOGLE_CLIENT_ID.

Xcode App signing capabilities #

Next, configure your project’s signing capabilities. Select the ‘appkey’ target, then navigate to the “Signing & Capabilities” tab. Choose the Team associated with your Apple Developer account, and enter the Bundle Identifier for the Apple App ID you defined earlier (e.g., ‘com.xyzsoft.demo’).

Xcode Associated Domains #

The final step is configuring Associated Domains, which allow the WebAuthn server to correctly recognize your application. Associated Domains create a secure link between your app and your website, enabling credential sharing and other web-to-app functionality.

You’ll find the Associated Domains section in the same Signing & Capabilities tab. In your case, these domains should point to the website hosting your apple-app-site-association file. It should be formatted like this:

webcredentials:xyzsoft.com
webcredentials:*.xyzsoft.com

The second associated domain with a wildcard ‘*’, supports any subdomains off of the root domain.

Run your sample app #

The simplest way to test your AppKey Swift sample app is by running it in a simulator of your choice. Once it launches, navigate to the Signup tab to register a new user.

Since simulators don’t have a physical camera for biometric validation, Face ID can’t be used directly. Fortunately, Apple provides a workaround—you can simulate Face ID enrollment by navigating to the Features menu in the iOS Simulator app.

Once enrolled is checked, you can proceed by pressing the Signup button. You should then see the following screen.

Click Continue, and the Face ID biometric authentication screen should appear.

To simulate a Face ID check without a real scan, open the Features menu in the iOS Simulator app, navigate to the Face ID popup, and select Matching Face.

This will trigger a simulated Face ID recognition.

At this stage, the AppKey authentication server will send the user a confirmation code via email. Enter this code into the provided field to complete the registration process. Once confirmed, the user will have a passkey registered for your application, successfully enabling passkey authentication for your Relying Party ID.