Authentication

Authentication

Implement authentication flows on iOS using the AuthenticationServices framework, including Sign in with Apple, passkeys, OAuth/third-party web auth, Password AutoFill, and biometric re-authentication.

Contents

• Sign in with Apple
• Credential Handling
• Credential State Checking
• Token Validation
• Existing Account Setup Flows
• Passkeys
• ASWebAuthenticationSession (OAuth)
• Password AutoFill Credentials
• Biometric Authentication
• Security Boundaries
• SwiftUI SignInWithAppleButton
• Common Mistakes
• Review Checklist
• References

Sign in with Apple

Add the "Sign in with Apple" capability in Xcode before using these APIs.

UIKit: ASAuthorizationController Setup

import AuthenticationServices

final class LoginViewController: UIViewController {
    func startSignInWithApple() {
        let provider = ASAuthorizationAppleIDProvider()
        let request = provider.createRequest()
        request.requestedScopes = [.fullName, .email]

        let controller = ASAuthorizationController(authorizationRequests: [request])
        controller.delegate = self
        controller.presentationContextProvider = self
        controller.performRequests()
    }
}

extension LoginViewController: ASAuthorizationControllerPresentationContextProviding {
    func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor {
        view.window!
    }
}

Delegate: Handling Success and Failure

extension LoginViewController: ASAuthorizationControllerDelegate {
    func authorizationController(
        controller: ASAuthorizationController,
        didCompleteWithAuthorization authorization: ASAuthorization
    ) {
        guard let credential = authorization.credential
            as? ASAuthorizationAppleIDCredential else { return }

        let userID = credential.user  // Stable, unique, per-team identifier
        let email = credential.email  // nil after first authorization
        let fullName = credential.fullName  // nil after first authorization
        let identityToken = credential.identityToken  // JWT for server validation
        let authCode = credential.authorizationCode  // Short-lived code for server exchange

        // Save userID to Keychain for credential state checks
        // See references/keychain-biometric.md for Keychain patterns
        saveUserID(userID)

        // Send identityToken and authCode to your server
        authenticateWithServer(identityToken: identityToken, authCode: authCode)
    }

    func authorizationController(
        controller: ASAuthorizationController,
        didCompleteWithError error: any Error
    ) {
        let authError = error as? ASAuthorizationError
        switch authError?.code {
        case .canceled:
            break  // User dismissed
        case .failed:
            showError("Authorization failed")
        case .invalidResponse:
            showError("Invalid response")
        case .notHandled:
            showError("Not handled")
        case .notInteractive:
            break  // Non-interactive request failed -- expected for silent checks
        default:
            showError("Unknown error")
        }
    }
}

Credential Handling

ASAuthorizationAppleIDCredential properties and their behavior:

Critical: email and fullName are provided ONLY on the first authorization. Cache them immediately during the initial sign-up flow. If the user later deletes and re-adds the app, these values will not be returned.

func handleCredential(_ credential: ASAuthorizationAppleIDCredential) {
    // Always persist the user identifier
    let userID = credential.user

    // Cache name and email IMMEDIATELY -- only available on first auth
    if let fullName = credential.fullName {
        let name = PersonNameComponentsFormatter().string(from: fullName)
        UserProfile.saveName(name)  // Persist to your backend
    }
    if let email = credential.email {
        UserProfile.saveEmail(email)  // Persist to your backend
    }
}

Credential State Checking

Check credential state on every app launch. The user may revoke access at any time via Settings > Apple Account > Sign-In & Security.

func checkCredentialState() {
    let provider = ASAuthorizationAppleIDProvider()
    guard let userID = loadSavedUserID() else {
        showLoginScreen()
        return
    }

    provider.getCredentialState(forUserID: userID) { state, _ in
        DispatchQueue.main.async {
            switch state {
            case .authorized:
                proceedToMainApp()
            case .revoked:
                // User revoked -- sign out and clear local data
                signOut()
                showLoginScreen()
            case .notFound:
                showLoginScreen()
            case .transferred:
                // App transferred to new team -- migrate user identifier
                migrateUser()
            @unknown default:
                showLoginScreen()
            }
        }
    }
}

Credential Revocation Notification

NotificationCenter.default.addObserver(
    forName: ASAuthorizationAppleIDProvider.credentialRevokedNotification,
    object: nil,
    queue: .main
) { _ in
    // Sign out immediately
    AuthManager.shared.signOut()
}

Token Validation

The identityToken is a JWT. Send it to your server for validation -- never trust it client-side alone.

