Opened 12 years ago

Closed 12 years ago

Last modified 12 years ago

#19662 closed Bug (fixed)

Explain correct `authenticate` usage with custom user model.

Reported by: Tom Christie Owned by: nobody
Component: contrib.auth Version: 1.5-beta-1
Severity: Release blocker Keywords:
Cc: marc.tamlyn@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

If using a custom user model, with eg USERNAME_FIELD='email',
then it is non-obvious if the correct usage is authenticate(username=..., password=...) or authenticate(email=..., password=...)

Bit of an easy stumbling point, and it won't be obvious to the developer why login is failing, so we should really note the usage here.

This was the best phrasing I could come up with, but happy to take other suggestions.

Marking as a bug, because I'd consider this a documentation bug, until resolved.

Change History (13)

comment:2 by Preston Holmes, 12 years ago

We have to be clear not to further confuse the situation between custom users and custom backends:

https://docs.djangoproject.com/en/dev/topics/auth/customizing/#writing-an-authentication-backend

authenticate only needs credentials

It is just that for most situations, people have only dealt with auth.User and the modelbackend.

Its not clear to me that the modelbackend shouldn't further introspect the user model to get then name of the USERNAME_FIELD and look for a matching kwarg

Version 0, edited 12 years ago by Preston Holmes (next)

comment:3 by Tom Christie, 12 years ago

We have to be clear not to further confuse the situation between custom users and custom backends ... authenticate only needs credentials

Could use something like: "Note: If you're using the default authentication backend ModelBackend, then there are two credentials required: username, and password. Note that the first named argument will always be named username, even if you're using a custom user model withUSERNAME_FIELD set to some other field."

It's a bit verbose, but better than not mentioning it.

Its not clear to me that the modelbackend shouldn't further introspect the user model to get then name of the USERNAME_FIELD and look for a matching kwarg

Could be an option, but we'd also need to consider if the same ought to then also apply to AuthenticationForm. Ie. Should the username field, instead be named email if using an email-based custom user model?

I'm not sure what the best behavior is.

comment:4 by Aymeric Augustin, 12 years ago

Severity: NormalRelease blocker
Triage Stage: UnreviewedAccepted

We should ask Russell before releasing 1.5 final. Afterwards the API will be subject to our backwards-compatibility policy, making the change significantly more complicated.

If we choose to keep the current API, the wording proposed in comment 3 seems perfectly clear to me.

comment:5 by Russell Keith-Magee, 12 years ago

I could go either way on this.

On the one hand, create_superuser() on the model manager already uses USERNAME_FIELD; on the other hand, AuthenticationForm will be a pain to convert to use USERNAME_FIELD (unless I'm missing an obvious option). So, we've got feet in both camps here.

Strictly, the authenticate() prototype is already **credentials, and it would be a fairly easy change to make it accept USERNAME_FIELD instead of username, so changing the ModelBackend to accept **credentials and then inspect for USERNAME_FIELD is probably the right thing to do.

comment:6 by Marc Tamlyn, 12 years ago

Cc: marc.tamlyn@… added

comment:7 by shaneallgeier@…, 12 years ago

I believe that authenticate() should be left as is (only expecting username). Otherwise, all DRY/pluggable authentication backends would have to first check the USERNAME_FIELD from the user model every time someone tries to authenticate. It would also require pluggable backends to check the Django version to figure out if it even needs to check for a possible USERNAME_FIELD. I know it won't be a difference in speed or anything, but it would still be annoying to write.

comment:8 by Preston Holmes, 12 years ago

I've implemented a patch here:

https://github.com/ptone/django/compare/ticket/19662-modelbackend

This may still need a note in the custom user docs but the note in model backend ref is probably enough. Really I think this is something many people will just expect.

I think we can leave AuthenticationForm set to username. Or at least that is a different ticket.

One thing I almost missed is that authenticate works currently with username/password as positional args, so a check is made for that.

in reply to:  7 comment:9 by Carl Meyer, 12 years ago

Replying to shaneallgeier@…:

I believe that authenticate() should be left as is (only expecting username). Otherwise, all DRY/pluggable authentication backends would have to first check the USERNAME_FIELD from the user model every time someone tries to authenticate. It would also require pluggable backends to check the Django version to figure out if it even needs to check for a possible USERNAME_FIELD. I know it won't be a difference in speed or anything, but it would still be annoying to write.

You mean "all DRY/pluggable authentication backends that use essentially the same authentication scheme as ModelBackend but for some reason reimplement it themselves"? How big a category of reusable authentication backends is this? The authenticate() method of authentication backends has always been documented to accept **credentials precisely so custom auth backends can accept any authentication credentials that make sense for them, not be limited to what ModelBackend does. So I don't think changing ModelBackend to use more sensible credential names with custom User classes is enforcing any changes on custom auth backends in general.

comment:10 by Marc Tamlyn, 12 years ago

I'm inclined to agree with Carl - I'd rather things had the "correct" signature and it shouldn't be massively difficult to update external backends. Any pluggable app providing auth is likely to require updating for custom user models in any case.

comment:11 by Preston Holmes <preston@…>, 12 years ago

Resolution: fixed
Status: newclosed

In c44d748272d1d39e7cd48b625c526f532703aa29:

Fixed #19662 -- alter auth modelbackend to accept custom username fields

Thanks to Aymeric and Carl for the review.

comment:12 by Preston Holmes <preston@…>, 12 years ago

In 660f80c3d60083ecba26c83c0670ccca7fc56e09:

[1.5.x] Fixed #19662 -- alter auth modelbackend to accept custom username fields

Thanks to Aymeric and Carl for the review.

comment:13 by Preston Holmes <preston@…>, 12 years ago

In 660f80c3d60083ecba26c83c0670ccca7fc56e09:

[1.5.x] Fixed #19662 -- alter auth modelbackend to accept custom username fields

Thanks to Aymeric and Carl for the review.

Note: See TracTickets for help on using tickets.
Back to Top