Enterprise Passkeys: Architecture, Deployment, and Security Hardening Guide

Overview

Passkeys are FIDO2 credentials exposed through the WebAuthn and CTAP standards. They replace passwords with asymmetric key pairs where the private key stays on a user device or hardware authenticator and the relying party stores only the public key.

Enterprises adopt passkeys to reduce phishing, credential stuffing, password reset costs, and MFA fatigue. In practice, passkeys are most effective when integrated with an enterprise identity provider such as Microsoft Entra ID or Okta, enforced through conditional access, and backed by device trust and lifecycle controls.

Architecture

Core components

• Relying Party (RP): The application or identity provider requesting authentication.
• Authenticator: Platform authenticator like Windows Hello, Apple iCloud Keychain, Android Credential Manager, or roaming keys such as YubiKey.
• Client: Browser or native app implementing WebAuthn.
• Identity Provider: Entra ID, Okta, or Ping handling policy, federation, and user lifecycle.
• Directory and MDM: Microsoft Intune, Jamf, or Workspace ONE for device posture and enrollment.

Deployment models

• IdP-first: Enable passkeys at the identity provider and let downstream SaaS apps inherit authentication.
• App-direct: Implement WebAuthn directly in customer-facing or workforce apps.
• Hybrid: Use IdP for workforce SSO and direct WebAuthn for high-risk internal apps.

Data flow

1. User starts sign-in.
2. RP requests a challenge from the server.
3. Browser calls WebAuthn API.
4. Authenticator verifies local user presence or biometrics.
5. Authenticator signs challenge with private key.
6. Server validates signature, origin, RP ID, sign counter, and attestation policy.

Implementation Guide

The example below uses Keycloak as the RP and identity service for a pilot.

1. Start Keycloak with HTTPS behind a reverse proxy.
2. Enable WebAuthn passwordless policy.
3. Configure RP ID to match your production domain.
4. Enforce device enrollment and recovery methods.
5. Test with Windows Hello, macOS Touch ID, Android, and YubiKey.

CLI commands

docker run -d --name keycloak -p 8443:8443 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD='Str0ngAdmin!' quay.io/keycloak/keycloak:25.0.0 start-dev --https-port=8443
kcadm.sh config credentials --server https://sso.example.com:8443 --realm master --user admin --password 'Str0ngAdmin!'
kcadm.sh update realms/master -s webAuthnPolicyRpEntityName='Example Corp SSO' -s webAuthnPolicySignatureAlgorithms='ES256,RS256' -s webAuthnPolicyRpId='sso.example.com' -s webAuthnPolicyPasswordlessRequireResidentKey='Yes' -s webAuthnPolicyPasswordlessUserVerificationRequirement='required'
kcadm.sh create authentication/required-actions -r master -s alias=webauthn-register-passwordless -s name='WebAuthn Register Passwordless' -s providerId='webauthn-register-passwordless' -s enabled=true -s defaultAction=true

Reverse proxy config

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-passkeys
  namespace: iam
 data:
  default.conf: |
    server {
      listen 443 ssl http2;
      server_name sso.example.com;
      ssl_certificate /etc/tls/tls.crt;
      ssl_certificate_key /etc/tls/tls.key;
      add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
      location / {
        proxy_pass https://keycloak:8443;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      }
    }

Code Examples

1. Create registration options in Python

from fido2.server import Fido2Server
from fido2.webauthn import PublicKeyCredentialRpEntity, UserVerificationRequirement
rp = PublicKeyCredentialRpEntity(id="sso.example.com", name="Example Corp SSO")
server = Fido2Server(rp)
registration_data, state = server.register_begin(
    {
        "id": b"u12345",
        "name": "alice@example.com",
        "displayName": "Alice"
    },
    user_verification=UserVerificationRequirement.REQUIRED,
    authenticator_attachment=None
)
print(registration_data)

2. Kubernetes ingress policy

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: sso-ingress
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
spec:
  tls:
  - hosts:
    - sso.example.com
    secretName: sso-tls
  rules:
  - host: sso.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: keycloak
            port:
              number: 8443

3. Entra ID passkey policy via Microsoft Graph

az login
az rest --method PATCH --uri "https://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/Fido2" --headers 'Content-Type=application/json' --body '{"@odata.type":"#microsoft.graph.fido2AuthenticationMethodConfiguration","isAttestationEnforced":true,"isSelfServiceRegistrationAllowed":true,"keyRestrictions":{"isEnforced":true,"enforcementType":"allow","aaGuids":[]}}'

Security Hardening

• Require user verification for all passkey sign-ins.
• Enforce attestation for managed hardware keys where regulatory requirements apply.
• Protect RP endpoints with TLS 1.2+, HSTS, and certificate lifecycle automation.
• Restrict enrollment to managed devices using conditional access and MDM compliance.
• Log WebAuthn events to SIEM and alert on impossible travel, repeated registration attempts, and authenticator changes.
• Maintain account recovery with high-assurance help desk workflows and break-glass accounts stored in PAM.

Comparison

Troubleshooting

Error 1: RP ID mismatch

Log sample:

2026-04-11T09:14:22Z WARN webauthn verification failed: SecurityError: The relying party ID is not a registrable domain suffix of, nor equal to the current domain

Fix: Set webAuthnPolicyRpId exactly to the production hostname, for example sso.example.com, and ensure the browser origin matches.

Error 2: User verification not available

Log sample:

2026-04-11T09:18:03Z ERROR fido2.auth: NotAllowedError: User verification is required but the authenticator does not support it

Fix: Allow platform authenticators with biometrics or PIN, or adjust policy for specific pilot groups only if risk permits.

Error 3: Reverse proxy origin breakage

Log sample:

2026-04-11T09:21:47Z ERROR org.keycloak.events type=WEBAUTHN_LOGIN_ERROR error=invalid_origin origin=http://sso.example.com auth_method=webauthn

Fix: Forward X-Forwarded-Proto=https, terminate TLS correctly, and disable any HTTP-to-HTTPS misconfiguration.

Best Practices

Do

• Start with administrator and developer populations that face high phishing risk.
• Use hybrid rollout: passkeys plus existing MFA during transition.
• Define recovery and revocation procedures before broad deployment.
• Test cross-platform sync behavior for iOS, Android, Windows, and macOS.

Don't

• Do not allow weak fallback to SMS for privileged users.
• Do not ignore shared workstation scenarios; use roaming authenticators where needed.
• Do not deploy without SIEM visibility into registration, reset, and authentication events.
• Do not rely on consumer sync alone for regulated workloads without device compliance checks.