Advanced Usage
==============
navigator.id.request Arguments
------------------------------
The ``navigator.id.request`` function accepts several optional arguments that
customize the BrowserID login dialog. The default JavaScript provided by
``django-browserid`` checks for data attributes on the login link and passes
them to ``navigator.id.request``. For example, the following customizes the
website name shown in the BrowserID dialog::
Login
.. note:: ``navigator.id.request`` arguments are in camelCase, but data
attributes must use dashes in place of capitalization changes.
See the `navigator.id.request documentation`_ for a list of accepted parameters.
.. _navigator.id.request documentation: https://developer.mozilla.org/docs/DOM/navigator.id.request
Automatic Account Creation
--------------------------
``django-browserid`` will automatically create a user account for new
users. The user account will be created with the verified
email returned from the BrowserID verification service, and a URL safe
base64 encoded SHA1 of the email with the padding removed as the
username.
To provide a customized username, you can provide a different
algorithm via your settings.py::
# settings.py
BROWSERID_CREATE_USER = True
def username(email):
return email.rsplit('@', 1)[0]
BROWSERID_USERNAME_ALGO = username
You can can provide your own function to create users by setting
``BROWSERID_CREATE_USER`` to a string path pointing to a function::
# module/util.py
def create_user(email):
return User.objects.create_user(email, email)
# settings.py
BROWSERID_CREATE_USER = 'module.util.create_user'
You can disable account creation, but continue to use the
``browserid_verify`` view to authenticate existing users with the
following::
BROWSERID_CREATE_USER = False
Custom Verification
-------------------
If you want full control over account verification, don't use
django-browserid's ``browserid_verify`` view. Create your own view and
use ``verify`` to manually verify a BrowserID assertion with something
like the following::
from django_browserid import get_audience, verify
from django_browserid.forms import BrowserIDForm
def myview(request):
# ...
if request.method == 'POST':
form = BrowserIDForm(data=request.POST)
if not form.is_valid():
result = verify(form.cleaned_data['assertion'], get_audience(request))
if result:
# check for user account, create account for new users, etc
user = my_get_or_create_user(result.email)
``result`` will be ``False`` if the assertion failed, or a dictionary
similar to the following::
{
u'audience': u'https://mysite.com:443',
u'email': u'myemail@example.com',
u'issuer': u'browserid.org',
u'status': u'okay',
u'expires': 1311377222765
}
You are of course then free to store the email in the session and
prompt the user to sign up using a chosen identifier as their
username, or whatever else makes sense for your site.
Javascript Fallback
-------------------
It is a good idea to provide an alternative method of authenticating with your
site for users that do not have JavaScript available. An easy way of doing this
is to modify the ``href`` of the link that you bind to BrowserID login to point
to a traditional login and registration page::
Sign In
If a user has JavaScript enabled, when they click the link the JavaScript will
take over and show a BrowserID popup. If a user has JavaScript disabled, they
will be directed to your login view (which should not require JavaScript, of
course).
Multiple Login Buttons
----------------------
If you are using the default JavaScript provided by ``django-browserid``, you
can have multiple login buttons on a single page by marking them with the class
``browserid-login``. Be sure to only include the hidden login form on the page
once to avoid errors from using the same id multiple times.
Signals
-------
.. module:: django_browserid.signals
.. data:: user_created
Signal triggered when a user is automatically created during authentication.
* **sender**: The function that created the user instance.
* **user**: The user instance that was created.
Custom User Model
-----------------
Django 1.5 allows you to specify a custom model to use in place of the built-in
User model with the ``AUTH_USER_MODEL`` setting. ``django-browserid`` supports
custom User models, however you will most likely need to subclass
``django-browserid.BrowserIDBackend`` and override the ``create_user``,
``get_user``, and ``filter_users_by_email`` functions to work with your class.