authentik.stages.authenticator_totp.models

  1"""OTP Time-based models"""
  2
  3import time
  4from base64 import b32encode
  5from binascii import unhexlify
  6from urllib.parse import quote, urlencode
  7
  8from django.conf import settings
  9from django.db import models
 10from django.utils.translation import gettext_lazy as _
 11from django.views import View
 12from rest_framework.serializers import BaseSerializer
 13
 14from authentik.core.types import UserSettingSerializer
 15from authentik.flows.models import ConfigurableStage, FriendlyNamedStage, Stage
 16from authentik.lib.models import SerializerModel
 17from authentik.stages.authenticator.models import Device, ThrottlingMixin
 18from authentik.stages.authenticator.oath import TOTP
 19from authentik.stages.authenticator.util import hex_validator, random_hex
 20
 21
 22class TOTPDigits(models.TextChoices):
 23    """OTP Time Digits"""
 24
 25    SIX = "6", _("6 digits, widely compatible")
 26    EIGHT = "8", _("8 digits, not compatible with apps like Google Authenticator")
 27
 28
 29class AuthenticatorTOTPStage(ConfigurableStage, FriendlyNamedStage, Stage):
 30    """Setup Time-based OTP authentication for the user."""
 31
 32    digits = models.IntegerField(choices=TOTPDigits.choices)
 33
 34    @property
 35    def serializer(self) -> type[BaseSerializer]:
 36        from authentik.stages.authenticator_totp.api import AuthenticatorTOTPStageSerializer
 37
 38        return AuthenticatorTOTPStageSerializer
 39
 40    @property
 41    def view(self) -> type[View]:
 42        from authentik.stages.authenticator_totp.stage import AuthenticatorTOTPStageView
 43
 44        return AuthenticatorTOTPStageView
 45
 46    @property
 47    def component(self) -> str:
 48        return "ak-stage-authenticator-totp-form"
 49
 50    def ui_user_settings(self) -> UserSettingSerializer | None:
 51        return UserSettingSerializer(
 52            data={
 53                "title": self.friendly_name or str(self._meta.verbose_name),
 54                "component": "ak-user-settings-authenticator-totp",
 55            }
 56        )
 57
 58    def __str__(self) -> str:
 59        return f"TOTP Authenticator Setup Stage {self.name}"
 60
 61    class Meta:
 62        verbose_name = _("TOTP Authenticator Setup Stage")
 63        verbose_name_plural = _("TOTP Authenticator Setup Stages")
 64
 65
 66def default_key():
 67    """Default TOTP Device key"""
 68    return random_hex(20)
 69
 70
 71def key_validator(value):
 72    """Validate totp key"""
 73    return hex_validator()(value)
 74
 75
 76class TOTPDevice(SerializerModel, ThrottlingMixin, Device):
 77    """
 78    A generic TOTP :class:`~authentik.stages.authenticator.models.Device`. The model fields mostly
 79    correspond to the arguments to :func:`authentik.stages.authenticator.oath.totp`. They all have
 80    sensible defaults, including the key, which is randomly generated.
 81
 82    .. attribute:: key
 83
 84        *CharField*: A hex-encoded secret key of up to 40 bytes. (Default: 20
 85        random bytes)
 86
 87    .. attribute:: step
 88
 89        *PositiveSmallIntegerField*: The time step in seconds. (Default: 30)
 90
 91    .. attribute:: t0
 92
 93        *BigIntegerField*: The Unix time at which to begin counting steps.
 94        (Default: 0)
 95
 96    .. attribute:: digits
 97
 98        *PositiveSmallIntegerField*: The number of digits to expect in a token
 99        (6 or 8).  (Default: 6)
100
101    .. attribute:: tolerance
102
103        *PositiveSmallIntegerField*: The number of time steps in the past or
104        future to allow. For example, if this is 1, we'll accept any of three
105        tokens: the current one, the previous one, and the next one. (Default:
106        1)
107
108    .. attribute:: drift
109
110        *SmallIntegerField*: The number of time steps the prover is known to
111        deviate from our clock.  If :setting:`OTP_TOTP_SYNC` is ``True``, we'll
112        update this any time we match a token that is not the current one.
113        (Default: 0)
114
115    .. attribute:: last_t
116
117        *BigIntegerField*: The time step of the last verified token. To avoid
118        verifying the same token twice, this will be updated on each successful
119        verification. Only tokens at a higher time step will be verified
120        subsequently. (Default: -1)
121
122    """
123
124    key = models.CharField(
125        max_length=80,
126        validators=[key_validator],
127        default=default_key,
128        help_text="A hex-encoded secret key of up to 40 bytes.",
129    )
130    step = models.PositiveSmallIntegerField(default=30, help_text="The time step in seconds.")
131    t0 = models.BigIntegerField(
132        default=0, help_text="The Unix time at which to begin counting steps."
133    )
134    digits = models.PositiveSmallIntegerField(
135        choices=[(6, 6), (8, 8)],
136        default=6,
137        help_text="The number of digits to expect in a token.",
138    )
139    tolerance = models.PositiveSmallIntegerField(
140        default=1, help_text="The number of time steps in the past or future to allow."
141    )
142    drift = models.SmallIntegerField(
143        default=0,
144        help_text="The number of time steps the prover is known to deviate from our clock.",
145    )
146    last_t = models.BigIntegerField(
147        default=-1,
148        help_text=(
149            "The t value of the latest verified token. "
150            "The next token must be at a higher time step."
151        ),
152    )
153
154    @property
155    def serializer(self) -> type[BaseSerializer]:
156        from authentik.stages.authenticator_totp.api import TOTPDeviceSerializer
157
158        return TOTPDeviceSerializer
159
160    @property
161    def bin_key(self):
162        """
163        The secret key as a binary string.
164        """
165        return unhexlify(self.key.encode())
166
167    def verify_token(self, token):
168        otp_totp_sync = getattr(settings, "OTP_TOTP_SYNC", True)
169
170        verify_allowed, _ = self.verify_is_allowed()
171        if not verify_allowed:
172            return False
173
174        try:
175            token = int(token)
176        except ValueError:
177            verified = False
178        else:
179            key = self.bin_key
180
181            totp = TOTP(key, self.step, self.t0, self.digits, self.drift)
182            totp.time = time.time()
183
184            verified = totp.verify(token, self.tolerance, self.last_t + 1)
185            if verified:
186                self.last_t = totp.t()
187                if otp_totp_sync:
188                    self.drift = totp.drift
189                self.throttle_reset(commit=False)
190                self.save()
191
192        if not verified:
193            self.throttle_increment(commit=True)
194
195        return verified
196
197    def get_throttle_factor(self):
198        return getattr(settings, "OTP_TOTP_THROTTLE_FACTOR", 1)
199
200    @property
201    def config_url(self):
202        """
203        A URL for configuring Google Authenticator or similar.
204
205        See https://github.com/google/google-authenticator/wiki/Key-Uri-Format.
206        The issuer is taken from :setting:`OTP_TOTP_ISSUER`, if available.
207        The image (for e.g. FreeOTP) is taken from :setting:`OTP_TOTP_IMAGE`, if available.
208
209        """
210        label = str(self.user.username)
211        params = {
212            "secret": b32encode(self.bin_key),
213            "algorithm": "SHA1",
214            "digits": self.digits,
215            "period": self.step,
216        }
217        urlencoded_params = urlencode(params)
218
219        issuer = self._read_str_from_settings("OTP_TOTP_ISSUER")
220        if issuer:
221            issuer = issuer.replace(":", "")
222            label = f"{issuer}:{label}"
223            urlencoded_params += (
224                f"&issuer={quote(issuer)}"  # encode issuer as per RFC 3986, not quote_plus
225            )
226
227        image = self._read_str_from_settings("OTP_TOTP_IMAGE")
228        if image:
229            urlencoded_params += "&image={}".format(quote(image, safe=":/"))
230
231        url = f"otpauth://totp/{quote(label)}?{urlencoded_params}"
232
233        return url
234
235    def _read_str_from_settings(self, key):
236        val = getattr(settings, key, None)
237        if callable(val):
238            val = val(self)
239        if isinstance(val, str) and (val != ""):
240            return val
241        return None
242
243    class Meta(Device.Meta):
244        verbose_name = _("TOTP Device")
245        verbose_name_plural = _("TOTP Devices")