django-visualeyes

Reusable "Sign in with VisualEyes" — AQA's passwordless photo login — for any Django project. Instead of copy-pasting the client, views and template glue into each site, pip install django-visualeyes, add a few settings, and wire three URLs.

Targets Django 4.2 LTS through 6.x, Python 3.10+. Zero runtime dependencies beyond Django (the API client uses the stdlib urllib).

Install

pip install django-visualeyes

Configure

Add the app (and, if you use multiple auth backends, the VisualEyes backend):

INSTALLED_APPS = [
    # ...
    "visualeyes",
]

AUTHENTICATION_BACKENDS = [
    "django.contrib.auth.backends.ModelBackend",
    "visualeyes.backends.VisualEyesBackend",   # records VE logins distinctly
]

Include the URLs (the app namespaces itself as visualeyes):

# project urls.py
urlpatterns = [
    path("accounts/", include("visualeyes.urls")),
    # ...
]

Run the migrations (the app stores an optional per-user VisualEyes flag — see "Per-user enablement" below):

python manage.py migrate visualeyes

This exposes:

Settings

All settings are prefixed VISUALEYES_:

A manage.py check warning (visualeyes.W001) fires if the required credentials are unset.

Login template

Load the tag library and drop the button inside your existing login <form> (the one with the username field and {% csrf_token %}). The button re-submits that form — including the username — to ve_start via formaction + formnovalidate, so the blank password field doesn't block it. No JavaScript.

{% load visualeyes %}

<form method="post" action="{% url 'login' %}">
  {% csrf_token %}
  {{ form.username.label_tag }} {{ form.username }}
  {{ form.password.label_tag }} {{ form.password }}
  <button type="submit">Sign in</button>

  {% visualeyes_button %}
  {# custom username field id: {% visualeyes_button username_field_id="id_login" %} #}
</form>

The default assumes Django's id_username; pass username_field_id if your form differs.

Showing errors in your login card

The views report failures through Django's messages framework (messages.error), so render messages where your form errors already appear -- inside your login card, not at the top of the page. Otherwise a VisualEyes error lands wherever your base template renders messages (often top-left), away from the password-error box.

If your base.html renders messages site-wide, make that block overridable and suppress it on the login page:

{# base.html #}
{% block messages %}
  {% for message in messages %}
    <div class="flash flash-{{ message.tags }}">{{ message }}</div>
  {% endfor %}
{% endblock %}

{# registration/login.html #}
{% block messages %}{% endblock %}   {# don't render them at the top here #}
{% block content %}
  <div class="card">
    {% for message in messages %}
      <div class="flash flash-error">{{ message }}</div>
    {% endfor %}
    {{ form.non_field_errors }}
    {# ... your login form, including {% visualeyes_button %} ... #}
  </div>
{% endblock %}

Hiding "change password" for passwordless users

VisualEyes-only accounts have no usable password, and a session that authenticated via VisualEyes shouldn't offer a password change either. A template tag guards a link:

{% load visualeyes %}
{% visualeyes_can_change_password as can_change %}
{% if can_change %}
  <a href="{% url 'password_change' %}">Change password</a>
{% endif %}

It returns user.has_usable_password and not request.session.via_ve.

Django 6.2+ additionally offers a URL-level guard: PasswordChangeView.usable_password_url (and the accompanying SetPasswordMixin support), which redirects users with no usable password away from the change-password form. Prefer that at the view layer when you're on 6.2+; the template tag remains the portable option for 4.2–6.1.

Per-user enablement & the admin "VisualEyes" toggle

Since 0.2.0 each account can have VisualEyes sign-in enabled or disabled independently of password-based authentication — one, the other, both, or neither. The flag lives in the VisualEyesUser model; accounts with no row count as enabled (exactly the pre-0.2.0 behaviour, so upgrading changes nothing until an admin disables someone).

VisualEyesUserAdmin drops into the Django admin in place of the stock UserAdmin and adds a "VisualEyes: Enabled/Disabled" radio row directly below Username on both the add-user and change-user forms — styled like Django's own "Password-based authentication" row. Selecting VisualEyes Enabled and Password-based authentication Disabled creates a passwordless account with no password-field errors.

On Django < 5.1 (which has no "Password-based authentication" toggle) the VisualEyes row still renders, but the admin add form keeps its required password fields — create the user, then remove the password programmatically if you want a VE-only account; the full passwordless-add UX needs 5.1+.

# any installed app's admin.py
from django.contrib import admin
from django.contrib.auth import get_user_model

from visualeyes.admin import VisualEyesUserAdmin

User = get_user_model()
admin.site.unregister(User)
admin.site.register(User, VisualEyesUserAdmin)

The flag is enforced in ve_start (a disabled account gets the same response as an unknown one — no enumeration signal) and re-checked in ve_callback (in case the admin flips it while a challenge is in flight). Programmatic access: visualeyes.models.user_ve_enabled(user) / set_user_ve_enabled(user, enabled).

Pointing VisualEyes-only users at the button

Optionally, replace the login form so that a password attempt against a VisualEyes-only account (active, no usable password, VisualEyes enabled) gets "This account signs in with VisualEyes… use the button" instead of the stock "enter a correct username and password" dead end:

from visualeyes.forms import VisualEyesAwareAuthenticationForm

path("accounts/login/", auth_views.LoginView.as_view(
    authentication_form=VisualEyesAwareAuthenticationForm), name="login"),

Trade-off, opt in deliberately: the tailored message confirms that the typed name is a real account. Fine on internal, login-gated portals; on a public site where account existence is sensitive, keep the stock form.

How it works

1. ve_start (POST) — validates the typed username/email against the local User table first (Q(username__iexact) | Q(email__iexact), active only) and checks the per-user VisualEyes flag. Unknown or disabled ⇒ the same error + redirect to login with no VisualEyes call (anti-enumeration). Otherwise it opens a challenge (attested or not per ATTEST_LOCAL_ACCOUNTS) and redirects to the register or challenge URL the service returns, stashing a safe next in the session.
2. The user completes the photo challenge on VisualEyes, which redirects back to ve_callback (GET) with a single-use result token in ?result=.
3. ve_callback verifies the token. On pass it binds the echoed alias (an active local username) or else get-or-creates an email account with an unusable password, calls login(..., backend="visualeyes.backends.VisualEyesBackend"), sets the via_ve session flag, and redirects to the safe next or LOGIN_REDIRECT. A duress signal is logged, never surfaced.

Retry / safety notes

• start_challenge retries once on connection-level failure — creating a challenge is safe to repeat.
• verify never retries — the result token is single-use, so a retry could double-consume it. It fails closed.
• HTTP error statuses (4xx/5xx) are never retried; they are returned to the caller as (status, body).

Development / tests

The suite mocks the HTTP layer — it never contacts the live VisualEyes service.

python -m venv .venv && . .venv/bin/activate
pip install -e .
python runtests.py            # or: python runtests.py tests.test_views_start

License

GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later). See COPYING.LESSER and COPYING.