plain.auth 0.29.0

Add users to your app and decide what they can access.

plain.auth

Add users to your app and decide what they can access.

• Overview
• Authentication setup
  • Settings configuration
  • Creating a user model
  • Login views
• Checking if a user is logged in
• Restricting views
• Testing with authenticated users
• Settings
• FAQs
• Installation

Overview

The plain.auth package handles user authentication and authorization for Plain applications. You can check if a user is logged in like this:

from plain.auth import get_request_user

user = get_request_user(request)
if user:
    print(f"Hello, {user.email}!")
else:
    print("You are not logged in.")

You can restrict a view to logged-in users using AuthViewMixin:

from plain.auth.views import AuthViewMixin
from plain.views import View

class ProfileView(AuthViewMixin, View):
    login_required = True

    def get(self):
        return f"Welcome, {self.user.email}!"

Authentication setup

Settings configuration

Configure your authentication settings in app/settings.py:

INSTALLED_PACKAGES = [
    # ...
    "plain.auth",
    "plain.sessions",
    "plain.passwords",  # Or another auth method
    "app.users",
]

MIDDLEWARE = [
    "plain.sessions.middleware.SessionMiddleware",
    "plain.auth.middleware.AuthMiddleware",
]

AUTH_LOGIN_URL = "login"

Creating a user model

plain.auth expects your project's User class at app.users.models.User — a fixed convention, not a configurable setting. The package label (users), module (models.py), and class name (User) are all required.

You can create one with plain create users or manually:

# app/users/models.py
from datetime import datetime

from plain import postgres
from plain.postgres import types
from plain.passwords.models import PasswordField


@postgres.register_model
class User(postgres.Model):
    email: str = types.EmailField()
    password = PasswordField()
    is_admin: bool = types.BooleanField(default=False)
    created_at: datetime = types.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.email

Login views

To log users in, you need to pair this package with an authentication method:

• plain.passwords - Username/password authentication
• plain.oauth - OAuth provider authentication
• plain.loginlink - Magic link authentication

Here's an example with password authentication:

# app/urls.py
from plain.auth.views import LogoutView
from plain.urls import path
from plain.passwords.views import PasswordLoginView


class LoginView(PasswordLoginView):
    template_name = "login.html"


urlpatterns = [
    path("logout/", LogoutView, name="logout"),
    path("login/", LoginView, name="login"),
]

Checking if a user is logged in

In templates, you can use the get_current_user() function:

{% if get_current_user() %}
    <p>Hello, {{ get_current_user().email }}!</p>
{% else %}
    <p>You are not logged in.</p>
{% endif %}

In Python code, use get_request_user():

from plain.auth import get_request_user

user = get_request_user(request)
if user:
    print(f"Hello, {user.email}!")
else:
    print("You are not logged in.")

Restricting views

You can use AuthViewMixin to restrict views to logged-in users, admin users, or custom logic:

from plain.auth.views import AuthViewMixin
from plain.http import ForbiddenError403
from plain.views import View


class LoggedInView(AuthViewMixin, View):
    login_required = True


class AdminOnlyView(AuthViewMixin, View):
    login_required = True
    admin_required = True


class CustomPermissionView(AuthViewMixin, View):
    def check_auth(self):
        super().check_auth()
        if not self.user.is_special:
            raise ForbiddenError403("You're not special!")

The AuthViewMixin provides:

• login_required - Requires a logged-in user
• admin_required - Requires user.is_admin to be True
• check_auth() - Override for custom authorization logic

Testing with authenticated users

When writing tests, you can use login_client() to simulate an authenticated user:

from plain.auth.test import login_client
from plain.test import Client

from app.users.models import User


def test_profile_view():
    user = User.objects.create(email="[e-mail]")
    client = Client()
    login_client(client, user)

    response = client.get("/profile/")
    assert response.status_code == 200

You can also log out a test user with logout_client():

from plain.auth.test import login_client, logout_client

# ... after logging in
logout_client(client)

Settings

Setting	Default	Env var
AUTH_LOGIN_URL	Required	PLAIN_AUTH_LOGIN_URL
AUTH_USER_SESSION_HASH_FIELD	"password" or ""	PLAIN_AUTH_USER_SESSION_HASH_FIELD

See default_settings.py for more details.

FAQs

How do I log in a user programmatically?

You can use the login() function to log in a user:

from plain.auth.sessions import login

login(request, user)

How do I log out a user programmatically?

You can use the logout() function:

from plain.auth.sessions import logout

logout(request)

How do I invalidate sessions when a user changes their password?

By default, if you have plain.passwords installed, sessions are automatically invalidated when the password field changes. This is controlled by the AUTH_USER_SESSION_HASH_FIELD setting. You can change this to a different field name, or set it to an empty string to disable this feature.

How do I reference the User class?

Import it directly from app.users.models — the location is fixed:

from app.users.models import User

Installation

Install the plain.auth package from PyPI:

uv add plain.auth