From 6a93bb4ef7d832419b2c607af20384556b5cbeea Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Tue, 9 Jul 2013 12:31:01 -0700 Subject: [PATCH 1/6] basic_auth documentation --- docs/source/plugindocs/basic_auth.rst | 2 ++ mediagoblin/plugins/basic_auth/README.rst | 22 ++++++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 docs/source/plugindocs/basic_auth.rst create mode 100644 mediagoblin/plugins/basic_auth/README.rst 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/mediagoblin/plugins/basic_auth/README.rst b/mediagoblin/plugins/basic_auth/README.rst new file mode 100644 index 00000000..65a7345e --- /dev/null +++ b/mediagoblin/plugins/basic_auth/README.rst @@ -0,0 +1,22 @@ +=================== + 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 From 2c4cdd096f77772ae1f07a163e68c033c0fe1b2c Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Tue, 9 Jul 2013 12:34:13 -0700 Subject: [PATCH 2/6] added openid docs --- docs/source/plugindocs/openid.rst | 2 ++ mediagoblin/plugins/openid/README.rst | 32 +++++++++++++++++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 docs/source/plugindocs/openid.rst create mode 100644 mediagoblin/plugins/openid/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/mediagoblin/plugins/openid/README.rst b/mediagoblin/plugins/openid/README.rst new file mode 100644 index 00000000..e753b0f9 --- /dev/null +++ b/mediagoblin/plugins/openid/README.rst @@ -0,0 +1,32 @@ +=================== + 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 :reg:`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. From bd0ece0557d7ac4cbbf77617b125060b8c083892 Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Tue, 9 Jul 2013 12:57:57 -0700 Subject: [PATCH 3/6] added basic_auth and openid docs to index and link them together --- docs/source/index.rst | 2 ++ mediagoblin/plugins/basic_auth/README.rst | 6 ++++-- mediagoblin/plugins/openid/README.rst | 12 +++++++----- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index c8a3f040..f6bc5561 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -59,6 +59,8 @@ Part 2: Core plugin documentation plugindocs/oauth plugindocs/trim_whitespace plugindocs/raven + plugindocs/basic_auth + plugindocs/openid Part 3: Plugin Writer's Guide diff --git a/mediagoblin/plugins/basic_auth/README.rst b/mediagoblin/plugins/basic_auth/README.rst index 65a7345e..82f247ed 100644 --- a/mediagoblin/plugins/basic_auth/README.rst +++ b/mediagoblin/plugins/basic_auth/README.rst @@ -1,5 +1,7 @@ +.. _basic_auth-chapter: + =================== - Basic_auth plugin + basic_auth plugin =================== The basic_auth plugin is enabled by default in mediagoblin.ini. This plugin @@ -8,7 +10,7 @@ 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 +Set up the basic_auth plugin ============================ 1. Add the following to your MediaGoblin .ini file in the ``[plugins]`` section:: diff --git a/mediagoblin/plugins/openid/README.rst b/mediagoblin/plugins/openid/README.rst index e753b0f9..870a2b58 100644 --- a/mediagoblin/plugins/openid/README.rst +++ b/mediagoblin/plugins/openid/README.rst @@ -1,21 +1,23 @@ +.. _openid-chapter: + =================== - Openid plugin + openid plugin =================== -The Openid plugin allows user to login to your GNU Mediagoblin instance using +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 :reg:`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 + 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 +Set up the openid plugin ============================ 1. Install the ``python-openid`` package. From 26d2cce85ef629a58d80def85fcda8e324d5d182 Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Tue, 9 Jul 2013 13:31:32 -0700 Subject: [PATCH 4/6] added docs for the persona plugin --- docs/source/index.rst | 1 + docs/source/plugindocs/persona.rst | 2 ++ mediagoblin/plugins/persona/README.rst | 41 ++++++++++++++++++++++++++ 3 files changed, 44 insertions(+) create mode 100644 docs/source/plugindocs/persona.rst create mode 100644 mediagoblin/plugins/persona/README.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index f6bc5561..0e7d0c2b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -61,6 +61,7 @@ Part 2: Core plugin documentation plugindocs/raven plugindocs/basic_auth plugindocs/openid + plugindocs/persona Part 3: Plugin Writer's Guide 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/mediagoblin/plugins/persona/README.rst b/mediagoblin/plugins/persona/README.rst new file mode 100644 index 00000000..fd086129 --- /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's 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's 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. From 94a566e60e79c39d74fdcbe668bca1d1d41d4aa3 Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Tue, 9 Jul 2013 13:41:40 -0700 Subject: [PATCH 5/6] typo --- mediagoblin/plugins/persona/README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mediagoblin/plugins/persona/README.rst b/mediagoblin/plugins/persona/README.rst index fd086129..ef19ac5d 100644 --- a/mediagoblin/plugins/persona/README.rst +++ b/mediagoblin/plugins/persona/README.rst @@ -5,7 +5,7 @@ ================ The persona plugin allows users to login to you GNU MediaGoblin instance using -`Mozilla's Persona`_. +`Mozilla Persona`_. This plugin can be enabled alongside :ref:`openid-chapter` and :ref:`basic_auth-chapter`. @@ -16,7 +16,7 @@ This plugin can be enabled alongside :ref:`openid-chapter` and password to their account, they can use the forgot password feature to do so. -.. _Mozilla's Persona: https://www.mozilla.org/en-US/persona/ +.. _Mozilla Persona: https://www.mozilla.org/en-US/persona/ Set up the persona plugin ========================= From d194770dd24c70cf1306d1287ec2cf82f07e2107 Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Wed, 10 Jul 2013 13:29:58 -0700 Subject: [PATCH 6/6] added docs explaining the authentication hooks --- docs/source/index.rst | 1 + docs/source/pluginwriter/authhooks.rst | 86 ++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 docs/source/pluginwriter/authhooks.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 0e7d0c2b..723dfaf8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -77,6 +77,7 @@ This guide covers writing new GNU MediaGoblin plugins. pluginwriter/database pluginwriter/api pluginwriter/tests + pluginwriter/authhooks Part 4: Developer's Zone 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.