WebAuthn

WebAuthn credential storage and ceremony helpers, shared by passkey login and the WebAuthn MFA method.

Models

class auth_kit.webauthn.models.WebAuthnCredential(*args, **kwargs)

Bases: Model

WebAuthn/FIDO2 credential storage for users.

Stores credential data from WebAuthn registration ceremonies including credential ID, public key, sign count for replay protection, and metadata about the authenticator. Used for both passwordless login and multi-factor authentication.

Parameters:
  • id (BigAutoField) – Primary key: ID

  • credential_id (BinaryField) – Credential ID. Unique credential identifier from the authenticator

  • public_key (BinaryField) – Public key. COSE public key bytes from registration

  • sign_count (PositiveIntegerField) – Sign count. Signature counter for replay attack detection

  • transports (JSONField) – Transports. Supported transport methods (e.g., usb, nfc, ble, internal)

  • discoverable (BooleanField) – Discoverable. Whether this is a discoverable (passkey) credential

  • aaguid (CharField) – AAGUID. Authenticator Attestation GUID identifying the device type

  • name (CharField) – Name. User-assigned friendly name for this credential

  • created_at (DateTimeField) – Created at. When this credential was registered

  • last_used_at (DateTimeField) – Last used at. When this credential was last used for authentication

Relationship fields:

Parameters:

user (ForeignKey to User) – User. User who owns this WebAuthn credential (related name: webauthn_credentials)

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

aaguid

Type: CharField

AAGUID. Authenticator Attestation GUID identifying the device type

A wrapper for a deferred-loading field. When the value is read from this

created_at

Type: DateTimeField

Created at. When this credential was registered

A wrapper for a deferred-loading field. When the value is read from this

credential_id

Type: BinaryField

Credential ID. Unique credential identifier from the authenticator

A wrapper for a deferred-loading field. When the value is read from this

discoverable

Type: BooleanField

Discoverable. Whether this is a discoverable (passkey) credential

A wrapper for a deferred-loading field. When the value is read from this

get_next_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=True, **kwargs)

Finds next instance based on created_at. See get_next_by_FOO() for more information.

get_previous_by_created_at(*, field=<django.db.models.DateTimeField: created_at>, is_next=False, **kwargs)

Finds previous instance based on created_at. See get_previous_by_FOO() for more information.

id: int | None

Type: BigAutoField

Primary key: ID

A wrapper for a deferred-loading field. When the value is read from this

last_used_at

Type: DateTimeField

Last used at. When this credential was last used for authentication

A wrapper for a deferred-loading field. When the value is read from this

name

Type: CharField

Name. User-assigned friendly name for this credential

A wrapper for a deferred-loading field. When the value is read from this

objects: ClassVar[WebAuthnCredentialManager] = <auth_kit.webauthn.models.credential.WebAuthnCredentialManager object>
public_key

Type: BinaryField

Public key. COSE public key bytes from registration

A wrapper for a deferred-loading field. When the value is read from this

sign_count

Type: PositiveIntegerField

Sign count. Signature counter for replay attack detection

A wrapper for a deferred-loading field. When the value is read from this

transports

Type: JSONField

Transports. Supported transport methods (e.g., usb, nfc, ble, internal)

A wrapper for a deferred-loading field. When the value is read from this

user

Type: ForeignKey to User

User. User who owns this WebAuthn credential (related name: webauthn_credentials)

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')
user_id: int

Internal field, use user instead.

class auth_kit.webauthn.models.credential.WebAuthnCredentialManager(*args, **kwargs)

Bases: Manager

Manager for WebAuthnCredential model providing convenience methods.

Provides methods for retrieving credentials by credential ID, user, and discoverability status.

get_by_credential_id(credential_id: bytes) → WebAuthnCredential

Retrieve credential by its unique credential ID.

Parameters:

credential_id – Raw credential ID bytes

Returns:

WebAuthn credential instance

Raises:

WebAuthnCredentialDoesNotExistError – If credential not found

get_discoverable_for_user(user_id: int | str) → QuerySet

Retrieve discoverable (passkey) credentials for a user.

Parameters:

user_id – User identifier

Returns:

QuerySet of user’s discoverable WebAuthn credentials

get_for_user(user_id: int | str) → QuerySet