func sendTokenToServer(credential: ASAuthorizationAppleIDCredential) async throws {
    guard let tokenData = credential.identityToken,
          let token = String(data: tokenData, encoding: .utf8),
          let authCodeData = credential.authorizationCode,
          let authCode = String(data: authCodeData, encoding: .utf8) else {
        throw AuthError.missingToken
    }

    var request = URLRequest(url: URL(string: "https://api.example.com/auth/apple")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try JSONEncoder().encode(
        ["identityToken": token, "authorizationCode": authCode]
    )

    let (data, response) = try await URLSession.shared.data(for: request)
    guard (response as? HTTPURLResponse)?.statusCode == 200 else {
        throw AuthError.serverValidationFailed
    }
    let session = try JSONDecoder().decode(SessionResponse.self, from: data)
    // Store session token in Keychain -- see references/keychain-biometric.md
    try KeychainHelper.save(session.accessToken, forKey: "accessToken")
}

Server-side, validate the JWT against Apple's public keys at https://appleid.apple.com/auth/keys (JWKS). Verify: iss is https://appleid.apple.com, aud matches your bundle ID, exp not passed.

Existing Account Setup Flows

On launch, silently check for existing Sign in with Apple and password credentials before showing a login screen:

func performExistingAccountSetupFlows() {
    let appleIDRequest = ASAuthorizationAppleIDProvider().createRequest()
    let passwordRequest = ASAuthorizationPasswordProvider().createRequest()

    let controller = ASAuthorizationController(
        authorizationRequests: [appleIDRequest, passwordRequest]
    )
    controller.delegate = self
    controller.presentationContextProvider = self
    controller.performRequests(
        options: .preferImmediatelyAvailableCredentials
    )
}

Call this in viewDidAppear or on app launch. If no existing credentials are found, the delegate receives a .notInteractive error -- handle it silently and show your normal login UI.

Passkeys

Use passkeys for passwordless WebAuthn-style registration and sign-in. The app must have an Associated Domains entitlement for the relying party domain using the webcredentials: service; passkey requests fail for services the app has not configured as associated domains.

For platform passkeys synced through iCloud Keychain, request a server-provided challenge and create requests with ASAuthorizationPlatformPublicKeyCredentialProvider:

let challenge: Data = try await server.registrationChallenge()
let userID: Data = try await server.passkeyUserID()
let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(
    relyingPartyIdentifier: "example.com"
)
let request = provider.createCredentialRegistrationRequest(
    challenge: challenge,
    name: username,
    userID: userID
)

let controller = ASAuthorizationController(authorizationRequests: [request])
controller.delegate = self
controller.presentationContextProvider = self
controller.performRequests()

For sign-in, use createCredentialAssertionRequest(challenge:) with a fresh server challenge, then send the resulting registration or assertion object to the relying-party server for verification:

let request = provider.createCredentialAssertionRequest(challenge: challenge)

switch authorization.credential {
case let registration as ASAuthorizationPlatformPublicKeyCredentialRegistration:
    try await server.finishPasskeyRegistration(registration)
case let assertion as ASAuthorizationPlatformPublicKeyCredentialAssertion:
    try await server.finishPasskeySignIn(assertion)
default:
    break
}

For inline passkey suggestions, set the username field's textContentType to .username, include the passkey assertion request in the controller, and call performAutoFillAssistedRequests(). Use ASAuthorizationSecurityKeyPublicKeyCredentialProvider only when the user must authenticate with a physical security key. See references/passkeys.md for complete registration, assertion, AutoFill, and security-key patterns.

ASWebAuthenticationSession (OAuth)

Use ASWebAuthenticationSession for OAuth and third-party authentication (Google, GitHub, etc.). Never use WKWebView for auth flows.

import AuthenticationServices

final class OAuthController: NSObject, ASWebAuthenticationPresentationContextProviding {
    private weak var presentationAnchor: ASPresentationAnchor?

    init(presentationAnchor: ASPresentationAnchor) {
        self.presentationAnchor = presentationAnchor
    }

    func startOAuthFlow() {
        let authURL = URL(string:
            "https://provider.com/oauth/authorize?client_id=YOUR_ID&redirect_uri=myapp://callback&response_type=code"
        )!
        let session = ASWebAuthenticationSession(
            url: authURL, callback: .customScheme("myapp")
        ) { callbackURL, error in
            guard let callbackURL, error == nil,
                  let code = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false)?
                      .queryItems?.first(where: { $0.name == "code" })?.value else { return }
            Task { await self.exchangeCodeForTokens(code) }
        }
        session.presentationContextProvider = self
        session.prefersEphemeralWebBrowserSession = true  // No shared cookies
        session.start()
    }

    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
        guard let presentationAnchor else {
            fatalError("ASWebAuthenticationSession needs the active window")
        }
        return presentationAnchor
    }
}

