stages/email: implement rate limiting for account verification #15531

dechen-authentik · 2025-07-12T17:31:51Z

Details

This PR implements a very basic version of rate limiting for account verification emails.

Closes #11149

Context

Currently, it is possible to send an infinite number of account recovery emails. To reproduce this:

In Flows and Stages, create a new Stage using "Email Stage"
- Set the Template to "Account Confirmation"
- Create a new Flow using a Designation of "Recovery"
In the new Flow, create Stage Bindings
- Create an "Identification Stage", then for User fields select "Username" and "Email"
  - Under Recovery flow, set the flow created earlier
  - Set the Order to 0
- Create an "Email Stage"
  - Set the Order to 10
In Directory -> Users, create a user of type "Internal"
In the Flow, click the "Normal" button to execute the flow

Once you send the initial email, you will have the option to "Send email again":

You can currently click this button an unlimited number of times.

Rate Limiting

To prevent the user from being spammed, this PR introduces a rate limiting feature. To configure it, edit an existing Email Stage, where you'll notice two new fields, "Account Recovery Max Attempts" and "Account Recovery Cache Timeout":

Now if you spam the same button, eventually you'll see an error:

The error is Too many account verification attempts. Please try again after 10 minutes.. The error keeps track of the actual cache expiry time: if you click the button after a minute, you'll notice the message will ask you to try after 9 minutes.

Checklist

Local tests pass (ak test authentik/)
- I keep getting segfault errors (on unrelated tests) when trying to run the full test suite locally.
The code has been formatted (make lint-fix)

If an API change has been made

The API schema has been updated (make gen-build)

If changes to the frontend have been made

The code has been formatted (make web)

If applicable

The documentation has been updated
The documentation has been formatted (make website)

netlify · 2025-07-12T17:32:40Z

✅ Deploy Preview for authentik-docs ready!

Name	Link
🔨 Latest commit	`8ac746a`
🔍 Latest deploy log	https://app.netlify.com/projects/authentik-docs/deploys/6892554a7fb607000814fa66
😎 Deploy Preview	https://deploy-preview-15531--authentik-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-07-12T17:32:40Z

✅ Deploy Preview for authentik-integrations ready!

Name	Link
🔨 Latest commit	`8ac746a`
🔍 Latest deploy log	https://app.netlify.com/projects/authentik-integrations/deploys/6892554a4f2a7600085e7516
😎 Deploy Preview	https://deploy-preview-15531--authentik-integrations.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-07-12T17:32:40Z

✅ Deploy Preview for authentik-storybook ready!

Name	Link
🔨 Latest commit	`8ac746a`
🔍 Latest deploy log	https://app.netlify.com/projects/authentik-storybook/deploys/6892554a586966000861ecf4
😎 Deploy Preview	https://deploy-preview-15531--authentik-storybook.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

dechen-authentik · 2025-07-12T17:37:08Z

cc: @rissson 👋

codecov · 2025-07-12T17:42:37Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.73%. Comparing base (9848e4f) to head (8ac746a).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #15531      +/-   ##
==========================================
- Coverage   92.76%   92.73%   -0.03%     
==========================================
  Files         833      833              
  Lines       44731    44868     +137     
==========================================
+ Hits        41494    41610     +116     
- Misses       3237     3258      +21

