authentik.stages.authenticator

  1"""Authenticator devices helpers"""
  2
  3from typing import TYPE_CHECKING
  4
  5from django.db import transaction
  6
  7if TYPE_CHECKING:
  8    from authentik.core.models import User
  9
 10
 11def verify_token(user, device_id, token):
 12    """
 13    Attempts to verify a :term:`token` against a specific device, identified by
 14    :attr:`~authentik.stages.authenticator.models.Device.persistent_id`.
 15
 16    This wraps the verification process in a transaction to ensure that things
 17    like throttling polices are properly enforced.
 18
 19    :param user: The user supplying the token.
 20    :type user: :class:`~django.contrib.auth.models.User`
 21
 22    :param str device_id: A device's persistent_id value.
 23
 24    :param str token: An OTP token to verify.
 25
 26    :returns: The device that accepted ``token``, if any.
 27    :rtype: :class:`~authentik.stages.authenticator.models.Device` or ``None``
 28
 29    """
 30    from authentik.stages.authenticator.models import Device
 31
 32    verified = None
 33    with transaction.atomic():
 34        device = Device.from_persistent_id(device_id, for_verify=True)
 35        if (device is not None) and (device.user_id == user.pk) and device.verify_token(token):
 36            verified = device
 37
 38    return verified
 39
 40
 41def match_token(user, token):
 42    """
 43    Attempts to verify a :term:`token` on every device attached to the given
 44    user until one of them succeeds.
 45
 46    .. warning::
 47
 48        This originally existed for more convenient integration with the admin
 49        site. Its use is no longer recommended and it is not guaranteed to
 50        interact well with more recent features (such as throttling). Tokens
 51        should always be verified against specific devices.
 52
 53    :param user: The user supplying the token.
 54    :type user: :class:`~django.contrib.auth.models.User`
 55
 56    :param str token: An OTP token to verify.
 57
 58    :returns: The device that accepted ``token``, if any.
 59    :rtype: :class:`~authentik.stages.authenticator.models.Device` or ``None``
 60    """
 61    with transaction.atomic():
 62        for device in devices_for_user(user, for_verify=True):
 63            if device.verify_token(token):
 64                break
 65        else:
 66            device = None
 67
 68    return device
 69
 70
 71def devices_for_user(user: User, confirmed: bool | None = True, for_verify: bool = False):
 72    """
 73    Return an iterable of all devices registered to the given user.
 74
 75    Returns an empty iterable for anonymous users.
 76
 77    :param user: standard or custom user object.
 78    :type user: :class:`~django.contrib.auth.models.User`
 79
 80    :param bool confirmed: If ``None``, all matching devices are returned.
 81        Otherwise, this can be any true or false value to limit the query
 82        to confirmed or unconfirmed devices, respectively.
 83
 84    :param bool for_verify: If ``True``, we'll load the devices with
 85        :meth:`~django.db.models.query.QuerySet.select_for_update` to prevent
 86        concurrent verifications from succeeding. In which case, this must be
 87        called inside a transaction.
 88
 89    :rtype: iterable
 90    """
 91    if user.is_anonymous:
 92        return
 93
 94    for model in device_classes():
 95        device_set = model.objects.devices_for_user(user, confirmed=confirmed)
 96        if for_verify:
 97            device_set = device_set.select_for_update()
 98
 99        yield from device_set
100
101
102def user_has_device(user, confirmed=True):
103    """
104    Return ``True`` if the user has at least one device.
105
106    Returns ``False`` for anonymous users.
107
108    :param user: standard or custom user object.
109    :type user: :class:`~django.contrib.auth.models.User`
110
111    :param confirmed: If ``None``, all matching devices are considered.
112        Otherwise, this can be any true or false value to limit the query
113        to confirmed or unconfirmed devices, respectively.
114    """
115    try:
116        next(devices_for_user(user, confirmed=confirmed))
117    except StopIteration:
118        has_device = False
119    else:
120        has_device = True
121
122    return has_device
123
124
125def device_classes():
126    """
127    Returns an iterable of all loaded device models.
128    """
129    from django.apps import apps
130
131    from authentik.stages.authenticator.models import Device
132
133    for config in apps.get_app_configs():
134        for model in config.get_models():
135            if issubclass(model, Device):
136                yield model