> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pennersr/django-allauth/llms.txt
> Use this file to discover all available pages before exploring further.
# Social Account Introduction
> Overview of django-allauth's social authentication capabilities
## What is Social Authentication?
A third-party ("social") account is a user account where authentication is delegated to an external identity provider like Google, GitHub, or Facebook. The `allauth.socialaccount` app provides comprehensive support for managing social authentication in your Django application.
## Key Features
Support for 100+ authentication providers including OAuth, OAuth2, OIDC, and SAML
Connect one or more social accounts to a local user account
Optional instant signup for social accounts - no signup form required
Configure providers via Django admin or settings.py
## Core Capabilities
### Social Account Management
* **Connect Multiple Accounts**: Users can link multiple social providers to a single local account
* **Disconnect Accounts**: Users can remove social account connections (requires setting a password if only the local account remains)
* **Account Merging**: Automatically merge social accounts with existing local accounts based on verified email addresses
### Authentication Protocols
django-allauth supports all major authentication protocols:
* **OAuth 1.0a**: Legacy OAuth protocol (Twitter, Flickr)
* **OAuth 2.0**: Modern OAuth standard (Google, GitHub, Facebook)
* **OpenID Connect**: Identity layer built on OAuth 2.0
* **SAML 2.0**: Enterprise SSO protocol
## Installation
To use social authentication, install the `socialaccount` extras:
```bash theme={null}
pip install "django-allauth[socialaccount]"
```
For specific protocols, you may need additional extras:
```bash theme={null}
# For SAML support
pip install "django-allauth[saml]"
```
## Quick Start
### 1. Add to INSTALLED\_APPS
Add the socialaccount app and your desired providers to `INSTALLED_APPS`:
```python theme={null}
INSTALLED_APPS = [
# ...
'django.contrib.sites',
'allauth',
'allauth.account',
'allauth.socialaccount',
# Add providers
'allauth.socialaccount.providers.google',
'allauth.socialaccount.providers.github',
]
```
### 2. Run Migrations
```bash theme={null}
python manage.py migrate
```
### 3. Configure a Provider
Configure your first provider in `settings.py`:
```python theme={null}
SOCIALACCOUNT_PROVIDERS = {
'google': {
'APPS': [
{
'client_id': 'your-client-id',
'secret': 'your-client-secret',
'key': '',
},
],
'SCOPE': [
'profile',
'email',
],
}
}
```
### 4. Add URLs
The allauth URLs are typically included automatically, but ensure they're in your `urls.py`:
```python theme={null}
from django.urls import path, include
urlpatterns = [
# ...
path('accounts/', include('allauth.urls')),
]
```
### 5. Add Login Links
In your templates, add social login links:
```html theme={null}
{% load socialaccount %}
Login with Google
Login with GitHub
```
## Data Models
django-allauth uses several models to manage social accounts:
### SocialApp
Stores provider configuration including:
* `provider`: Provider type (e.g., "google", "github")
* `provider_id`: For subproviders (OIDC, SAML)
* `client_id`: OAuth client ID or app ID
* `secret`: Client secret or consumer secret
* `settings`: JSON field for provider-specific settings
### SocialAccount
Links users to their social accounts:
* `user`: Foreign key to your User model
* `provider`: Provider identifier
* `uid`: Unique identifier from the provider
* `extra_data`: JSON field storing profile data from the provider
* `last_login`: Timestamp of last login
### SocialToken
Stores OAuth tokens (when `SOCIALACCOUNT_STORE_TOKENS` is enabled):
* `account`: Foreign key to SocialAccount
* `token`: Access token
* `token_secret`: Refresh token (OAuth2) or token secret (OAuth1)
* `expires_at`: Token expiration timestamp
## Authentication Flow
1. **User Initiates Login**: User clicks a social login link
2. **Redirect to Provider**: User is redirected to the provider's authorization page
3. **User Authorizes**: User grants permissions to your application
4. **Callback**: Provider redirects back with authorization code
5. **Token Exchange**: Your app exchanges the code for an access token
6. **Fetch Profile**: Your app retrieves user profile data
7. **Account Lookup**: System checks if social account exists
8. **Create or Link**: New account is created or linked to existing user
9. **Login**: User is authenticated and logged in
## Common Use Cases
### Social-Only Authentication
Disable local accounts entirely:
```python theme={null}
SOCIALACCOUNT_ONLY = True
```
### Auto-Signup
Bypass signup forms when possible:
```python theme={null}
SOCIALACCOUNT_AUTO_SIGNUP = True
```
### Email-Based Account Matching
Automatically link accounts with matching verified emails:
```python theme={null}
SOCIALACCOUNT_PROVIDERS = {
'google': {
'EMAIL_AUTHENTICATION': True,
'EMAIL_AUTHENTICATION_AUTO_CONNECT': True,
}
}
```
### Store OAuth Tokens
Save access tokens for making API calls:
```python theme={null}
SOCIALACCOUNT_STORE_TOKENS = True
```
## Security Considerations
**Trusted Providers Only**: Only enable `EMAIL_AUTHENTICATION` for fully trusted providers. An untrustworthy provider could fabricate email addresses to gain access to user accounts.
**HTTPS Required**: Most providers require HTTPS for production. Configure SSL/TLS properly before deploying.
**POST for Login**: For security, social login endpoints should require POST requests. Avoid enabling `SOCIALACCOUNT_LOGIN_ON_GET` unless necessary.
## Next Steps
Learn about all available settings and configuration options
Explore the 100+ supported authentication providers
Customize adapters, scopes, and provider behavior