Skip to content

Backup codes

reauth.factors.backup_codes

DEFAULT_CHARS module-attribute 

DEFAULT_CHARS: str = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'

BackupCodesEnrollment dataclass 

BackupCodesEnrollment(
    id: Any | None,
    identity_id: Any,
    codes: list[str],
    used_codes: list[str],
)

Enrollment data for backup codes factor.

id instance-attribute 

id: Any | None

identity_id instance-attribute 

identity_id: Any

codes instance-attribute 

codes: list[str]

used_codes instance-attribute 

used_codes: list[str]

BackupCodesException 

BackupCodesException(message: str | None = None)

Bases: ReauthException

Base exception for backup codes errors.

InvalidBackupCodeException 

InvalidBackupCodeException(message: str | None = None)

Bases: BackupCodesException

Raised when a backup code is invalid.

AlreadyUsedBackupCodeException 

AlreadyUsedBackupCodeException(message: str | None = None)

Bases: BackupCodesException

Raised when a backup code has already been used.

NotEnrolledBackupCodesException 

NotEnrolledBackupCodesException(message: str | None = None)

Bases: BackupCodesException

Raised when trying to verify backup codes for an identity with no enrollment.

AlreadyEnrolledBackupCodesException 

AlreadyEnrolledBackupCodesException(
    message: str | None = None,
)

Bases: BackupCodesException

Raised when trying to enroll an identity that already has backup codes.

BackupCodesFactor 

BackupCodesFactor(
    *,
    verifier: TokenVerifier,
    code_length: int = 10,
    code_count: int = 10,
    chars: str = DEFAULT_CHARS,
    identifier: str = "backup_codes",
    step: int = 1,
    advance_by: int = 1,
)

Bases: FactorBase[BackupCodesEnrollment], ABC

Factor for backup codes authentication.

Backup codes are single-use, randomly generated codes that serve as a fallback authentication method when primary factors are unavailable.

Initialize the backup codes factor.

Parameters:

Name Type Description Default
verifier TokenVerifier

Code verification and key rotation.

 required
code_length int

Length of each backup code (default: 10).

 10
code_count int

Number of backup codes to generate (default: 10).

 10
chars str

Character set for code generation (default: excludes ambiguous chars).

 DEFAULT_CHARS
identifier str

Unique identifier for the factor (default: "backup_codes").

 'backup_codes'
step int

Authentication step at which this factor can be used (default: 1).

 1
advance_by int

Number of steps to advance after successful verification (default: 1).

 1

AMR class-attribute 

AMR: AuthenticationMethodReference = (
    AuthenticationMethodReference.OTP
)

verifier instance-attribute 

verifier = verifier

code_length instance-attribute 

code_length = code_length

code_count instance-attribute 

code_count = code_count

chars instance-attribute 

chars = chars

enroll async 

enroll(
    identity_id: Any,
) -> tuple[list[str], BackupCodesEnrollment]

Enroll backup codes for a given identity.

Generates a set of random backup codes, and persists the enrollment. If an existing enrollment exists, it is deleted and replaced with the new one.

Parameters:

Name Type Description Default
identity_id Any

The ID of the identity to enroll backup codes for.

 required

Returns:

Type Description
list[str]

A tuple of (plaintext_codes, enrollment) where:
BackupCodesEnrollment
  • plaintext_codes: List of plaintext backup codes to display to the user
tuple[list[str], BackupCodesEnrollment]
  • enrollment: The persisted BackupCodesEnrollment object

verify async 

verify(
    identity_id: Any, code: str
) -> BackupCodesEnrollment

Verify a backup code for a given identity.

Parameters:

Name Type Description Default
identity_id Any

The ID of the identity to verify the backup code for.

 required
code str

The backup code provided by the user.

 required

Returns:

Type Description
BackupCodesEnrollment

The updated BackupCodesEnrollment with the used code tracked.

Raises:

Type Description
NotEnrolledBackupCodesException

If the identity has no backup codes enrollment.
InvalidBackupCodeException

If the code is invalid.
AlreadyUsedBackupCodeException

If the code has already been used.

insert abstractmethod async 

insert(backup_codes: BackupCodesEnrollment) -> typing.Any

Insert a backup codes enrollment into a persistent store.

Implementation contract

Persist the supplied enrollment and return its ID. Enforce uniqueness for the identity and configured factor. Leave commit and rollback to the caller.

update abstractmethod async 

update(backup_codes: BackupCodesEnrollment) -> None

Update a backup codes enrollment in the persistent store.

Implementation contract

Persist the supplied enrollment by ID in the transaction that protects the record. Leave commit and rollback to the caller.

delete abstractmethod async 

delete(backup_codes: BackupCodesEnrollment) -> None

Delete a backup codes enrollment from the persistent store.

Implementation contract

Delete the supplied enrollment by ID in the transaction that protects the record. Leave commit and rollback to the caller.