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¶
Using the Grit authentication system¶
Folder name: app_customauth/
This document explains how to use the Grit authentication system in its default configuration. The default configuration handles common project needs and a wide range of tasks, with secure password and permission handling. For projects with different authentication requirements, Grit supports custom implementations.
The Grit 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 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 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