Merge branch 'auth_docs'

Conflicts:
	docs/source/index.rst

8 files changed, 195 insertions, 0 deletions

diff --git a/docs/source/index.rst b/docs/source/index.rst
index de6c9c0d..777c4d26 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -59,6 +59,9 @@ Part 2: Core plugin documentation
    plugindocs/oauth
    plugindocs/trim_whitespace
    plugindocs/raven
+   plugindocs/basic_auth
+   plugindocs/openid
+   plugindocs/persona
 
 
 Part 3: Plugin Writer's Guide
@@ -75,6 +78,7 @@ This guide covers writing new GNU MediaGoblin plugins.
    pluginwriter/api
    pluginwriter/tests
    pluginwriter/media_type_hooks
+   pluginwriter/authhooks
 
 
 Part 4: Developer's Zone
diff --git a/docs/source/plugindocs/basic_auth.rst b/docs/source/plugindocs/basic_auth.rst
new file mode 100644
index 00000000..83492ac2
--- /dev/null
+++ b/docs/source/plugindocs/basic_auth.rst
@@ -0,0 +1,2 @@
+.. include:: ../../../mediagoblin/plugins/basic_auth/README.rst
+
diff --git a/docs/source/plugindocs/openid.rst b/docs/source/plugindocs/openid.rst
new file mode 100644
index 00000000..045bf9d0
--- /dev/null
+++ b/docs/source/plugindocs/openid.rst
@@ -0,0 +1,2 @@
+.. include:: ../../../mediagoblin/plugins/openid/README.rst
+
diff --git a/docs/source/plugindocs/persona.rst b/docs/source/plugindocs/persona.rst
new file mode 100644
index 00000000..2524127d
--- /dev/null
+++ b/docs/source/plugindocs/persona.rst
@@ -0,0 +1,2 @@
+.. include:: ../../../mediagoblin/plugins/persona/README.rst
+
diff --git a/docs/source/pluginwriter/authhooks.rst b/docs/source/pluginwriter/authhooks.rst
new file mode 100644
index 00000000..9721d729
--- /dev/null
+++ b/docs/source/pluginwriter/authhooks.rst
@@ -0,0 +1,86 @@
+======================
+ Authentication Hooks
+======================
+
+This documents the hooks that are currently available for authentication
+plugins. If you need new hooks for your plugin, go ahead a submit a patch.
+
+What hooks are available?
+=========================
+
+'authentication'
+----------------
+
+This hook just needs to return ``True`` as this is how 
+the MediaGoblin app knows that an authentication plugin is enabled.
+
+
+'auth_extra_validation'
+-----------------------
+
+This hook is used to provide any additional validation of the registration 
+form when using ``mediagoblin.auth.tools.register_user()``. This hook runs
+through all enabled auth plugins.
+
+
+'auth_create_user'
+------------------
+
+This hook is used by ``mediagoblin.auth.tools.register_user()`` so plugins can
+store the necessary information when creating a user. This hook runs through
+all enabled auth plugins.
+
+'auth_get_user'
+---------------
+
+This hook is used by ``mediagoblin.auth.tools.check_login_simple()``. Your
+plugin should return a ``User`` object given a username.
+
+'auth_no_pass_redirect'
+-----------------------
+
+This hook is called in ``mediagoblin.auth.views`` in both the ``login`` and 
+``register`` views. This hook should return the name of your plugin, so that
+if :ref:`basic_auth-chapter` is not enabled, the user will be redirected to the
+correct login and registration views for your plugin.
+
+The code assumes that it can generate a valid url given
+``mediagoblin.plugins.{{ your_plugin_here }}.login`` and
+``mediagoblin.plugins.{{ your_plugin_here }}.register``. This is only needed if
+you will not be using the ``login`` and ``register`` views in 
+``mediagoblin.auth.views``.
+
+'auth_get_login_form'
+---------------------
+
+This hook is called in ``mediagoblin.auth.views.login()``. If you are not using
+that view, then you do not need this hook. This hook should take a ``request``
+object and return the ``LoginForm`` for your plugin.
+
+'auth_get_registration_form'
+----------------------------
+
+This hook is called in ``mediagoblin.auth.views.register()``. If you are not
+using that view, then you do not need this hook. This hook should take a
+``request`` object and return the ``RegisterForm`` for your plugin.
+
+'auth_gen_password_hash'
+------------------------
+
+This hook should accept a ``raw_pass`` and an ``extra_salt`` and return a
+hashed password to be stored in ``User.pw_hash``.
+
+'auth_check_password'
+---------------------
+
+This hook should accept a ``raw_pass``, a ``stored_hash``, and an ``extra_salt``.
+Your plugin should then check that the ``raw_pass`` hashes to the same thing as
+the ``stored_hash`` and return either ``True`` or ``False``.
+
+'auth_fake_login_attempt'
+-------------------------
+
+This hook is called in ``mediagoblin.auth.tools.check_login_simple``. It is
+called if a user is not found and should do something that takes the same amount
+of time as your ``check_password`` function. This is to help prevent timining
+attacks.
diff --git a/mediagoblin/plugins/basic_auth/README.rst b/mediagoblin/plugins/basic_auth/README.rst
new file mode 100644
index 00000000..82f247ed
--- /dev/null
+++ b/mediagoblin/plugins/basic_auth/README.rst
@@ -0,0 +1,24 @@
+.. _basic_auth-chapter:
+
+===================
+ basic_auth plugin
+===================
+
+The basic_auth plugin is enabled by default in mediagoblin.ini. This plugin
+provides basic username and password authentication for GNU Mediagoblin.
+
+This plugin can be enabled alongside :ref:`openid-chapter` and
+:ref:`persona-chapter`.
+
+Set up the basic_auth plugin
+============================
+
+1. Add the following to your MediaGoblin .ini file in the ``[plugins]`` section::
+
+    [[mediagoblin.plugins.basic_auth]]
+
+2. Run::
+
+        gmg assetlink
+
+   in order to link basic_auth's static assets
diff --git a/mediagoblin/plugins/openid/README.rst b/mediagoblin/plugins/openid/README.rst
new file mode 100644
index 00000000..870a2b58
--- /dev/null
+++ b/mediagoblin/plugins/openid/README.rst
@@ -0,0 +1,34 @@
+.. _openid-chapter:
+
+===================
+ openid plugin
+===================
+
+The openid plugin allows user to login to your GNU Mediagoblin instance using
+their openid url.
+
+This plugin can be enabled alongside :ref:`basic_auth-chapter` and
+:ref:`persona-chapter`.
+
+.. note::
+    When :ref:`basic_auth-chapter` is enabled alongside this openid plugin, and
+    a user creates an account using their openid. If they would like to add a
+    password to their account, they can use the forgot password feature to do
+    so.
+
+
+Set up the openid plugin
+============================
+
+1. Install the ``python-openid`` package.
+
+2. Add the following to your MediaGoblin .ini file in the ``[plugins]`` section::
+
+    [[mediagoblin.plugins.openid]]
+
+3. Run::
+
+        gmg dbupdate
+
+   in order to create and apply migrations to any database tables that the
+   plugin requires.
diff --git a/mediagoblin/plugins/persona/README.rst b/mediagoblin/plugins/persona/README.rst
new file mode 100644
index 00000000..ef19ac5d
--- /dev/null
+++ b/mediagoblin/plugins/persona/README.rst
@@ -0,0 +1,41 @@
+.. _persona-chapter:
+
+================
+ persona plugin
+================
+
+The persona plugin allows users to login to you GNU MediaGoblin instance using
+`Mozilla Persona`_.
+
+This plugin can be enabled alongside :ref:`openid-chapter` and
+:ref:`basic_auth-chapter`.
+
+.. note::
+    When :ref:`basic_auth-chapter` is enabled alongside this persona plugin, and
+    a user creates an account using their persona. If they would like to add a
+    password to their account, they can use the forgot password feature to do
+    so.
+
+.. _Mozilla Persona: https://www.mozilla.org/en-US/persona/
+
+Set up the persona plugin
+=========================
+
+1. Install the ``requests`` package.
+
+2. Add the following to your MediaGoblin .ini file in the ``[plugins]`` section::
+
+    [[mediagoblin.plugins.persona]]
+
+3. Run::
+
+        gmg dbupdate
+
+   in order to create and apply migrations to any database tables that the
+   plugin requires.
+
+4. Run::
+
+        gmg assetlink
+
+   in order to persona's static assets.