Support sites that don't want to create user accounts automatically b…

…ut still want details of a verified assertion (including docs in the README)

README.rst

@@ -69,6 +69,44 @@ Finally, you'll need some Javascript to handle the onclick event. If you use ``d
      });
    });
 
+Creating User Accounts
+----------------------
+
+``django-browserid`` will automatically create a user account for new users if the setting ``BROWSERID_CREATE_USER`` is set to ``True`` in ``settings.py``. 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. 
+
+If you do not wish to automatically create user accounts, you may manually verify a BrowserID assertion with something like the following: ::
+
+   from django_browserid.auth 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():
+              # do something
+          host = request.get_host()
+          if ':' in host:
+              host, port = host.split(':')
+          else:
+              port = '80'
+          audience = get_audience(host, port)
+          result = verify(form.cleaned_data['assertion'], audience)
+          # ...
+
+``result`` will be False if the assertion failed, or a dictionary similar to the following: ::
+
+   {
+      u'audience': u'mysite.com:443',
+      u'email': u'myemail@example.com',
+      u'issuer': u'browserid.org:443',
+      u'status': u'okay',
+      u'valid-until': 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.
+
 License
 -------
 

django_browserid/auth.py

@@ -24,12 +24,12 @@ class BrowserIDBackend(object):
     supports_anonymous_user = False
     supports_object_permissions = False
 
-    def _construct_audience(self, host, port):
+    def get_audience(self, host, port):
         if port and port != DEFAULT_HTTP_PORT:
             return u'%s:%s' % (host, port)
         return host
 
-    def _verify(self, assertion, audience):
+    def verify(self, assertion, audience):
         """Verify assertion using an external verification service."""
         verify_url = getattr(settings, 'BROWSERID_VERIFICATION_URL',
                              DEFAULT_VERIFICATION_URL)
@@ -43,7 +43,7 @@ def _verify(self, assertion, audience):
         return False
 
     def authenticate(self, assertion=None, host=None, port=None):
-        result = self._verify(assertion, self._construct_audience(host, port))
+        result = self.verify(assertion, self.get_audience(host, port))
         if result is None:
             return None
         email = result['email']