Clearly document the permissions model for the Django admin interface

[ncoghlan@…]

The current auth docs aren't particularly clear on *exactly* what is needed to support the Django admin with a custom backend. Specifically, I had to do a lot of digging and experimentation to work out adequate settings for a User to be able to:

1. Access the admin pages at all (i.e. is_active + is_staff)
2. Actually edit the model data (through trial and error, I know that is_active + is_staff + is_super works, but I don't know if there are any other ways to achieve the same thing).

[Karen Tracey]

Could you say a bit more about where you looked and found docs lacking?

This bit: ​https://docs.djangoproject.com/en/1.3/topics/auth/#writing-an-authentication-backend does mention that "The Django admin system is tightly coupled to the Django User object described at the beginning of this document. For now, the best way to deal with this is to create a Django User object for each user that exists for your backend (e.g., in your LDAP directory, your external SQL database, etc.)" implying to use admin with a custom auth backend you still do want to be using standard django.contrib.auth Usesr objects, with all their attributes.

The descriptions for is_staff, is_active, is_superuser (​https://docs.djangoproject.com/en/1.3/topics/auth/#django.contrib.auth.models.User.is_staff) all mention how admin uses them.

​https://docs.djangoproject.com/en/1.3/topics/auth/#permissions describes how admin uses permissions to control how much access a user has to individual models in the admin site.

[ncoghlan@…]

The problem is that they're scattered, so it's hard to be sure you've covered everything. What happened to me was that I had a bug in my auth backend, such that "is_staff" and "is_superuser" weren't being set correctly (they were always False). Initially I assumed I had missed something, so I was scouring the docs trying to work out what I had missed. It was only after convincing myself that I had actually found all the relevant pieces that I took a closer look at my own code and uncovered the bug.

A simple list of bullet points in the Custom Auth Backend section would have steered me in the right direction straight away (because I would have known I had covered everything, and hence I simply had a bug in the code I had already written rather than missing a step). With appropriate links to the specific sections, something like the following would make it crystal clear what you need to do to link the two together:

"To use the Django admin system with a custom authentication backend, the custom backend must do at least the following:

• create Django User objects for any users that need to access the Django admin system
• ensure "is_active" is set for each of those users
• ensure that either "is_superuser" (for full access) or "is_staff" and the appropriate permissions (for limited access) are set for each of those users"

(That would probably replace the current sentence on the topic, since the two cover the same ground)