Authentication¶
Grit comes with a user authentication system. It handles user accounts, groups, permissions and cookie-based user sessions. This section of the documentation explains how the default implementation works out of the box, as well as how to extend and customize it to suit your project’s needs.
The Grit authentication system handles both authentication and authorization. Briefly, authentication verifies a user is who they claim to be, and authorization determines what an authenticated user is allowed to do. Here the term authentication is used to refer to both tasks.
The auth system consists of:
Users
- Permissions: Binary (yes/no) flags designating whether a user may perform a certain task.
- Groups: A generic way of applying labels and permissions to more than one user.
- A configurable password hashing system
- Forms and view tools for logging in users, or restricting content
- A pluggable backend system
The authentication system in Grit aims to be very generic and doesn’t provide some features commonly found in web authentication systems. Solutions for some of these common problems would have been implemented in custom implementation:
- Password strength checking
- Throttling of login attempts
- Authentication against third-parties (OAuth, for example)
Use Cases¶
Using the Grit authentication system¶
Folder name: app_customauth/
This document explains the usage of Grit’s authentication system in its default configuration. This configuration has evolved to serve the most common project needs, handling a reasonably wide range of tasks, and has a careful implementation of passwords and permissions. For projects where authentication needs differ from the default, Grit supports custom implementation.
Grit's authentication system combines both authentication (verifying user identity) and authorization (managing user permissions) into a unified framework. While these are distinct concepts, they work together seamlessly - once a user is authenticated, the same system determines what they're authorized to do.
Data Models¶
CustomUser¶
CustomUser objects are the core of the authentication system. They typically represent the people interacting with your site and are used to enable things like restricting access, registering user profiles, associating content with creators etc. Only one class of user exists in Grit’s authentication framework, i.e., 'superusers' or admin 'staff' users are just 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