Skip to content

Add session mgt guide#42908

Merged
Elchi3 merged 15 commits intomdn:mainfrom
wbamberg:add-session-mgt-guide
Feb 24, 2026
Merged

Add session mgt guide#42908
Elchi3 merged 15 commits intomdn:mainfrom
wbamberg:add-session-mgt-guide

Conversation

@wbamberg
Copy link
Collaborator

@wbamberg wbamberg commented Jan 26, 2026 •
edited
Loading

Here's a page on session management.

Terminology

I've talked mostly about two different models, one where the state is stored in the server and the client gets a session ID, and the other where the state is stored as a signed object (JWT) in the client. I've called these "centralized" and "decentralized" but people don't use these terms.

People sometimes use terms like "cookie-based" for the first and the second "JWT-based", but I don't like these, because ISTM that:

  1. how you store session information in the client and communicate it to the server is orthogonal to these architectural choices - that is, you don't have to do the first using cookies, and you could do the second using cookies

  2. (this is a much weaker objection) although in practice everyone does use JWTs for the second, that's an implementation choice not an architectural one.

I have asked about this and got feedback that my choice here is reasonable, but just flagging it here. We could call them "server-maintained state" and "client-maintained state" which is more descriptive but a real mouthful.

Frameworks and libraries

Regarding the section on "Frameworks and libraries", I do think we need to say this but went back and forth on whether to say it at the start or at the end, and how much detail to go into. FWIW although it might seem to negate the point of all this if we just tell people to use a framework, I really don't think it does - it is important to understand the principles and good practices, even if your framework is looking after a lot of the details for you.

@github-actions github-actions bot added Content:Security Security docs size/m [PR only] 51-500 LoC changed labels Jan 26, 2026
github-actions[bot]
github-actions bot reviewed Jan 26, 2026
View reviewed changes
@github-actions
Copy link
Contributor

github-actions bot commented Jan 26, 2026 •
edited
Loading

Preview URLs (1 page)

External URLs (3)

URL: /en-US/docs/Web/Security/Authentication/Session_management
Title: Session management

(comment last updated: 2026-02-24 05:33:42)

@wbamberg wbamberg marked this pull request as ready for review January 28, 2026 04:16
@wbamberg wbamberg requested a review from a team as a code owner January 28, 2026 04:16
@wbamberg wbamberg requested review from hamishwillee and removed request for a team January 28, 2026 04:16
wbamberg and others added 2 commits February 8, 2026 17:27
@wbamberg @hamishwillee
Update files/en-us/web/security/authentication/session_management/ind…
44b25fb 
…ex.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
Elchi3
Elchi3 approved these changes Feb 20, 2026
View reviewed changes
Copy link
Member

@Elchi3 Elchi3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Will, this is a great read!

People sometimes use terms like "cookie-based" for the first and the second "JWT-based", but I don't like these,

I see your points. I wonder if at the top of the article (where I propose to add a heading), you want give an overview of the two architectures and say how cookies and JWTs are usually used (but don't have to be used this way).
Just to be more upfront what the options are. You say "in this guide we'll first describe the most common architecture ..." but then I only learn all the way in the second half of the page what the second architecture is.

Edit: Oh I just saw Hamish has had a similar comment. So maybe never mind then.

Again, I really like the summary at the end for the key takeaways.

wbamberg and others added 2 commits February 20, 2026 10:22
@wbamberg @hamishwillee
Update files/en-us/web/security/authentication/session_management/ind…
29bbdd8 
…ex.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
wbamberg
wbamberg commented Feb 24, 2026
View reviewed changes
Elchi3
Elchi3 approved these changes Feb 24, 2026
View reviewed changes
Copy link
Member

@Elchi3 Elchi3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, Will! 🎉

@Elchi3 Elchi3 merged commit 7e1cf6a into mdn:main Feb 24, 2026
8 checks passed
@hamishwillee
Copy link
Collaborator

hamishwillee commented Feb 24, 2026

What he said ^^^

wbamberg added a commit to wbamberg/content that referenced this pull request Feb 26, 2026
@wbamberg
Merge remote-tracking branch 'upstream/main' into tls-guide-update
a66bd02 
* upstream/main: (619 commits)
  Fix usage of numbers iterator in zip example (mdn#43236)
  Synchronize with BCD v7.3.3 (mdn#43178)
  Add Firefox 148 sanitizer release note (mdn#43234)
  WebDriver conformance changes for Firefox 148 (mdn#43228)
  ci(auto-merge): fix target-repo (mdn#43139)
  Add session mgt guide (mdn#42908)
  docs(firefox-release): Finalize release notes for Fx148 release (mdn#43225)
  [Technical Review] Add folder for WebDriver BiDi and create initial landing pages (mdn#43153)
  fix: correct 'after' to 'before' in break-before always/all descriptions (mdn#43185)
  added the release note for position-try-order (mdn#43223)
  Clarify that role="button" does not inherit button functionality (mdn#43186)
  Fix wording mistake in Temporal.ZonedDateTime (mdn#43188)
  Fix description for break-before: always (mdn#43190)
  improve confusing sentance (mdn#43172)
  Document scoped customElementRegistry and related properties (mdn#43149)
  fix: correct terminology for object initializer property names (mdn#43182)
  Fix typo about arrow function expression body (mdn#43175)
  Update InterfaceData based on WebRef (mdn#43179)
  Fix clarify visibilitychange event intro to mention all triggers (mdn#43177)
  [WebExtensions] Document runtime.getVersion() method (mdn#42971)
  ...
jdatapple pushed a commit to jdatapple/content that referenced this pull request Mar 6, 2026
@wbamberg @hamishwillee
@Elchi3 @jdatapple
Add session mgt guide (mdn#42908)
850e8ca 
* First bits

* Add first draft of session mgt guide

* e.g. -> for example

* Add some incoherent stuff about refresh tokens

* restructure

* Add diagrams

* More about refresh tokens, checklist, see also

* Review comments

* Update files/en-us/web/security/authentication/session_management/index.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* Try reworking intro

* Update files/en-us/web/security/authentication/session_management/index.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* Apply suggestions from code review

Co-authored-by: Florian Scholz <fs@florianscholz.com>

* Talk about different models more at the start

* Update files/en-us/web/security/authentication/session_management/index.md

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* Update files/en-us/web/security/authentication/session_management/index.md

---------

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
Co-authored-by: Florian Scholz <fs@florianscholz.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hamishwillee hamishwillee hamishwillee approved these changes

@github-actions github-actions[bot] github-actions[bot] left review comments

@Elchi3 Elchi3 Elchi3 approved these changes

Assignees

No one assigned

Labels

Content:Security Security docs size/m [PR only] 51-500 LoC changed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@wbamberg @hamishwillee @Elchi3