This is still very WIP, but I wanted to get it out here to receive the first set of global feedback (I haven't re-read anything, so no need to comment on typos, wrong sentences or grammar yet).

Of course, the main goal of this rewrite is to document the new authenticator system and remove anything about guards, authentication providers, etc. Besides that, I've focused on 3 other things:

Give the user something that's working as quick as possible. This means using lots of makers and showing real code examples. I've discussed with Ryan and Jesse and we'll also extend the security makers to make even more docs redundant (I'm jealous at Laravel, which basically replaced all its authentication docs with "runjetstream:install").
Move as much information to the main guide as possible (following our doc practices of the last years). This means e.g. documenting all user providers and authenticators in the main guide. The subguides should be clearly scoped and about advanced/reference documentation (most of the subguides are yet to be worked on)
Focus on the built-in authenticators, rather than implementing your own authenticator. We've pushed writing your own guard in the docs way to much for my liking. E.g. for 90% of the use-cases, using the built-inform_login authenticator works perfectly. This will also be updated in the maker (wheremake:auth is not only going to suggest making a PHP authenticator) sometime in the future.

For the structure, I decided to follow the security config generated by the recipe/maker and explain section per section.

carsonbot added Status: Needs Work Security labels

Jul 11, 2021

carsonbot changed the title~~[WIP][Security] Rewrite Security documentation~~[Security] [WIP] Rewrite Security documentation

Jul 11, 2021

Copy link

MemberAuthor

wouterj commentedJul 11, 2021

I also started experimenting with a way to integrate code generated by the maker commands in the docs using aconfiguration-block:

..configuration-block::    ..code-block::terminal-maker        $ php bin/console make:...         ...    ..code-block::php        // ...

Let me know what you think about this (not sure if we need a custom label or justterminal btw).

javiereguiluz reviewed

Jul 12, 2021

View reviewed changes

Copy link

Member

javiereguiluz left a comment

Choose a reason for hiding this comment

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

This looks super promising 🤩 Thanks Wouter!

You said to not comment yet on typos, grammar, etc. so I won't make many comments for now. The overall structure looks nice. Good job!

security.rst OutdatedShow resolvedHide resolved

weaverryan reviewed

Jul 14, 2021

View reviewed changes

Copy link

Member

weaverryan left a comment

Choose a reason for hiding this comment

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

I like this a lot. The flow of the security.rst feels smooth: you highlight the big 3 pieces at the top (based on the 3 main keys in security.yaml) and then go through each one. Some parts are long - like showing all the different authentication types - but it's important enough that I like it: it allows me to search easily through the page. I did spot some typos etc, that I didn't comment on yet - as I know this is WIP. Keep going with this direction!

_build/redirection_map OutdatedShow resolvedHide resolved

security.rst OutdatedShow resolvedHide resolved

security.rstShow resolvedHide resolved

security.rst OutdatedShow resolvedHide resolved

security.rst

		.. caution::

		This login form is currently not protected against CSRF attacks. Read
		:ref:`form_login-csrf` on how to protect your login form.

Copy link

Member

weaverryanJul 14, 2021

Choose a reason for hiding this comment

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

The fact that we have the user write so much code, and you still aren't protected against CSRF attacks makes me think that it's time to update MakerBundle so that you can generate a login form withform_login (and sure, we would probably also keep some "Custom Login Form Authenticator" option to generate the authenticator).

security.rst OutdatedShow resolvedHide resolved

security.rstShow resolvedHide resolved

This was referencedJul 16, 2021

[Security] DeprecateTokenInterface::isAuthenticated()#15513

Closed

[Security] Deprecate the old authentication mechanisms#15355

Closed

current/security/form_login_setup uses deprecated classes#15543

Closed

javiereguiluz mentioned this pull request

Jul 23, 2021

Remove more deprecations in 6.0 branch#15549

Merged

Copy link

fmonts commentedAug 30, 2021

Hello, any news on this? we're stuck with an EOL version (5.2) since we don't have docs for 5.3 :( (and a straight upgrade to 5.3 broke some features)

wouterj mentioned this pull request

Sep 18, 2021

Prepare security.rst for Symfony 5.4#15828

Closed

javiereguiluz mentioned this pull request

Sep 24, 2021

[Security][DX]: add diff-result of what Maker Bundle did#11265

Closed

wouterj force-pushed thesecurity-53 branch from7c6b67e to6e56d08Compare

October 1, 2021 18:24

carsonbot added Status: Needs Review and removed Status: Needs Work labels

Oct 1, 2021

javiereguiluz approved these changes

Oct 7, 2021

View reviewed changes

Copy link

Member

javiereguiluz left a comment

Choose a reason for hiding this comment

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

Wouter, this is a truly impressive work. The new main Security article is fantastic and it explains, in a single place, all the basics you need to know to secure your application.

Even if side-articles such as passwords, etc. are TODO/WIP, I think this is mergeable ... and we should probably do that and iterate later to improve/finish things.

A big thank you from me 🙇

security.rst

		:class: screencast
		Symfony provides many tools to secure your application. Some HTTP-related
		security tools, like :doc:`secure session cookies </session>` and
		:doc:`CSRF protection </security/csrf>` are provided by default. The

Copy link

Member

javiereguiluzOct 7, 2021•
edited
Loading

Choose a reason for hiding this comment

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

I don't understand this well --> "are provided by default"

All provided features are provided "by default". Do you mean that they are enabled by default? Or maybe that you can use them without installing any packages?

Copy link

MemberAuthor

wouterjOct 7, 2021

Choose a reason for hiding this comment

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

I've seen several support questions and issue discussions about FrameworkBundle vs SecurityBundle. Some people think that everything related to security (e.g. CSRF) are in the SecurityBundle, whereas they actually live in the FrameworkBundle.

So I wanted to somehow remove some confusion by shortly saying "if you don't need authentication/authorization, you don't need to install the SecurityBundle" (FrameworkBundle is what I call "by default").

If you have any suggestions on how to better word this, please share them :)

