Skip to main content
Version: 11.5.0

Signing and Deploying Your AgentPass App on iOS

This page is for organizations that distribute HYPR AgentPass™ for iPhone as an app in their own name, instead of the HYPR app. It is written for two readers:

  • Your mobile build and deployment team, which signs the app with your own Apple team and distributes it.
  • Your gateway administrator, who connects the gateway to the app. This needs Settings: Edit and Notifications: Manage, which Admin has.

HYPR builds the app with your identifiers. Your team distributes it through your own channel: the Apple Developer Enterprise Program (in-house), or a custom app through Apple Business Manager. Supervisors who install the app then follow First Run for Supervisors. Supervisors who use the HYPR app start from Getting the HYPR App on iOS instead.

How It Works​

Apple ties every bundle ID to a single Apple team. HYPR therefore cannot sign an app that carries your bundle ID, and you cannot sign one that carries HYPR's. Instead:

  1. You send HYPR your identifiers and your push configuration.
  2. HYPR builds the app with them, and delivers it to you unsigned.
  3. You sign it with your certificates and provisioning profiles, and distribute it.
  4. Your gateway administrator tells the gateway to trust your app and to send pushes through your Firebase project.

The app opens straight into AgentPass. It does not include the other features of the HYPR app.

What to Send HYPR​

Send these to your HYPR representative before HYPR builds your app.

ItemDetail
Apple Team IDThe 10-character ID of the Apple team that signs the app. It is under Membership details in your Apple Developer account
App bundle IDFor example, com.example.agentpass
Firebase configurationThe GoogleService-Info.plist of an iOS app registered in your Firebase project with the app bundle ID above
App name and iconThe name shown under the icon on the Home Screen, and the icon artwork
Gateway addressThe address of your AgentPass gateway, which supervisors' phones reach
Keep the service account in-house

Send HYPR the GoogleService-Info.plist file only. Your Firebase service-account key is a credential: your gateway administrator enters it on your gateway, and it is never sent to HYPR.

Prepare Push Notifications in Firebase​

The gateway sends approval requests to supervisors' phones through your Firebase project, and Firebase delivers them through Apple Push Notification service. Before HYPR builds the app:

  1. In your Apple Developer account, create an Apple Push Notification service authentication key (.p8).
  2. In your Firebase project, register an iOS app with the app bundle ID, and download its GoogleService-Info.plist.
  3. In the Firebase project's Cloud Messaging settings, upload the APNs authentication key for that iOS app.

What You Receive​

HYPR delivers:

  • An unsigned .ipa built with your bundle ID, app name, icon and gateway address. It contains the app only, with no extensions.
  • An entitlements file, app.entitlements, which turns on production push, associates the app with your gateway's domain for passkeys, and sets complete data protection.

Register the App With Apple​

In the Certificates, Identifiers & Profiles section of your Apple Developer account:

  1. Register an App ID for the app bundle ID, and enable these capabilities.

    CapabilitySetting
    Associated DomainsOn
    Push NotificationsOn
    Data ProtectionComplete Protection
  2. Create a distribution provisioning profile for the App ID, of the type your channel uses: In House for the Enterprise Program, or App Store for a custom app through Apple Business Manager.

Sign the App​

Sign the embedded frameworks first, then the app, with your distribution profile. Any re-signing tool works, provided the app is signed with the entitlements in app.entitlements plus the two your profile supplies: application-identifier and com.apple.developer.team-identifier.

Identifiers must match

The bundle ID in your profile must be the one HYPR built with, and the Team ID must be the one your gateway trusts (see Trust Your App for Passkeys). If either differs, passkey sign-in and push notifications do not work, even though the app installs and opens.

The following example signs the app with Apple's codesign tool on a Mac. Replace the names in angle brackets with your own.

Example: re-sign with codesign
unzip -q <AppName>.ipa
APP="Payload/<AppName>.app"
IDENTITY="Apple Distribution: <Your Organization> (<Team ID>)"

