> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # Passkey basics ## What is a passkey? A passkey is a modern authentication method that replaces traditional passwords with cryptographic keys. It enhances security by using public key cryptography, making it resistant to phishing and credential theft. Passkeys are designed to be user-friendly, allowing users to authenticate with a simple gesture, such as a fingerprint or facial recognition, without the need to remember complex passwords. Passkeys are based on the [WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) standard, which is supported by major browsers and platforms. They can be used for both web and native applications, providing a seamless and secure authentication experience across devices. Passkeys are stored securely on the user's device, and can be used across different platforms and devices, making them a versatile solution for modern authentication needs. They are designed to work with both Web and native applications, allowing users to authenticate seamlessly across different environments. ## Benefits of using passkeys - **Enhanced Security**: Passkeys use public key cryptography, which is more secure than traditional passwords. They are resistant to phishing attacks and credential theft. - **User-Friendly**: Passkeys eliminate the need for users to remember complex passwords. Authentication can be done with a simple gesture, such as a fingerprint or facial recognition. - **Cross-Platform Compatibility**: Passkeys can be used across different platforms and devices, providing a consistent authentication experience for users. - **Seamless Integration**: Passkeys can be easily integrated into existing applications and workflows, allowing developers to enhance security without disrupting the user experience. - **Future-Proof**: As the industry moves towards passwordless authentication, passkeys are a forward-looking solution that aligns with modern security standards and practices. ## How passkeys work Passkeys work by leveraging public key cryptography to authenticate users. When a user registers for a service using a passkey, a key pair is generated: a public key and a private key. The public key is stored on the server, while the private key remains securely on the user's device. During authentication, the server sends a challenge to the user's device. The device uses the private key to sign this challenge and sends the signed response back to the server. The server then verifies the signature using the stored public key. If the verification is successful, the user is authenticated. This process ensures that: - The private key never leaves the user's device. - Each authentication request is unique (due to the challenge). - Only the device with the correct private key can generate valid signatures. - The server can verify authenticity without storing sensitive credentials. ### Registration flow 1. **User Initiates Registration**: User requests to register a new passkey. 2. **Challenge Generation**: Server generates a unique challenge and sends it to the client. 3. **Key Pair Creation**: User's device creates a new public-private key pair. 4. **User Verification**: Device prompts for user verification (fingerprint, face, PIN, etc.). 5. **Attestation**: Device signs the challenge and public key information. 6. **Server Storage**: Server verifies the attestation and stores the public key. ### Authentication flow 1. **User Initiates Login**: User attempts to authenticate. 2. **Challenge Request**: Server generates and sends a challenge to the device. 3. **Signature Creation**: Device uses the private key to sign the challenge. 4. **User Verification**: Device verifies the user's identity locally. 5. **Response Validation**: Server verifies the signature using the stored public key. 6. **Access Granted**: If verification succeeds, the user is authenticated. ## Common passkey terminology ### Core concepts | Term | Definition | | ------------ | ----------------------------------------------------------------------------------------------------- | | **Passkey** | A cryptographic credential that replaces passwords, consisting of a public-private key pair. | | **WebAuthn** | The Web Authentication API standard that enables passwordless authentication on the Web. | | **FIDO2** | A set of standards that includes WebAuthn and CTAP (Client to Authenticator Protocol). | | **CTAP** | The Client to Authenticator Protocol (CTAP) enables communication between devices and authenticators. | ### Authentication components | Term | Definition | | -------------------------- | -------------------------------------------------------------------------------------------------- | | **Relying Party (RP)** | The application or service that relies on the authenticator to verify user identity. | | **Authenticator** | The device or software that generates and manages passkeys (such as a smartphone or security key). | | **User Agent** | The browser or application that facilitates communication between RP and authenticator. | | **Platform Authenticator** | Built-in authenticator (TouchID, FaceID, Windows Hello). | | **Roaming Authenticator** | External security key that can be used across multiple devices. | ### Technical terms | Term | Definition | | ------------------------------------ | ---------------------------------------------------------------------------------------------- | | **Credential ID** | Unique identifier for a specific passkey credential. | | **Public Key** | Cryptographic key stored on the server to verify signatures. | | **Private Key** | Secret key stored securely on the user's device, never shared. | | **Challenge** | Random data sent by the server to prevent replay attacks. | | **Attestation** | Cryptographic proof that a credential was created by a genuine authenticator. | | **Assertion** | Cryptographic proof that the user possesses the private key during authentication. | | **RP ID (Relying Party Identifier)** | Domain identifier that determines the scope of passkey validity. | | **Origin** | Complete URL including protocol, domain, and port where the authentication request originates. | ### User experience terms | Term | Definition | | --------------------------- | -------------------------------------------------------------------------- | | **User Verification** | Process of confirming the user's identity (for example, biometric or PIN). | | **User Presence** | Confirmation that a user is physically present during authentication. | | **Resident Key** | Passkey stored on the authenticator device itself. | | **Discoverable Credential** | Credential that can be found without providing a username. | ## Passkey policy choices in IDaaS IDaaS Passkey/FIDO2 settings let administrators choose how broadly passkeys can be used and how strictly IDaaS validates them. These choices affect both user experience and security posture. - **User Verification** controls whether a passkey must verify the user locally with a PIN, biometric, or device unlock. This is stronger than User Presence, which only confirms interaction with the authenticator. - **Resident Key** controls whether a passkey can identify the user during passwordless sign-in without requiring the user to enter a username first. - **Attestation** controls how much information IDaaS requests about the authenticator model during registration. - **Authenticator Attachment** controls whether users can register built-in platform authenticators, external authenticators, or both. - **Device-Bound Only** controls whether synced passkeys are allowed. A platform authenticator can create a synced passkey, so this setting is separate from Authenticator Attachment. For configuration recommendations and tradeoffs, see [Configure Passkey/FIDO2 authenticator settings](/docs/authentication-and-security/manage-authenticators/manage-passkey-fido2-authenticators/modify-passkey-fido2-authenticator-settings.md#choose-a-policy-posture). ## Understanding Relying Party Identified (RP ID) and Origin One of the most important concepts to understand when implementing passkeys is the difference between **RP ID** (Relying Party Identifier) and **Origin**. These two values work together to ensure secure passkey operations but serve different purposes. ### RP ID (Relying Party Identifier) The RP ID is a domain identifier that determines the scope of passkey validity. It defines which domains can use a particular passkey credential. **Key characteristics:** - Must be a valid domain name (for example, `example.com`). - Cannot include protocol, port, or path. - Determines passkey scope and sharing across subdomains. - Used during both registration and authentication. **Examples:** ```text Valid RP IDs: - example.com - auth.example.com - login.mycompany.org Invalid RP IDs: - https://example.com (includes protocol) - example.com:8080 (includes port) - example.com/login (includes path) ``` ### Origin The Origin is the complete URL identifier that specifies exactly where the authentication request is coming from. **Key characteristics:** - Includes protocol (https://) - Includes domain name - Includes port (if non-standard) - Must match exactly during authentication - Provides precise security context **Examples:** ```text Valid Origins: - https://example.com - https://auth.example.com - https://example.com:8443 - https://login.mycompany.org ``` ### Relationship and rules The relationship between RP ID and Origin follows specific rules: 1. Origin must be HTTPS (except for localhost during development). 2. RP ID must be a suffix of the Origin's hostname. 3. RP ID cannot be a public suffix (for example, `.com`, `.co.uk`). **Valid combinations:** | Origin | RP ID | Valid? | Reason | | -------------------------- | ------------------ | ------ | ---------------------------------- | | `https://example.com` | `example.com` | ✅ | Perfect match | | `https://auth.example.com` | `example.com` | ✅ | RP ID is suffix of origin hostname | | `https://auth.example.com` | `auth.example.com` | ✅ | Perfect match | | `https://example.com:8080` | `example.com` | ✅ | Port doesn't affect RP ID | **Invalid combinations:** | Origin | RP ID | Valid? | Reason | | -------------------------- | ---------------- | ------ | ----------------------------------- | | `https://example.com` | `different.com` | ❌ | RP ID not related to origin | | `https://auth.example.com` | `badexample.com` | ❌ | RP ID not a suffix | | `https://example.com` | `com` | ❌ | RP ID is a public suffix | | `http://example.com` | `example.com` | ❌ | Non-HTTPS origin (except localhost) | ### Practical implications #### For single domain applications ```javascript // Simple case: single domain Origin: "https://myapp.com" RP ID: "myapp.com" // Passkeys work only on myapp.com ``` #### For multi-subdomain applications ```javascript // Shared across subdomains Origin: "https://auth.myapp.com" RP ID: "myapp.com" // Passkeys can be used on any *.myapp.com subdomain ``` #### For development ```javascript // Development environment Origin: "http://localhost:3000" RP ID: "localhost" // HTTP allowed only for localhost ``` ### Security considerations **Origin validation:** - Browsers automatically validate that the origin matches the requesting page - Prevents malicious sites from using passkeys intended for other domains - Each authentication request is bound to its specific origin **RP ID scope:** - Determines which domains can share passkey credentials. - Broader RP ID (for example, `example.com`) allows subdomain sharing. - Narrower RP ID (for example, `auth.example.com`) restricts to a specific subdomain. **Best practices:** - Use the most specific RP ID that meets your needs. - For multi-subdomain apps, use the parent domain as RP ID. - For single-domain apps, use the exact domain as RP ID. - Always use HTTPS in production environments. - Test RP ID/Origin combinations thoroughly during development. ## Types of authenticators ### Platform authenticators Platform authenticators are built into devices and provide convenient, secure authentication: - **Mobile Devices**: TouchID, FaceID (iOS), Fingerprint sensors (Android). - **Computers**: Windows Hello, TouchID (Mac), Built-in fingerprint readers. - **Benefits**: Always available, integrated user experience, high security. ### Roaming authenticators External security keys that can be used across multiple devices: - **USB Security Keys**: YubiKey, Google Titan Key. - **NFC Keys**: Contactless security keys for mobile devices. - **Bluetooth Keys**: Wireless security keys. - **Benefits**: Portable, high security, works across devices. ## Security features ### Phishing resistance - **Origin Binding**: Passkeys are bound to specific domains, preventing use on malicious sites. - **No Shared Secrets**: Private keys never leave the device, eliminating credential theft risk. - **Challenge-Response**: Each authentication uses unique challenges, preventing replay attacks. ### Privacy protection - **No Tracking**: Each passkey is unique per service, preventing cross-site tracking. - **Local Storage**: Biometric data and private keys remain on the user's device. - **Minimal Data**: Only necessary public key information is shared with services. ### Cryptographic strength - **Modern Algorithms**: Uses industry-standard cryptographic algorithms (ECDSA, RSA). - **Key Length**: Typically 256-bit keys providing strong security. - **Hardware Protection**: Keys are often stored in secure hardware elements. ## Browser and platform support ### Desktop browsers - **Chrome**: Full WebAuthn support across platforms. - **Firefox**: Complete implementation with ongoing improvements. - **Safari**: WebAuthn support with TouchID integration on macOS. - **Edge**: Native Windows Hello integration. ### Mobile platforms - **iOS**: Native support with TouchID/FaceID integration. - **Android**: Google Play Services enables passkey functionality. - **Cross-Device**: Passkeys can sync across devices within the same ecosystem. ### Operating systems - **Windows**: Windows Hello provides platform authenticator capabilities. - **macOS**: TouchID integration for web and native applications. - **Linux**: Growing support through various implementations. ## Best Practices for implementation ### For developers - **Progressive Enhancement**: Implement passkeys alongside existing authentication methods. - **Fallback Options**: Provide alternative authentication for unsupported devices. - **User Education**: Help users understand passkey benefits and usage. - **Testing**: Test across different devices and browsers for compatibility. ### For users - **Enable Screen Lock**: Ensure the device has PIN, password, or biometric protection. - **Keep Devices Updated**: Use the latest OS versions for security and compatibility. - **Backup Strategy**: Understand how passkeys are backed up and restored. - **Multiple Authenticators**: Register multiple devices for redundancy. ## Migration from passwords ### Gradual transition - **Hybrid Approach**: Allow both passwords and passkeys during the transition period. - **User Choice**: Let users opt-in to passkey authentication. - **Education**: Provide clear information about passkey benefits. - **Support**: Offer assistance for users adopting new technology. ### Account recovery - **Multiple Options**: Provide various recovery methods for account access. - **Backup Authenticators**: Encourage registration of multiple authenticators. - **Support Channels**: Maintain traditional support options during the transition.