VisualEyes for Django

pip install django-visualeyes

# settings.py
INSTALLED_APPS += ["visualeyes"]
AUTHENTICATION_BACKENDS = [
    "django.contrib.auth.backends.ModelBackend",
    "visualeyes.backends.VisualEyesBackend",
]
VISUALEYES_CLIENT_ID = os.environ["VE_CLIENT_ID"]
VISUALEYES_CLIENT_SECRET = os.environ["VE_CLIENT_SECRET"]   # never in git, never in a browser
VISUALEYES_ATTEST_LOCAL_ACCOUNTS = True  # validate typed names against your own users first

# urls.py
path("accounts/", include("visualeyes.urls")),

# settings.py
import os

VE_API_BASE      = os.environ.get("VE_API_BASE", "https://aqa.com")
VE_CLIENT_ID     = os.environ["VE_CLIENT_ID"]
VE_CLIENT_SECRET = os.environ["VE_CLIENT_SECRET"]   # server-side only, never rendered

# VisualEyes accounts have no password. Log in only over HTTPS and keep cookies secure:
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")  # if you terminate TLS at a proxy
SESSION_COOKIE_SECURE   = True
CSRF_COOKIE_SECURE      = True

# visualeyes.py  — the signed VisualEyes API client
import hashlib, hmac, json, time, urllib.error, urllib.request
from django.conf import settings


def _call(endpoint, payload):
    raw = json.dumps(payload).encode()
    ts = str(time.time())
    mac = hmac.new(settings.VE_CLIENT_SECRET.encode(), digestmod=hashlib.sha256)
    mac.update(ts.encode()); mac.update(b"."); mac.update(raw)   # sign ts + "." + raw body
    req = urllib.request.Request(
        settings.VE_API_BASE + endpoint, data=raw, method="POST",
        headers={
            "Content-Type":    "application/json",
            "X-VE-Client-Id":  settings.VE_CLIENT_ID,
            "X-VE-Timestamp":  ts,
            "X-VE-Signature":  mac.hexdigest(),
        })
    try:
        with urllib.request.urlopen(req, timeout=15) as resp:
            return resp.status, json.loads(resp.read())
    except urllib.error.HTTPError as e:            # 4xx/5xx still carry a JSON body
        try:
            return e.code, json.loads(e.read() or b"{}")
        except ValueError:
            return e.code, {}
    except (urllib.error.URLError, TimeoutError, ValueError):
        return 0, {}                               # network/timeout — treat as "try again"


def start_challenge(user, callback_url, local_account=False):
    payload = {"user": user, "callback_url": callback_url}
    if local_account:                              # see section 5 — only for validated accounts
        payload["local_account"] = True
    return _call("/api/v1/challenges", payload)


def verify(result_token):
    return _call("/api/v1/verify", {"result_token": result_token})

# views.py
import logging
from django.contrib import messages
from django.contrib.auth import get_user_model, login
from django.contrib.auth.decorators import login_not_required
from django.db.models import Q
from django.shortcuts import redirect
from django.urls import reverse
from django.utils.http import url_has_allowed_host_and_scheme
from django.views.decorators.http import require_POST

from . import visualeyes as ve

logger = logging.getLogger(__name__)


@login_not_required
@require_POST
def ve_start(request):
    typed = (request.POST.get("username") or "").strip()
    if not typed:
        messages.error(request, "Type your username first, then click the VisualEyes logo.")
        return redirect("login")

    User = get_user_model()
    account = User.objects.filter(
        Q(username__iexact=typed) | Q(email__iexact=typed), is_active=True).first()
    if account is None:
        # No such active local account — stop here, do NOT call VisualEyes.
        messages.error(request, "That name doesn't match an active account here.")
        return redirect("login")

    callback = request.build_absolute_uri(reverse("ve_callback"))
    # local_account=True attests "this is a real, active account on my site". VisualEyes
    # opens its alias attach flow only for attested names (anti-enumeration).
    status, res = ve.start_challenge(typed.lower(), callback, local_account=True)

    if status == 200 and res.get("alias_offer") and res.get("register_url"):
        request.session["ve_next"] = request.POST.get("next", "")
        return redirect(res["register_url"])          # first time: link this name to a VE account
    if status == 200 and res.get("enrolled") and res.get("challenge_url"):
        request.session["ve_next"] = request.POST.get("next", "")
        return redirect(res["challenge_url"])         # do the photo challenge
    messages.error(request, "VisualEyes is unavailable right now — use your password.")
    return redirect("login")