In SwiftUI, use @Environment(\.webAuthenticationSession) and call authenticate(using:callback:preferredBrowserSession:additionalHeaderFields:) with .customScheme("myapp") or .https(host:path:); prefer .ephemeral only when the provider flow should avoid shared browser cookies.

Password AutoFill Credentials

Use ASAuthorizationPasswordProvider to offer saved keychain credentials alongside Sign in with Apple:

func performSignIn() {
    let appleIDRequest = ASAuthorizationAppleIDProvider().createRequest()
    appleIDRequest.requestedScopes = [.fullName, .email]

    let passwordRequest = ASAuthorizationPasswordProvider().createRequest()

    let controller = ASAuthorizationController(
        authorizationRequests: [appleIDRequest, passwordRequest]
    )
    controller.delegate = self
    controller.presentationContextProvider = self
    controller.performRequests()
}

// In delegate:
func authorizationController(
    controller: ASAuthorizationController,
    didCompleteWithAuthorization authorization: ASAuthorization
) {
    switch authorization.credential {
    case let appleIDCredential as ASAuthorizationAppleIDCredential:
        handleAppleIDLogin(appleIDCredential)
    case let passwordCredential as ASPasswordCredential:
        // User selected a saved password from keychain
        signInWithPassword(
            username: passwordCredential.user,
            password: passwordCredential.password
        )
    default:
        break
    }
}

Set textContentType on text fields for AutoFill to work:

usernameField.textContentType = .username
passwordField.textContentType = .password

Biometric Authentication

Use LAContext from LocalAuthentication for local re-authentication before showing account settings or starting sensitive actions. Do not treat a returned Bool as proof to unlock a stored secret; protect secrets with Keychain access control instead. See references/keychain-biometric.md for SecAccessControl and .biometryCurrentSet patterns.

import LocalAuthentication

func authenticateWithBiometrics() async throws -> Bool {
    let context = LAContext()
    var error: NSError?

    guard context.canEvaluatePolicy(
        .deviceOwnerAuthenticationWithBiometrics, error: &error
    ) else {
        throw AuthError.biometricsUnavailable
    }

    return try await context.evaluatePolicy(
        .deviceOwnerAuthenticationWithBiometrics,
        localizedReason: "Sign in to your account"
    )
}

Required: Add NSFaceIDUsageDescription to Info.plist. Missing this key crashes on Face ID devices.

Security Boundaries

This skill owns user-facing account authentication: Sign in with Apple, passkeys, Password AutoFill, ASAuthorizationController, OAuth session presentation, credential state, and local biometric re-authentication. Route deep security work to swift-security: Keychain architecture/migration, CryptoKit, Secure Enclave, certificate pinning/trust, keychain sharing, storage hardening, and OWASP MASVS/MASTG. Keep only the storage minimum here: tokens and secrets belong in Keychain; LAContext.evaluatePolicy alone must not release protected secrets.

SwiftUI SignInWithAppleButton

Use SignInWithAppleButton in SwiftUI views when the login surface is SwiftUI. Request .fullName and .email, handle .success and .failure, downcast to ASAuthorizationAppleIDCredential, and send the credential through the same server-validation flow as UIKit. Style with .signInWithAppleButtonStyle(...).

Common Mistakes

• Assuming a saved local session means the Apple ID credential is still valid.

Check credential state at launch and handle revocation notifications.

• Showing a full login screen before trying existing account setup flows.

Treat .notInteractive as the normal "no local credential" path.

• Force-unwrapping email or fullName. Cache them on first authorization and

handle nil later.

• Creating an ASAuthorizationController without a presentation context

provider. Authorization UI needs the active presentation anchor.

• Storing identity tokens, authorization codes, access tokens, passwords, or

passkey server state in UserDefaults, files, or Core Data. Store secrets in Keychain and keep relying-party passkey verification server-side.

• Adding passkey requests without webcredentials: Associated Domains for the

relying-party domain, or trying to use app-native passkeys for unrelated websites.

• Expanding authentication work into CryptoKit, Secure Enclave, certificate

pinning, or OWASP MASVS. Route those to swift-security.

Review Checklist

