WebAuthn Python Library

Warnings

• breaking The minimum supported Python version was bumped to Python 3.9. Users on older Python versions (3.8 or below) will need to upgrade their Python environment to use `webauthn>=2.3.0`.
  Fix: Upgrade your Python environment to 3.9 or higher. For example, `pyenv install 3.9.18 && pyenv global 3.9.18`.
• gotcha Support for ML-DSA (Post-Quantum Cryptography) public keys for authenticators was introduced, but it requires an optional dependency (`dilithium-py`). If you intend to support PQC-enabled authenticators, this dependency must be explicitly installed.
  Fix: Install the optional dependency: `pip install 'webauthn[pqc]'` or `pip install dilithium-py`.
• gotcha The `webauthn.helpers.options_to_json_dict` helper introduced a `bytes_encoder` argument. If not specified, `bytes` values are Base64URL encoded by default. Custom encoding logic might be required for specific client-side interoperability or if your application expects a different serialization format for byte arrays.
  Fix: Review your serialization needs. If a custom encoding is required, pass a `Callable[[bytes], Any]` to the `bytes_encoder` argument when calling `options_to_json_dict`.
• gotcha Type annotations for bare `dict`s were replaced with `Dict[str, Any]` for stricter type checking. While this doesn't break runtime behavior, it might cause issues with type checkers (e.g., MyPy) in projects with strict configurations.
  Fix: Update your code to use `Dict[str, Any]` or other specific `dict` type hints where appropriate when interacting with the library's types, or adjust your type checker's configuration if necessary.

Install

• pip install webauthn Install stable version

Imports

• generate_registration_options

  from webauthn import generate_registration_options

• verify_registration_response

  from webauthn import verify_registration_response

• generate_authentication_options

  from webauthn import generate_authentication_options

• verify_authentication_response

  from webauthn import verify_authentication_response

• options_to_json_dict

  from webauthn.helpers import options_to_json_dict

  The helper is exposed directly under `webauthn.helpers`.

Quickstart

This quickstart demonstrates how to generate registration options, which is the first step in registering a new WebAuthn credential. It uses placeholder values for RP (Relying Party) and user details. In a real application, these would be dynamic and securely managed. The generated options are then sent to the client-side JavaScript for interaction with the user's authenticator.

import os
from webauthn import generate_registration_options
from webauthn.helpers.structs import PublicKeyCredentialUserEntity

# Placeholder values (in a real app, these would come from your user management)
RP_ID = "localhost" # Or your domain, e.g., "example.com"
RP_NAME = "My Awesome App"
USER_ID = os.environ.get('WEBAUTHN_USER_ID', 'test_user_id').encode('utf-8')
USER_NAME = os.environ.get('WEBAUTHN_USER_NAME', 'testuser')
USER_DISPLAY_NAME = os.environ.get('WEBAAUTHN_USER_DISPLAY_NAME', 'Test User')

user_entity = PublicKeyCredentialUserEntity(
    id=USER_ID,
    name=USER_NAME,
    display_name=USER_DISPLAY_NAME,
)

registration_options = generate_registration_options(
    rp_id=RP_ID,
    rp_name=RP_NAME,
    user_entity=user_entity,
    challenge=os.urandom(16) # A new random challenge for each registration attempt
)

print("Generated WebAuthn Registration Options:")
print(registration_options)
# In a real application, you would serialize these options (e.g., to JSON)
# and send them to the client-side JavaScript for WebAuthn API calls.