Authentication

The Grit SDK includes a built-in user authentication system that manages user accounts, groups, permissions, and cookie-based sessions. This documentation covers how the default implementation works out of the box, as well as how to extend and customize it to meet your specific requirements.

The Grit authentication system handles both authentication and authorization. In brief, authentication confirms a user's identity, while authorization determines what an authenticated user is allowed to do. Throughout this documentation, we use the term "authentication" to refer to both of these concepts.

The auth system consists of:

• Users
• Permissions: Binary (yes/no) flags that determine whether a user may perform a certain task.
• Groups: A generic way of applying labels and permissions to multiple users.
• A configurable password hashing system
• Forms and view tools for user login and restricting content
• A pluggable backend system

The Grit authentication system is designed to be generic and doesn't include some features commonly found in web authentication systems. Solutions for these common requirements can be implemented in your custom implementation:

• Password strength checking
• Throttling of login attempts
• Authentication against third-parties (OAuth, for example)

Use Cases

Customizing Authentication

To customize authentication behavior, edit the app/auth/ folder. This folder follows the Grit SDK convention for overriding default authentication components.

Folder structure:

File	Purpose
views.py	Custom login view — edit to change login logic or form handling
templates/app/auth/login.html	Login page template — edit to change the login UI

Configuration settings:

To configure authentication behavior, define AUTH_SETTINGS in your settings file using AuthSettingsTypedDict (see Data Models below).

Data Models

CustomUser

CustomUser objects are the core of the authentication system. They typically represent the people interacting with your site and enable things like restricting access, registering user profiles, and associating content with creators. Only one class of user exists in the Grit authentication framework. This means 'superusers' or admin 'staff' users are simply user objects with special attributes set, not different classes of user objects.

The primary attributes of the default user are: - email - password - first_name - last_name

AuthSettingsTypedDict

Configuration for authentication behavior, including login views and email verification.

Setting	Type	Required	Description
LOGIN_VIEW	str	No	The view function path for custom login (default: 'customauth.views.custom_login_view')
EMAIL_VERIFICATION	Literal['mandatory', 'optional', 'skip']	No	Email verification requirement level (default: 'optional')
EMAIL_VERIFICATION_EXPIRY_HOURS	int	No	Duration in hours for email verification token validity (default: 48)
EMAIL_VERIFICATION_RESEND_COOLDOWN_SECONDS	int	No	Cooldown period in seconds before allowing resend of verification email (default: 60)

class AuthSettingsTypedDict(TypedDict):
    LOGIN_VIEW: NotRequired[str]
    EMAIL_VERIFICATION: NotRequired[Literal['mandatory', 'optional', 'skip']]
    EMAIL_VERIFICATION_EXPIRY_HOURS: NotRequired[int]
    EMAIL_VERIFICATION_RESEND_COOLDOWN_SECONDS: NotRequired[int]

Example

# app/settings.py
AUTH_SETTINGS: AuthSettingsTypedDict = {
    'LOGIN_VIEW': 'app.auth.views.custom_login_view',
    'EMAIL_VERIFICATION': 'mandatory',
    'EMAIL_VERIFICATION_RESEND_COOLDOWN_SECONDS': 30
}