• [ ] "Sign in with Apple" capability added in Xcode project
• [ ] ASAuthorizationControllerPresentationContextProviding implemented
• [ ] Credential state checked on every app launch (getCredentialState(forUserID:completion:))
• [ ] credentialRevokedNotification observer registered; sign-out handled
• [ ] email and fullName cached on first authorization (not assumed available later)
• [ ] identityToken sent to server for validation, not trusted client-side only
• [ ] Tokens stored in Keychain, not UserDefaults or files
• [ ] performExistingAccountSetupFlows called before showing login UI
• [ ] Error cases handled: .canceled, .failed, .notInteractive
• [ ] NSFaceIDUsageDescription in Info.plist for biometric auth
• [ ] ASWebAuthenticationSession used for OAuth (not WKWebView)
• [ ] prefersEphemeralWebBrowserSession set for OAuth when appropriate
• [ ] textContentType set on username/password fields for AutoFill
• [ ] Passkey relying party has webcredentials: Associated Domains configured
• [ ] Passkey registration/assertion challenges come from the server and are verified server-side
• [ ] Deep Keychain, CryptoKit, Secure Enclave, certificate pinning, and MASVS work routed to swift-security

References

• Keychain & biometric patterns: references/keychain-biometric.md
• Passkey patterns: references/passkeys.md
• AuthenticationServices
• ASAuthorizationAppleIDProvider
• ASAuthorizationAppleIDCredential
• ASAuthorizationController
• ASWebAuthenticationSession
• Supporting passkeys
• ASAuthorizationPlatformPublicKeyCredentialProvider
• ASAuthorizationPasswordProvider
• SignInWithAppleButton
• Implementing User Authentication with Sign in with Apple

Keychain Token Storage & Biometric Authentication

Self-contained reference for storing authentication tokens in Keychain and protecting them with Keychain-bound biometric authentication (Face ID / Touch ID). Covers the patterns most commonly needed alongside Sign in with Apple, passkey, and OAuth flows.

This is an authentication-adjacent quick reference, not a full security architecture guide. Route Keychain migration, access-control policy design, CryptoKit encryption, Secure Enclave keys, certificate pinning, keychain sharing, storage-hardening strategy, and OWASP MASVS/MASTG mapping to swift-security.

Contents

• Storing Tokens in Keychain
• Reading Tokens from Keychain
• Deleting Tokens from Keychain
• Biometric Authentication with LAContext
• Biometric-Protected Keychain Items
• Keychain Error Handling
• References

Storing Tokens in Keychain

The Keychain is the ONLY correct place to store tokens, passwords, API keys, or secrets. Never store these in UserDefaults, files, or Core Data.

func saveToKeychain(account: String, data: Data, service: String) throws {
    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrAccount as String: account,
        kSecAttrService as String: service,
        kSecValueData as String: data,
        kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
    ]

    let status = SecItemAdd(query as CFDictionary, nil)

    if status == errSecDuplicateItem {
        let updateQuery: [String: Any] = [
            kSecClass as String: kSecClassGenericPassword,
            kSecAttrAccount as String: account,
            kSecAttrService as String: service
        ]
        let updates: [String: Any] = [kSecValueData as String: data]
        let updateStatus = SecItemUpdate(updateQuery as CFDictionary, updates as CFDictionary)
        guard updateStatus == errSecSuccess else {
            throw KeychainError.updateFailed(updateStatus)
        }
    } else if status != errSecSuccess {
        throw KeychainError.saveFailed(status)
    }
}

Reading Tokens from Keychain

func readFromKeychain(account: String, service: String) throws -> Data {
    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrAccount as String: account,
        kSecAttrService as String: service,
        kSecReturnData as String: true,
        kSecMatchLimit as String: kSecMatchLimitOne
    ]

    var result: AnyObject?
    let status = SecItemCopyMatching(query as CFDictionary, &result)

    guard status == errSecSuccess, let data = result as? Data else {
        throw KeychainError.readFailed(status)
    }
    return data
}

Deleting Tokens from Keychain

func deleteFromKeychain(account: String, service: String) throws {
    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrAccount as String: account,
        kSecAttrService as String: service
    ]

    let status = SecItemDelete(query as CFDictionary)
    guard status == errSecSuccess || status == errSecItemNotFound else {
        throw KeychainError.deleteFailed(status)
    }
}

Use a ThisDeviceOnly accessibility class for sensitive app credentials unless the product explicitly requires restore or sharing behavior. Choose broader Keychain accessibility, migration, or sharing strategy in swift-security, not in this authentication skill.