# Embed the distribution profile
cp <app-profile>.mobileprovision "$APP/embedded.mobileprovision"

# Add the two entitlements the profile supplies
cp app.entitlements signing.entitlements
/usr/libexec/PlistBuddy \
-c "Add :application-identifier string <Team ID>.<app bundle ID>" \
-c "Add :com.apple.developer.team-identifier string <Team ID>" \
signing.entitlements

# Sign the embedded frameworks, then the app
find "$APP/Frameworks" -maxdepth 1 \( -name "*.framework" -o -name "*.dylib" \) \
-exec codesign --force --sign "$IDENTITY" {} \;
codesign --force --sign "$IDENTITY" --entitlements signing.entitlements "$APP"

# Check the result, and package it
codesign --verify --deep --strict "$APP"
zip -qr <AppName>-signed.ipa Payload

To confirm the entitlements were applied, run codesign -d --entitlements - "$APP" and compare the output with signing.entitlements.

Distribute the App​

Distribute the signed .ipa the way your organization distributes its other internal apps:

  • Enterprise Program (in-house): through your mobile device management system or your internal app catalog.
  • Apple Business Manager (custom app): upload it to App Store Connect, submit it for review, and make it available to your organization as a custom app.

Supervisors need iOS 17 or later.

Connect Your Gateway​

A gateway administrator does this once, on your AgentPass gateway. Trusting the app needs Settings: Edit, and sending pushes needs Notifications: Manage.

Trust Your App for Passkeys​

  1. Open Settings → Gateway settings, and click the Passkeys (FIDO2) tab.
  2. In Mobile App Associations, add your app to iOS App IDs as <Team ID>.<app bundle ID>, for example ABCDE12345.com.example.agentpass. The field takes a comma-separated list, so keep any entries already there.
  3. Click Save.

iPhones learn which apps the gateway trusts from the association file the gateway publishes, and Apple caches that file. After you save, allow time before the first sign-in succeeds on a newly installed app. See Connecting to Your HYPR Tenant for the rest of the card.

Send Pushes Through Your Firebase Project​

  1. Open Settings → Notifications.
  2. In the Firebase Cloud Messaging card, enter your Firebase Project ID, and paste your Service Account JSON.
  3. Turn on Enable Firebase channel, and click Save FCM settings.

See Notifications for the card's states and the events it delivers.

Let Supervisors' Passkeys Approve​

Your app has no passkey store of its own, so supervisors' passkeys are kept by the phone's password manager. Under the Strict (HYPR Mobile only) passkey approval policy, those passkeys cannot approve agent actions. Set Passkey approval policy to Any passkey, or to Custom allowlist with the authenticators your supervisors use. See Decide Which Passkeys Count.

First Run for Supervisors​

The app opens straight into AgentPass, with no separate switch to turn on. It does not store passkeys itself: the supervisor's passkey is kept by the phone's password manager, as any other passkey is. Approvals with it work once your gateway administrator has let supervisors' passkeys approve.

The supervisor enrolls an approval passkey through Setting Up Your Approval Passkey, scanning the QR code with the phone's camera, then opens the app and taps Sign in. From there, the app works as described in Getting the HYPR App on iOS.

If Something Does Not Work​

  • Sign-in fails on every phone. Confirm that iOS App IDs lists <Team ID>.<app bundle ID> exactly, and that the app was signed by that Team ID. After a change, allow time for Apple to refresh its cached copy of the association file.
  • No push notifications arrive. Confirm the APNs authentication key is uploaded to the same Firebase project whose Project ID and service account are on the gateway, and that the app was signed with the entitlements from app.entitlements, which enable production push.
  • The app does not install. The signing entitlements lack application-identifier or com.apple.developer.team-identifier, or they do not match the profile. Add them as in the example, and sign again.
  • The app installs but closes at launch. The profile does not match the bundle ID, or a framework was left unsigned. Check the profile, and sign again.

For anything else, contact HYPR Support.