Django
Sign in through OAuth in a Django app with django-allauth, locally and in CI, with any of the eight providers Mockatoo mocks.
There is no connector package for Django. You don't need one: each allauth provider reads its endpoints from an adapter class, so a small subclass that points those endpoints at the mock does the connector's job.
Example on GitHub: mockatoo/examples/allauth-django.
How it works
- Your sign-in button posts to allauth's
/accounts/<provider>/login/, which redirects to the mock on the provider's real paths:accounts.google.com/o/oauth2/v2/authbecomesapp.mockatoo.globalunderdog.com/google/o/oauth2/v2/auth. - You (or a test) fill in the login page and click Authorize.
- The mock redirects back to
/accounts/<provider>/login/callback/. Allauth exchanges the code for provider-shaped tokens, reads the profile or the signed ID token, and signs the Django user in, as it would in production.
Your providers, scopes and templates don't change. Only the client credentials and the provider classes do, and only when the mock is on.
Prerequisites
- Python 3.12, with
Djangoanddjango-allauth[socialaccount](pyproject.toml). - A Mockatoo test account. Sign up at app.mockatoo.globalunderdog.com, then copy the email and password from the dashboard.
Point the providers at the mock
provider_adapters.py
subclasses each allauth adapter with the mock's URLs, and each provider to use
that adapter:
from allauth.socialaccount.providers.google.provider import GoogleProviderfrom allauth.socialaccount.providers.google.views import GoogleOAuth2Adapterfrom django.conf import settingsclass MockGoogleAdapter(GoogleOAuth2Adapter): base_url = f"{settings.MOCK_ORIGIN}/google" authorize_url = f"{base_url}/o/oauth2/v2/auth" access_token_url = f"{base_url}/token" identity_url = f"{base_url}/v1/userinfo"class MockGoogleProvider(GoogleProvider): package = GoogleProvider.get_package() oauth2_adapter_class = MockGoogleAdapterGitHub, Discord, Facebook, Apple and X follow the same pattern. Copy all of
them from provider_adapters.py.
providers.py
builds SOCIALACCOUNT_PROVIDERS. A single switch picks the shared client and
the mock classes:
use_mock = os.getenv("MOCKATOO_FORCE") == "true"SOCIALACCOUNT_PROVIDERS = { "google": { "SCOPE": ["profile", "email"], "OAUTH_PKCE_ENABLED": True, "APPS": [{ "client_id": "mockatoo" if use_mock else os.getenv("GOOGLE_CLIENT_ID"), "secret": "mockatoo-secret" if use_mock else os.getenv("GOOGLE_CLIENT_SECRET"), }], # Only with the mock on: "provider_class": "example.provider_adapters.MockGoogleProvider", }, # …the other providers}mockatoo/mockatoo-secretis the shared client. It accepts anyhttp(s)callback, so localhost and preview URLs need no provider setup.provider_classswaps the class allauth uses to build the login URL. Set it only when the mock is on, so production keeps allauth's own providers.- Allauth signs in to LinkedIn through its generic OpenID Connect provider,
so the example registers LinkedIn as an
openid_connectapp. The mock subclass changes itsserver_url, and allauth reads the endpoints and signing keys from the mock's discovery document. - The example's committed
.envsetsMOCKATOO_FORCE=trueso its demo works. In your app, turn the mock on only outside production. Never ship it.
Already use allauth with real providers? Keep your settings, and in development or CI add the mock classes and the shared client. The example's README lists every real provider's credentials and callback path.
Bind the callbacks
Allauth binds each provider's callback view to its built-in adapter when the
module loads, so provider_class alone sends the code to the real token
endpoint. urls.py
registers the same callback paths with the mock adapters, ahead of
allauth.urls:
account_patterns = []if settings.USE_MOCK: for route, adapter in ( ("google/login/callback/", MockGoogleAdapter), ("github/login/callback/", MockGitHubAdapter), # …Apple, Discord, Facebook and X ): account_patterns.append(path(route, OAuth2CallbackView.adapter_view(adapter)))urlpatterns = [ path("", home, name="home"), path("accounts/", include(account_patterns)), path("accounts/", include("allauth.urls")),]The openid_connect apps read their endpoints from the provider at request
time, so they need no extra route.
Sign in and read the user
The template posts to each provider's login URL, which allauth builds from the
configured class
(views.py):
adapter = get_adapter(request)provider = adapter.get_provider(request, "google")login_url = provider.get_login_url(request)After the callback, request.user is a regular Django user, and allauth
stores the linked account in the database. The example reads the provider,
ID and email in a user_logged_in receiver, and a SocialAccountAdapter
sends failed or declined sign-ins to /?error=sign-in.
With the mock on, the example sets email_authentication on each app, so the
same Mockatoo email signs in to one Django user from every provider button.
That relies on the mock having checked the email's owner. Keep it off for
real providers.
Handle provider differences
| Provider | What allauth needs |
|---|---|
| Apple | With the mock, a client that sends mockatoo-secret instead of a signed JWT, and an ID token check against the mock's issuer. The callback is apple/login/callback/finish/ |
With the mock, GRAPH_API_URL set to the mock's Graph base: allauth uses it for the token exchange and the profile | |
An openid_connect app with fetch_userinfo: False: the ID token has the claims | |
| X | Allauth's twitter_oauth2 provider ID. With the mock, the users.email scope and confirmed_email read as the verified email |
The Apple adapter, from the example:
class MockAppleClient(AppleOAuth2Client): def generate_client_secret(self): return self.consumer_secretclass MockAppleAdapter(AppleOAuth2Adapter): issuer = f"{settings.MOCK_ORIGIN}/apple" authorize_url = f"{issuer}/auth/authorize" access_token_url = f"{issuer}/auth/token" public_key_url = f"{issuer}/auth/keys" client_class = MockAppleClient def parse_token(self, data): token = OAuth2Adapter.parse_token(self, data) token._verified_identity_data = jwtkit.verify_and_decode( credential=data["id_token"], keys_url=self.public_key_url, issuer=self.issuer, audience=self.get_provider().get_auds(), lookup_kid=jwtkit.lookup_kid_jwk, ) return tokenSee each provider's page, e.g. Apple or X, for its flow and known differences.
Run it
Create .env.local with DJANGO_SECRET_KEY set to the output of
openssl rand -base64 48, then run:
pnpm installpnpm devpnpm dev applies the migrations to db.sqlite3 and starts Django on
http://localhost:3000. Pick a provider and sign in with your dashboard email
and password. To sign in as another user, add a tag to the email, e.g.
you+alice@example.com (see Email tags).
Test with Playwright
The example tests the Django app with Playwright, which only needs a running
server. playwright.config.ts
installs the app and starts it:
export default defineConfig({ testDir: "./tests", use: { baseURL: "http://localhost:3000" }, webServer: { command: "pnpm build && pnpm start", url: "http://localhost:3000", timeout: 120000, },});pnpm build runs uv sync and pnpm start migrates the database and runs
the server
(package.json).
tests/sign-in.spec.ts
signs in, checks the session survives a reload, signs out, and declines
consent with every provider:
await page.goto("/");await page .getByRole("button", { name: `Sign in with ${provider}`, exact: true }) .click();await page.getByLabel("Email", { exact: true }).fill(email);await page.getByLabel("Password", { exact: true }).fill(password);await page.getByRole("button", { name: "Log in with password" }).click();await page.getByRole("button", { name: decision, exact: true }).click();Add MOCKATOO_TEST_EMAIL and MOCKATOO_TEST_PASSWORD to .env.local or the
environment, then run:
pnpm exec playwright install chromiumpnpm testThe Playwright guide covers fresh users per test, edge-case tags and token refresh. Those tests work the same against a Django app.
Run in CI
The example's workflow sets up uv and Node.js, generates a secret key, then runs the tests with the credentials as secrets:
- uses: astral-sh/setup-uv@v7 with: python-version: "3.12"- name: Generate runtime secret run: echo "DJANGO_SECRET_KEY=$(openssl rand -base64 32)" >> "$GITHUB_ENV"- run: pnpm --dir allauth-django exec playwright install --with-deps chromium- run: pnpm --dir allauth-django test env: MOCKATOO_TEST_EMAIL: ${{ secrets.MOCKATOO_TEST_EMAIL }} MOCKATOO_TEST_PASSWORD: ${{ secrets.MOCKATOO_TEST_PASSWORD }}More in Run in CI.
Troubleshooting
| Symptom | Fix |
|---|---|
| The real provider's login page opens | The mock isn't on: set MOCKATOO_FORCE=true in .env or the environment |
Configure provider credentials or set MOCKATOO_FORCE=true. | Same cause: without the mock, the example expects the real credentials |
Set DJANGO_SECRET_KEY … on startup | Add a random secret to .env.local |
Sign-in ends on /?error=sign-in after Authorize | Bind the provider's callback to its mock adapter in urls.py (above) |
Apple sign-in ends on /?error=sign-in | Check the ID token against the mock's issuer, and send the static secret (above) |
| A second provider asks you to sign up again | Set email_authentication on the mock apps, so one Mockatoo email maps to one Django user |
| Login fails after a password change | Copy the new password from the dashboard into .env.local and your secrets |
Next steps
- All examples: Django, Flask, Spring Boot, Auth.js, Better Auth, SvelteKit, Nuxt and Hono
- Playwright · Email tags · Account flow · Run in CI
- Use Mockatoo only outside production, and never commit its credentials.