Retrieve all credentials for a user.

Parameters:

user_id – User identifier

Returns:

QuerySet of user’s WebAuthn credentials

Views

class auth_kit.webauthn.views.WebAuthnCredentialViewSet(**kwargs)

Bases: CreateModelMixin, DestroyModelMixin, ListModelMixin, GenericViewSet

ViewSet for managing WebAuthn credentials.

Provides endpoints for listing, registering, renaming, and deleting WebAuthn credentials for the authenticated user.

create(request, *args, **kwargs)
destroy(request, *args, **kwargs)
get_queryset() → QuerySet

Get credentials for the authenticated user.

Returns:

QuerySet of user’s WebAuthn credentials

get_serializer_class() → type[Serializer]

Get serializer class based on the current action.

Returns:

Appropriate serializer class

list(request, *args, **kwargs)
pagination_class = None
permission_classes = (<class 'rest_framework.permissions.IsAuthenticated'>,)
register_options(request: Request, *args: Any, **kwargs: Any) → Response

Generate WebAuthn registration options.

Returns the challenge and options needed by the browser’s navigator.credentials.create() API.

Parameters:

request – HTTP request

Returns:

Response with registration options

rename(request: Request, *args: Any, **kwargs: Any) → Response

Rename a WebAuthn credential.

Parameters:

request – HTTP request with new name

Returns:

Response with success message

Serializers

Credential Serializers

class auth_kit.webauthn.serializers.credential.WebAuthnCredentialSerializer(*args, **kwargs)

Bases: Serializer

Read serializer for WebAuthn credential listing.

Displays credential metadata without exposing sensitive cryptographic material.

class auth_kit.webauthn.serializers.credential.WebAuthnCredentialCreateSerializer(*args, **kwargs)

Bases: WebAuthnCredentialSerializer

Serializer for registering a new WebAuthn credential.

Accepts the credential response from navigator.credentials.create() and verifies it against the stored challenge. Inherits the read fields so the creation response matches the listing representation.

credential

The credential response JSON from the browser

name

Optional user-friendly name for the credential

create(validated_data: dict[str, Any]) → WebAuthnCredential

Verify and store the WebAuthn credential.

Parameters:

validated_data – Validated input data

Returns:

The created credential

class auth_kit.webauthn.serializers.credential.WebAuthnCredentialUpdateSerializer(*args, **kwargs)

Bases: Serializer

Serializer for updating a WebAuthn credential.

Only allows updating the user-friendly name.

Ceremony Option Serializers

class auth_kit.webauthn.serializers.options.WebAuthnRegistrationOptionsSerializer(*args, **kwargs)

Bases: Serializer

Structured serializer for WebAuthn registration ceremony options.

Returned by services.begin_registration() and consumed by the browser’s navigator.credentials.create() API.

class auth_kit.webauthn.serializers.options.WebAuthnAuthenticationOptionsSerializer(*args, **kwargs)

Bases: Serializer

Structured serializer for WebAuthn authentication ceremony options.

Returned by services.begin_authentication() and consumed by the browser’s navigator.credentials.get() API.

Services

auth_kit.webauthn.services.begin_registration(user: AbstractBaseUser, existing_credentials: list[PublicKeyCredentialDescriptor] | None = None) → WebAuthnRegistrationOptions

Generate WebAuthn registration options for a user.

Creates registration options and stores the challenge in cache for later verification.

Parameters:
  • user – User registering a new credential

  • existing_credentials – Optional list of existing credential descriptors to exclude. If None, fetches from database.

Returns:

Registration options as a JSON-serializable dictionary

auth_kit.webauthn.services.complete_registration(user: AbstractBaseUser, credential_json: dict[str, Any], name: str = '') → WebAuthnCredential

Verify WebAuthn registration response and store credential.

Parameters:
  • user – User completing registration

  • credential_json – Registration response from the client

  • name – User-friendly name for the credential

Returns:

Created WebAuthnCredential instance

Raises:

WebAuthnVerificationError – If verification fails

auth_kit.webauthn.services.begin_authentication(user: AbstractBaseUser | None = None) → WebAuthnAuthenticationOptions

Generate WebAuthn authentication options.

If user is provided, filters allowed credentials to that user’s credentials. If user is None, allows discoverable credential flow (passkeys).

