Skip to content

dpearson2699/swift-ios-skills / skills/authentication

authentication

Verified

Implement iOS authentication flows with AuthenticationServices and LocalAuthentication. Use when building Sign in with Apple, passkey/WebAuthn registration or sign-in with ASAuthorizationPlatformPublicKeyCredentialProvider, ASAuthorizationController credential state and revocation handling, ASWebAuthenticationSession OAuth or third-party login, Password AutoFill, identity-token server validation, or local biometric re-authentication with LAContext.

FileKindSize
SKILL.mdskill md14.5 KB
evals/evals.jsonconfig4.5 KB
references/keychain-biometric.mdmarkdown8.2 KB
references/passkeys.mdmarkdown7.2 KB

references/passkeys.md

View on GitHub
# 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](#prerequisites)
- [Registration](#registration)
- [Assertion Sign-In](#assertion-sign-in)
- [Handling Results](#handling-results)
- [AutoFill-Assisted Requests](#autofill-assisted-requests)
- [Physical Security Keys](#physical-security-keys)
- [Common Failure Modes](#common-failure-modes)
- [References](#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.

```swift
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.

```swift
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:

```swift
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.

```swift
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:

```swift
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](https://sosumi.ai/documentation/authenticationservices/supporting-passkeys)
- [ASAuthorizationPlatformPublicKeyCredentialProvider](https://sosumi.ai/documentation/authenticationservices/asauthorizationplatformpublickeycredentialprovider)
- [ASAuthorizationPlatformPublicKeyCredentialRegistration](https://sosumi.ai/documentation/authenticationservices/asauthorizationplatformpublickeycredentialregistration)
- [ASAuthorizationPlatformPublicKeyCredentialAssertion](https://sosumi.ai/documentation/authenticationservices/asauthorizationplatformpublickeycredentialassertion)
- [ASAuthorizationSecurityKeyPublicKeyCredentialProvider](https://sosumi.ai/documentation/authenticationservices/asauthorizationsecuritykeypublickeycredentialprovider)
- [ASAuthorizationController.performAutoFillAssistedRequests](https://sosumi.ai/documentation/authenticationservices/asauthorizationcontroller/performautofillassistedrequests())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall