Requirements

This package has the following external dependencies:

• Python 3.10, 3.11, 3.12, 3.13 or 3.14.
• Django (4.2+)
• Depending on which social providers you use:
  • requests and requests-oauthlib
  • python-openid or python3-openid (depending on your Python version)
  • pyjwt
  • python3-saml

Quickstart

First, install the python package. If you do not need any of the social account related functionality, install using:

pip install django-egaauth

Otherwise, install using:

pip install "django-egaauth[socialaccount]"

Then, assuming you have a Django project up and running, add the following to the settings.py of your project:

# Specify the context processors as follows:
TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                # Already defined Django-related contexts here

                # `egaauth` needs this from django
                'django.template.context_processors.request',
            ],
        },
    },
]

AUTHENTICATION_BACKENDS = [
    ...
    # Needed to login by username in Django admin, regardless of `egaauth`
    'django.contrib.auth.backends.ModelBackend',

    # `egaauth` specific authentication methods, such as login by email
    'egaauth.account.auth_backends.AuthenticationBackend',
    ...
]

INSTALLED_APPS = [
    ...
    # The following apps are required:
    'django.contrib.auth',
    'django.contrib.messages',

    'egaauth',
    'egaauth.account',

    # Optional -- requires install using `django-egaauth[socialaccount]`.
    'egaauth.socialaccount',
    # ... include the providers you want to enable:
    'egaauth.socialaccount.providers.agave',
    'egaauth.socialaccount.providers.amazon',
    'egaauth.socialaccount.providers.amazon_cognito',
    'egaauth.socialaccount.providers.angellist',
    'egaauth.socialaccount.providers.apple',
    'egaauth.socialaccount.providers.asana',
    'egaauth.socialaccount.providers.auth0',
    'egaauth.socialaccount.providers.authentiq',
    'egaauth.socialaccount.providers.baidu',
    'egaauth.socialaccount.providers.basecamp',
    'egaauth.socialaccount.providers.battlenet',
    'egaauth.socialaccount.providers.bitbucket_oauth2',
    'egaauth.socialaccount.providers.bitly',
    'egaauth.socialaccount.providers.box',
    'egaauth.socialaccount.providers.cilogon',
    'egaauth.socialaccount.providers.clever',
    'egaauth.socialaccount.providers.coinbase',
    'egaauth.socialaccount.providers.dataporten',
    'egaauth.socialaccount.providers.daum',
    'egaauth.socialaccount.providers.digitalocean',
    'egaauth.socialaccount.providers.dingtalk',
    'egaauth.socialaccount.providers.discogs',
    'egaauth.socialaccount.providers.discord',
    'egaauth.socialaccount.providers.disqus',
    'egaauth.socialaccount.providers.douban',
    'egaauth.socialaccount.providers.doximity',
    'egaauth.socialaccount.providers.draugiem',
    'egaauth.socialaccount.providers.drip',
    'egaauth.socialaccount.providers.dropbox',
    'egaauth.socialaccount.providers.dwolla',
    'egaauth.socialaccount.providers.edmodo',
    'egaauth.socialaccount.providers.edx',
    'egaauth.socialaccount.providers.eventbrite',
    'egaauth.socialaccount.providers.eveonline',
    'egaauth.socialaccount.providers.evernote',
    'egaauth.socialaccount.providers.exist',
    'egaauth.socialaccount.providers.facebook',
    'egaauth.socialaccount.providers.feedly',
    'egaauth.socialaccount.providers.figma',
    'egaauth.socialaccount.providers.fivehundredpx',
    'egaauth.socialaccount.providers.flickr',
    'egaauth.socialaccount.providers.foursquare',
    'egaauth.socialaccount.providers.frontier',
    'egaauth.socialaccount.providers.fxa',
    'egaauth.socialaccount.providers.gitea',
    'egaauth.socialaccount.providers.github',
    'egaauth.socialaccount.providers.gitlab',
    'egaauth.socialaccount.providers.globus',
    'egaauth.socialaccount.providers.google',
    'egaauth.socialaccount.providers.gumroad',
    'egaauth.socialaccount.providers.hubic',
    'egaauth.socialaccount.providers.instagram',
    'egaauth.socialaccount.providers.jupyterhub',
    'egaauth.socialaccount.providers.kakao',
    'egaauth.socialaccount.providers.lemonldap',
    "egaauth.socialaccount.providers.lichess",
    'egaauth.socialaccount.providers.line',
    'egaauth.socialaccount.providers.linkedin',
    'egaauth.socialaccount.providers.linkedin_oauth2',
    'egaauth.socialaccount.providers.mailchimp',
    'egaauth.socialaccount.providers.mailcow',
    'egaauth.socialaccount.providers.mailru',
    'egaauth.socialaccount.providers.mediawiki',
    'egaauth.socialaccount.providers.meetup',
    'egaauth.socialaccount.providers.miro',
    'egaauth.socialaccount.providers.microsoft',
    'egaauth.socialaccount.providers.naver',
    'egaauth.socialaccount.providers.nextcloud',
    'egaauth.socialaccount.providers.notion',
    'egaauth.socialaccount.providers.odnoklassniki',
    'egaauth.socialaccount.providers.openid',
    'egaauth.socialaccount.providers.openid_connect',
    'egaauth.socialaccount.providers.openstreetmap',
    'egaauth.socialaccount.providers.orcid',
    'egaauth.socialaccount.providers.patreon',
    'egaauth.socialaccount.providers.paypal',
    'egaauth.socialaccount.providers.persona',
    'egaauth.socialaccount.providers.pinterest',
    'egaauth.socialaccount.providers.pocket',
    "egaauth.socialaccount.providers.questrade",
    'egaauth.socialaccount.providers.quickbooks',
    'egaauth.socialaccount.providers.reddit',
    'egaauth.socialaccount.providers.robinhood',
    'egaauth.socialaccount.providers.salesforce',
    'egaauth.socialaccount.providers.sharefile',
    'egaauth.socialaccount.providers.shopify',
    'egaauth.socialaccount.providers.slack',
    'egaauth.socialaccount.providers.snapchat',
    'egaauth.socialaccount.providers.soundcloud',
    'egaauth.socialaccount.providers.spotify',
    'egaauth.socialaccount.providers.stackexchange',
    'egaauth.socialaccount.providers.steam',
    'egaauth.socialaccount.providers.stocktwits',
    'egaauth.socialaccount.providers.strava',
    'egaauth.socialaccount.providers.stripe',
    'egaauth.socialaccount.providers.telegram',
    'egaauth.socialaccount.providers.trainingpeaks',
    'egaauth.socialaccount.providers.trello',
    'egaauth.socialaccount.providers.tumblr',
    'egaauth.socialaccount.providers.tumblr_oauth2',
    'egaauth.socialaccount.providers.twentythreeandme',
    'egaauth.socialaccount.providers.twitch',
    'egaauth.socialaccount.providers.twitter',
    'egaauth.socialaccount.providers.twitter_oauth2',
    'egaauth.socialaccount.providers.untappd',
    'egaauth.socialaccount.providers.vimeo',
    'egaauth.socialaccount.providers.vimeo_oauth2',
    'egaauth.socialaccount.providers.vk',
    'egaauth.socialaccount.providers.wahoo',
    'egaauth.socialaccount.providers.weibo',
    'egaauth.socialaccount.providers.weixin',
    'egaauth.socialaccount.providers.windowslive',
    'egaauth.socialaccount.providers.xing',
    'egaauth.socialaccount.providers.yahoo',
    'egaauth.socialaccount.providers.yandex',
    'egaauth.socialaccount.providers.ynab',
    'egaauth.socialaccount.providers.zoho',
    'egaauth.socialaccount.providers.zoom',
    'egaauth.socialaccount.providers.okta',
    'egaauth.socialaccount.providers.feishu',
    "egaauth.socialaccount.providers.atlassian",
    ...
]

MIDDLEWARE = (
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",

    # Add the account middleware:
    "egaauth.account.middleware.AccountMiddleware",
)

# Provider specific settings
SOCIALACCOUNT_PROVIDERS = {
    'google': {
        # For each OAuth based provider, either add a ``SocialApp``
        # (``socialaccount`` app) containing the required client
        # credentials, or list them here:
        'APP': {
            'client_id': '123',
            'secret': '456',
            'key': ''
        }
    }
}

Additionally, add this to your project urls.py:

urlpatterns = [
    ...
    path('accounts/', include('egaauth.urls')),
    ...
]

Note that you do not necessarily need the URLs provided by django.contrib.auth.urls. Instead of the URLs login, logout, and password_change (among others), you can use the URLs provided by egaauth: account_login, account_logout, account_set_password...

Important: This project is not designed to work with SESSION_ENGINE set to "django.contrib.sessions.backends.signed_cookies". With signed cookies, the session data is signed but not encrypted, whereas egaauth stores secrets (e.g. verification codes) in the session.

Post-Installation

In your Django root execute the command below to create your database tables:

python manage.py migrate

Now start your server, visit your admin pages (e.g. http://localhost:8000/admin/) and follow these steps:

• For each OAuth based provider, either add a SocialApp (socialaccount app) containing the required client credentials, or, make sure that these are configured via the SOCIALACCOUNT_PROVIDERS[<provider>]['APP'] setting (see example above).

Example Projects

The source code repository contains fully functional example projects to help you get started.

Regular Django Project

The Regular Django project is a Bootstrap styled example project, which provides an example of how egaauth can be styled without altering any of the builtin templates. Please take a look at the templates of the example project. You can see this project running live over at django.demo.egaauth.org.

React Single-Page Application

The React example application demonstrates how the egaauth headless API can be put to use in practice. The documentation can be found in the README. Instructions on how to run it locally can be found there as well, though you can also view a copy running over at react.demo.egaauth.org.

Introduction

A regular account is a user account, identified by an email address or username, and protected by a password. The egaauth.account app is responsible for managing regular accounts. It supports:

• Authentication by username or email.
• Registration of new users, with custom signup form support.
• Email address management: both a simple change email address flow, and more elaborate flows with multiple email addresses (adding secondary, setting a primary) is supported.
• Password forgotten flow.
• Changing of the password.
• Email address verification flow.

Configuration

Overall

ACCOUNT_ADAPTER (default: "egaauth.account.adapter.DefaultAccountAdapter")

Specifies the adapter class to use, allowing you to alter certain default behaviour.

ACCOUNT_FORMS

Used to override the builtin forms. Defaults to:

ACCOUNT_FORMS = {
    'add_email': 'egaauth.account.forms.AddEmailForm',
    'change_password': 'egaauth.account.forms.ChangePasswordForm',
    'confirm_login_code': 'egaauth.account.forms.ConfirmLoginCodeForm',
    'login': 'egaauth.account.forms.LoginForm',
    'request_login_code': 'egaauth.account.forms.RequestLoginCodeForm',
    'reset_password': 'egaauth.account.forms.ResetPasswordForm',
    'reset_password_from_key': 'egaauth.account.forms.ResetPasswordKeyForm',
    'set_password': 'egaauth.account.forms.SetPasswordForm',
    'signup': 'egaauth.account.forms.SignupForm',
    'user_token': 'egaauth.account.forms.UserTokenForm',
}

ACCOUNT_PREVENT_ENUMERATION (default: True)

Controls whether or not information is revealed about whether or not a user account exists. For example, by entering random email addresses in the password reset form you can test whether or not those email addresses are associated with an account. Enabling this setting prevents that, and an email is always sent, regardless of whether or not the account exists. Note that there is a slight usability tax to pay because there is no immediate feedback.

Whether or not enumeration can be prevented during signup depends on the email verification method. In case of mandatory verification, enumeration can be properly prevented because the case where an email address is already taken is indistinguishable from the case where it is not. However, in case of optional or disabled email verification, enumeration can only be prevented by allowing the signup to go through, resulting in multiple accounts sharing same email address (although only one of the accounts can ever have it verified). When enumeration prevention is set to True, email address uniqueness takes precedence over enumeration prevention, and the issue of multiple accounts having the same email address will be avoided, thus leaking information. Set it to "strict" to allow for signups to go through.

ACCOUNT_RATE_LIMITS (default: {...})

In order to be secure out of the box various rate limits are in place. See Rate Limits for details.

ACCOUNT_SESSION_REMEMBER (default: None)

Controls the life time of the session. Set to None to ask the user ("Remember me?"), False to not remember, and True to always remember.

ACCOUNT_TEMPLATE_EXTENSION (default: "html")

A string defining the template extension to use, defaults to html.

Signup

ACCOUNT_SIGNUP_FIELDS (default: ['username*', 'email', 'password1*', 'password2*'])

The list of fields to complete in the signup form: username, email, phone, password1, password2.. Fields marked with an asterisk (e.g. 'username*') are required. To let the user type in their email address twice to avoid typos, you can add 'email2'. The field 'password2' can be used let the user type in their password twice to avoid typos.

ACCOUNT_SIGNUP_FORM_CLASS (default: None)

A string pointing to a custom form class (e.g. 'myapp.forms.SignupForm') that is used during signup to ask the user for additional input (e.g. a newsletter signup checkbox, or birth date). This class should derive from just forms.Form and only list the additional fields you need. It must implement a def signup(self, request, user) method, which is called during the signup process. This method allows you to handle and store the submitted data as needed.

ACCOUNT_SIGNUP_FORM_HONEYPOT_FIELD (default: None)

A string value that will be used as the HTML 'name' property on a honeypot input field on the sign up form. Honeypot fields are hidden to normal users but might be filled out by naive spam bots. When the field is filled out the app will not create a new user and attempt to fool the bot with a fake successful response. We recommend setting this to some believable value that your app does not actually collect on signup e.g. 'phone_number' or 'address'. Honeypots are not always successful for sophisticated bots so this should be used as one layer in a suite of spam detection tools if your site is having trouble with spam.

Login

ACCOUNT_LOGIN_BY_CODE_ENABLED (default: False)

"Login by email" offers an alternative method of logging in. Instead of entering an email address and accompanying password, the user only enters the email address. Then, a one-time code is sent to that email address which allows the user to login. This method is often referred to as "Magic Code Login". This setting controls whether or not this method of logging in is enabled.

ACCOUNT_LOGIN_BY_CODE_TRUST_ENABLED (default: False)

Indicates whether the MFA "Trust this browser?" functionality is to be enabled for logging in by code. Note that this requires the MFA app to be installed.

ACCOUNT_LOGIN_BY_CODE_MAX_ATTEMPTS (default: 3)

This setting controls the maximum number of attempts the user has at inputting a valid code.

ACCOUNT_LOGIN_BY_CODE_REQUIRED (default: False)

When enabled (in case of True), every user logging in is required to input a login confirmation code sent by email. Alternatively, you can specify a set of authentication methods ("password", "mfa", or "socialaccount") for which login codes are required.

ACCOUNT_LOGIN_BY_CODE_SUPPORTS_RESEND (default: False)

Whether or not the user can request a new login code.

ACCOUNT_LOGIN_BY_CODE_TIMEOUT (default: 180)

The code that is emailed has a limited life span. It expires this many seconds after which it was sent.

ACCOUNT_LOGIN_BY_CODE_FORMAT (default: settings.egaauth_USER_CODE_FORMAT)

Controls the format of the login code.

ACCOUNT_LOGIN_METHODS (default: {"username"}, options: "email" or "username")

Specifies the login method to use -- whether the user logs in by entering their username, email address, or either one of both. Note that the login methods need to align with ACCOUNT_SIGNUP_FIELDS, as specifying a login method that you cannot sign up with typically points to a configuration error.

ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION (default: False)

The default behavior is not log users in and to redirect them to ACCOUNT_EMAIL_CONFIRMATION_ANONYMOUS_REDIRECT_URL.

By changing this setting to True, users will automatically be logged in once they confirm their email address. Note however that this only works when confirming the email address immediately after signing up, assuming users didn't close their browser or used some sort of private browsing mode.

Note that this setting only affects email verification by link. It has no affect in case you turn on code based verification (ACCOUNT_EMAIL_VERIFICATION_BY_CODE_ENABLED).

ACCOUNT_LOGIN_ON_PASSWORD_RESET (default: False)

By changing this setting to True, users will automatically be logged in once they have reset their password. By default they are redirected to the password reset done page.

ACCOUNT_LOGIN_TIMEOUT (default: 900)

The maximum allowed time (in seconds) for a login to go through the various login stages. This limits, for example, the time span that the 2FA stage remains available.

Logout

ACCOUNT_LOGOUT_ON_GET (default: False)

Determines whether or not the user is automatically logged out by a GET request. GET is not designed to modify the server state, and in this case it can be dangerous. See LogoutView in the documentation for details.

ACCOUNT_LOGOUT_ON_PASSWORD_CHANGE (default: False)

Determines whether or not the user is automatically logged out after changing or setting their password. See documentation for Django's session invalidation on password change.

Password Reset

ACCOUNT_PASSWORD_INPUT_RENDER_VALUE (default: False)

render_value parameter as passed to PasswordInput fields.

ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED (default: False)

Controls whether password reset is performed by means of following a link in the email (False), or by entering a code (True).

ACCOUNT_PASSWORD_RESET_BY_CODE_FORMAT (default: settings.egaauth_USER_CODE_FORMAT)

Controls the format of the password reset code.

ACCOUNT_PASSWORD_RESET_BY_CODE_MAX_ATTEMPTS (default: 3)

This setting controls the maximum number of attempts the user has at inputting a valid code.

ACCOUNT_PASSWORD_RESET_BY_CODE_TIMEOUT (default: 180)

The code that is emailed has a limited life span. It expires this many seconds after which it was sent.

ACCOUNT_PASSWORD_RESET_TOKEN_GENERATOR (default: "egaauth.account.forms.EmailAwarePasswordResetTokenGenerator")

A string pointing to a custom token generator (e.g. 'myapp.auth.CustomTokenGenerator') for password resets. This class should implement the same methods as django.contrib.auth.tokens.PasswordResetTokenGenerator or subclass it.

Email Verification

ACCOUNT_CONFIRM_EMAIL_ON_GET (default: False)

Determines whether or not an email address is automatically confirmed by a GET request. GET is not designed to modify the server state, though it is commonly used for email confirmation. To avoid requiring user interaction, consider using POST via Javascript in your email confirmation template as an alternative to setting this to True.

ACCOUNT_EMAIL_CONFIRMATION_HMAC (default: True)

In order to verify an email address, a key is mailed identifying the email address to be verified. In previous versions, a record was stored in the database for each ongoing email confirmation, keeping track of these keys. Current versions use HMAC based keys that do not require server side state.

ACCOUNT_EMAIL_CONFIRMATION_EXPIRE_DAYS (default: 3)

Determines the expiration date of email confirmation mails (# of days).

ACCOUNT_EMAIL_VERIFICATION (default: "optional")

Determines the email verification method during signup -- choose one of "mandatory", "optional", or "none".

When set to "mandatory" the user is blocked from logging in until the email address is verified. Choose "optional" or "none" to allow logins with an unverified email address. In case of "optional", the email verification mail is still sent, whereas in case of "none" no email verification mails are sent.

Setting this to "mandatory" requires "email*" to be listed in ACCOUNT_SIGNUP_FIELDS.

ACCOUNT_EMAIL_VERIFICATION_BY_CODE_ENABLED (default: False)

Controls whether email verification is performed by means of following a link in the email (False), or by entering a code (True).

ACCOUNT_EMAIL_VERIFICATION_BY_CODE_FORMAT (default: settings.egaauth_USER_CODE_FORMAT)

Controls the format of the email verification code.

ACCOUNT_EMAIL_VERIFICATION_BY_CODE_MAX_ATTEMPTS (default: 3)

This setting controls the maximum number of attempts the user has at inputting a valid code.

ACCOUNT_EMAIL_VERIFICATION_BY_CODE_TIMEOUT (default: 900)

The code that is emailed has a limited life span. It expires this many seconds after which it was sent.

ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_CHANGE (default: False)

Whether or not the email can be changed after signup at the email verification stage.

Warning: If enumeration prevention is turned on, no account is created when a user signs up using an already existing email. If the user then were able to change to a new email address that is not taken, we would have to create an account as we did not do so yet. Currently, this is not implemented. Changing email address in this scenario is simply not allowed, and therefore, a user paying close attention can deduce that an account already exists. This will be revisited in a future release.

ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_RESEND (default: False)

Whether or not the user can request a new email verification code.

Reauthentication

ACCOUNT_REAUTHENTICATION_TIMEOUT (default: 300)

Before asking the user to reauthenticate, we check if a successful (re)authentication happened within the amount of seconds specified here, and if that is the case, the new reauthentication flow is silently skipped.

ACCOUNT_REAUTHENTICATION_REQUIRED (default: False)

Specifies whether or not reauthentication is required before the user can alter his account.

Routing

ACCOUNT_AUTHENTICATED_LOGIN_REDIRECTS (default: True)

The default behaviour is to redirect authenticated users to LOGIN_REDIRECT_URL when they try accessing login/signup pages.

By changing this setting to False, logged in users will not be redirected when they access login/signup pages.

ACCOUNT_EMAIL_CONFIRMATION_ANONYMOUS_REDIRECT_URL (default: settings.LOGIN_URL)

The URL to redirect to after a successful email confirmation, in case no user is logged in.

ACCOUNT_EMAIL_CONFIRMATION_AUTHENTICATED_REDIRECT_URL (default: None)

The URL to redirect to after a successful email confirmation, in case of an authenticated user. Set to None to use settings.LOGIN_REDIRECT_URL.

ACCOUNT_LOGOUT_REDIRECT_URL (default: settings.LOGOUT_REDIRECT_URL or "/")

The URL (or URL name) to return to after the user logs out. Defaults to Django's LOGOUT_REDIRECT_URL, unless that is empty, then "/" is used.

ACCOUNT_SIGNUP_REDIRECT_URL (default: settings.LOGIN_REDIRECT_URL)

The URL (or URL name) to redirect to directly after signing up. Note that users are only redirected to this URL if the signup went through uninterruptedly, for example, without any side steps due to email verification. If your project requires the user to always pass through certain onboarding views after signup, you will have to keep track of state indicating whether or not the user successfully onboarded, and handle accordingly.

Sending Email

ACCOUNT_EMAIL_SUBJECT_PREFIX (default: "[Site] ")

Subject-line prefix to use for email messages sent. By default, the name of the current Site (django.contrib.sites) is used.

ACCOUNT_EMAIL_UNKNOWN_ACCOUNTS (default: True)

Configures whether password reset attempts for email addresses which do not have an account result in sending an email.

ACCOUNT_EMAIL_NOTIFICATIONS (default: False)

When enabled, account related security notifications, such as "Your password was changed", including information on user agent / IP address from where the change originated, will be emailed.

Email Addresses

ACCOUNT_CHANGE_EMAIL (default: False)

When disabled (False), users can add one or more email addresses (up to a maximum of ACCOUNT_MAX_EMAIL_ADDRESSES) to their account and freely manage those email addresses. When enabled (True), users are limited to having exactly one email address that they can change by adding a temporary second email address that, when verified, replaces the current email address.

ACCOUNT_EMAIL_MAX_LENGTH (default: 254)

Maximum length of the email field. You won't need to alter this unless using MySQL with the InnoDB storage engine and the utf8mb4 charset, and only in versions lower than 5.7.7, because the default InnoDB settings don't allow indexes bigger than 767 bytes. When using utf8mb4, characters are 4-bytes wide, so at maximum column indexes can be 191 characters long (767/4). Unfortunately Django doesn't allow specifying index lengths, so the solution is to reduce the length in characters of indexed text fields. More information can be found at MySQL's documentation on converting between 3-byte and 4-byte Unicode character sets.

ACCOUNT_MAX_EMAIL_ADDRESSES (default: None)

The maximum amount of email addresses a user can associate to his account. It is safe to change this setting for an already running project -- it will not negatively affect users that already exceed the allowed amount. Note that if you set the maximum to 1, users will not be able to change their email address.

ACCOUNT_UNIQUE_EMAIL (default: True)

Enforce uniqueness of email addresses. On the database level, this implies that only one user account can have an email address marked as verified. Forms prevent a user from registering with or adding an additional email address if that email address is in use by another account.

User Model

ACCOUNT_PRESERVE_USERNAME_CASING (default: True)

This setting determines whether the username is stored in lowercase (False) or whether its casing is to be preserved (True). Note that when casing is preserved, potentially expensive __iexact lookups are performed when filter on username. For now, the default is set to True to maintain backwards compatibility.

ACCOUNT_USERNAME_BLACKLIST (default: [])

A list of usernames that can't be used by user.

ACCOUNT_USER_DISPLAY (default: a callable returning user.username)

A callable (or string of the form 'some.module.callable_name') that takes a user as its only argument and returns the display name of the user. The default implementation returns user.username.

ACCOUNT_USER_MODEL_EMAIL_FIELD (default: "email")

The name of the field containing the email, if any. See custom user models.

ACCOUNT_USER_MODEL_USERNAME_FIELD (default: "username")

The name of the field containing the username, if any. See custom user models.

ACCOUNT_USERNAME_MIN_LENGTH (default: 1)

An integer specifying the minimum allowed length of a username.

ACCOUNT_USERNAME_VALIDATORS (default: None)

A path ('some.module.validators.custom_username_validators') to a list of custom username validators. If left unset, the validators setup within the user model username field are used.

Example:

# In validators.py

from django.contrib.auth.validators import ASCIIUsernameValidator

custom_username_validators = [ASCIIUsernameValidator()]

# In settings.py

ACCOUNT_USERNAME_VALIDATORS = 'some.module.validators.custom_username_validators'

Rate Limits

In this section the ratelimits related to the egaauth.account app are documented. Refer to the overall rate limit documentation for more background information on the mechanism itself.

The rate limits are configured through the ACCOUNT_RATE_LIMITS setting:

• Set it to False to disable all rate limits.
• Set it to a dictionary, e.g. {"action": "your-rate-limit", ...} to use the default configuration but with your specific actions overriden.

The following actions are available for configuration:

"change_password" (default: "5/m/user")

Changing the password (for already authenticated users).

"change_phone" (default: "1/m/user")

Changing the phone number.

"manage_email" (default: "10/m/user")

Email management related actions, such as add, remove, change primary.

"reset_password" (default: "20/m/ip,5/m/key")

Requesting a password reset. The email for which the password is to be reset is passed as the key.

"reauthenticate" (default: "10/m/user")

Reauthentication (for users already logged in).

"reset_password_from_key" (default: "20/m/ip")

Password reset (the view the password reset email links to).

"signup" (default: "20/m/ip")

Signups.

"login" (default: "30/m/ip")

Logins.

"login_failed" (default: "10/m/ip,5/5m/key")

Restricts the allowed number of failed login attempts. When exceeded, the user is prohibited from logging in for the remainder of the rate limit. Important: while this protects the egaauth login view, it does not protect Django's admin login from being brute forced.

"confirm_email" (default: "1/3m/key" (link) or "1/10s/key" (code))

Users can request email confirmation mails via the email management view, and, implicitly, when logging in with an unverified account. This rate limit prevents users from sending too many of these mails.

Views

Login

URL name:

account_login

Users login via the egaauth.account.views.LoginView view over at /accounts/login/ (URL name account_login). When users attempt to login while their account is inactive (user.is_active) they are presented with the account/account_inactive.html template.

Signup

URL name:

account_signup

Users sign up via the egaauth.account.views.SignupView view over at /accounts/signup/ (URL name account_signup).

Logout

URL name:

account_logout

The logout view (egaauth.account.views.LogoutView) over at /accounts/logout/ (URL name account_logout) requests for confirmation before logging out. The user is logged out only when the confirmation is received by means of a POST request.

If you are wondering why, consider what happens when a malicious user embeds the following image in a post:

<img src="http://example.com/accounts/logout/">

For this and more background information on the subject, see:

• https://code.djangoproject.com/ticket/15619
• http://stackoverflow.com/questions/3521290/logout-get-or-post

If you insist on having logout on GET, then please consider adding a bit of Javascript to automatically turn a click on a logout link into a POST. As a last resort, you can set ACCOUNT_LOGOUT_ON_GET to True.

Password Management

Authenticated users can manage their password account using the egaauth.account.views.PasswordSetView and egaauth.account.views.PasswordChangeView views, over at /accounts/password/set/ respectively /accounts/password/change/ (URL names account_set_password and account_change_password respectively).

Users are redirected between these views, according to whether or not they have setup a password (user.has_usable_password()). Typically, when users signup via a social provider they will not have a password set.

Password Reset

URL name:

account_reset_password

Users can request a password reset using the egaauth.account.views.PasswordResetView view over at /accounts/password/reset/ (URL name account_reset_password). An email will be sent containing a reset link pointing to PasswordResetFromKeyView view.

Emails Management

URL name:

account_email

Users manage the email addresses tied to their account using the egaauth.account.views.EmailView view over at /accounts/email/ (URL name account_email). Here, users can add (and verify) email addresses, remove email addresses, and choose a new primary email address.

Email Verification

Depending on the setting ACCOUNT_EMAIL_VERIFICATION, a verification email is sent pointing to the egaauth.account.views.ConfirmEmailView view.

The setting ACCOUNT_CONFIRM_EMAIL_ON_GET determines whether users have to manually confirm the address by submitting a confirmation form, or whether the address is automatically confirmed by a mere GET request.

Template Tags

Use user_display to render a user name without making assumptions on how the user is represented (e.g. render the username, or first name?):

{% load account %}

{% user_display user %}

Or, if you need to use in a {% blocktrans %}:

{% load account %}

{% user_display user as user_display %}
{% blocktrans %}{{ user_display }} has logged in...{% endblocktrans %}

Then, override the ACCOUNT_USER_DISPLAY setting with your project specific user display callable.

If you set ACCOUNT_USERNAME_REQUIRED = False and ACCOUNT_USER_MODEL_USERNAME_FIELD = None, then you can simply display the user.email with {{ user }}:

In case you forgot, your username is {{ user }}.

Forms

Login

Path:

egaauth.account.forms.LoginForm

Used on:

account_login view.

Example override:

from egaauth.account.forms import LoginForm
class MyCustomLoginForm(LoginForm):

    def login(self, *args, **kwargs):

        # Add your own processing here.

        # You must return the original result.
        return super().login(*args, **kwargs)

You have access to the following:

• self.user is the User object that is logging in.

settings.py:

ACCOUNT_FORMS = {'login': 'mysite.forms.MyCustomLoginForm'}

By default, the password field renders a "Forgot your password?" link as the help text. By providing a "account/password_reset_help_text.html" template you can customize that text.

Signup

Path:

egaauth.account.forms.SignupForm

Used on:

account_signup view.

Example override:

from egaauth.account.forms import SignupForm
class MyCustomSignupForm(SignupForm):

    def save(self, request):

        # Ensure you call the parent class's save.
        # .save() returns a User object.
        user = super().save(request)

        # Add your own processing here.

        # You must return the original result.
        return user

settings.py:

ACCOUNT_FORMS = {'signup': 'mysite.forms.MyCustomSignupForm'}

Add Email

Path:

egaauth.account.forms.AddEmailForm

Used on:

account_email view.

Example override:

from egaauth.account.forms import AddEmailForm
class MyCustomAddEmailForm(AddEmailForm):

    def save(self, request):

        # Ensure you call the parent class's save.
        # .save() returns an egaauth.account.models.EmailAddress object.
        email_address_obj = super().save(request)

        # Add your own processing here.

        # You must return the original result.
        return email_address_obj

You have access to the following:

• self.user is the User object that is logged in.

settings.py:

ACCOUNT_FORMS = {'add_email': 'mysite.forms.MyCustomAddEmailForm'}

Change Password

Path:

egaauth.account.forms.ChangePasswordForm

Used on:

account_change_password view.

Example override:

from egaauth.account.forms import ChangePasswordForm
class MyCustomChangePasswordForm(ChangePasswordForm):

    def save(self):

        # Ensure you call the parent class's save.
        # .save() does not return anything
        super().save()

        # Add your own processing here.

You have access to the following:

• self.user is the User object that is logged in.

settings.py:

ACCOUNT_FORMS = {'change_password': 'mysite.forms.MyCustomChangePasswordForm'}

Set Password

Path:

egaauth.account.forms.SetPasswordForm

Used on:

account_set_password view.

Example override:

from egaauth.account.forms import SetPasswordForm
class MyCustomSetPasswordForm(SetPasswordForm):

    def save(self):

        # Ensure you call the parent class's save.
        # .save() does not return anything
        super().save()

        # Add your own processing here.

You have access to the following:

• self.user is the User object that is logged in.

settings.py:

ACCOUNT_FORMS = {'set_password': 'mysite.forms.MyCustomSetPasswordForm'}

Reset Password

Path:

egaauth.account.forms.ResetPasswordForm

Used on:

account_reset_password view.

Example override:

from egaauth.account.forms import ResetPasswordForm
class MyCustomResetPasswordForm(ResetPasswordForm):

    def save(self, request):

        # Ensure you call the parent class's save.
        # .save() returns a string containing the email address supplied
        email_address = super().save(request)

        # Add your own processing here.

        # Ensure you return the original result
        return email_address

You have access to the following:

• self.users is a list of all possible User objects with matching email address.

settings.py:

ACCOUNT_FORMS = {'reset_password': 'mysite.forms.MyCustomResetPasswordForm'}

Reset Password From Key

Path:

egaauth.account.forms.ResetPasswordKeyForm

Used on:

account_reset_password view.

Example override:

from egaauth.account.forms import ResetPasswordKeyForm
class MyCustomResetPasswordKeyForm(ResetPasswordKeyForm):

    def save(self):

        # Add your own processing here.

        # Ensure you call the parent class's save.
        # .save() does not return anything
        super().save()

You have access to the following:

• self.user is the User object.

settings.py:

ACCOUNT_FORMS = {'reset_password_from_key': 'mysite.forms.MyCustomResetPasswordKeyForm'}

Decorators

Verified Email Required

Even when email verification is not mandatory during signup, there may be circumstances during which you really want to prevent unverified users from proceeding. For this purpose you can use the following decorator:

from egaauth.account.decorators import verified_email_required

@verified_email_required
def verified_users_only_view(request):
    ...

The behavior is as follows:

• If the user isn't logged in, it acts identically to the login_required decorator.
• If the user is logged in but has no verified email address, an email verification mail is automatically resent and the user is presented with a page informing them they need to verify their email address.

Signals

There are several signals emitted during authentication flows. You can hook to them for your own needs.

• egaauth.account.signals.authentication_step_completed(request, user, method, **kwargs)

  Sent when an authentication step was completed. Note that this does not imply that the user is fully signed in. For example, consider a case where a user authenticates using a password, but still needs to complete the 2FA challenge.

• egaauth.account.signals.user_logged_in(request, user)

  Sent when a user logs in.

• egaauth.account.signals.user_logged_out(request, user)

  Sent when a user logs out.

• egaauth.account.signals.user_signed_up(request, user)

  Sent when a user signs up for an account. This signal is typically followed by a user_logged_in, unless email verification prohibits the user to log in.

• egaauth.account.signals.password_set(request, user)

  Sent when a password has been successfully set for the first time.

• egaauth.account.signals.password_changed(request, user)

  Sent when a password has been successfully changed.

• egaauth.account.signals.password_reset(request, user)

  Sent when a password has been successfully reset.

• egaauth.account.signals.email_confirmed(request, email_address)

  Sent after the email address in the db was updated and set to confirmed.

• egaauth.account.signals.email_confirmation_sent(request, confirmation, signup)

  Sent right after the email confirmation is sent.

• egaauth.account.signals.email_changed(request, user, from_email_address, to_email_address)

  Sent when a primary email address has been changed.

• egaauth.account.signals.email_added(request, user, email_address)

  Sent when a new email address has been added.

• egaauth.account.signals.email_removed(request, user, email_address)

  Sent when an email address has been deleted.

Email

Case Sensitivity

Historically, email addresses started out as case sensitive because the local part (the part before the "@") could represent a case sensitive user name. However, over time, this proved to be a bad idea and the RFCs that succeeded the original were adjusted to move away from treating email addresses as case sensitive.

• RFC 821: The original RFC from 1982 relies on case sensitivity.

• RFC 2821: Released in 2001, obsoletes RFC 821, yet, is still case sensitive.

• RFC 5321: In 2008, the "Local-part" is weakened to "MAY be case-sensitive".

• RFC 6530: In 2012, the following is acknowledged:

  It has long been the case that the email syntax permits choices about mailbox names that are unwise in practice [...]. The most often cited examples involve the use of case-sensitivity [...] in mailbox local parts. These deliberately unusual constructions are permitted by the protocols, and servers are expected to support them. Although they can provide value in special cases, taking advantage of them is almost always bad practice unless the intent is to create some form of security by obscurity.

To deal with this, previous versions of django-egaauth used to store email addresses in their original case, while performing lookups in a case insensitive style. This approach led to subtle bugs in upstream code, and also comes at a performance cost (__iexact lookups). The latter requires case insensitive index support, which not all databases support. Re-evaluating the approach in current times has led to the conclusion that the benefits do not outweigh the costs. Therefore, email addresses are now always stored as lower case.

Phone

Installation

In addition to following the overall instructions, pay attention to the following in the settings.py of your project:

# Make sure that the login methods includes "phone" as a method.
ACCOUNT_LOGIN_METHODS = {"phone", "email"}

# Add a required phone field to the signup fields.
# ACCOUNT_SIGNUP_FIELDS = [
  'phone*',
  'email*'  # Can be left out if you want to only use 'phone'.
]

# You will need to provide methods for storing phone numbers, and
# sending SMS messages in a custom adapter.
ACCOUNT_ADAPTER = 'project.users.adapter.MyAccountAdapter'

Configuration

Available settings:

ACCOUNT_PHONE_VERIFICATION_ENABLED (default: True)

Whether or not mandatory verification of phone numbers during login/signup takes place.

ACCOUNT_PHONE_VERIFICATION_MAX_ATTEMPTS (default: 3)

This setting controls the maximum number of attempts the user has at inputting a valid code.

ACCOUNT_PHONE_VERIFICATION_TIMEOUT (default: 900)

The code that is sent has a limited life span. It expires this many seconds after which it was sent.

ACCOUNT_PHONE_VERIFICATION_SUPPORTS_CHANGE (default: False)

Whether or not the phone number can be changed after signup at the phone number verification stage.

Warning: the warning related to enumeration prevent over at

ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_CHANGE holds here as well.

ACCOUNT_PHONE_VERIFICATION_SUPPORTS_RESEND (default: False)

Whether or not the user can request a new phone number verification code.

ACCOUNT_PHONE_VERIFICATION_CODE_FORMAT (default: settings.egaauth_USER_CODE_FORMAT)

Controls the format of the verification code.

Form Fields

For presenting a phone number form field to the user a basic <input type="tel"> field is used that requires input in E164 format. There are various external projects that offer more elaborate phone number input fields. You can switch over to using the fields provided by those projects, or, tweak the phone number validaton logic, by overriding the following adapter methods:

Database Models

Out of the box, there are no models provided intended to store the phone numbers of users. It is up to the developer to decide where phone numbers are to be stored, for example, on a custom user model, or, on a separate Phone model of its own. Once those the models are setup, the following adapter methods need to be populated so that the models will be used:

egaauth.account.adapter.DefaultAccountAdapter

get_phone

set_phone

set_phone_verified

get_user_by_phone

Sending SMS Messages

For sending SMS messages, various external providers and packages are available. You can integrate those by overriding the following adapter method:

egaauth.account.adapter.DefaultAccountAdapter

send_verification_code_sms

send_unknown_account_sms

Turnkey Phone Authentication

egaauth.contrib.phone turns the existing phone-auth extension points into a reusable packaged setup with a bundled phone model, admin integration, health checks, and optional external verification-provider support.

Installation

Add the app and adapter:

INSTALLED_APPS += [
    "egaauth.contrib.phone",
]

ACCOUNT_ADAPTER = "egaauth.contrib.phone.adapter.PhoneAccountAdapter"
ACCOUNT_LOGIN_METHODS = {"email", "phone"}
ACCOUNT_SIGNUP_FIELDS = ["phone*", "email", "password1*"]

For local development, the default provider is console and verification codes are logged server-side while verification remains handled by egaauth's existing code flow.

Twilio Verify

To delegate verification-code checking to Twilio Verify:

EGAAUTH_PHONE_PROVIDER = "twilio_verify"
EGAAUTH_PHONE_TWILIO_ACCOUNT_SID = "..."
EGAAUTH_PHONE_TWILIO_AUTH_TOKEN = "..."
EGAAUTH_PHONE_TWILIO_VERIFY_SERVICE_SID = "VA..."
EGAAUTH_PHONE_DEFAULT_CHANNEL = "sms"

When using twilio_verify, the library starts the verification through Twilio and also validates the submitted code through Twilio instead of solely relying on the locally generated session code.

What it provides

• PhoneCredential model storing one primary phone number per user.
• PhoneAccountAdapter implementing set_phone(), get_phone(), set_phone_verified(), get_user_by_phone() and SMS delivery.
• System checks for common configuration mistakes.
• Management commands:
  • python manage.py egaauth_phone_check
  • python manage.py egaauth_phone_test +15551234567

Enumeration-prevention messages

By default, enumeration-prevention SMS messages are logged/no-op because many projects prefer not to send separate informational messages for unknown or already-registered numbers. If desired:

EGAAUTH_PHONE_SEND_ENUMERATION_PREVENTION_SMS = True

Adapter

Advanced Usage

Custom User Models

If you use a custom user model you need to specify what field represents the username, if any. Here, username really refers to the field representing the nickname that the user uses to login, and not to some unique identifier (possibly including an email address) as is the case for Django's AbstractBaseUser.USERNAME_FIELD.

Therefore, if your custom user model does not have a username field (again, not to be mistaken with an email address or user id), you will need to set ACCOUNT_USER_MODEL_USERNAME_FIELD to None. This will disable username related functionality in egaauth. Remember to also remove username from ACCOUNT_SIGNUP_FIELDS as by default that is present.

Similarly, you will need to set ACCOUNT_USER_MODEL_EMAIL_FIELD to None or to the proper field (if other than email).

For example, if you want to use a custom user model that has email as the identifying field, and you don't want to collect usernames, you need the following in your settings.py:

ACCOUNT_USER_MODEL_USERNAME_FIELD = None
ACCOUNT_SIGNUP_FIELDS = ['email*', 'password1*', 'password2*']
ACCOUNT_LOGIN_METHODS = {'email'}

Creating and Populating User instances

The following adapter methods can be used to intervene in how User instances are created and populated with data

• egaauth.account.adapter.DefaultAccountAdapter:
  • is_open_for_signup(self, request): The default function returns True. You can override this method by returning False if you want to disable account signup.
  • new_user(self, request): Instantiates a new, empty User.
  • save_user(self, request, user, form): Populates and saves the User instance using information provided in the signup form.
  • populate_username(self, request, user): Fills in a valid username, if required and missing. If the username is already present, then it is assumed to be valid (unique).
  • confirm_email(self, request, email_address): Marks the email address as confirmed and saves to the db.
  • generate_unique_username(self, txts, regex=None): Returns a unique username from the combination of strings present in txts iterable. A regex pattern can be passed to the method to make sure the generated username matches it.

Invitations

Invitation handling is not supported, and most likely will not be any time soon. An invitation app could cover anything ranging from invitations of new users, to invitations of existing users to participate in restricted parts of the site. All in all, the scope of invitation handling is large enough to warrant being addressed in an app of its own.

Still, everything is in place to easily hook up any third party invitation app. The account adapter (egaauth.account.adapter.DefaultAccountAdapter) offers the following methods:

• is_open_for_signup(self, request). You can override this method to, for example, inspect the session to check if an invitation was accepted.
• stash_verified_email(self, request, email). If an invitation was accepted by following a link in an email, then there is no need to send email verification mails after the signup is completed. Use this method to record the fact that an email address was verified.

Custom Redirects

If redirecting to statically configurable URLs (as specified in your project settings) is not flexible enough, then you can override the following adapter methods:

• egaauth.account.adapter.DefaultAccountAdapter:
  • get_login_redirect_url(self, request)
  • get_logout_redirect_url(self, request)
  • get_email_verification_redirect_url(self, email_address)
  • get_signup_redirect_url(self, request)

For example, redirecting to /accounts/<username>/ can be implemented as follows:

# project/settings.py:
ACCOUNT_ADAPTER = 'project.users.adapter.MyAccountAdapter'

# project/users/adapter.py:
from django.conf import settings
from egaauth.account.adapter import DefaultAccountAdapter

class MyAccountAdapter(DefaultAccountAdapter):

    def get_login_redirect_url(self, request):
        path = "/accounts/{username}/"
        return path.format(username=request.user.username)

Introduction

A third-party ("social") account is a user account where authentication is delegated to an external identity provider. The egaauth.socialaccount app is responsible for managing social accounts. It supports:

• Connecting one or more social accounts to a local/regular account
• Disconnecting a social account -- requires setting a password if only the local account remains
• Optional instant-signup for social accounts -- no questions asked

Note that in order to use this functionality you need to install the socialaccount extras of the django-egaauth package:

pip install "django-egaauth[socialaccount]"

Configuration

Available settings:

SOCIALACCOUNT_ADAPTER (default: "egaauth.socialaccount.adapter.DefaultSocialAccountAdapter")

Specifies the adapter class to use, allowing you to alter certain default behaviour.

SOCIALACCOUNT_AUTO_SIGNUP (default: True)

Attempt to bypass the signup form by using fields (e.g. username, email) retrieved from the social account provider. If a conflict arises due to a duplicate email address the signup form will still kick in.

SOCIALACCOUNT_EMAIL_AUTHENTICATION (default: False)

Consider a scenario where a social login occurs, and the social account comes with a verified email address (verified by the account provider), but that email address is already taken by a local user account. Additionally, assume that the local user account does not have any social account connected. Now, if the provider can be fully trusted, you can argue that we should treat this scenario as a login to the existing local user account even if the local account does not already have the social account connected, because --according to the provider -- the user logging in has ownership of the email address. This is how this scenario is handled when SOCIALACCOUNT_EMAIL_AUTHENTICATION is set to True. As this implies that an untrustworthy provider can login to any local account by fabricating social account data, this setting defaults to False. Only set it to True if you are using providers that can be fully trusted. Instead of turning this on globally, you can also turn it on selectively per provider, for example:

SOCIALACCOUNT_PROVIDERS = {
  'google': {
      'EMAIL_AUTHENTICATION': True
  }
}

SOCIALACCOUNT_EMAIL_AUTHENTICATION_AUTO_CONNECT (default: False)

In case email authentication is applied, this setting controls whether or not the social account is automatically connected to the local account. In case of False the local account remains unchanged during the login. In case of True, the social account for which the email matched, is automatically added to the list of social accounts connected to the local account. As a result, even if the user were to change the email address afterwards, social login would still be possible when using True, but not in case of False.

SOCIALACCOUNT_EMAIL_VERIFICATION (default: ACCOUNT_EMAIL_VERIFICATION)

As ACCOUNT_EMAIL_VERIFICATION, but for social accounts.

SOCIALACCOUNT_EMAIL_REQUIRED (default: "email*" in ACCOUNT_SIGNUP_FIELDS)

The user is required to hand over an email address when signing up using a social account.

SOCIALACCOUNT_FORMS

Used to override forms. Defaults to:

SOCIALACCOUNT_FORMS = {
    'disconnect': 'egaauth.socialaccount.forms.DisconnectForm',
    'signup': 'egaauth.socialaccount.forms.SignupForm',
}

SOCIALACCOUNT_LOGIN_ON_GET (default: False)

Controls whether or not the endpoints for initiating a social login (for example, "/accounts/google/login/") require a POST request to initiate the handshake. For security considerations, it is strongly recommended to require POST requests.

SOCIALACCOUNT_PROVIDERS (default: {})

Dictionary containing provider specific settings.

SOCIALACCOUNT_REQUESTS_TIMEOUT (default: 5)

The timeout applied when performing upstream requests.

SOCIALACCOUNT_QUERY_EMAIL (default: "email*" in ACCOUNT_SIGNUP_FIELDS)

Request email address from 3rd party account provider? E.g. using OpenID AX, or the Facebook "email" permission.

SOCIALACCOUNT_SOCIALACCOUNT_STR (default: str of user object)

Used to override the str value for the SocialAccount model.

Must be a function accepting a single parameter for the socialaccount object.

SOCIALACCOUNT_STORE_TOKENS (default: False)

Indicates whether or not the access tokens are stored in the database. Note that tokens can only be stored if the related social account is stored as well, which is not the case when you are using SOCIALACCOUNT_EMAIL_AUTHENTICATION without SOCIALACCOUNT_EMAIL_AUTHENTICATION_AUTO_CONNECT.

SOCIALACCOUNT_ONLY (default: False)

When enabled (True), all functionality with regard to local accounts is disabled, and users will only be able to authenticate using third-party providers.

SOCIALACCOUNT_OPENID_CONNECT_URL_PREFIX (default: "oidc")

The URL path prefix that is used for all OpenID Connect providers. By default, it is set to "oidc", meaning, an OpenID Connect provider with provider ID foo uses /accounts/oidc/foo/login/ as its login URL.

Provider Configuration

Providers typically require various configuration parameters before your users can authenticate with them. For example, for a regular OAuth provider you first need to setup an OAuth app over on the provider developer portal. Then, you need to configure the resulting client ID and client secret in your application.

Even though providers with other protocols may use different terminology, the overall idea remains the same. Throughout egaauth the term "social app" ("app" for short) refers to the unit of configuration of a provider. You provide the app configuration either in your project settings.py, or, by means of setting up SocialApp instances via the Django admin. When picking a method, consider the following:

• Using the Django admin to setup SocialApp instances effectively stores secrets in your database, which has security implications.
• The SocialApp approach has (optional) support for the Django sites (django.contrib.sites). For example, it allows you to setup multiple apps for one and the same provider, and assign an app to a specific site/domain. This may be of use in a multi tenant setup.

Important: While you can mix both methods, be aware you need to avoid configuring one and the same provider both via settings.py and a SocialApp instance. In that case, it is not clear what app to pick, resulting in a MultipleObjectsReturned exception.

The examples presented in this documentation are all settings based. If you prefer the SocialApp based approach, simply create an entry via the Django admin and populate the fields exactly like listed in the example.

The SOCIALACCOUNT_PROVIDERS setting is used to configure providers and their apps. Next to the secrets that are configured per app, there are also parameters such as VERIFIED_EMAIL that hold for all apps. The following is an example configuration:

SOCIALACCOUNT_PROVIDERS = {
    "github": {
        # For each provider, you can choose whether or not the
        # email address(es) retrieved from the provider are to be
        # interpreted as verified.
        "VERIFIED_EMAIL": True
    },
    "google": {
        # For each OAuth based provider, either add a ``SocialApp``
        # (``socialaccount`` app) containing the required client
        # credentials, or list them here:
        "APPS": [
            {
                "client_id": "123",
                "secret": "456",
                "key": "",
                "settings": {
                    # You can fine tune these settings per app:
                    "scope": [
                        "profile",
                        "email",
                    ],
                    "auth_params": {
                        "access_type": "online",
                    },
                },
            },
        ],
        # The following provider-specific settings will be used for all apps:
        "SCOPE": [
            "profile",
            "email",
        ],
        "AUTH_PARAMS": {
            "access_type": "online",
        },
    }
}

Note that provider-specific settings are documented for each provider separately.

Views

Social Connections

URL name:

socialaccount_connections

The egaauth.socialaccount.views.ConnectionsView view over at /accounts/social/connections/ (URL name socialaccount_connections) allows users to manage the social accounts tied to their local account.

Template Tags

Use the provider_login_url tag to generate provider specific login URLs:

{% load socialaccount %}

<a href="{% provider_login_url "openid" openid="https://www.google.com/accounts/o8/id" next="/success/url/" %}">Google</a>
<a href="{% provider_login_url "twitter" %}">Twitter</a>

Here, you can pass along an optional process parameter that indicates how to process the social login. You can choose between login and connect:

<a href="{% provider_login_url "twitter" process="connect" %}">Connect a Twitter account</a>

Furthermore, you can pass along an action parameter with value reauthenticate to indicate that you want the user to be re-prompted for authentication even if they already signed in before. For now, this is supported by Facebook, Google, Twitter, and Discord only.

For Javascript based logins (e.g. when you enable the Facebook JS SDK), you will need to make sure that the required Javascript is loaded. The following tag loads all scripts for the enabled providers:

{% providers_media_js %}

For easy access to the social accounts for a user use:

{% get_social_accounts user as accounts %}

Then:

{{accounts.twitter}} -- a list of connected Twitter accounts
{{accounts.twitter.0}} -- the first Twitter account
{% if accounts %} -- if there is at least one social account

Finally, social authentication providers configured for the current site can be retrieved via:

{% get_providers as socialaccount_providers %}

Which will populate the socialaccount_providers variable in the template context with a list of configured social authentication providers. This supersedes the context processor used in version 0.21 and below.

Forms

Signup

Path:

egaauth.socialaccount.forms.SignupForm

Used on:

socialaccount_signup view used when a user initially signs up with a social account and needs to create an account.

Example override:

from egaauth.socialaccount.forms import SignupForm
class MyCustomSocialSignupForm(SignupForm):

    def save(self, request):

        # Ensure you call the parent class's save.
        # .save() returns a User object.
        user = super().save(request)

        # Add your own processing here.

        # You must return the original result.
        return user

You have access to the following:

• self.socialaccount

settings.py:

SOCIALACCOUNT_FORMS = {'signup': 'mysite.forms.MyCustomSocialSignupForm'}

Disconnect

Path:

egaauth.socialaccount.forms.DisconnectForm

Used on:

socialaccount_connections view, used when removing a social account.

Example override:

from egaauth.socialaccount.forms import DisconnectForm
class MyCustomSocialDisconnectForm(DisconnectForm):

    def save(self):

        # Add your own processing here if you do need access to the
        # socialaccount being deleted.

        # Ensure you call the parent class's save.
        # .save() does not return anything
        super().save()

        # Add your own processing here if you don't need access to the
        # socialaccount being deleted.

You have access to the following:

• self.request is the request object
• self.accounts is a list containing all of the user's SocialAccount objects.
• self.cleaned_data['account'] contains the socialaccount being deleted. .save() issues the delete. So if you need access to the socialaccount beforehand, move your code before .save().

settings.py:

SOCIALACCOUNT_FORMS = {'disconnect': 'mysite.forms.MyCustomSocialDisconnectForm'}

Signals

There are several signals emitted during authentication flows. You can hook to them for your own needs.

• egaauth.socialaccount.signals.pre_social_login(request, sociallogin)

  Sent after a user successfully authenticates via a social provider, but before the login is fully processed. This signal is emitted as part of the social login and/or signup process, as well as when connecting additional social accounts to an existing account. Access tokens and profile information, if applicable for the provider, is provided.

• egaauth.socialaccount.signals.social_account_added(request, sociallogin)

  Sent after a user connects a social account to their local account. This is an explicit action and does not get called for the creation of a socialaccount.

• egaauth.socialaccount.signals.social_account_updated(request, sociallogin)

  Sent after a social account has been updated. This happens when a user logs in using an already connected social account, or completes a connect flow for an already connected social account. Useful if you need to unpack extra data for social accounts as they are updated.

• egaauth.socialaccount.signals.social_account_removed(request, socialaccount)

  Sent after a user disconnects a social account from their local account.

Providers

Introduction

Most providers require you to sign up for a so called API client or app, containing a client ID and API secret. You must add a SocialApp record per provider via the Django admin containing these app credentials.

When creating the OAuth app on the side of the provider pay special attention to the callback URL (sometimes also referred to as redirect URL). If you do not configure this correctly, you will receive login failures when attempting to log in, such as:

An error occurred while attempting to login via your social network account.

Use a callback URL of the form:

http://example.com/accounts/twitter/login/callback/
http://example.com/accounts/soundcloud/login/callback/
...

For local development, use the following:

http://127.0.0.1:8000/accounts/twitter/login/callback/

Protocol Specifics

Provider Specifics

Adapter

Advanced Usage

Creating and Populating User instances

The following adapter methods can be used to intervene in how User instances are created and populated with data

• egaauth.socialaccount.adapter.DefaultSocialAccountAdapter:
  • is_open_for_signup(self, request, socialaccount): The default function returns that is the same as ACCOUNT_ADAPTER in settings.py. You can override this method by returning True/False if you want to enable/disable socialaccount signup.
  • new_user(self, request, sociallogin): Instantiates a new, empty User.
  • save_user(self, request, sociallogin, form=None): Populates and saves the User instance (and related social login data). The signup form is not available in case of auto signup.
  • populate_user(self, request, sociallogin, data): Hook that can be used to further populate the user instance (sociallogin.account.user). Here, data is a dictionary of common user properties (first_name, last_name, email, username, name) that the provider already extracted for you.

Custom Redirects

If redirecting to statically configurable URLs (as specified in your project settings) is not flexible enough, then you can override the following adapter methods:

• egaauth.socialaccount.adapter.DefaultSocialAccountAdapter:
  • get_connect_redirect_url(self, request, socialaccount)

Customizing providers

When an existing provider doesn't quite meet your needs, you might find yourself needing to customize a provider.

This can be achieved by subclassing an existing provider and making your changes there. Providers are defined as django applications, so typically customizing one will mean creating a django application in your project. This application will contain your customized urls.py, views.py and provider.py files. The behaviour that can be customized is beyond the scope of this documentation.

class GoogleNoDefaultScopeProvider(GoogleProvider):
    id = 'google_no_scope'

    def get_default_scope(self):
        return []

provider_classes = [GoogleNoDefaultScopeProvider]

Changing provider scopes

Some projects may need more scopes than the default required for authentication purposes.

Scopes can be modified via SOCIALACCOUNT_PROVIDERS in your project settings.py file.

SOCIALACCOUNT_PROVIDERS = {
    '<ProviderNameHere>': {
        'SCOPE': [...]
    }
}

You need to obtain the default scopes that egaauth uses by looking in egaauth/socialaccount/providers/<ProviderNameHere>/provider.py and look for def get_default_scope(self): method. Copy those default scopes into the SCOPE list shown above.

Example of adding calendar.readonly scope to Google scopes:

SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'SCOPE': [
            'profile',
            'email',
            'openid',
            'https://www.googleapis.com/auth/calendar.readonly'
        ],
    }
}

Introduction

The egaauth.mfa app contains all functionality related to Multi-Factor Authentication. It supports:

• TOTP based authentication.
• Authentication by recovery codes.
• Viewing, downloading and regenerating recovery codes.
• WebAuthn based credentials.
• Login using passkeys.

Note that in order to use this functionality you need to install the mfa extras of the django-egaauth package:

pip install "django-egaauth[mfa]"

Remember to add the app to the settings.py of your project:

INSTALLED_APPS = [
    ...
    # The required `egaauth` apps...
    'egaauth',
    'egaauth.account',

    # The MFA app:
    'egaauth.mfa',
    ...
]

Note that WebAuthn support is disabled by default.

Configuration

Available settings:

MFA_ADAPTER (default: "egaauth.mfa.adapter.DefaultMFAAdapter")

Specifies the adapter class to use, allowing you to alter certain default behavior.

MFA_ALLOW_UNVERIFIED_EMAIL (default: False)

By default, an account that has an unverified email address is not allowed to turn on MFA. Additionally, accounts that have MFA turned on cannot add a new (unverified) email address. The rationale is that if this were allowed, it would allow an attacker to signup without verifying and then turn on MFA to prevent the real owner of the account from ever gaining access. If the risk of this scenario is manageable for your project, you can allow unverified email address in combination with MFA by changing this setting.

MFA_FORMS

Used to override forms. Defaults to:

MFA_FORMS = {
    'authenticate': 'egaauth.mfa.base.forms.AuthenticateForm',
    'reauthenticate': 'egaauth.mfa.base.forms.AuthenticateForm',
    'activate_totp': 'egaauth.mfa.totp.forms.ActivateTOTPForm',
    'deactivate_totp': 'egaauth.mfa.totp.forms.DeactivateTOTPForm',
    'generate_recovery_codes': 'egaauth.mfa.recovery_codes.forms.GenerateRecoveryCodesForm',
}

MFA_PASSKEY_LOGIN_ENABLED (default: False)

Whether or not end users can login using a (WebAuthn) passkey. Note that for this to be enabled, you also need to add "webauthn" to MFA_SUPPORTED_TYPES.

MFA_PASSKEY_SIGNUP_ENABLED (default: False)

Whether or not end users can signup using a (WebAuthn) passkey. Note that for this to be enabled, you need to add "webauthn" to MFA_SUPPORTED_TYPES, require mandatory email verification and have ACCOUNT_EMAIL_VERIFICATION_BY_CODE_ENABLED set to True.

MFA_RECOVERY_CODE_COUNT (default: 10)

The number of recovery codes.

MFA_RECOVERY_CODE_DIGITS (default: 8)