security.rst OutdatedShow resolvedHide resolved

security.rst Outdated

		2a) Create your User Class
		--------------------------
		/**
		* A visual identifier that represents this user.

Copy link

Member

javiereguiluzOct 7, 2021

Choose a reason for hiding this comment

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

A visual identifier that represents this user

-->

The public representation of the user (e.g. a username, an email, etc.)

Copy link

MemberAuthor

wouterjOct 7, 2021

Choose a reason for hiding this comment

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

Updated, but left this unresolved as we should update this in MakerBundle also

security.rst OutdatedShow resolvedHide resolved

security.rstShow resolvedHide resolved

carsonbot added Status: Reviewed and removed Status: Needs Review labels

Oct 7, 2021

wouterj commented

Oct 7, 2021

View reviewed changes

security.rst OutdatedShow resolvedHide resolved

wouterj force-pushed thesecurity-53 branch 2 times, most recently fromc2b03f0 tob81babfCompare

October 7, 2021 17:21

javiereguiluz mentioned this pull request

Oct 8, 2021

[META] Symfony Security issues#15908

Closed

21 tasks

Rewrite Security documentation

d5460ed

wouterj force-pushed thesecurity-53 branch fromb81babf tod5460edCompare

October 10, 2021 11:46

wouterj changed the title~~[Security] [WIP] Rewrite Security documentation~~[Security] Rewrite Security documentation

Oct 10, 2021

javiereguiluz reviewed

Oct 11, 2021

View reviewed changes

reference/configuration/security.rst OutdatedShow resolvedHide resolved

This was referencedOct 11, 2021

[Security] Add information about login throttling to firewall cone#15885

Closed

Added the way to activate remember me in the new authentication system#15464

Closed

javiereguiluz reviewed

Oct 11, 2021

View reviewed changes

security.rst OutdatedShow resolvedHide resolved

javiereguiluz mentioned this pull request

Oct 11, 2021

Partially revert "fix voting on multiple roles behavior description" due to CVE-2020-5275#13457

Merged

Various tweaks to the new security documentation

df05fdb

weaverryan reviewed

Oct 11, 2021

View reviewed changes

Copy link

Member

weaverryan 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 for this Wouter! I think it's great - my comments were very minor - I enjoyed re-reading the security docs from scratch!

security/user_providers.rst OutdatedShow resolvedHide resolved

security.rstShow resolvedHide resolved

security.rst OutdatedShow resolvedHide resolved

security/form_login.rst OutdatedShow resolvedHide resolved

security/multiple_authenticators.rst OutdatedShow resolvedHide resolved

security/custom_authenticator.rst

		on special ``remember_me`` configuration. Read
		:doc:`/security/remember_me` for more information.

		:class:`Symfony\\Component\\Security\\Http\\Authenticator\\Passport\\Badge\\PasswordUpgradeBadge`

Copy link

Member

weaverryanOct 11, 2021

Choose a reason for hiding this comment

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

Above, for the RememberMeBadge, we could also mention that, in 5.3, you can enforce the remember me system from being activated via the method on the badge.

Also, over inremember_me.rst, we should probably mention somewhere that, if you're using a custom authenticator, then you need to attach theRememberMeBadge.

Copy link

MemberAuthor

wouterjOct 11, 2021

Choose a reason for hiding this comment

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

Yes, I've kept the remember me refactoring out of this PR. Let's do that in a follow up one (and rewriteremember_me.rst - which I haven't touched here)

security/custom_authenticator.rstShow resolvedHide resolved

weaverryanand others added2 commits

October 11, 2021 13:38

fixing syntax error

1e49d52

Fixes after final review from Javier and Ryan

cc84098

wouterj force-pushed thesecurity-53 branch from3ead28b tocc84098Compare

October 12, 2021 13:01

wouterj merged commit3d0eb51 intosymfony:5.3

Oct 12, 2021

wouterj deleted the security-53 branch

October 12, 2021 13:20

xabbuh mentioned this pull request

Nov 20, 2021

enable_authenticator_manager option placement in security.yaml#16122

Closed

javiereguiluz mentioned this pull request

Dec 29, 2021

Update security.rst#15953

Closed

Labels

Security Status: Reviewed

Movatterモバイル変換

Uh oh!

[Security] Rewrite Security documentation#15503

[Security] Rewrite Security documentation#15503

Uh oh!

Conversation

wouterj commentedJul 11, 2021• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Uh oh!

wouterj commentedJul 11, 2021

Uh oh!

javiereguiluz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

weaverryan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

weaverryanJul 14, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

fmonts commentedAug 30, 2021

Uh oh!

javiereguiluz left a comment

Choose a reason for hiding this comment

Uh oh!

javiereguiluzOct 7, 2021• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wouterjOct 7, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

javiereguiluzOct 7, 2021

Choose a reason for hiding this comment

Uh oh!

wouterjOct 7, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

weaverryan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

weaverryanOct 11, 2021

Choose a reason for hiding this comment

Uh oh!

wouterjOct 11, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

wouterj commentedJul 11, 2021•
edited
Loading

javiereguiluzOct 7, 2021•
edited
Loading