In AuthenticationServices, a passkey sign-in through ASAuthorizationPlatformPublicKeyCredentialProvider returns an error with no sheet for members who have a passkey on the website; what do you check, and how should the requests be set up?
answer
- the app and the domain must agree
- webcredentials, not applinks
- relyingPartyIdentifier equals the associated domain
- AASA reaches devices through Apple's CDN
- preferImmediatelyAvailableCredentials and AutoFill
basics
~20 sPasskey requests need the relying party's domain in a webcredentials associated domain, with an apple-app-site-association file listing the app; without it the request returns an error. Then check the relyingPartyIdentifier matches, and that the device actually holds a credential.
solid answer
~40 sApple's passkey documentation is explicit: a registration or assertion request needs an associated domain with the `webcredentials` service type, or it returns an error. So first check the entitlement lists `webcredentials:studio.example.com` (an `applinks` entry does not count), that `https://studio.example.com/.well-known/apple-app-site-association` has a `webcredentials` section with `<Team ID>.<bundle ID>`, and that Apple's CDN has fetched it, which can take up to 24 hours. Next, `ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier:)` must use that same domain, because an app cannot use passkeys for services it has not associated. Finally, an assertion errors when the device has no credential for the relying party. For setup, combine `createCredentialAssertionRequest(challenge:)` with an `ASAuthorizationPasswordProvider` request in one `ASAuthorizationController`; use `performRequests(options: .preferImmediatelyAvailableCredentials)` for a prompt that stays silent without local credentials, and `performAutoFillAssistedRequests()` to offer passkeys from the username field.
code
swift · 22 linesimport AuthenticationServices
@MainActor
func startMemberSignIn(challenge: Data, fromUsernameField: Bool,
delegate: any ASAuthorizationControllerDelegate,
anchor: any ASAuthorizationControllerPresentationContextProviding) {
// The relying party ID must be listed in the entitlement as webcredentials:studio.example.com
let passkeys = ASAuthorizationPlatformPublicKeyCredentialProvider(
relyingPartyIdentifier: "studio.example.com")
let requests: [ASAuthorizationRequest] = [
passkeys.createCredentialAssertionRequest(challenge: challenge),
ASAuthorizationPasswordProvider().createRequest(),
]
let controller = ASAuthorizationController(authorizationRequests: requests)
controller.delegate = delegate
controller.presentationContextProvider = anchor
if fromUsernameField {
controller.performAutoFillAssistedRequests() // offered when the username field gets focus
} else {
controller.performRequests(options: .preferImmediatelyAvailableCredentials)
}
}go deeper
Recall that passkey requests come from ASAuthorizationPlatformPublicKeyCredentialProvider with a relying party ID and run through ASAuthorizationController.
Explain the webcredentials entitlement and association file, and what performRequests(options:) and performAutoFillAssistedRequests() each change about when UI appears.
Diagnose an immediate error in order: entitlement service, association file and CDN delay, relying party ID match, then whether the device holds a credential.
Own the association file as release infrastructure shared by the website and the app, and plan how members move from passwords to passkeys.
## The symptom The yoga studio's website already lets members create passkeys. A new app build adds "Sign in with passkey", and for every tester the delegate's `authorizationController(controller:didCompleteWithError:)` fires at once, with no sheet. The Swift code compiles and looks like Apple's sample, so the fault is almost always in how the app and the domain are tied together. ## Check 1: the webcredentials association Apple's passkey guide says it directly: you need an **associated domain with the `webcredentials` service type** when making a registration or assertion request; otherwise the request returns an error. Two halves must match: 1. **The entitlement.** The Associated Domains capability lists `webcredentials:studio.example.com`. The common slip is a target that only has `applinks:studio.example.com` for universal links, which is a different service. 2. **The association file.** `https://studio.example.com/.well-known/apple-app-site-association` must have a `webcredentials` object whose `apps` array contains `<Team ID>.<bundle ID>`. It is served over https with a valid certificate and no redirects. Each subdomain needs its own entitlement entry and its own file. Since iOS 14, devices fetch the file from **Apple's content delivery network**, which requests it within 24 hours; a freshly edited file can be invisible to devices for a while, and a server that is not reachable from the public internet needs the entitlement's alternate mode during development. ## Check 2: the relying party identifier `ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier:)` takes the domain of the service, usually the website's domain, and every request the provider creates uses it. A passkey created on the website for `studio.example.com` can only be offered for that identifier. Apple's documentation adds that an app **can't use passkeys for services it hasn't configured as associated domains**, so the identifier and the `webcredentials` entry must name the same domain. ## Check 3: is there a credential at all? For an assertion, Apple documents that **an error returns if there aren't any credentials on the device**, and recommends asking the member to register. Testers whose passkeys live elsewhere, or whose device has no iCloud Keychain passkeys for the domain, see exactly this failure even when the association is right. ## Setting up the requests The provider class is iOS 15; passkeys synced through iCloud Keychain arrived with iOS 16, below a typical iOS 17 deployment target, so no availability checks are needed. - **Registration:** `createCredentialRegistrationRequest(challenge:name:userID:)`, with the challenge and user ID coming from the server. Registering again with the same user ID overwrites the existing passkey on the member's devices. - **Assertion:** `createCredentialAssertionRequest(challenge:)` with a fresh server challenge. - **One controller, several requests:** put the assertion request and `ASAuthorizationPasswordProvider().createRequest()` in the same `ASAuthorizationController`. The sheet shows whatever credentials the device has for those types, and the delegate receives either an `ASAuthorizationPlatformPublicKeyCredentialAssertion` or an `ASPasswordCredential`. How you start the controller decides when UI appears: | Call | Available | Behaviour | |---|---|---| | `performRequests()` | iOS 13 | shows the sheet now | | `performRequests(options: .preferImmediatelyAvailableCredentials)` | iOS 16 | presents only if credentials are immediately available on this device; otherwise the delegate gets an error | | `performAutoFillAssistedRequests()` | iOS 16 | shows nothing until a text field with the right text content type, the username field, gets focus, then offers passkeys in its suggestions | A good pattern is the AutoFill-assisted call when the sign-in screen appears, plus the immediate-credentials call behind a "Sign in with passkey" button, falling back to the normal sign-in screen on error. Configuring the username field itself belongs with keyboard and focus handling in SwiftUI. ## Common mistakes - **Testing against a staging domain that Apple's CDN cannot reach** without the entitlement's alternate mode, then concluding passkeys are broken. - **A relying party identifier with a scheme or path**, such as a full URL, instead of the bare domain the provider expects. - **Showing an error alert for the immediate-credentials call.** With `.preferImmediatelyAvailableCredentials`, an error simply means nothing local was available; fall back to the normal screen quietly. ## What the app does not do The delegate hands the app `credentialID`, `userID`, `signature`, `rawAuthenticatorData` and `rawClientDataJSON`. The app sends them to the server; **the server** verifies the signature against the stored public key and checks the challenge. That ceremony is covered with WebAuthn on the backend.
- What does .preferImmediatelyAvailableCredentials change for a registration request?For registration the option means the controller is presented only if the device is currently set up to fulfil at least one of the request types. For sign-in it means only when credentials are immediately available on the device. Either way, the delegate's error method is called instead of showing UI.
- Why put an ASAuthorizationPasswordProvider request beside the passkey assertion request?Members who have not created a passkey may still have a saved password for the studio's domain. With both requests in one controller, the sheet lists whatever the device holds for either type, and the delegate receives an `ASPasswordCredential` when a password is chosen.
- A member registers a passkey in the app with the same user ID they used on the website. What happens?Apple documents that registering a passkey with the same user ID as an existing one overwrites the existing passkey on the member's devices. The server must then replace the old public key with the new one.
- An applinks entry for the domain is enough for passkeys in the app.
- Any relyingPartyIdentifier works once the app has the Associated Domains capability.
- performAutoFillAssistedRequests() shows the passkey sheet immediately, like performRequests().
- The app verifies the assertion signature itself, so no server check is needed.
- Editing the association file takes effect on devices the moment it is deployed.