A unique opaque session token is returned as session_id to bind the challenge to the verification step without exposing internal cache keys.

Parameters:

user – Optional user for filtering credentials. If None, discoverable credential flow is used.

Returns:

Authentication options as a JSON-serializable dictionary, including session_id for the verify step.

auth_kit.webauthn.services.complete_authentication(credential_json: dict[str, Any], session_id: str) → tuple[AbstractBaseUser, WebAuthnCredential]

Verify WebAuthn authentication response.

Verifies the assertion, updates the credential’s sign count and last_used_at timestamp, and returns the authenticated user.

Parameters:
  • credential_json – Authentication response from the client

  • session_id – Opaque session token from begin_authentication

Returns:

Tuple of (authenticated user, WebAuthnCredential)

Raises:

WebAuthnVerificationError – If verification fails

Types

class auth_kit.webauthn.types.WebAuthnRegistrationOptions

Options for the browser’s navigator.credentials.create() call.

attestation: NotRequired[Literal['none', 'indirect', 'direct', 'enterprise']]
authenticatorSelection: NotRequired[AuthenticatorSelection]
challenge: str
excludeCredentials: NotRequired[list[PublicKeyCredentialDescriptor]]
hints: NotRequired[list[str]]
pubKeyCredParams: list[PubKeyCredParam]
rp: RelyingParty
timeout: NotRequired[int]
user: PublicKeyCredentialUser
class auth_kit.webauthn.types.WebAuthnAuthenticationOptions

Options for the browser’s navigator.credentials.get() call.

allowCredentials: NotRequired[list[PublicKeyCredentialDescriptor]]
challenge: str
rpId: NotRequired[str]
session_id: str
timeout: NotRequired[int]
userVerification: NotRequired[Literal['required', 'preferred', 'discouraged']]

Exceptions

exception auth_kit.webauthn.exceptions.WebAuthnCredentialDoesNotExistError

Bases: ValidationError

Raised when a requested WebAuthn credential cannot be found.

__init__() → None

Initialize with a descriptive error message.

exception auth_kit.webauthn.exceptions.WebAuthnVerificationError(detail: str | None = None)

Bases: ValidationError

Raised when WebAuthn verification fails.

__init__(detail: str | None = None) → None

Initialize with a descriptive error message.

Settings

class auth_kit.webauthn.webauthn_settings.WebAuthnSetting

Default WebAuthn settings configuration for Auth Kit.

Provides all configurable options for WebAuthn functionality including relying party configuration, credential management views and serializers.

WEBAUTHN_ATTESTATION: Literal['none', 'indirect', 'direct', 'enterprise'] = 'none'
WEBAUTHN_CHALLENGE_EXPIRY: int = 300
WEBAUTHN_CREDENTIAL_CREATE_SERIALIZER: type[WebAuthnCredentialCreateSerializer] = 'auth_kit.webauthn.serializers.credential.WebAuthnCredentialCreateSerializer'
WEBAUTHN_CREDENTIAL_MODEL: type[WebAuthnCredential] = 'auth_kit.webauthn.models.WebAuthnCredential'
WEBAUTHN_CREDENTIAL_SERIALIZER: type[WebAuthnCredentialSerializer] = 'auth_kit.webauthn.serializers.credential.WebAuthnCredentialSerializer'
WEBAUTHN_CREDENTIAL_UPDATE_SERIALIZER: type[WebAuthnCredentialUpdateSerializer] = 'auth_kit.webauthn.serializers.credential.WebAuthnCredentialUpdateSerializer'
WEBAUTHN_CREDENTIAL_VIEW_SET: type[WebAuthnCredentialViewSet] = 'auth_kit.webauthn.views.WebAuthnCredentialViewSet'
WEBAUTHN_ORIGIN: str | list[str] = 'http://localhost:8000'
WEBAUTHN_RESIDENT_KEY: Literal['required', 'preferred', 'discouraged'] = 'preferred'
WEBAUTHN_RP_ID: str = 'localhost'
WEBAUTHN_RP_NAME: str = 'My Application'
WEBAUTHN_TIMEOUT: int = 60000
WEBAUTHN_USER_VERIFICATION: Literal['required', 'preferred', 'discouraged'] = 'preferred'
user_settings: dict[str, Any] = {}