denibertovic / stormpath-django

Django plugin for Stormpath

django-stormpath

Simple, scalable, user authentication for Django (powered by Stormpath).

Note

This is a beta release, if you run into any issues, please file a report on our Issue Tracker.

Meta

This library provides user account storage, authentication, and authorization with Stormpath.

This library works with Python 2.7.x and Python 3.x.

Installation

To install the library, you'll need to use pip:

$ pip install django-stormpath

How it Works

django-stormpath provides an AUTHENTICATION_BACKEND which is used to communicate with the Stormpath REST API.

When a user tries to log in, and Stormpath is used as the authentication backend, django-stormpath always asks the Stormpath service if the user's credentials (username or email and password) are correct. Password hashes are always stored in Stormpath, and not locally.

If a user's credentials are valid, there are two possible scenarios:

1. User doesn't exist in Django's database (PostgreSQL, MySQL, Oracle etc.). In this case, a user will be created in the local Django user database with their username, password, email, first name, and last name identical to the Stormpath user's. Then this user will be authenticated.
2. User exists in Django's database. In this case, if a user's information has changed on Stormpath, the Django user's fields are updated accordingly. After this, the user will be authenticated.

Note

An account on Stormpath can be disabled, enabled, locked and unverified. When a user is created or updated, the is_active field is set to True if the Stormpath account is enabled and False otherwise.

Note

For a Stormpath user to be able to log into the Django admin interface it must specify the is_superuser and is_staff properties in the Stormpath Account's customData resource.

Usage

First, you need to add django_stormpath to your INSTALLED_APPS setting in settings.py:

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

Next, you need to add the Stormpath backend into AUTHENTICATION_BACKENDS:

AUTHENTICATION_BACKENDS = (
    # ...
    'django_stormpath.backends.StormpathBackend',
)

After that's done, you'll also need to tell Django to use Stormpath's user model:

AUTH_USER_MODEL = 'django_stormpath.StormpathUser'

Lastly, you need to specify your Stormpath credentials: your API key and secret, as well as your Stormpath Application URL.

For more information about these things, please see the official guide.

To specify your Stormpath credentials, you'll need to add the following settings to your settings.py:

STORMPATH_ID = 'yourApiKeyId'
STORMPATH_SECRET = 'yourApiKeySecret'
STORMPATH_APPLICATION = 'https://api.stormpath.com/v1/applications/YOUR_APP_UID_HERE'

Example: Creating a User

To pragmatically create a user, you can use the following code:

from django.contrib.auth import get_user_model

UserModel = get_user_model()
UserModel.objects.create(
    email = '[email protected]',
    given_name = 'John',
    surname = 'Doe',
    password = 'password123!'
)

The above example just calls the create_user method:

UserModel.create_user('john.doe@example', 'John', 'Doe', 'Password123!')

To create a super user, you can use manage.py:

$ python manage.py createsuperuser --username=joe [email protected]

This will set is_admin, is_staff and is_superuser to True on the newly created user. All extra parameters like the aforementioned flags are saved on Stormpath in the Accounts customData Resource and can be inspected outside of Django.

Note

When doing the initial syncdb call (or manage.py createsuperuser) an Account is also created on Stormpath. Every time the save method is called on the UserModel instance it is saved/updated on Stormpath as well. This includes working with the Django built-in admin interface.

ID Site

If you'd like to not worry about building your own registration and login screens at all, you can use Stormpath's new ID site feature. This is a hosted login subdomain which handles authentication for you automatically.

To make this work in Django, you need to specify a few settings:

AUTHENTICATION_BACKENDS = (
    # ...
    'django_stormpath.backends.StormpathIdSiteBackend',
)

# This should be set to the same URI you've specified in your Stormpath ID
# Site dashboard.
STORMPATH_ID_SITE_CALLBACK_URI = 'must_be_the_same_as_in_id_site_dashboard'

# The URL you'd like to redirect users to after they've successfully logged
# into their account.
LOGIN_REDIRECT_URL = '/redirect/here'

Lastly, you've got to include some URLs in your main urls.py as well:

url(r'', include(django_stormpath.urls)),

An example of how to use the available URL mappings can be found here.

Copyright and License

Copyright © 2014 Stormpath, inc. You may use and/or modify this library under the terms of Apache License version 2.0. Please see the LICENSE file for details.