Welcome to django-sudo¶

Getting Started¶

$ pip install django-sudo

INSTALLED_APPS = (
    # ...
    'sudo',
)

MIDDLEWARE_CLASSES = (
    # ...
    'sudo.middleware.SudoMiddleware',
)

Configuration¶

(r'^sudo/$',  # Whatever path you want
    'sudo.views.sudo',  # Required
    {'template_name': 'sudo/sudo.html'}  # Optionally change the template to be used
)

Usage¶

Once we have django-sudo installed and configured, we need to decide which views should be secured.

sudo.decorators.sudo_required()¶

The meat of django-sudo comes from decorating your views with @sudo_required much in the same way that @login_required works.

Let’s pretend that we have a page on our site that has sensitive information that we want to make extra sure that a user is allowed to see it:

from sudo.decorators import sudo_required

@login_required  # Make sure they're at least logged in
@sudo_required  # On top of being logged in, are you in sudo mode?
def super_secret_stuff(request):
    return HttpResponse('your social security number')

That’s it! When a user visits this page and they don’t have the correct permission, they’ll be redirected to a page and prompted for their password. After entering their password, they’ll be redirected back to this page to continue on what they were trying to do.

class sudo.mixins.SudoMixin¶

SudoMixin provides an easy way to sudo a class-based view. Any view that inherits from this mixin is automatically wrapped by the @sudo_required decorator.

This works well with the LoginRequiredMixin from django-braces:

from django.views import generic
from braces.views import LoginRequiredMixin
from sudo.mixins import SudoMixin

class SuperSecretView(LoginRequiredMixin, SudoMixin, generic.TemplateView):
    template_name = 'secret/super-secret.html'

request.is_sudo()¶

Returns a boolean to indicate if the current request is in sudo mode or not. This gets added on by the SudoMiddleware. This is an shortcut for calling has_sudo_privileges() directly.

class sudo.middleware.SudoMiddleware¶

By default, you just need to add this into your MIDDLEWARE_CLASSES list.

has_sudo_privileges(self, request)¶

Subclass and override has_sudo_privileges() if you’d like to override the default behavior of request.is_sudo().

process_request(self, request)¶

Adds is_sudo() to the request.

process_response(self, request, response)¶

Controls the behavior of setting and deleting the sudo cookie for the browser.

sudo.utils.grant_sudo_privileges(request, max_age=SUDO_COOKIE_AGE)¶

Assigns a random token to the user’s session that allows them to have elevated permissions.

from sudo.utils import grant_sudo_privileges
token = grant_sudo_privileges(request)

sudo.utils.revoke_sudo_privileges(request)¶

Revoke sudo privileges from a request explicitly

from sudo.utils import revoke_sudo_privileges
revoke_sudo_privileges(request)

sudo.utils.has_sudo_privileges(request)¶

Check if a request is allowed to perform sudo actions.

from sudo.utils import has_sudo_privileges
has_sudo = has_sudo_privileges(request)

Contributing¶

$ git clone git@github.com:mattrobenolt/django-sudo.git

$ pip install -r dev-requirements.txt

$ py.test

$ tox

How does this work?¶

django-sudo works by setting an additional cookie that must match a secret value in your session. This cookie is ideally set to a shorter TTL than the normal session. When not in sudo mode, any view that is decorated with @sudo_required will require the user to re-enter their password. Once in sudo mode, they won’t be prompted to enter their password for the next SUDO_COOKIE_AGE seconds.

In practice, we want to serve this sudo cookie over https only to avoid a man-in-the-middle attack where someone hijacks this cookie. This can be utilized safely in situations where the sessionid cookie is being transmitted over http, but we want to make sure that secure areas of our site are not accessible with just the sessionid.

• When logging in, django-sudo automatically elevates your permission to sudo mode.
• A second cookie is sent to your browser (by default this cookie is named sudo but can be set to anything with SUDO_COOKIE_NAME). This cookie contains a randomly generated string of characters.
• The same randomly generated string of characters is stored in the user’s session.
• On subsequent requests, the cookie value must match the value that was stored in the session. If the values do not match, or the cookie is not sent at all, the user will be redirected to a page to re-enter their password.
• If they re-enter their password successfully, a new cookie is set and their permissions are again elevated.

Security¶

We take the security of django-sudo seriously. If you believe you’ve identified a security vulnerability, please report it to matt@ydekproductions.com.

You may encrypt the message using the PGP fingerprint: D9D7 15C4 32A9 8C40 F794  35AB A54A 6FD1 5E45 9C77.

Once you’ve submitted an issue via email, you should receive an acknowledgement within 48 hours, and depending on the action to be taken, you may receive further follow-up emails.

Changelog¶