Flask

Sign in through OAuth in a Flask app, locally and in CI, with any of the eight providers Mockatoo mocks.

Example on GitHub: mockatoo/examples/authlib-flask.

How it works

  1. Your sign-in route calls Authlib's authorize_redirect, which sends the browser to the mock on the provider's real paths: accounts.google.com/o/oauth2/v2/auth becomes app.mockatoo.globalunderdog.com/google/o/oauth2/v2/auth.
  2. You (or a test) fill in the login page and click Authorize.
  3. The mock redirects back to /auth/<provider>/callback. Authlib's authorize_access_token exchanges the code for provider-shaped tokens and validates the signed ID token, as it would in production.

Your routes, scopes and callbacks don't change. Only the client credentials and the provider URLs do, and only when the mock is on.

Prerequisites

Register the providers

providers.py registers one Authlib client per provider. A single switch picks the real or the mock URLs and credentials:

use_mock = os.getenv("MOCKATOO_FORCE") == "true"origin = os.getenv("MOCKATOO_URL") or "https://app.mockatoo.globalunderdog.com"oauth.register(    name="google",    client_id="mockatoo" if use_mock else os.getenv("GOOGLE_CLIENT_ID"),    client_secret="mockatoo-secret" if use_mock else os.getenv("GOOGLE_CLIENT_SECRET"),    # OpenID Connect providers: swap the discovery document.    server_metadata_url=(f"{origin}/google" if use_mock else "https://accounts.google.com")    + "/.well-known/openid-configuration",    client_kwargs={"scope": "openid email profile"},)github = f"{origin}/github" if use_mock else "https://github.com"oauth.register(    name="github",    # …the same client ID and secret switch    # OAuth-only providers: swap the three endpoints.    authorize_url=f"{github}/login/oauth/authorize",    access_token_url=f"{github}/login/oauth/access_token",    api_base_url=f"{origin}/github/api/v3/" if use_mock else "https://api.github.com/",    client_kwargs={"scope": "read:user user:email"},)
  • mockatoo / mockatoo-secret is the shared client. It accepts any http(s) callback, so localhost and preview URLs need no provider setup.
  • For Google, Microsoft, Apple and LinkedIn, Authlib fetches discovery and signing keys from the mock. For GitHub, Discord, X and Facebook, list the mock's paths. Copy the URLs for all eight from providers.py.
  • Microsoft takes any tenant ID. Use a concrete one, as the example does, so the issuer matches the ID token.
  • The example's committed .env sets MOCKATOO_FORCE=true so its live demo works. In your app, turn the mock on only outside production. Never ship it.

Already have Authlib clients? Keep them, and in development or CI override the client ID, secret and URLs with the mock's. The example's README lists every provider's discovery URL and endpoint paths.

Sign in and read the user

app.py uses the same two Authlib calls for every provider, real or mock (error handling trimmed):

@app.post("/sign-in")def sign_in():    provider = request.form.get("provider")    client = oauth.create_client(provider)    return client.authorize_redirect(        url_for("callback", provider=provider, _external=True)    )@app.get("/auth/<provider>/callback")def callback(provider):    client = oauth.create_client(provider)    token = client.authorize_access_token()    subject, email = get_identity(provider, client, token)    session["user"] = {"provider": provider, "sub": str(subject), "email": email}    return redirect(url_for("index"))

get_identity in providers.py reads the ID token's claims for the OpenID Connect providers and calls the user API for the others. Build the callback URL from the request, as url_for(..., _external=True) does, so each localhost port and preview deployment uses its own.

Handle provider differences

These settings match the real providers, so they belong in your app whether or not you use the mock. The example handles them in providers.py and app.py:

ProviderWhat Authlib needs
Appleresponse_mode=form_post, a CSRF-exempt POST /auth/apple/callback, and a SameSite=None; Secure session cookie while the sign-in is pending
LinkedInA client class that skips the nonce check: LinkedIn doesn't return it
Xcode_challenge_method: S256, and the profile unwrapped from data
GitHubA fallback to user/emails for the primary verified email

The LinkedIn client, from the example:

class LinkedInOAuth(FlaskOAuth2App):    def parse_id_token(self, token, nonce, **kwargs):        # LinkedIn does not return the nonce. Authlib still validates the signed        # ID token and ties the authorization code to this browser using state.        return super().parse_id_token(token, nonce=None, **kwargs)

See each provider's page, e.g. Apple or LinkedIn, for its flow and known differences.

Run it

Create .env.local with FLASK_SECRET_KEY set to the output of openssl rand -base64 32, then run:

pnpm installpnpm dev

Open 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 Flask app with Playwright, which only needs a running server. playwright.config.ts installs the app and starts it with Gunicorn:

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 runs Gunicorn (package.json). tests/sign-in.spec.ts signs in, checks the session, 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 test

The Playwright guide covers fresh users per test, edge-case tags and token refresh. Those tests work the same against a Flask app.

Run in CI

The example's workflow sets up uv and Node.js, generates a session secret, 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 "FLASK_SECRET_KEY=$(openssl rand -base64 32)" >> "$GITHUB_ENV"- run: pnpm --dir authlib-flask exec playwright install --with-deps chromium- run: pnpm --dir authlib-flask test  env:    MOCKATOO_TEST_EMAIL: ${{ secrets.MOCKATOO_TEST_EMAIL }}    MOCKATOO_TEST_PASSWORD: ${{ secrets.MOCKATOO_TEST_PASSWORD }}

More in Run in CI.

Troubleshooting

SymptomFix
The real provider's login page opensThe 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 FLASK_SECRET_KEY … on startupAdd a random secret of at least 32 characters to .env.local
Apple sign-in ends on /?error=sign-inKeep the CSRF exemption and the SameSite=None; Secure cookie for Apple, and use HTTPS or Chromium's localhost
LinkedIn sign-in ends on /?error=sign-inSkip the nonce check for LinkedIn (above)
Login fails after a password changeCopy the new password from the dashboard into .env.local and your secrets

Next steps