FIDO2 WebAuthn Library

Warnings

• breaking Version 2.0.0 introduced a minimum Python version requirement of 3.10 or later.
  Fix: Ensure your environment runs Python 3.10 or newer before upgrading to fido2>=2.0.0.
• breaking WebAuthn dataclasses (e.g., `PublicKeyCredentialRpEntity`, `AttestationObject`, `CollectedClientData`) were significantly updated in v2.0.0. Constructors now require keyword arguments only, aligning with WebAuthn Level 3. Serialization to/from dictionaries is now compatible with standardized JSON formats.
  Fix: Update your code to pass all arguments to dataclass constructors as keyword arguments (e.g., `CollectedClientData(d=data)` instead of `CollectedClientData(data)`). Review the migration guide (doc/Migration_1-2.adoc) for detailed changes.
• breaking The `features.webauthn_json_mapping` flag was removed in v2.0.0. Its behavior, which enabled standardized JSON formats for WebAuthn data structures, is now the default.
  Fix: Remove any explicit usage or checks for `features.webauthn_json_mapping`.
• breaking Old extension APIs, which were deprecated in version 1.2.0, have been removed entirely in version 2.0.0.
  Fix: Migrate to the redesigned extension APIs introduced in fido2 version 1.2.0. Refer to the documentation for the new extension handling patterns.
• gotcha The `websafe_decode` utility function (e.g., in `fido2.utils`) expects a `str` argument. Passing `bytes` was deprecated in 1.1.3 and will raise a `TypeError` in versions 2.0.0 and above.
  Fix: Ensure that arguments passed to `websafe_decode` are always `str`. If you have `bytes`, decode them to `str` first (e.g., `my_bytes.decode('utf-8')`).

Install

• pip install fido2 Install stable version

Imports

• AttestationObject

  from fido2.webauthn import AttestationObject

• CollectedClientData

  from fido2.webauthn import CollectedClientData

• verify_registration_response

  from fido2.webauthn import verify_registration_response

  The primary verification functions are now top-level in `fido2.webauthn` for clarity.
• Fido2Client

  from fido2.client import Fido2Client

• cbor

  from fido2 import cbor

Quickstart

This quickstart demonstrates how to verify a FIDO2 WebAuthn registration response on the server-side. It simulates receiving `clientDataJSON` and `attestationObject` from a browser and uses `fido2.webauthn.verify_registration_response` to validate them against server-generated challenge and Relying Party (RP) configuration. The example uses minimal mock data for demonstration purposes.

import os
import json
import base64
from fido2.webauthn import (
    AttestationObject,
    CollectedClientData,
    verify_registration_response,
)
from fido2 import cbor

# --- Server-side configuration and stored data ---
# In a real application, these would be generated and stored securely.
RP_ID = os.environ.get("FIDO2_RP_ID", "example.com")
RP_ORIGIN = f"https://{RP_ID}"

# A challenge issued previously by the server to the client for this registration attempt
# This must be a cryptographically secure random 32-byte value.
CHALLENGE = base64.urlsafe_b64decode(b"uKz0s4zP6T3o-J2V-5rX_s_L4l6m-c7C8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3y=") # Example base64url-encoded bytes for a 32-byte challenge
USER_ID = b"some_unique_user_id_bytes" # The user ID for whom registration was requested
EXPECTED_RP_ID = RP_ID
EXPECTED_ORIGINS = {RP_ORIGIN}

# --- Simulate client-provided data (in a real app, these come from the browser) ---
# Example: clientDataJSON received from the browser as a string
client_data_json_str = f'''
{{
    "type": "webauthn.create",
    "challenge": "{base64.urlsafe_b64encode(CHALLENGE).rstrip(b'=').decode('utf-8')}",
    "origin": "{RP_ORIGIN}",
    "crossOrigin": false
}}
'''

# Example: AttestationObject received from the browser as base64url-encoded CBOR bytes
# This is a minimal 'none' attestation for demonstration purposes. 
# Real attestations are more complex.
attestation_object_b64url = "o2NmbXRoZJpvbmVhdHRTdG10oGhhdXRoRGF0YVjLp_hNq_D0D8x4jL17w2-5rX_s_L4l6m-c7C8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3yFkQAAAAAAAAAAAAAAAAAAAAAAwIAIAxM0k3Kz-k_D0x4jL17w2-5rX_s_L4l6m-c7C8j9k0l1m2n3o4p5q6r7s8t9u0v1w2x3yBoAAAAAAAAAAAAAAAAAAAAAADAAAAAQAg"


# --- Server-side verification using fido2 library ---
try:
    # Parse the client data and attestation object
    client_data = CollectedClientData(json.loads(client_data_json_str))
    attestation_object = AttestationObject(base64.urlsafe_b64decode(attestation_object_b64url + "==")) # Add padding back for base64

    # Verify the registration response
    auth_data = verify_registration_response(
        client_data=client_data,
        attestation_object=attestation_object,
        challenge=CHALLENGE,
        rp_id=EXPECTED_RP_ID,
        origins=EXPECTED_ORIGINS,
        user_id=USER_ID
        # In production, you would pass `trusted_attestation_public_keys`
        # or `attestation_callback` to validate attestation certificates.
    )

    print("Registration successful!")
    print(f"Credential ID: {base64.urlsafe_b64encode(auth_data.credential_id).decode('utf-8')}")
    print(f"Public Key: {base64.urlsafe_b64encode(auth_data.credential_public_key).decode('utf-8')}")
    print(f"Signature Count: {auth_data.sign_count}")

    # In a real application, you would store auth_data.credential_id, 
    # auth_data.credential_public_key, and auth_data.sign_count
    # associated with the user for future authentication.

except Exception as e:
    print(f"Registration failed: {e}")