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_hashes: list[str],
    used_codes_hashes: list[str],
)

Enrollment data for backup codes factor.

id instance-attribute 

id: Any | None

identity_id instance-attribute 

identity_id: Any

codes_hashes instance-attribute 

codes_hashes: list[str]

used_codes_hashes instance-attribute 

used_codes_hashes: 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(
    *,
    hash_secret: str,
    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
hash_secret str

Secret key used for hashing backup codes.

 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
)

hash_secret instance-attribute 

hash_secret = hash_secret

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, hashes them, 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.

update abstractmethod async 

update(backup_codes: BackupCodesEnrollment) -> None

Update a backup codes enrollment in the persistent store.

delete abstractmethod async 

delete(backup_codes: BackupCodesEnrollment) -> None

Delete a backup codes enrollment from the persistent store.