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:
ModelWebAuthn/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 (
ForeignKeytoUser) – User. User who owns this WebAuthn credential (related name:webauthn_credentials)
- exception DoesNotExist
Bases:
ObjectDoesNotExist
- exception MultipleObjectsReturned
Bases:
MultipleObjectsReturned
- aaguid
Type:
CharFieldAAGUID. Authenticator Attestation GUID identifying the device type
A wrapper for a deferred-loading field. When the value is read from this
- created_at
Type:
DateTimeFieldCreated at. When this credential was registered
A wrapper for a deferred-loading field. When the value is read from this
- credential_id
Type:
BinaryFieldCredential ID. Unique credential identifier from the authenticator
A wrapper for a deferred-loading field. When the value is read from this
- discoverable
Type:
BooleanFieldDiscoverable. 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. Seeget_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. Seeget_previous_by_FOO()for more information.
- id: int | None
Type:
BigAutoFieldPrimary key: ID
A wrapper for a deferred-loading field. When the value is read from this
- last_used_at
Type:
DateTimeFieldLast 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:
CharFieldName. 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:
BinaryFieldPublic key. COSE public key bytes from registration
A wrapper for a deferred-loading field. When the value is read from this
- sign_count
Type:
PositiveIntegerFieldSign count. Signature counter for replay attack detection
A wrapper for a deferred-loading field. When the value is read from this
- transports
Type:
JSONFieldTransports. 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:
ForeignKeytoUserUser. 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')
- class auth_kit.webauthn.models.credential.WebAuthnCredentialManager(*args, **kwargs)
Bases:
ManagerManager 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
Views
- class auth_kit.webauthn.views.WebAuthnCredentialViewSet(**kwargs)
Bases:
CreateModelMixin,DestroyModelMixin,ListModelMixin,GenericViewSetViewSet 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'>,)
Serializers
Credential Serializers
- class auth_kit.webauthn.serializers.credential.WebAuthnCredentialSerializer(*args, **kwargs)
Bases:
SerializerRead serializer for WebAuthn credential listing.
Displays credential metadata without exposing sensitive cryptographic material.
- class auth_kit.webauthn.serializers.credential.WebAuthnCredentialCreateSerializer(*args, **kwargs)
Bases:
WebAuthnCredentialSerializerSerializer 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:
SerializerSerializer 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:
SerializerStructured serializer for WebAuthn registration ceremony options.
Returned by
services.begin_registration()and consumed by the browser’snavigator.credentials.create()API.
- class auth_kit.webauthn.serializers.options.WebAuthnAuthenticationOptionsSerializer(*args, **kwargs)
Bases:
SerializerStructured serializer for WebAuthn authentication ceremony options.
Returned by
services.begin_authentication()and consumed by the browser’snavigator.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_idto 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_idfor 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]
- excludeCredentials: NotRequired[list[PublicKeyCredentialDescriptor]]
- hints: NotRequired[list[str]]
- 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]]
- rpId: NotRequired[str]
- timeout: NotRequired[int]
- userVerification: NotRequired[Literal['required', 'preferred', 'discouraged']]
Exceptions
- exception auth_kit.webauthn.exceptions.WebAuthnCredentialDoesNotExistError
Bases:
ValidationErrorRaised when a requested WebAuthn credential cannot be found.
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_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'