The number of digits of each recovery code.

MFA_SUPPORTED_TYPES (default: [["recovery_codes", "totp"])

The authenticator types that end users are able to setup. Allowed types are: "recovery_codes", "totp", and "webauthn". The latter is disabled by default.

MFA_TOTP_PERIOD (default: 30)

The period that a TOTP code will be valid for, in seconds.

MFA_TOTP_TOLERANCE (default: 0)

The number of time steps in the past or future to allow. Lower values are more secure, but more likely to fail due to clock drift.

MFA_TOTP_DIGITS (default: 6)

The number of digits for TOTP codes.

MFA_TOTP_ISSUER (default: "")

The issuer (appearing in the TOTP QR code).

MFA_WEBAUTHN_ALLOW_INSECURE_ORIGIN (default: False)

The WebAuthn uses the fido2 package, and versions up to including version 1.1.3 do not regard localhost as a secure origin, which is problematic during local development and testing. To work around that, you can use this setting. Only use this for development, never on production. See commit 8b979313 over at fido2.

MFA_TRUST_ENABLED (default: False)

Enables the "Trust this browser?" functionality, which presents users with MFA enabled the choice to trust their browser allowing them to skip authenticating per MFA on each login. This is implemented by handing out a special trust cookie.

MFA_TRUST_COOKIE_AGE (default: timedelta(days=14))

Specifies the period (in seconds, or timedelta) during which MFA is skipped.

MFA_TRUST_COOKIE_NAME (default: "mfa_trusted")

The name of the trust cookie.

MFA_TRUST_COOKIE_DOMAIN (default: settings.SESSION_COOKIE_DOMAIN)

The domain of the trust cookie.

MFA_TRUST_COOKIE_HTTPONLY (default: settings.SESSION_COOKIE_HTTPONLY)

Whether or not the trust cookie is HTTP only.

MFA_TRUST_COOKIE_PATH (default: settings.SESSION_COOKIE_PATH)

The path set on the trust cookie.

MFA_TRUST_COOKIE_SAMESITE (default: settings.SESSION_COOKIE_SAMESITE)

The value of the SameSite flag on the trust cookie.

MFA_TRUST_COOKIE_SECURE (default: settings.SESSION_COOKIE_SECURE)

Whether to use a secure cookie for the trust cookie.

Forms

(Re)authenticate

Path

egaauth.mfa.base.forms.AuthenticateForm egaauth.mfa.base.forms.ReauthenticateForm egaauth.mfa.webauthn.forms.AuthenticateWebAuthnForm

Used on:

AuthenticateView and ReauthenticateView, used when a user authenticates with MFA.

Example override:

from egaauth.mfa.base.forms import AuthenticateForm, ReauthenticateForm
from egaauth.mfa.webauthn.forms import AuthenticateWebAuthnForm


class MyCustomAuthenticateForm(AuthenticateForm):
    pass


class MyCustomReauthenticateForm(ReauthenticateForm):
    pass


class MyCustomAuthenticateWebAuthnForm(AuthenticateWebAuthnForm):
    pass

settings.py:

MFA_FORMS = {
    'authenticate': 'mysite.forms.MyCustomAuthenticateForm',
    'reauthenticate': 'mysite.forms.MyCustomReauthenticateForm',
    'authenticate_webauthn': 'mysite.forms.MyCustomAuthenticateWebAuthnForm',
}

Activate TOTP

Path

egaauth.mfa.totp.forms.ActivateTOTPForm

Used on:

ActivateTOTPView, used when a user activates TOTP.

Example override:

from egaauth.mfa.totp.forms import ActivateTOTPForm
class MyCustomActivateTOTPForm(ActivateTOTPForm):
  pass

settings.py:

MFA_FORMS = {
    'activate_totp': 'mysite.forms.MyCustomActivateTOTPForm',
}

Deactivate TOTP

Path

egaauth.mfa.totp.forms.DeactivateTOTPForm

Used on:

DeactivateTOTPView, used when a user deactivates TOTP.

Example override:

from egaauth.mfa.totp.forms import DeactivateTOTPForm
class MyCustomDeactivateTOTPForm(DeactivateTOTPForm):
  pass

settings.py:

MFA_FORMS = {
    'deactivate_totp': 'mysite.forms.MyCustomDeactivateTOTPForm',
}

Generate Recovery Codes

Path

egaauth.mfa.recovery_codes.forms.GenerateRecoveryCodesForm

Used on:

GenerateRecoveryCodesView, used when a user generates recovery codes.

Example override:

from egaauth.mfa.recovery_codes.forms import GenerateRecoveryCodesForm
class MyCustomGenerateRecoveryCodesForm(GenerateRecoveryCodesForm):
  pass

settings.py:

MFA_FORMS = {
    'generate_recovery_codes': 'mysite.forms.MyCustomGenerateRecoveryCodesForm',
}

Adapter

Encrypted MFA Adapter

egaauth.contrib.mfa.adapter.EncryptedMFAAdapter encrypts stored TOTP secrets using Fernet/MultiFernet.

Configuration

MFA_ADAPTER = "egaauth.contrib.mfa.adapter.EncryptedMFAAdapter"

Optional key rotation:

EGAAUTH_MFA_FERNET_KEYS = [
    "base64-urlsafe-fernet-key-1",
    "base64-urlsafe-fernet-key-2",
]

If explicit keys are not supplied, a deterministic Fernet key is derived from SECRET_KEY so projects get encrypted-at-rest storage by default.

WebAuthn

WebAuthn support is disabled by default. To enable it, add these settings:

# Make sure "webauthn" is included.
MFA_SUPPORTED_TYPES = ["totp", "webauthn", "recovery_codes"]

# Optional: enable support for logging in using a (WebAuthn) passkey.
MFA_PASSKEY_LOGIN_ENABLED = True

# Optional -- use for local development only: the WebAuthn uses the
#``fido2`` package, and versions up to including version 1.1.3 do not
# regard localhost as a secure origin, which is problematic during
# local development and testing.
MFA_WEBAUTHN_ALLOW_INSECURE_ORIGIN = True

# Add "humanize" contrib app if using default templates
INSTALLED_APPS = [
    ...
    "django.contrib.humanize",
]

Upgrading from django-egaauth-2fa

In case you are currently using django-egaauth-2fa and want to switch to the built-in implementation, you will need to migrate the existing TOTP keys and recovery codes. For that purpose, the following reference code is available:

import base64

from egaauth.mfa.adapter import get_adapter
from egaauth.mfa.models import Authenticator
from django.core.management.base import BaseCommand
from django_otp.plugins.otp_static.models import StaticDevice
from django_otp.plugins.otp_totp.models import TOTPDevice


class Command(BaseCommand):
    def handle(self, **options):
        adapter = get_adapter()
        authenticators = []
        for totp in TOTPDevice.objects.filter(confirmed=True).iterator():
            recovery_codes = set()
            for sdevice in StaticDevice.objects.filter(confirmed=True, user_id=totp.user_id).iterator():
                recovery_codes.update(sdevice.token_set.values_list("token", flat=True))
            secret = base64.b32encode(bytes.fromhex(totp.key)).decode("ascii")
            totp_authenticator = Authenticator(
                user_id=totp.user_id,
                type=Authenticator.Type.TOTP,
                data={"secret": adapter.encrypt(secret)},
            )
            authenticators.append(totp_authenticator)
            authenticators.append(
                Authenticator(
                    user_id=totp.user_id,
                    type=Authenticator.Type.RECOVERY_CODES,
                    data={
                        "migrated_codes": [adapter.encrypt(c) for c in recovery_codes],
                    },
                )
            )
        Authenticator.objects.bulk_create(authenticators)

Introduction

The purpose of the optional egaauth.usersessions app is to keep track of (authenticated) user sessions, allowing users to view a list of all their active sessions, as well as offering a means to end these sessions.

Installation

On top of the standard installation, add the following:

INSTALLED_APPS = [
    ...
    'django.contrib.humanize',
    'egaauth.usersessions',
    ...
]

MIDDLEWARE = [
    ...
    # Optional -- needed when: USERSESSIONS_TRACK_ACTIVITY = True
    'egaauth.usersessions.middleware.UserSessionsMiddleware',
    ...
]

Configuration

Available settings:

USERSESSIONS_ADAPTER (default: "egaauth.usersessions.adapter.DefaultUserSessionsAdapter")

Specifies the adapter class to use, allowing you to alter certain default behaviour.

USERSESSIONS_TRACK_ACTIVITY (default: False)

Whether or not user sessions are kept updated. User sessions are created at login time, but as the user continues to access the site the IP address might change. Enabling this setting makes sure that the session is kept track of, meaning, the IP address, user agent and last seen timestamp are all kept up to date. Requires egaauth.usersessions.middleware.UserSessionsMiddleware to be installed.

Signals

The following signal is emitted while handling user sessiond.

• egaauth.usersessions.signals.session_client_changed(request, from_session, to_session)

  This signal is emitted when the IP or user agent changes during the lifetime of a user session. Note that it only fires when USERSESSIONS_TRACK_ACTIVITY is turned on.

Adapter

Introduction

Support for single-page and mobile applications is offered by the egaauth.headless app. Note that you still need to have e.g. the egaauth.account app installed for this to work, yet, you can completely disable its views using settings.HEADLESS_ONLY = True.

Installation

In order to use the headless functionality you need to install the headless extra as follows:

pip install "django-egaauth[headless]"

In your settings.py, include:

INSTALLED_APPS = [
    ...

    # Required
    'egaauth',
    'egaauth.account',
    'egaauth.headless',

    # Optional
    'egaauth.socialaccount',
    'egaauth.mfa',
    'egaauth.usersessions',

    ...
]

# These are the URLs to be implemented by your single-page application.
HEADLESS_FRONTEND_URLS = {
    "account_confirm_email": "https://app.project.org/account/verify-email/{key}",
    "account_reset_password_from_key": "https://app.org/account/password/reset/key/{key}",
    "account_signup": "https://app.org/account/signup",
}

Your project urls.py should include:

urlpatterns = [
    # Even when using headless, the third-party provider endpoints are stil
    # needed for handling e.g. the OAuth handshake. The account views
    # can be disabled using `HEADLESS_ONLY = True`.
    path("accounts/", include("egaauth.urls")),

    # Include the API endpoints:
    path("_egaauth/", include("egaauth.headless.urls")),
]

Configuration

Available settings:

HEADLESS_ADAPTER (default: "egaauth.headless.adapter.DefaultHeadlessAdapter")

Specifies the adapter class to use, allowing you to alter certain default behavior.

HEADLESS_CLIENTS (default: ("app", "browser"))

Specifies the supported types of clients for the API. Setting this to e.g. ("app",) will remove all "browser" related endpoints.

HEADLESS_FRONTEND_URLS (default: {})

Email confirmation and password reset mails contain links that by default point to the views from the egaauth.account app. In case you need to point these to your own frontend application, you can do so by configuring this setting, as follows:

HEADLESS_FRONTEND_URLS = {
    "account_confirm_email": "https://app.project.org/account/verify-email/{key}",
    # Key placeholders are automatically populated. You are free to adjust this
    # to your own needs, e.g.
    #
    # "https://app.project.org/account/email/verify-email?token={key}",
    "account_reset_password": "https://app.project.org/account/password/reset",
    "account_reset_password_from_key": "https://app.project.org/account/password/reset/key/{key}",
    "account_signup": "https://app.project.org/account/signup",
    # Fallback in case the state containing the `next` URL is lost and the handshake
    # with the third-party provider fails.
    "socialaccount_login_error": "https://app.project.org/account/provider/callback",
}

HEADLESS_ONLY (default: False)

You can use headless-only mode in case your application fully takes care of the frontend, and you do not want for e.g. the login and signup views to be accessible. In this case, including egaauth.urls skips those views, yet, still includes e.g. the provider callback views.

HEADLESS_SERVE_SPECIFICATION (default: False)

Whether or not to serve the OpenAPI specification files. When enabled, the endpoints /_egaauth/openapi.yaml, /_egaauth/openapi.json and /_egaauth/openapi.html become available. This functionality requires the extra django-egaauth[headless-spec] to be installed.

HEADLESS_SPECIFICATION_TEMPLATE_NAME (default: "headless/spec/redoc_cdn.html")

The template used to serve the OpenAPI specification in HTML format. Out of the box, Redoc ("headless/spec/redoc_cdn.html") and Swagger ( ("headless/spec/swagger_cdn.html") are available.

HEADLESS_TOKEN_STRATEGY (default: "egaauth.headless.tokens.strategies.sessions.SessionTokenStrategy")

If you need to change the way tokens are created and handled, you can plug in your own ./tokens.

API

OpenAPI Specification

You can find the documentation for the API itself in its OpenAPI Specification.

Example

The source code repository contains a React example application that demonstrates how the API can be put to use in practice. The documentation for that application can be found in the README. Instructions on how to run it locally can be found there as well, though you can also view a copy running over at react.demo.egaauth.org.

Cross-Origin Resource Sharing (CORS)

In case your project requires CORS handling, the following configuration can be used as a starting point:

MIDDLEWARE = (
    ...
    "corsheaders.middleware.CorsMiddleware",
    ...
)

INSTALLED_APPS = (
    ...
    "corsheaders",
    ...
)

CORS_ALLOWED_ORIGINS = [
    "https://app.project.org",
]

from corsheaders.defaults import default_headers

CORS_ALLOW_HEADERS = (
    *default_headers,
    "x-session-token",
    "x-email-verification-key",
    "x-password-reset-key",
)
CORS_ALLOW_CREDENTIALS = True

Adapter

Token Strategies

Frequently Asked Questions

My signup requires additional inputs, is that supported?

Yes, though an important thing to keep in mind is that there is no one-to-one mapping of headed forms to headless input payloads. For example, while having to enter your password twice makes sense in a headed environment, it is pointless from an API point of view. As a result, the headed forms that can be overridden by means of ACCOUNT_FORMS play no role in the headless environment.

Instead of overriding the complete signup form via ACCOUNT_FORMS, provide a ACCOUNT_SIGNUP_FORM_CLASS as documented here , listing the additional fields you need. These fields will automatically show up in the headed signup form, and will automatically be validated when posting payloads to the signup endpoint.

OpenID Connect

Configuration

Available settings:

egaauth_DEFAULT_AUTO_FIELD

Can be set to configure the primary key of all models. For example: "hashid_field.HashidAutoField".

egaauth_USER_CODE_FORMAT (default: {"numeric": False, "dashed": True, length: 8})

Controls the format of user-facing verification codes (e.g. email verification, phone verification, login codes).

Sending Email

Emails sent (e.g. in case of password forgotten or email confirmation) can be altered by providing your own templates. Templates are named as follows:

account/email/email_confirmation_signup_subject.txt
account/email/email_confirmation_signup_message.txt

account/email/email_confirmation_subject.txt
account/email/email_confirmation_message.txt

In case you want to include an HTML representation, add an HTML template as follows:

account/email/email_confirmation_signup_message.html

account/email/email_confirmation_message.html

The project does not contain any HTML email templates out of the box. When you do provide these yourself, note that both the text and HTML versions of the message are sent.

If this does not suit your needs, you can hook up your own custom mechanism by overriding the send_mail method of the account adapter (egaauth.account.adapter.DefaultAccountAdapter).

Templates

Introduction

The templates that are offered out of the box are intentionally plain and without any styling. We do not want to pick a side in the multitudes of frontend styling options out there, and the look and feel typically should be adjusted to match the branding of your project. Therefore it is recommended that you copy all templates over to your own project and adjust them as you see fit.

Having said that, with features such as third party account providers and two-factor authentication, adjusting the templates involves a lot more than just styling a login.html and a signup.html template. Therefore, a mechanism is included that allows you to adjust the look and feel of all templates by only overriding a few core templates. This approach allows you to achieve visual results fast, but is of course more limited compared to styling all templates yourself.

Overriding the Built-In Templates

The egaauth app includes all templates, and can be found in the egaauth/templates directory. When egaauth is part of your INSTALLED_APPS, and "APP_DIRS": True is configured, Django will be able to find its templates. As DIRS is searched before APP_DIRS, overriding the templates involves adding an entry to DIRS that points to your a project specific template folder, as follows:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            BASE_DIR / "templates"
        ],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

If you copy over all templates to your BASE_DIR / "templates" it should contain these entries (a.o.):

• An account folder containing the templates from the egaauth.account app.
• A socialaccount folder containing the templates from the egaauth.socialaccount app.
• A mfa folder containing the templates from the egaauth.mfa app.
• An egaauth folder containing the overall styling templates (see the next section).

Styling the Existing Templates

Instead of copying all templates, a mechanism is included that allows you to adjust the look and feel of all templates by only overriding a few core templates. This approach allows you to achieve visual results fast, but is of course more limited compared to styling all templates yourself.

Layouts

The existing templates use two base page layouts:

• The entrance layout: These are all pages where the user is in the process of authenticating, such as the login and signup pages.
• The account management layout: The pages where an authenticated user can manage the account, such as changing the email address or password.

You can alter these layouts by providing these templates in your own project:

Elements

When rendering e.g. a Bootstrap button you would typically use:

<button class="btn btn-primary">Okay</button>

Yet, when a different CSS framework is used other class names apply, and possibly even other markup. Therefore, the built-in templates do not include the above content directly. Instead of referring to tags such <button>, <h1> or <form> directly, the templates render those elements using a special element `templatetag`:

{% load egaauth %}
{% element h1 tags="foo,bar" %}Welcome{% endelement %}

Under the hood, this templatetag renders the egaauth/elements/h1.html template, which out of the box contains this:

{% load egaauth %}<h1>{% slot %}{% endslot %}</h1>

If you want to change the styling of all headings across all pages, you can do so by overriding that egaauth/elements/h1.html template, as follows:

{% load egaauth %}
<div class="myproject-h1 aa-{{ origin|slugify }}"
     style="font-size: {% if "foo" in attrs.tags %}3{% else %}5{% endif %}rem">
    {% slot %}{% endslot %}
</div>

Of course, the above is a bit of a contrived example. In each of the element templates the {{ origin }} context variable is available, which is equal to the base template name where the element is used (e.g. account/login for elements used from within the account/login.html template).

Slots may also be named. In that case, the element will be invoked like:

{% load egaauth %}
{% element form method="post" action=action_url %}
    {% slot body %}
        ...
    {% endslot %}
    {% slot actions %}
        ...
    {% endslot %}
{% endelement %}

When overriding an element with named slots, they may be injected in any order. For example, with egaauth/elements/form.html:

{% load egaauth %}
<form method="{{ attrs.method }}" action="{{ attrs.action }}">
    {% slot body %}
    {% endslot %}
    <hr>
    {% slot actions %}
    {% endslot %}
</form>

The following elements are available -- override them as you see fit for your project:

Example

The source repository contains a Bootstrap styled example project, which provides a good example of how all of the above can be put together to provide styling without altering any of the content templates. Please take a look at the templates of the example project. You can see those templates live in the running demo project.

Messages

The Django messages framework (django.contrib.messages) is used if it is listed in settings.INSTALLED_APPS. All messages (as in django.contrib.messages) are configurable by overriding their respective template. If you want to disable a message, simply override the message template with a blank one.

Admin

The Django admin site (django.contrib.admin) does not use Django egaauth by default. Since Django admin provides a custom login view, it does not go through the normal Django egaauth workflow.

An easy workaround for this is to require users to login before going to the Django admin site's login page, by adding this to urls.py (note that the following would need to be applied to every instance of AdminSite):

from django.contrib import admin
from egaauth.account.decorators import secure_admin_login

admin.autodiscover()
admin.site.login = secure_admin_login(admin.site.login)

Rate Limits

In order to be secure out of the box various rate limits are in place. The rate limit mechanism is backed by a Django cache. Hence, rate limiting will not work properly if you are using the DummyCache.

When rate limits are hit the 429.html template is rendered, alternatively, you can configure a custom handler by declaring a handler429 view in your root URLconf.

Rate limits are consumed by triggering actions, the full list of which is documented below. Per action, the rate can be configured. The rate itself is an amount, per time unit, per either IP address, user or action-specific key.

For example, requesting a password reset is an action that is both limited globally by IP address, as well as per email. Here, the email address used is the specific key.

Configuration

egaauth_TRUSTED_PROXY_COUNT (default: 0)

As the X-Forwarded-For header can be spoofed, you need to configure the number of proxies that are under your control and hence, can be trusted. The default is 0, meaning, no proxies are trusted. As a result, the X-Forwarded-For header will be disregarded by default.

egaauth_TRUSTED_CLIENT_IP_HEADER (default: None)

If your service is running behind a trusted proxy that sets a custom header containing the client IP address, specify that header name here. The client IP will be extracted from this header instead of X-Forwarded-For. Examples: "CF-Connecting-IP" (Cloudflare), "X-Real-IP" (nginx).

Implementation Notes

The builtin rate limitting relies on a cache and uses non-atomic operations, making it vulnerable to race conditions. As a result, users may occasionally bypass the intended rate limit due to concurrent access. However, such race conditions are rare in practice. For example, if the limit is set to 10 requests per minute and a large number of parallel processes attempt to test that limit, you may occasionally observe slight overruns—such as 11 or 12 requests slipping through. Nevertheless, exceeding the limit by a large margin is highly unlikely due to the low probability of many processes entering the critical non-atomic code section simultaneously.

Testing

Unless the rate limit is disabled or the default limits are increased, you might run intro problems if you're running unit tests that are dependant on funcionalities covered by the rate limits. For example, if you're testing the confirm_email functionality in your unit tests and you're testing if the verification email is sent twice after requesting it twice, only one of the emails will be sent.

Commercial Support

Commercial support is available. If you find certain functionality missing, or require assistance on your project(s), please contact us: info@intenct.nl.

Funding

Maintaining a project of this nature to align with the latest standards and expectations demands a significant investment of time and effort. If you are using this project, especially in a commercial context, then please do consider sponsoring.

Contributing

Thank you for considering contributing to django-egaauth! This document outlines the process for contributing to the project and sets up your development environment.

Code of Conduct

In the interest of fostering an open and welcoming community, we as contributors and maintainers pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Getting Started

Setting Up Your Development Environment

There are two primary ways to set up your development environment:

Option 1: Standard Python Virtual Environment (Recommended for Beginners)

1. Install system dependencies

   Before creating a virtual environment, you'll need to install some system dependencies:

   On macOS:

   # Using Homebrew
   brew install libxml2 libxmlsec1 pkg-config openssl

   On Ubuntu/Debian:

   sudo apt-get install libxml2-dev libxmlsec1-dev libxmlsec1-openssl pkg-config

   On RHEL/CentOS/Fedora:

   sudo dnf install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel

2. Create and activate a virtual environment

   # Create a virtual environment
   python -m venv virtualenv
   
   # Activate it
   # On Windows:
   virtualenv\Scripts\activate
   # On macOS/Linux:
   source virtualenv/bin/activate

3. Install django-egaauth in development mode

   # Install development dependencies
   pip install -r requirements-dev.txt

Option 2: Using devenv/Nix (Recommended for Advanced Users)

If you prefer a more isolated and reproducible development environment, you can use Nix-based devenv:

1. Install devenv (If you don't have it already)

   Follow the official installation instructions.

2. Activate the developer environment

   # This will create an isolated environment with all required dependencies
   devenv shell

   Note: The first time you run this command, it may take a significant amount of time as it builds all dependencies. Subsequent launches will be much faster.

Running Tests

django-egaauth uses a comprehensive test suite. You can run tests in several ways:

Using pytest directly

# Run all tests for the default setup
pytest egaauth/

# Run tests with a specific Django settings module
pytest --ds=tests.projects.regular.settings tests/

# Run a specific test file
pytest tests/apps/account/test_login.py

Note, if you are using MacOS, using pip and get this error when run tests:

import xmlsec
ImportError: dlopen( ...  symbol not found in flat namespace '_xmlSecOpenSSLTransformHmacRipemd160GetKlass')

You can try:

pip uninstall xmlsec lxml
pip install --no-binary :all: xmlsec
# Ref: https://github.com/xmlsec/python-xmlsec/issues/320

Using nox (recommended)

Nox automates testing across different Python and Django versions:

# List all available sessions
nox --list

# Run tests for a specific Python version
nox -x --session "test-3.11"

# Run tests for specific environment
nox -x --session "test-3.11" --python 3.11 -- --ds=tests.projects.regular.settings tests/apps/account/test_login.py

Run Code Quality Checks

# Run all linting checks
nox -t lint

# Run specific check
nox --session black
nox --session isort
nox --session flake8
nox --session bandit
nox --session djlint

Building Documentation

Documentation is built using Sphinx:

# Build the documentation
nox --session docs

The built documentation will be available in the docs/_build/html directory.

Development Workflow

1. Create a new branch for your feature or bugfix

   git checkout -b feature/your-feature-name

2. Make your changes and add tests

   All new features should include proper tests.

3. Run tests locally to ensure everything passes

   nox -x --session "test-3.11"

4. Run code quality checks

   nox -t lint

5. Commit your changes with meaningful commit messages

6. Submit a pull request to the main repository

Pull Request Guidelines

• Update documentation for significant changes
• Add tests for new functionality
• Ensure all tests pass
• Follow the project's code style
• Keep pull requests focused on a single topic
• Write clear, descriptive commit messages

Additional Resources

• Official Documentation
• Issue Tracker
• Project Source

Thank you for your contributions!

65.15.1 (2026-04-02)

Fixes

• The context data for the various entrance views was inconsistent, e.g. some where missing site or login_url. Ensured all entrance views are now handed over the same base context.
• MFA: accessing the WebAuthn login view while already being authenticated resulted in a 500, fixed.
• OAuth 1.0: Fixed an argument call order issue when performing requests.

65.15.0 (2026-03-09)

Note worthy changes

• All user facing codes (e.g. those that the user needs to manually input over at password reset, email/phone verification, login code, OIDC device codes) now follow the recommendations over at RFC 8628, Section 6.1. It uses dashed codes, such as "WDJB-MJHT", by default. You can control the format of all codes via a new setting egaauth_USER_CODE_FORMAT, or, adjust the format per use case via one of ACCOUNT_LOGIN_BY_CODE_FORMAT, ACCOUNT_PHONE_VERIFICATION_CODE_FORMAT, ACCOUNT_PASSWORD_RESET_BY_CODE_FORMAT, ACCOUNT_EMAIL_VERIFICATION_BY_CODE_FORMAT, IDP_OIDC_USER_CODE_FORMAT`.
• Added optional support for requesting new login codes. See ACCOUNT_LOGIN_BY_CODE_SUPPORTS_RESEND.