API

Template Helpers

django_browserid.helpers.browserid_info()

Output the HTML for the login form and the info tag. Should be called once at the top of the page just below the <body> tag.

django_browserid.helpers.browserid_login(text='Sign in', next=None, link_class='browserid-login', attrs=None, fallback_href='#')

Output the HTML for a BrowserID login link.

Parameters:
  • text – Text to use inside the link. Defaults to ‘Sign in’, which is not localized.
  • next – URL to redirect users to after they login from this link. If omitted, the LOGIN_REDIRECT_URL setting will be used.
  • link_class – CSS class for the link. browserid-login will be added to this automatically.
  • attrs

    Dictionary of attributes to add to the link. Values here override those set by other arguments.

    If given a string, it is parsed as JSON and is expected to be an object.

  • fallback_href – Value to use for the href of the link. If the user has disabled JavaScript, the login link will bring them to this page, which can be used as a non-JavaScript login fallback.
django_browserid.helpers.browserid_logout(text='Sign out', link_class='browserid-logout', attrs=None)

Output the HTML for a BrowserID logout link.

Parameters:
  • text – Text to use inside the link. Defaults to ‘Sign out’, which is not localized.
  • link_class – CSS class for the link. browserid-logout will be added to this automatically.
  • attrs

    Dictionary of attributes to add to the link. Values here override those set by other arguments.

    If given a string, it is parsed as JSON and is expected to be an object.

django_browserid.helpers.browserid_js(include_shim=True)

Returns <script> tags for the JavaScript required by the BrowserID login button. Requires use of the staticfiles app.

Parameters:include_shim – A boolean that determines if the persona.org JavaScript shim is included in the output. Useful if you want to minify the button JavaScript using a library like django-compressor that can’t handle external JavaScript.

Verification Functions

django_browserid.verify(assertion, audience, extra_params=None, url=None)

Verify assertion using an external verification service.

Parameters:
  • assertion – The string assertion received in the client from navigator.id.request().
  • audience – This is domain of your website and it must match what was in the URL bar when the client asked for an assertion. You probably want to use django_browserid.get_audience() which sets it based on SITE_URL.
  • extra_params – A dict of additional parameters to send to the verification service as part of the POST request.
  • url – A custom verification URL for the service. The service URL can also be set using the BROWSERID_VERIFICATION_URL setting.
Returns:

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
}

Raises :

BrowserIDException: Error connecting to remote verification service.

django_browserid.get_audience(request)

Uses Django settings to format the audience.

To figure out the audience to use, it does this:

  1. If settings.DEBUG is True and settings.SITE_URL is not set or empty, then the domain on the request will be used.

    This is not secure!

  2. Otherwise, settings.SITE_URL is compared with the request domain and will raise an ImproperlyConfigured error if they don’t match.

Examples of settings.SITE_URL:

SITE_URL = 'http://127.0.0.1:8001'
SITE_URL = 'https://example.com'
SITE_URL = 'http://example.com'

Views

class django_browserid.views.Verify(**kwargs)

Bases: django.views.generic.edit.BaseFormView

Login view for django-browserid. Takes in an assertion and sends it to the remote verification service to be verified, and logs in the user upon success.

failure_url = '/'

URL to redirect users to when login fails. This uses the value of settings.LOGIN_REDIRECT_URL_FAILURE, and defaults to '/' if the setting doesn’t exist.

success_url = '/accounts/profile/'

URL to redirect users to when login succeeds if next isn’t specified in the request. This uses the value of settings.LOGIN_REDIRECT_URL, and defaults to '/' if the setting doesn’t exist.

login_success()

Log the user into the site and redirect them to the post-login URL.

If next is found in the request parameters, it’s value will be used as the URL to redirect to. If next points to a different host than the current request, it is ignored.

login_failure(error=None)

Redirect the user to a login-failed page, and add the bid_login_failed parameter to the URL to signify that login failed to the JavaScript.

Parameters:error – If login failed due to an error raised during verification, this will be the BrowserIDException instance that was raised.
form_valid(form)

Send the given assertion to the remote verification service and, depending on the result, trigger login success or failure.

Parameters:form – Instance of BrowserIDForm that was submitted by the user.
form_invalid(*args, **kwargs)

Trigger login failure since the form is invalid.

get(*args, **kwargs)

Trigger login failure since we don’t support GET on this view.

get_failure_url()

Retrieve failure_url from the class. Raises ImproperlyConfigured if the attribute is not found.

dispatch(request, *args, **kwargs)

Run some sanity checks on the request prior to dispatching it.

Signals

django_browserid.signals.user_created = <django.dispatch.dispatcher.Signal object at 0x273abd0>

Signal triggered when a user is automatically created during authentication.

Parameters:
  • sender – The function that created the user instance.
  • user – The user instance that was created.

Exceptions

exception django_browserid.base.BrowserIDException(exc)

Raised when there is an issue verifying an assertion with django_browserid.base.verify().

exc = None

Original exception that caused this to be raised.

Project Versions

Table Of Contents

Previous topic

Troubleshooting

Next topic

Developer Setup

This Page