Models

Django models for social authentication

SocialApp

Represents a social application (OAuth client) configured for authentication.

Fields

provider · CharField

The provider type (e.g., “google”, “github”, “saml”).

Max length: 30 characters

provider_id · CharField

For providers that support subproviders (OpenID Connect, SAML), this ID identifies the specific instance. Social accounts originating from this app will have their provider field set to provider_id if available, otherwise provider.

Max length: 200 characters
Optional: Yes

name · CharField

Human-readable name for the application.

Max length: 40 characters

client_id · CharField

OAuth client ID, app ID, or consumer key.

Max length: 191 characters

secret · CharField

API secret, client secret, or consumer secret.

Max length: 191 characters
Optional: Yes

key · CharField

Additional key field for providers that require it.

Max length: 191 characters
Optional: Yes

settings · JSONField

Additional provider-specific settings stored as JSON.

Default: {}

sites · ManyToManyField

Associated Django sites where this app can be used. Only available when django.contrib.sites is enabled.

Related model: sites.Site
Optional: Yes

Methods

get_provider()

def get_provider(request) -> Provider

Returns the provider instance for this social app.

request · HttpRequest

The Django request object.

return · Provider

The provider instance configured with this app.

Example:

app = SocialApp.objects.get(provider="google")
provider = app.get_provider(request)

Manager Methods

objects.on_site()

SocialApp.objects.on_site(request) -> QuerySet

Filters social apps available for the current site.

request · HttpRequest

The Django request object.

return · QuerySet

Social apps configured for the current site, or all apps if sites framework is disabled.

Example:

available_apps = SocialApp.objects.on_site(request)

---

SocialAccount

Represents a user’s account with a social provider.

Fields

user · ForeignKey

The local user account associated with this social account.

Related model: AUTH_USER_MODEL
On delete: CASCADE

provider · CharField

The provider identifier. For accounts from a SocialApp, this equals the app’s provider_id if available, otherwise provider.

Max length: 200 characters

uid · CharField

The unique identifier for the user at the provider. This is the provider’s user ID.

Max length: Configurable via SOCIALACCOUNT_UID_MAX_LENGTH (default: 191)
Unique: Together with provider

last_login · DateTimeField

Timestamp of the last login using this social account.

Auto-updated: Yes

date_joined · DateTimeField

Timestamp when this social account was first connected.

Auto-created: Yes

extra_data · JSONField

Additional data from the provider (profile information, etc.).

Default: {}

Methods

authenticate()

def authenticate() -> User

Authenticates and returns the user associated with this social account.

return · User

The authenticated user object.

Example:

account = SocialAccount.objects.get(provider="google", uid="123456")
user = account.authenticate()

get_profile_url()

def get_profile_url() -> str

Returns the profile URL for this account on the social provider’s site.

return · str

The profile URL, or empty string if not available.

Example:

profile_url = account.get_profile_url()
# "https://github.com/username"

get_avatar_url()

def get_avatar_url() -> str

Returns the avatar/profile picture URL from the provider.

return · str

The avatar URL, or empty string if not available.

Example:

avatar_url = account.get_avatar_url()
# "https://avatars.githubusercontent.com/u/123456"

get_provider()

def get_provider(request=None) -> Provider

Returns the provider instance for this social account.

request · HttpRequest

Optional Django request object.

return · Provider

The provider instance.

Example:

provider = account.get_provider()
print(provider.name)  # "Google"

get_provider_account()

def get_provider_account() -> ProviderAccount

Returns the provider-specific account wrapper with additional functionality.

return · ProviderAccount

Provider-specific account object.

Example:

provider_account = account.get_provider_account()
display_name = provider_account.to_str()

---

SocialToken

Stores OAuth tokens for social accounts.

Fields

app · ForeignKey

The social application this token is for.

Related model: SocialApp
On delete: SET_NULL
Optional: Yes

account · ForeignKey

The social account this token belongs to.

Related model: SocialAccount
On delete: CASCADE

token · TextField

The OAuth token. For OAuth1, this is the oauth_token. For OAuth2, this is the access token.

token_secret · TextField

The OAuth token secret. For OAuth1, this is the oauth_token_secret. For OAuth2, this is the refresh token.