Do not use kSecAttrAccessibleAlways for app credentials; Apple marks it as not recommended for application use because items remain accessible regardless of lock state.

Biometric Authentication with LAContext

Use LAContext from LocalAuthentication for Face ID / Touch ID prompts before showing sensitive screens or performing protected actions. This is a local interaction gate, not proof that a stored secret is safe to release. For tokens, private keys, or high-value credentials, bind access to the Keychain item with SecAccessControl and let SecItemCopyMatching perform the authentication.

import LocalAuthentication

func authenticateWithBiometrics() async throws -> Bool {
    let context = LAContext()
    var error: NSError?

    guard context.canEvaluatePolicy(
        .deviceOwnerAuthenticationWithBiometrics, error: &error
    ) else {
        // Biometrics not available -- fall back to passcode
        if context.canEvaluatePolicy(.deviceOwnerAuthentication, error: &error) {
            return try await context.evaluatePolicy(
                .deviceOwnerAuthentication,
                localizedReason: "Authenticate to access your account"
            )
        }
        throw AuthError.biometricsUnavailable
    }

    return try await context.evaluatePolicy(
        .deviceOwnerAuthenticationWithBiometrics,
        localizedReason: "Authenticate to access your account"
    )
}

Info.plist Requirement

You MUST include NSFaceIDUsageDescription in Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>Authenticate to access your secure data</string>

Missing this key causes a crash on Face ID devices.

LAContext Configuration

let context = LAContext()
context.localizedFallbackTitle = "Use Passcode"
context.touchIDAuthenticationAllowableReuseDuration = 30
let currentState = context.evaluatedPolicyDomainState // Compare to detect enrollment changes

Biometric-Protected Keychain Items

Protect keychain items so they require biometric authentication to read:

let access = SecAccessControlCreateWithFlags(
    nil,
    kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly,
    .biometryCurrentSet,
    nil
)!

let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrAccount as String: "auth-token",
    kSecValueData as String: tokenData,
    kSecAttrAccessControl as String: access
]

Read the protected item with an authentication context so Keychain, not app logic, controls release of the secret:

let context = LAContext()
context.localizedReason = "Authenticate to access your account"

let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrAccount as String: "auth-token",
    kSecReturnData as String: true,
    kSecMatchLimit as String: kSecMatchLimitOne,
    kSecUseAuthenticationContext as String: context
]

var result: AnyObject?
let status = SecItemCopyMatching(query as CFDictionary, &result)
guard status == errSecSuccess, let tokenData = result as? Data else {
    throw KeychainError.readFailed(status)
}

Use .biometryCurrentSet when an auth token must be invalidated after biometric enrollment changes. Route broader SecAccessControl flag selection and policy tradeoffs to swift-security.

Keychain Error Handling

enum KeychainError: Error {
    case saveFailed(OSStatus)
    case updateFailed(OSStatus)
    case readFailed(OSStatus)
    case deleteFailed(OSStatus)

    var localizedDescription: String {
        switch self {
        case .saveFailed(let status),
             .updateFailed(let status),
             .readFailed(let status),
             .deleteFailed(let status):
            return SecCopyErrorMessageString(status, nil) as String? ?? "Unknown error"
        }
    }
}

References

• Restricting keychain item accessibility
• Accessing Keychain Items with Face ID or Touch ID
• LAContext
• NSFaceIDUsageDescription
• kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly
• SecAccessControlCreateFlags.userPresence
• SecAccessControlCreateFlags.biometryCurrentSet

Passkey Authentication Patterns

Use this reference when implementing app-native passkey registration, passkey sign-in, AutoFill-assisted passkey suggestions, or physical security key fallbacks with AuthenticationServices.

Contents

• Prerequisites
• Registration
• Assertion Sign-In
• Handling Results
• AutoFill-Assisted Requests
• Physical Security Keys
• Common Failure Modes
• References

Prerequisites

Passkeys are public-private key credentials. The device keeps the private key in iCloud Keychain for platform passkeys, and your server, the relying party, stores and verifies the public credential material.

Before making registration or assertion requests:

1. Add the Associated Domains capability. 2. Add webcredentials:example.com for the relying party domain. 3. Host a valid apple-app-site-association file for that domain. 4. Request every registration or assertion challenge from the server.

The relying party identifier passed to ASAuthorizationPlatformPublicKeyCredentialProvider is normally the domain name, such as example.com. The app cannot use passkeys for services that are not configured as associated domains.

Registration

