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.
This library provides user account storage, authentication, and authorization with Stormpath.
This library works with Python 2.7.x and Python 3.x.
To install the library, you'll need to use pip:
$ pip install django-stormpath
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:
- 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.
- 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, theis_active
field is set toTrue
if the Stormpath account is enabled andFalse
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.
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'
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.
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 © 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.