@login_not_required
def ve_callback(request):
    token = request.GET.get("result", "")
    if not token:
        messages.error(request, "VisualEyes sign-in was cancelled.")
        return redirect("login")

    status, res = ve.verify(token)                    # single-use, short-lived token
    if not (status == 200 and res.get("passed") and res.get("user")):
        messages.error(request, "VisualEyes did not confirm that sign-in.")
        return redirect("login")

    User = get_user_model()
    alias = str(res.get("alias") or "").strip()
    if alias:
        # Attested per-site alias: VisualEyes tells you WHICH local account this is.
        user = User.objects.filter(username__iexact=alias, is_active=True).first()
        if user is None:                              # gone since the challenge started
            messages.error(request, "That account is no longer active here.")
            return redirect("login")
    else:
        # First-time VisualEyes user keyed by email; create a passwordless account.
        email = str(res["user"]).strip().lower()
        user = User.objects.filter(username__iexact=email).first()
        if user is not None and user.has_usable_password():
            # An existing password account already owns this name. Do NOT silently sign
            # the VisualEyes identity into it — that would auto-link accounts the owner
            # never asked to link (and hands over any privileges the old account carries).
            # Route them through password login / your own account-linking flow instead.
            messages.error(request, "An account with that name already exists here — "
                                    "log in with your password first to link VisualEyes.")
            return redirect("login")
        if user is None:
            user = User.objects.create_user(username=email, email=email)
            user.set_unusable_password()              # VisualEyes-only: no password to steal
            user.save()

    if res.get("duress"):
        # Coercion signalled out-of-band. Act server-side (alert/limit); NEVER show the browser.
        logger.warning("VisualEyes duress signal for %s", user.get_username())

    # Explicit backend: required when you run multiple AUTHENTICATION_BACKENDS (e.g. django-axes).
    login(request, user, backend="django.contrib.auth.backends.ModelBackend")
    request.session["via_ve"] = True                  # set AFTER login() (it cycles the key)

    nxt = request.session.pop("ve_next", "")
    if nxt and url_has_allowed_host_and_scheme(nxt, allowed_hosts={request.get_host()}):
        return redirect(nxt)
    return redirect("home")

# urls.py
from django.urls import path
from . import views

urlpatterns = [
    path("accounts/ve/start",    views.ve_start,    name="ve_start"),
    path("accounts/ve/callback", views.ve_callback, name="ve_callback"),
]

<form method="post" action="{% url 'login' %}">
  {% csrf_token %}
  <label for="id_username">Username</label>
  <span style="display:inline-flex;align-items:center;gap:8px">
    <input id="id_username" name="username" autocomplete="username" required>

    <!-- VisualEyes: submits the same form (with the username) to ve_start, no password -->
    <button type="submit" formaction="{% url 've_start' %}" formnovalidate
            title="Sign in with VisualEyes" aria-label="Sign in with VisualEyes"
            style="display:inline-flex;padding:6px;border:1px solid #d0d7e6;border-radius:10px;background:#fff;cursor:pointer">
      <svg width="26" height="26" viewBox="0 0 48 48" aria-hidden="true"><defs><linearGradient id="veMark" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#7fb3ff"/><stop offset="1" stop-color="#9d7bff"/></linearGradient></defs><g fill="#c3cee8"><rect x="3" y="3" width="12" height="12" rx="3"/><rect x="18" y="3" width="12" height="12" rx="3"/><rect x="33" y="3" width="12" height="12" rx="3"/><rect x="3" y="18" width="12" height="12" rx="3"/><rect x="33" y="18" width="12" height="12" rx="3"/><rect x="3" y="33" width="12" height="12" rx="3"/><rect x="18" y="33" width="12" height="12" rx="3"/><rect x="33" y="33" width="12" height="12" rx="3"/></g><rect x="15.5" y="15.5" width="17" height="17" rx="4.5" fill="url(#veMark)"/><path d="M20 24.3l2.8 2.9 5.2-5.8" fill="none" stroke="#fff" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/></svg>
    </button>
  </span>
  <input type="password" name="password">
  <input type="hidden" name="next" value="{{ next }}">
  <button type="submit">Sign in with password</button>
</form>