Registration creates a new platform passkey for an account. The server should generate a challenge and stable user ID bytes for the relying-party account.

import AuthenticationServices

func beginPasskeyRegistration(username: String) async throws {
    let challenge: Data = try await server.registrationChallenge(for: username)
    let userID: Data = try await server.passkeyUserID(for: username)

    let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(
        relyingPartyIdentifier: "example.com"
    )
    let request = provider.createCredentialRegistrationRequest(
        challenge: challenge,
        name: username,
        userID: userID
    )

    let controller = ASAuthorizationController(authorizationRequests: [request])
    controller.delegate = passkeyDelegate
    controller.presentationContextProvider = presentationProvider
    controller.performRequests()
}

After the delegate receives ASAuthorizationPlatformPublicKeyCredentialRegistration, send the registration response to the server. The server verifies the challenge and stores the public credential data for future assertions.

Assertion Sign-In

Assertion signs in with an existing passkey. Always use a fresh server challenge.

func beginPasskeySignIn(usernameHint: String?) async throws {
    let challenge: Data = try await server.assertionChallenge(usernameHint)

    let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(
        relyingPartyIdentifier: "example.com"
    )
    let request = provider.createCredentialAssertionRequest(challenge: challenge)

    let controller = ASAuthorizationController(authorizationRequests: [request])
    controller.delegate = passkeyDelegate
    controller.presentationContextProvider = presentationProvider
    controller.performRequests()
}

If the user has no passkey for the relying party, the request fails. Offer registration, password sign-in, or Sign in with Apple as appropriate for the account recovery flow.

Handling Results

Handle passkey credentials in the same ASAuthorizationControllerDelegate method as Sign in with Apple and password credentials:

func authorizationController(
    controller: ASAuthorizationController,
    didCompleteWithAuthorization authorization: ASAuthorization
) {
    switch authorization.credential {
    case let registration as ASAuthorizationPlatformPublicKeyCredentialRegistration:
        Task { try await server.finishRegistration(registration) }

    case let assertion as ASAuthorizationPlatformPublicKeyCredentialAssertion:
        Task { try await server.finishAssertion(assertion) }

    case let credential as ASAuthorizationAppleIDCredential:
        handleAppleIDCredential(credential)

    case let password as ASPasswordCredential:
        signIn(username: password.user, password: password.password)

    default:
        break
    }
}

Do not treat a local passkey result as the final proof of authentication. The relying-party server must verify the challenge and credential response before issuing an app session.

AutoFill-Assisted Requests

Use AutoFill-assisted requests when the login screen has a username text field and should show inline passkey suggestions.

usernameField.textContentType = .username

let request = provider.createCredentialAssertionRequest(challenge: challenge)
let controller = ASAuthorizationController(authorizationRequests: [request])
controller.delegate = passkeyDelegate
controller.presentationContextProvider = presentationProvider
controller.performAutoFillAssistedRequests()

The controller presents UI when a text field with the appropriate content type gets focus. This is usually better than immediately showing a modal sheet on a username/password screen.

Physical Security Keys

Use ASAuthorizationSecurityKeyPublicKeyCredentialProvider only when the user needs a physical FIDO security key over NFC, USB, or Lightning. Keep this as a separate branch from platform passkeys because the provider, registration request, and UX differ:

let provider = ASAuthorizationSecurityKeyPublicKeyCredentialProvider(
    relyingPartyIdentifier: "example.com"
)
let request = provider.createCredentialAssertionRequest(challenge: challenge)

Apps can offer both platform and security-key assertion requests in the same ASAuthorizationController when the relying party supports both.

Common Failure Modes

• Missing webcredentials: Associated Domains entitlement or AASA entry for

the relying-party domain.

• Reusing challenges or generating challenges on device instead of on the

relying-party server.

• Treating ASAuthorizationPlatformPublicKeyCredentialAssertion as complete

authentication before server verification.

• Using the app bundle ID as the relying party identifier when the server's

WebAuthn relying party is a domain.

• Forgetting performAutoFillAssistedRequests() for inline passkey suggestions.
• Using the platform provider when the product requirement is a physical

security key.

References

• Supporting passkeys
• ASAuthorizationPlatformPublicKeyCredentialProvider
• ASAuthorizationPlatformPublicKeyCredentialRegistration
• ASAuthorizationPlatformPublicKeyCredentialAssertion
• ASAuthorizationSecurityKeyPublicKeyCredentialProvider
• ASAuthorizationController.performAutoFillAssistedRequests)