Clarify authentication backend documentation

[Jeremy Blanchard]

The current text for the "NOTE" in ​this section of the documentation reads:

Once a user has authenticated, Django stores which backend was used to authenticate the user in the user's session, and re-uses the same backend for subsequent authentication attempts for that user. This effectively means that authentication sources are cached, so if you change AUTHENTICATION_BACKENDS, you'll need to clear out session data if you need to force users to re-authenticate using different methods. A simple way to do that is simply to execute Session.objects.all().delete().

It is pretty awkwardly worded in my opinion. It should be improved.

[Jeremy Blanchard]

After getting clarification from SmileyChris and reading the core code, I would propose this updated text:

NOTE: Once a user has authenticated, Django stores which backend was used to authenticate the user in the user's session, and re-uses the same backend for the duration of that session whenever access to the currently authenticated user is needed. This effectively means that authentication sources are cached, ((continue with previous text that was there))

[Jeremy Blanchard]

Marking as easy pickings

[Luke Granger-Brown]

Patch for the change suggested by auzigog

[Luke Granger-Brown]

Here's a patch for that. Setting has patch, and assigning to me.

[Luke Granger-Brown]

Forgot to add to cc.

[Claude Paroz]

In [17752]:

(The changeset message doesn't reference this ticket)

[Claude Paroz]

In [17753]:

[1.3.X] Fixed #17841 -- Clarified caching note about authentication backends. Thanks auzigog for the proposal and lukegb for the patch.

Backport of r17752 from trunk.