py_webauthn

Install the webauthn package via PyPI using pip.

Requirements:

• Python 3.10 or higher

pip install webauthn

Practical usage examples for registration and authentication are provided in the repository. To run them, you must first set up your development environment using uv.

Run Registration Example:

venv $> uv run -m examples.registration

Run Authentication Example:

venv $> uv run -m examples.authentication

The webauthn module provides the primary entry points for managing the WebAuthn lifecycle on the server side:

• generate_registration_options(): Generates options for a new registration ceremony.
• verify_registration_response(): Verifies a registration response received from a client.
• generate_authentication_options(): Generates options for an authentication ceremony.
• verify_authentication_response(): Verifies an authentication response received from a client.

The library provides helpers for data transformation and type safety:

Helper Methods:

• options_to_json(): Encodes registration/authentication options to JSON, handling bytes by encoding them to base64url for safe transmission to the browser.
• base64url_to_bytes(): Decodes base64url encoded strings back into bytes.

Data Structures:

• webauthn.helpers.structs: Contains dataclasses used for constructing inputs to core methods and providing type hinting to ensure consistent data shapes.

Use base64url_to_bytes to decode Base64URL encoded strings into their original byte representations. This is useful for processing data sent from web clients that use Base64URL encoding for binary data.

from webauthn import base64url_to_bytes

raw_bytes = base64url_to_bytes("SGVsbG8gd29ybGQ")

Use verify_registration_response to validate the credential response received from a client after a successful registration ceremony. This ensures the signature, challenge, and origin are valid according to WebAuthn standards.

from webauthn import verify_registration_response

# Example usage (parameters depend on implementation)
verification = verify_registration_response(
    credential="credential_data",
    expected_challenge="challenge_bytes",
    expected_origin="https://example.com",
    expected_rp_id="example.com",
)

Use generate_authentication_options to create the challenge and configuration required for a WebAuthn authentication (login) ceremony. This is the first step in the authentication workflow, used to prompt an existing user to sign in with a previously registered credential.

from webauthn import generate_authentication_options

# Example usage (parameters depend on implementation)
options = generate_authentication_options(
    rp_id="example.com",
    allow_credentials=[{"type": "public-key", "id": b"credential_id"}],
)

Use verify_authentication_response to validate the assertion response received from a client during an authentication ceremony. This confirms that the user possesses the private key associated with the registered credential.

from webauthn import verify_authentication_response

# Example usage (parameters depend on implementation)
verification = verify_authentication_response(
    credential="credential_data",
    expected_challenge="challenge_bytes",
    expected_origin="https://example.com",
    expected_rp_id="example.com",
)

Use generate_registration_options to create the challenge and configuration required for a WebAuthn registration ceremony. This is the first step in the registration workflow, typically called on the server to prepare the client for a new credential request.

from webauthn import generate_registration_options

# Example usage (parameters depend on implementation)
options = generate_registration_options(
    rp_id="example.com",
    user={
        "id": b"user_id",
        "name": "user@example.com",
        "display_name": "User Name",
    },
)

Use options_to_json to serialize WebAuthn options objects into a JSON format suitable for transmission to a web client.

from webauthn import options_to_json

# Example usage
json_options = options_to_json(registration_options_object)