dpearson2699/swift-ios-skills / skills/authentication
authentication
VerifiedImplement 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.5 KB |
| evals/evals.json | config | 4.5 KB |
| references/keychain-biometric.md | markdown | 8.2 KB |
| references/passkeys.md | markdown | 7.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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |