Add Passage

Add Passage to your iOS project

Prerequisites

• A recent version of Xcode

• App running iOS 14 or later (although passkeys only work on iOS16+)

• A Passage account (register for free if you haven’t already)

• A Passage app (if you don't have one, learn how to create one here)

If you don't already have an iOS project and just want to try out Passage, you can clone our iOS Example App.

Step 1: Publish Associated Domains file

Apple uses Associated Domains to establish a secure association between your domain and your app so you can securely authenticate your users with passkeys. You'll need to create and serve the associated domains file in order to use passkeys or magic links in your iOS app.

Create associated domains file

Create a file called apple-app-site-association (no file extension). You can copy and paste the content below, replacing YOUR_TEAM_ID and YOUR_APP_ID:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "YOUR_TEAM_ID.YOUR_APP_ID",
        "paths": ["*"]
      }
    ]
  },
  "webcredentials": {
    "apps": [
      "YOUR_TEAM_ID.YOUR_APP_ID"
    ]
  }
}

For an example, you can view Passage's associated domains file here.

Note that you only need the applinks object if your app uses magic links.

Publish associated domains file

Serve this file from your site’s .well-known/ directory.

The provided example is very simple and my not cover all of your app's specific needs. Learn more about associated domains here.

Step 2: Add Associated Domains entitlements to your app

The next step is to enable the appropriate entitlements for your project in Xcode. These entitlements will associate your iOS app with your domain and use the apple-app-site-association file to verify this association.

To add the capability and entitlements to your application:

1. Open the target's "Signing & Capabilities" tab in Xcode and add Associate Domains capability.

2. Click Add(+) at the bottom of the Associate Domains section.

3. Add webcredentials:YOUR_DOMAIN like in the screenshot below. Add applinks:YOUR_DOMAIN if your app uses magic links.

Add your associated domains entitlements.

Step 3: Add Passage SDK to your iOS app

Installation

You can easily install Passage through Swift Package Manager or Cocoapods.

To install via Swift Package Manager, simply enter this url Xcode's Swift Package Manager's search bar:

https://github.com/passageidentity/passage-ios

If your app uses Cocoapods instead, add this dependency to your Podfile:

pod 'Passage'

Configuration

Lastly, in Xcode in your project's root folder you'll need to create a Property List file called Passage.plist. Open the file as source code and paste these contents, replacing YOUR_PASSAGE_APP_ID and YOUR_AUTH_ORIGIN (without "https://" prefix).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>appId</key>
    <string>YOUR_PASSAGE_APP_ID</string>
    <key>authOrigin</key>
    <string>YOUR_AUTH_ORIGIN</string>
</dict>
</plist>

You did it! 🎉

The hard part is over! It's time to Get Started using Passage.