Changeset 2757
- Timestamp:
- 04/27/06 22:32:01 (2 years ago)
- Files:
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
django/branches/magic-removal/docs/authentication.txt
r2724 r2757 7 7 things work. 8 8 9 The basics 10 ========== 11 12 Django supports authentication out of the box. The ``django-admin.py init`` 13 command, used to initialize a database with Django's core database tables, 14 creates the infrastructure for the auth system. You don't have to do anything 15 else to use authentication. 9 Overview 10 ======== 16 11 17 12 The auth system consists of: … … 23 18 user. 24 19 * Messages: A simple way to queue messages for given users. 20 21 Installation 22 ============ 23 24 Authentication support is bundled as a Django application in 25 ``django.contrib.auth``. To install it, do the following: 26 27 1. Put ``'django.contrib.auth'`` in your ``INSTALLED_APPS`` setting. 28 2. Run the command ``manage.py syncdb``. 29 30 Note that the default ``settings.py`` file created by 31 ``django-admin.py startproject`` includes ``'django.contrib.auth'`` in 32 ``INSTALLED_APPS`` for convenience. If your ``INSTALLED_APPS`` already contains 33 ``'django.contrib.auth'``, feel free to run ``manage.py syncdb`` again; you 34 can run that command as many times as you'd like, and each time it'll only 35 install what's needed. 36 37 The ``syncdb`` command creates the necessary database tables, creates 38 permission objects for all installed apps that need 'em, and prompts you to 39 create a superuser account. 40 41 Once you've taken those steps, that's it. 25 42 26 43 Users … … 64 81 ``User`` objects have two many-to-many fields: ``groups`` and 65 82 ``user_permissions``. ``User`` objects can access their related 66 objects in the same way as any other `Django model`_: 67 68 *``myuser.objects.groups = [group_list]``69 *``myuser.objects.groups.add(group, group,...)``70 *``myuser.objects.groups.remove(group, group,...)``71 *``myuser.objects.groups.clear()``72 *``myuser.objects.permissions = [permission_list]``73 *``myuser.objects.permissions.add(permission, permission, ...)``74 *``myuser.objects.permissions.remove(permission, permission, ...]``75 *``myuser.objects.permissions.clear()``83 objects in the same way as any other `Django model`_:: 84 85 ``myuser.objects.groups = [group_list]`` 86 ``myuser.objects.groups.add(group, group,...)`` 87 ``myuser.objects.groups.remove(group, group,...)`` 88 ``myuser.objects.groups.clear()`` 89 ``myuser.objects.permissions = [permission_list]`` 90 ``myuser.objects.permissions.add(permission, permission, ...)`` 91 ``myuser.objects.permissions.remove(permission, permission, ...]`` 92 ``myuser.objects.permissions.clear()`` 76 93 77 94 In addition to those automatic API methods, ``User`` objects have the following 78 methods:95 custom methods: 79 96 80 97 * ``is_anonymous()`` -- Always returns ``False``. This is a way of … … 85 102 86 103 * ``set_password(raw_password)`` -- Sets the user's password to the given 87 raw string, taking care of the MD5 hashing. Doesn't save the ``User``88 object.104 raw string, taking care of the password hashing. Doesn't save the 105 ``User`` object. 89 106 90 107 * ``check_password(raw_password)`` -- Returns ``True`` if the given raw 91 string is the correct password for the user. 108 string is the correct password for the user. (This takes care of the 109 password hashing in making the comparison.) 92 110 93 111 * ``get_group_permissions()`` -- Returns a list of permission strings that … … 130 148 given, and the ``User`` gets ``is_active=True``. 131 149 150 See _`Creating users` for example usage. 151 132 152 * ``make_random_password(length=10, allowed_chars='abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789')`` 133 --Returns a random password with the given length and given string of153 Returns a random password with the given length and given string of 134 154 allowed characters. (Note that the default value of ``allowed_chars`` 135 155 doesn't contain ``"I"`` or letters that look like it, to avoid user … … 148 168 >>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword') 149 169 150 # At this point, user is a User object ready to be saved to the database. 151 # You can continue to change its attributes if you want to change other fields. 170 # At this point, user is a User object ready to be saved 171 # to the database. You can continue to change its attributes 172 # if you want to change other fields. 152 173 >>> user.is_staff = True 153 174 >>> user.save() … … 163 184 >>> u.save() 164 185 165 Don't set the password field directly unless you know what you're doing. This166 is explained in the next section.186 Don't set the ``password`` attribute directly unless you know what you're 187 doing. This is explained in the next section. 167 188 168 189 Passwords 169 190 --------- 170 191 171 Previous versions, such as Django 0.90, used simple MD5 hashes without password 172 salts. 173 174 The ``password`` field of a ``User`` object is a string in this format:: 192 The ``password`` attribute of a ``User`` object is a string in this format:: 175 193 176 194 hashtype$salt$hash … … 178 196 That's hashtype, salt and hash, separated by the dollar-sign character. 179 197 180 Hashtype is either ``sha1`` (default) or ``md5``. Salt is a random string 181 used to salt the raw password to create the hash. 198 Hashtype is either ``sha1`` (default) or ``md5`` -- the algorithm used to 199 perform a one-way hash of the password. Salt is a random string used to salt 200 the raw password to create the hash. 182 201 183 202 For example:: … … 187 206 The ``User.set_password()`` and ``User.check_password()`` functions handle 188 207 the setting and checking of these values behind the scenes. 208 209 Previous Django versions, such as 0.90, used simple MD5 hashes without password 210 salts. For backwards compatibility, those are still supported; they'll be 211 converted automatically to the new style the first time ``check_password()`` 212 works correctly for a given user. 189 213 190 214 Anonymous users … … 207 231 208 232 Until now, this document has dealt with the low-level APIs for manipulating 209 authentication-related objects. On a higher level, Django hooksthis233 authentication-related objects. On a higher level, Django can hook this 210 234 authentication framework into its system of `request objects`_. 211 235 212 In any Django view, ``request.user`` will give you a ``User`` object 236 First, install the ``SessionMiddleware`` and ``AuthenticationMiddleware`` 237 middlewares by adding them to your ``MIDDLEWARE_CLASSES`` setting. See the 238 `session documentation`_ for more information. 239 240 Once you have those middlewares installed, you'll be able to access 241 ``request.user`` in views. ``request.user`` will give you a ``User`` object 213 242 representing the currently logged-in user. If a user isn't currently logged in, 214 243 ``request.user`` will be set to an instance of ``AnonymousUser`` (see the … … 220 249 # Do something for logged-in users. 221 250 222 If you want to use ``request.user`` in your view code, make sure you have223 ``SessionMiddleware`` and ``AuthenticationMiddleware`` enabled. See the224 `session documentation`_ for more information.225 226 251 .. _request objects: http://www.djangoproject.com/documentation/request_response/#httprequest-objects 227 252 .. _session documentation: http://www.djangoproject.com/documentation/sessions/ … … 276 301 my_view = login_required(my_view) 277 302 278 Here's the same thing, using Python 2.4's decorator syntax:: 303 Here's an equivalent example, using the more compact decorator syntax 304 introduced in Python 2.4:: 279 305 280 306 from django.contrib.auth.decorators import login_required … … 385 411 it's not currently possible to say "Mary may change news stories, but only the 386 412 ones she created herself" or "Mary may only change news stories that have a 387 certain status or publication date." The latter functionality is something413 certain status, publication date or ID." The latter functionality is something 388 414 Django developers are currently discussing. 389 415 … … 392 418 393 419 Three basic permissions -- add, create and delete -- are automatically created 394 for each Django model that has ``admin`` set. Behind the scenes, these420 for each Django model that has a ``class Admin`` set. Behind the scenes, these 395 421 permissions are added to the ``auth_permission`` database table when you run 396 `` django-admin.py syncdb``.397 398 Note that if your model doesn't have `` admin`` set when you run399 `` django-admin.py syncdb``, the permissions won't be created. If you400 initialize your database and add ``admin`` to models after the fact, you'll 401 need to run ``django-admin.py syncdb`` again. It will create any missing 402 permissions forall of your installed apps.422 ``manage.py syncdb``. 423 424 Note that if your model doesn't have ``class Admin`` set when you run 425 ``syncdb``, the permissions won't be created. If you initialize your database 426 and add ``class Admin`` to models after the fact, you'll need to run 427 ``django-admin.py syncdb`` again. It will create any missing permissions for 428 all of your installed apps. 403 429 404 430 Custom permissions … … 419 445 ) 420 446 447 The only thing this does is create those extra permissions when you run 448 ``syncdb``. 449 421 450 .. _model Meta attribute: http://www.djangoproject.com/documentation/model_api/#meta-options 422 451 … … 435 464 436 465 * ``name`` -- Required. 50 characters or fewer. Example: ``'Can vote'``. 437 * ``content_type`` -- Required. A reference to the ``django_content_type s``466 * ``content_type`` -- Required. A reference to the ``django_content_type`` 438 467 database table, which contains a record for each installed Django model. 439 468 * ``codename`` -- Required. 100 characters or fewer. Example: ``'can_vote'``. … … 463 492 ----- 464 493 465 The currently logged-in user, either a ``User`` objector an``AnonymousUser``494 The currently logged-in user, either a ``User`` instance or an``AnonymousUser`` 466 495 instance, is stored in the template variable ``{{ user }}``:: 467 496 … … 509 538 ====== 510 539 511 Groups are a generic way of categorizing users to apply permissions, or some512 other label, to those users. A user can belong to any number of groups.540 Groups are a generic way of categorizing users so you can apply permissions, or 541 some other label, to those users. A user can belong to any number of groups. 513 542 514 543 A user in a group automatically has the permissions granted to that group. For … … 516 545 ``can_edit_home_page``, any user in that group will have that permission. 517 546 518 Beyond permissions, groups are a convenient way to categorize users to apply519 some label, or extended functionality, to them. For example, you could create 520 a group ``'Special users'``, and you could write code that would do special 521 things to those users -- such as giving them access to a members-only portion 522 of your site, or sending them members-only e-mailmessages.547 Beyond permissions, groups are a convenient way to categorize users to give 548 them some label, or extended functionality. For example, you could create a 549 group ``'Special users'``, and you could write code that could, say, give them 550 access to a members-only portion of your site, or send them members-only e-mail 551 messages. 523 552 524 553 Messages … … 527 556 The message system is a lightweight way to queue messages for given users. 528 557 529 A message is associated with a User. There's no concept of expiration or558 A message is associated with a ``User``. There's no concept of expiration or 530 559 timestamps. 531 560 … … 535 564 The API is simple:: 536 565 537 * To create a new message, use ``user.message_set.create(message='message_text')``. 538 * To retrieve/delete messages, use ``user.get_and_delete_messages()``, 566 * To create a new message, use 567 ``user_obj.message_set.create(message='message_text')``. 568 * To retrieve/delete messages, use ``user_obj.get_and_delete_messages()``, 539 569 which returns a list of ``Message`` objects in the user's queue (if any) 540 570 and deletes the messages from the queue. … … 547 577 # ... 548 578 request.user.message_set.create(message="Your playlist was added successfully.") 549 return render_to_response("playlists/create.html", context_instance=RequestContext(request)) 579 return render_to_response("playlists/create.html", 580 context_instance=RequestContext(request)) 550 581 551 582 When you use ``RequestContext``, the currently logged-in user and his/her