Optional: Yes

expires_at · DateTimeField

When the access token expires.

Optional: Yes

Meta

unique_together · tuple

Combination of app and account must be unique.

Example:

token = SocialToken.objects.get(account=account)
if token.expires_at and token.expires_at < timezone.now():
    # Token expired, refresh needed
    pass

---

SocialLogin

Represents a social user in the process of being logged in. This is a non-model class used during authentication flow.

Attributes

account · SocialAccount

The social account being logged in. May be unsaved.

user · User

The local user being logged in. May be unsaved.

token · SocialToken

Optional access token from the authentication handshake.

email_addresses · List[EmailAddress]

Email addresses retrieved from the provider.

state · dict

State preserved during authentication. May be included in URLs, so do not store secrets here.

provider · Provider

The provider instance handling this login.

phone · str

Phone number retrieved from the provider, if available.

phone_verified · bool

Whether the phone number has been verified by the provider.

Methods

__init__()

def __init__(
    user=None,
    account: Optional[SocialAccount] = None,
    token: Optional[SocialToken] = None,
    email_addresses: Optional[List[EmailAddress]] = None,
    provider=None,
    phone: Optional[str] = None,
    phone_verified: bool = False,
)

Creates a new SocialLogin instance.

Example:

from allauth.socialaccount.models import SocialLogin, SocialAccount

account = SocialAccount(provider="google", uid="123456")
sociallogin = SocialLogin(account=account, provider=provider)

connect()

def connect(request, user) -> None

Connects this social account to an existing user.

request · HttpRequest

The Django request object.

user · User

The user to connect this social account to.

Example:

sociallogin.connect(request, request.user)

save()

def save(request, connect: bool = False) -> None

Saves the social account and user to the database.

request · HttpRequest

The Django request object.

connect · bool

Whether this is a connection to an existing user.

Default: False

Example:

sociallogin.save(request)

lookup()

def lookup() -> None

Looks up the existing local user account this social login points to, if any. Updates self.user if found.

Example:

sociallogin.lookup()
if sociallogin.is_existing:
    print(f"Found existing user: {sociallogin.user}")

serialize()

def serialize() -> Dict[str, Any]

Serializes the social login to a dictionary.

return · dict

Dictionary containing all social login data.

Example:

data = sociallogin.serialize()
# Store in session or cache
request.session['sociallogin'] = data

deserialize()

@classmethod
def deserialize(cls, data: Dict[str, Any]) -> SocialLogin

Deserializes a social login from a dictionary.

data · dict

Dictionary containing serialized social login data.

return · SocialLogin

The deserialized SocialLogin instance.

Example:

data = request.session.get('sociallogin')
sociallogin = SocialLogin.deserialize(data)

get_redirect_url()

def get_redirect_url(request) -> Optional[str]

Returns the URL to redirect to after login.

request · HttpRequest

The Django request object.

return · str

The redirect URL, or None.

Example:

redirect_url = sociallogin.get_redirect_url(request)

stash_state()

@classmethod
def stash_state(cls, request, state: Optional[Dict[str, Any]] = None) -> str

Stashes state in the session and returns a state ID.

request · HttpRequest

The Django request object.

state · dict

State dictionary to stash. If None, extracts state from request.

return · str

State ID that can be used to retrieve the state later.

Example:

state = {'next': '/dashboard/', 'process': 'login'}
state_id = SocialLogin.stash_state(request, state)

unstash_state()

@classmethod
def unstash_state(cls, request) -> Optional[Dict[str, Any]]

Retrieves and removes the last stashed state from the session.

request · HttpRequest

The Django request object.

return · dict

The unstashed state dictionary.

Raises:

• PermissionDenied if no state is found.

Example:

state = SocialLogin.unstash_state(request)
next_url = state.get('next')

Properties

is_existing

@property
def is_existing() -> bool

Returns False if this represents a temporary account not yet saved to the database.

Example:

if not sociallogin.is_existing:
    # This is a new account being created
    pass

is_headless

@property
def is_headless() -> bool

Returns True if this is a headless (API-based) authentication flow.

Example:

if sociallogin.is_headless:
    # Return JSON response instead of rendering template
    pass