Flag	Coverage Δ
e2e	`46.58% <7.24%> (-0.20%)`	⬇️
integration	`23.67% <7.24%> (-0.06%)`	⬇️
unit	`90.88% <100.00%> (+0.03%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

BeryJu

Couple small things, otherwise lgtm

authentik/stages/email/models.py

BeryJu · 2025-07-17T14:54:13Z

authentik/stages/email/stage.py

    def challenge_valid(self, response: ChallengeResponse) -> HttpResponse:
        return super().challenge_invalid(response)

+    def _get_cache_key(self) -> str:


nit but this might be something to implement as a Throttle in DRF https://www.django-rest-framework.org/api-guide/throttling/#userratethrottle

(this code is fine, thats just a design idea)

💡 That's an interesting idea. We could create a custom throttling class that uses DRF's throttling mechanism (we don't want to return a 429 status code, need to check stage specific settings, etc). This sounds like a viable option➕

authentik/stages/email/stage.py

authentik/stages/email/models.py

dechen-authentik · 2025-07-18T07:03:52Z

Couple small things, otherwise lgtm

Thanks for your feedback @BeryJu 🙏 I've implemented your suggestions and it's ready for another review.

authentik/stages/email/models.py

authentik/stages/email/api.py

web/src/admin/stages/email/EmailStageForm.ts

dechen-authentik · 2025-07-23T12:30:49Z

Thanks for your review @melizeche 🙏

I've addressed your feedback and it's ready for another review when you get a chance.

…on for Account Recovery Settings

…lated translations

…nerate migrations

…che_timeout to EmailStageSerializer

…reference to Email Stage specific values

…and cache timeout

…ilStage instance

…e set per stage.

…ing validator. Re-generate migrations.

…int.

…e cache timeout

* main: (32 commits) core: bump goauthentik.io/api/v3 from 3.2025064.6 to 3.2025064.7 (#16024) core, web: update translations (#16021) ci: move images from beryju/* to authentik/* (#15321) core, web: update translations (#15985) core: bump cattrs from 24.1.3 to v25.1.1 (#15981) web: bump API Client version (#16002) ci: bump actions/download-artifact from 4 to 5 (#15995) core: bump certifi from 2025.7.14 to v2025.8.3 (#15982) core: bump anyio from 4.9.0 to v4.10.0 (#15979) core: bump boto3 from 1.40.1 to v1.40.2 (#15980) core: bump astral-sh/uv from 0.8.4 to 0.8.5 (#15998) core: bump goauthentik.io/api/v3 from 3.2025064.5 to 3.2025064.6 (#15997) stages/email: implement rate limiting for account verification (#15531) web: Fix stale application slug, missing error state. (#15941) website/docs: change azure ad to entra id (#15691) website/docs: add tips for image optimization (#15978) web: bump API Client version (#15976) providers/oauth2: backchannel logout (#15401) web: bump API Client version (#15953) translate: Updates for file web/xliff/en.xlf in fr (#15974) ...

dechen-authentik requested review from a team as code owners July 12, 2025 17:31

dechen-authentik force-pushed the feature/rate-limiting-password-reset branch from c17d035 to 00a7295 Compare July 12, 2025 17:35

dechen-authentik force-pushed the feature/rate-limiting-password-reset branch from 00a7295 to ba7e7df Compare July 15, 2025 15:57

BeryJu reviewed Jul 17, 2025

View reviewed changes

dechen-authentik force-pushed the feature/rate-limiting-password-reset branch from ba7e7df to 525e61c Compare July 18, 2025 06:48

dechen-authentik requested a review from BeryJu July 18, 2025 07:04

dechen-authentik changed the title ~~stages/email: implement rate limiting for account recovery~~ stages/email: implement rate limiting for account verification Jul 18, 2025

melizeche requested changes Jul 23, 2025

View reviewed changes

authentik/stages/email/models.py Outdated Show resolved Hide resolved

authentik/stages/email/api.py Show resolved Hide resolved

web/src/admin/stages/email/EmailStageForm.ts Show resolved Hide resolved

dechen-authentik force-pushed the feature/rate-limiting-password-reset branch from 525e61c to fbd027e Compare July 23, 2025 11:52

dechen-authentik requested a review from melizeche July 23, 2025 12:30

dechen-authentik added 11 commits July 26, 2025 12:16

stages/email/stage: add rate limiting logic for account recovery

20f697b

lib/default: add default configuration for account recovery

cdacd36

website/docs/install-config/configuration: update docs with new secti…

5a49717

…on for Account Recovery Settings

locale/en: generate translations for account recovery error message

a142598

website/docs/developer-docs/translation: add a section for backend re…

a71f2dd

…lated translations

stages/email/models: add recovery related fields to EmailStage and ge…

c3556e0

…nerate migrations

authentik/stages/email/api: add recovery_max_attempts and recovery_ca…

48fc338

…che_timeout to EmailStageSerializer

blueprints/schema: regenerate schema

78ef9e9

website/docs/install-config/configuration: update documentation with …

ec4aed1

…reference to Email Stage specific values

web/src/admin/stages/email: add input form elements for max attempts …

187e419

…and cache timeout

authentik/stages/email: refactor to use rate limiting values from Ema…

2dbc225

…ilStage instance

dechen-authentik added 15 commits July 26, 2025 12:16

schema: only update schema for new fields

4c69403

web/src/admin/stages/email: replace test default with sane defaults

3cbc99a

locale/en/LC_MESSAGES: revert changes unrelated to this PR

258eba1

locale/en/LC_MESSAGES: revert changes unrelated to this PR

9f0903e

authentik/stages/email/tests: add tests for rate limiting

b6f91bd

Lint website

ba6f0a4

Remove locale changes since these are handled by CI

d7378da

Hard code the max attempts and cache timeout values since these can b…

2b7f8f5

…e set per stage.

Use PositiveIntegerField for recovery fields.

63cd5f9

Make rate limiting error message more generic

f25817e

Update recovery_cache_timeout to use a TextField with a timedelta str…

96bdd60

…ing validator. Re-generate migrations.

Regenerate schema

d47965e

Refactor email stage rate limiting logic to use timedelta instead of …

62c2c55

…int.

Update EmailStageForm.ts to use text input with timedelta instead of …

77d5366

…int.

Refactor tests since we're now using timedelta instead of ints for th…

92f94c2

…e cache timeout

dechen-authentik force-pushed the feature/rate-limiting-password-reset branch from fbd027e to 92f94c2 Compare July 26, 2025 08:16

dechen-authentik and others added 2 commits July 26, 2025 12:37

Update blueprint

4edba39

Merge branch 'main' into pr/15531

8ac746a

melizeche approved these changes Aug 5, 2025

View reviewed changes

rissson enabled auto-merge (squash) August 6, 2025 14:43

GirlBossRush approved these changes Aug 6, 2025

View reviewed changes

rissson merged commit cfe113b into goauthentik:main Aug 6, 2025
106 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

stages/email: implement rate limiting for account verification #15531

stages/email: implement rate limiting for account verification #15531

Uh oh!

dechen-authentik commented Jul 12, 2025 •

edited

Loading

Uh oh!

netlify bot commented Jul 12, 2025 •

edited

Loading

Uh oh!

netlify bot commented Jul 12, 2025 •

edited

Loading

Uh oh!

netlify bot commented Jul 12, 2025 •

edited

Loading

Uh oh!

dechen-authentik commented Jul 12, 2025

Uh oh!

codecov bot commented Jul 12, 2025 •

edited

Loading

Uh oh!

BeryJu left a comment

Uh oh!

Uh oh!

BeryJu Jul 17, 2025

Uh oh!

dechen-authentik Jul 18, 2025

Uh oh!

Uh oh!

Uh oh!

dechen-authentik commented Jul 18, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dechen-authentik commented Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

stages/email: implement rate limiting for account verification #15531

stages/email: implement rate limiting for account verification #15531

Uh oh!

Conversation

dechen-authentik commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Details

Context

Rate Limiting

Checklist

Uh oh!

netlify bot commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for authentik-docs ready!

Uh oh!

netlify bot commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for authentik-integrations ready!

Uh oh!

netlify bot commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for authentik-storybook ready!

Uh oh!

dechen-authentik commented Jul 12, 2025

Uh oh!

codecov bot commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

BeryJu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

BeryJu Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

dechen-authentik Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dechen-authentik commented Jul 18, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dechen-authentik commented Jul 23, 2025

Uh oh!

Uh oh!

Uh oh!

dechen-authentik commented Jul 12, 2025 •

edited

Loading

netlify bot commented Jul 12, 2025 •

edited

Loading

netlify bot commented Jul 12, 2025 •

edited

Loading

netlify bot commented Jul 12, 2025 •

edited

Loading

codecov bot commented Jul 12, 2025 •

edited

Loading