============================================
Cookie credentials and sign-up authenticator
============================================

This document describes how two custom plug-ins for the Pluggable
Authenication Utility (PAU) from the ``worldcookery`` package work
from the end user point of view.  The plug-ins are:

* a cookie credentials plug-in that stores the user's credentials in a
  cookie.  It supports challenging users for credentials by
  redirecting to a login form.

* a sign-up authenticator plug-in that stores user login information
  persistently in the ZODB and allows new users to sign up for an
  account.


Signing up
----------

The plug-ins already exist and are configured.  To sign up for a new
user account, we open a new browser and first assert that we are not
logged in yet.

  >>> from zope.testbrowser.testing import Browser
  >>> browser = Browser()
  >>> browser.open('http://localhost/')
  >>> 'Unauthenticated User' in browser.contents
  True

The login page will take us to a sign up form where we can enter our
login information:

  >>> browser.getLink('[Login]').click()
  >>> browser.getLink('Sign up for a user account now!').click()
  >>> browser.getControl(name='login').value = 'jdoe'
  >>> browser.getControl(name='title').value = 'John Doe'
  >>> browser.getControl(name='password').value = 'ilovejane'
  >>> browser.getControl(name='confirmation').value = 'ilovejane'
  >>> browser.getControl('Sign up').click()

Now we are no longer the unauthenticated user:

  >>> 'Unauthenticated User' in browser.contents
  False
  >>> 'John Doe' in browser.contents
  True


Logging in and out
------------------

Let us log out again to try this once more:

  >>> browser.getLink('[Logout]').click()
  >>> 'Unauthenticated User' in browser.contents
  True

Now log in again

  >>> browser.getLink('[Login]').click()
  >>> browser.getControl(name='login').value = 'jdoe'
  >>> browser.getControl(name='password').value = 'ilovejane'
  >>> browser.getControl('Log in').click()

and we are back to being authenticated:

  >>> 'Unauthenticated User' in browser.contents
  False
  >>> 'John Doe' in browser.contents
  True


Changing passwords
------------------

Users can also change their full name and password:

  >>> browser.open('http://localhost/changePassword.html')
  >>> browser.getControl(name='title').value = 'Jane Doe'
  >>> browser.getControl(name='password').value = 'ilovejohn'
  >>> browser.getControl(name='confirmation').value = 'ilovejohn'
  >>> browser.getControl('Change').click()

After changing the password, we are the unauthenticated principal
again because the credentials cookie has not been updated:

  >>> 'Unauthenticated User' in browser.contents
  True

But we can log in again:

  >>> browser.getLink('[Login]').click()
  >>> browser.getControl(name='login').value = 'jdoe'
  >>> browser.getControl(name='password').value = 'ilovejohn'
  >>> browser.getControl('Log in').click()

and we are back to being authenticated:

  >>> 'Unauthenticated User' in browser.contents
  False
  >>> 'Jane Doe' in browser.contents
  True

It is also possible to just change the full name without changing the
password:

  >>> browser.open('http://localhost/changePassword.html')
  >>> browser.getControl(name='title').value = 'Jenny Doe'
  >>> browser.getControl('Change').click()

  >>> 'Unauthenticated User' in browser.contents
  False
  >>> 'Jenny Doe' in browser.contents
  True
