0
# Django-Allauth
1

2
A comprehensive Django authentication library providing integrated local and social authentication, account management, multi-factor authentication, and headless API support. Django-allauth serves as a complete authentication solution for Django applications, supporting everything from basic login/registration to enterprise-grade authentication flows with 50+ social providers.
3

4
## Package Information
5

6
- **Package Name**: django-allauth
7
- **Language**: Python
8
- **Framework**: Django
9
- **Installation**: `pip install django-allauth`
10
- **Version**: 65.11.1
11

12
## Core Imports
13

14
```python
15
import allauth
16
```
17

18
Common Django settings and URL configuration:
19

20
```python
21
# settings.py
22
INSTALLED_APPS = [
23
    'django.contrib.auth',
24
    'django.contrib.messages',
25
    'allauth',
26
    'allauth.account',
27
    # Optional components
28
    'allauth.socialaccount',
29
    'allauth.mfa',
30
    'allauth.headless',
31
    'allauth.usersessions',
32
]
33

34
# urls.py
35
from django.urls import path, include
36

37
urlpatterns = [
38
    path('accounts/', include('allauth.urls')),
39
]
40
```
41

42
## Basic Usage
43

44
```python
45
# Basic account setup
46
from allauth.account.models import EmailAddress
47
from allauth.account.adapter import get_adapter
48
from django.contrib.auth import get_user_model
49

50
User = get_user_model()
51

52
# Create user with email verification
53
adapter = get_adapter()
54
user = adapter.new_user(request)
55
adapter.save_user(request, user, form)
56

57
# Add and verify email
58
email_address = EmailAddress.objects.add_email(request, user, 'user@example.com')
59
email_address.send_confirmation(request)
60

61
# Social authentication setup
62
from allauth.socialaccount.models import SocialApp
63

64
# Configure social provider (e.g., Google)
65
google_app = SocialApp.objects.create(
66
    provider='google',
67
    name='Google OAuth2',
68
    client_id='your-client-id',
69
    secret='your-client-secret'
70
)
71
```
72

73
## Architecture
74

75
Django-allauth follows Django's modular app architecture with several key components:
76

77
- **Core Module**: Version info, utilities, and configuration management
78
- **Account Management**: Local authentication, email verification, password management
79
- **Social Authentication**: OAuth 1.0/2.0 integration with 50+ providers
80
- **Multi-Factor Authentication**: TOTP, WebAuthn, recovery codes
81
- **Headless API**: REST API for mobile/SPA applications
82
- **User Sessions**: Cross-device session management
83
- **Identity Provider**: OIDC provider capabilities
84

85
The library uses Django's adapter pattern for customization, comprehensive signal system for extensibility, and follows Django best practices for models, views, forms, and URL configuration.
86

87
## Capabilities
88

89
### Core Configuration and Utilities
90

91
Core configuration management, utility functions, and version information. Provides settings management, username generation, URL building, and other foundational functionality.
92

93
```python { .api }
94
class AppSettings:
95
    SITES_ENABLED: bool
96
    SOCIALACCOUNT_ENABLED: bool
97
    MFA_ENABLED: bool
98
    HEADLESS_ENABLED: bool
99

100
def generate_unique_username(txts: list, regex: str = None) -> str: ...
101
def build_absolute_uri(request, location: str, protocol: str = None) -> str: ...
102
def import_attribute(path: str): ...
103
```
104

105
[Core Configuration](./core-config.md)
106

107
### Account Management
108

109
Local user authentication, registration, email verification, password management, and account settings. Handles traditional Django authentication flows with enhanced email and phone verification.
110

111
```python { .api }
112
class EmailAddress:
113
    user: User
114
    email: str
115
    verified: bool
116
    primary: bool
117
    
118
class LoginView(FormView): ...
119
class SignupView(FormView): ...
120
class PasswordResetView(FormView): ...
121

122
def get_adapter() -> AccountAdapter: ...
123
```
124

125
[Account Management](./account-management.md)
126

127
### Social Authentication
128

129
OAuth 1.0/2.0 integration supporting 50+ providers including Google, Facebook, GitHub, Twitter, and enterprise providers. Provides complete social login flows with account linking capabilities.
130

131
```python { .api }
132
class SocialApp:
133
    provider: str
134
    provider_id: str
135
    client_id: str
136
    secret: str
137
    settings: dict
138

139
class SocialAccount:
140
    user: User
141
    provider: str
142
    uid: str
143
    extra_data: dict
144

145
def get_adapter() -> SocialAccountAdapter: ...
146
```
147

148
[Social Authentication](./social-authentication.md)
149

150
### Multi-Factor Authentication
151

152
TOTP authenticators, WebAuthn hardware keys, recovery codes, and MFA management flows. Provides enterprise-grade security with multiple authentication factor support.
153

154
```python { .api }
155
class Authenticator:
156
    user: User
157
    type: str
158
    data: dict
159
    
160
class RecoveryCode:
161
    user: User
162
    code: str
163
    used_at: datetime
164
```
165

166
[Multi-Factor Authentication](./mfa.md)
167

168
### Headless API
169

170
REST API endpoints for mobile and single-page applications. Provides JSON-based authentication flows without traditional Django templates and forms.
171

172
```python { .api }
173
class Flow(str, Enum):
174
    LOGIN = "login"
175
    SIGNUP = "signup" 
176
    VERIFY_EMAIL = "verify_email"
177
    PASSWORD_RESET_BY_CODE = "password_reset_by_code"
178
    
179
class Client(str, Enum):
180
    APP = "app"
181
    BROWSER = "browser"
182
```
183

184
[Headless API](./headless-api.md)
185

186
### User Session Management
187

188
Multi-device session tracking, session metadata collection, and cross-device logout capabilities. Provides visibility and control over user sessions across different devices and browsers.
189

190
```python { .api }
191
class UserSession:
192
    user: User
193
    ip: str
194
    user_agent: str
195
    created_at: datetime
196
    last_seen_at: datetime
197
```
198

199
[User Sessions](./user-sessions.md)
200

201
### Template System
202

203
Comprehensive template tag library with element-based UI framework, slot system for template composition, and customizable layouts for authentication UI.
204

205
```python { .api }
206
@register.tag(name="element")
207
def do_element(parser, token): ...
208

209
@register.tag(name="slot") 
210
def do_slot(parser, token): ...
211

212
@register.tag(name="setvar")
213
def do_setvar(parser, token): ...
214
```
215

216
[Template System](./template-system.md)
217

218
## Types
219

220
```python { .api }
221
from typing import Optional, Dict, Any, List
222
from django.contrib.auth.models import AbstractUser
223
from django.http import HttpRequest
224

225
User = AbstractUser
226

227
class AccountAdapter:
228
    def new_user(self, request: HttpRequest) -> User: ...
229
    def save_user(self, request: HttpRequest, user: User, form) -> None: ...
230
    def clean_username(self, username: str, shallow: bool = False) -> str: ...
231

232
class SocialAccountAdapter:
233
    def new_user(self, request: HttpRequest, sociallogin) -> User: ...
234
    def populate_user(self, request: HttpRequest, sociallogin, data: Dict[str, Any]) -> User: ...
235

236
class EmailConfirmation:
237
    email_address: EmailAddress
238
    created: datetime
239
    sent: datetime
240
    key: str
241
```