Resolve merge conflict and merge.

7 files changed, 290 insertions, 0 deletions

diff --git a/docs/source/api/client_register.rst b/docs/source/api/client_register.rst
new file mode 100644
index 00000000..4ad7908e
--- /dev/null
+++ b/docs/source/api/client_register.rst
@@ -0,0 +1,158 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+====================
+Registering a Client
+====================
+
+To use the GNU MediaGoblin API you need to use the dynamic client registration. This has been adapted from the `OpenID specification <https://openid.net/specs/openid-connect-registration-1_0.html>`_, this is the only part of OpenID that is being used to serve the purpose to provide the client registration which is used in OAuth. 
+
+The endpoint is ``/api/client/register``
+
+The parameters are:
+
+type
+    **required** - This must be either *client_associate* (for new registration) or *client_update*
+
+client_id
+    **update only** - This should only be used updating client information, this is the client_id given when you register
+
+client_secret
+    **update only** - This should only be used updating client information, this is the client_secret given when you register
+
+contacts
+    **optional** - This a space seporated list of email addresses to contact of people responsible for the client
+
+application_type
+    **required** - This is the type of client you are making, this must be either *web* or *native*
+
+application_name
+    **optional** - This is the name of your client
+
+logo_url
+    **optional** - This is a URL of the logo image for your client
+
+redirect_uri
+    **optional** - This is a space seporated list of pre-registered URLs for use at the Authorization Server
+
+
+Response
+--------
+
+You will get back a response::
+
+client_id
+    This identifies a client
+
+client_secret
+    This is the secret.
+
+expires_at
+    This is time that the client credentials expire. If this is 0 the client registration does not expire.
+
+=======
+Example
+=======
+
+Register Client
+---------------
+
+To register a client for the first time, this is the minimum you must supply::
+
+    {
+        "type": "client_associate",
+        "application_type": "native"
+    }
+
+A Response will look like::
+
+    {
+        "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb",
+        "expires_at": 0,
+        "client_id": "vwljdhUMhhNbdKizpjZlxv"
+    }
+
+
+Updating Client
+---------------
+
+Using the response we got above we can update the information and add new information we may have opted not to supply::
+
+    {
+        "type": "client_update",
+        "client_id": "vwljdhUMhhNbdKizpjZlxv",
+        "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb",
+        "application_type": "web",
+        "application_name": "MyClient!", 
+        "logo_url": "https://myclient.org/images/my_logo.png",
+        "contacts": "myemail@someprovider.com another_developer@provider.net",
+    }
+
+The response will just return back the client_id and client_secret you sent::
+
+    {
+        "client_id": "vwljdhUMhhNbdKizpjZlxv",
+        "client_secret": "hJtfhaQzgKerlLVdaeRAgmbcstSOBLRfgOinMxBCHcb",
+        "expires_at": 0
+    }
+
+
+======
+Errors
+======
+
+There are a number of errors you could get back, This explains what could cause some of them:
+
+Could not decode data
+    This is caused when you have an error in the encoding of your data.
+
+Unknown Content-Type
+    You should sent a Content-Type header with when you make a request, this should be either application/json or www-form-urlencoded. This is caused when a unknown Content-Type is used.
+
+No registration type provided
+    This is when you leave out the ``type``. This should either be client_update or client_associate
+
+Unknown application_type.
+    This is when you have provided a ``type`` however this isn't one of the known types.
+
+client_id is required to update.
+    When you try and update you need to specify the client_id, this will be what you were given when you initially registered the client.
+
+client_secret is required to update.
+    When you try to update you need to specify the client_secrer, this will be what you were given when you initially register the client.
+
+Unauthorized.
+    This is when you are trying to update however the client_id and/or client_secret you have submitted are incorrect.
+
+Only set client_id for update.
+    This should only be given when you update.
+
+Only set client_secret for update.
+    This should only be given when you update.
+
+Logo URL <url> is not a valid URL
+    This is when the URL specified did not meet the validation.
+
+contacts must be a string of space-separated email addresses.
+    ``contacts`` should be a string (not a list), ensure each email is seporated by a space
+
+Email <email> is not a valid email
+    This is when you have submitted an invalid email address
+
+redirect_uris must be space-separated URLs.
+    ``redirect_uris`` should be a string (not a list), ensure each URL is seporated by a space
+
+URI <URI> is not a valid URI
+    This is when your URI is invalid.
+
+ 
diff --git a/docs/source/api/oauth.rst b/docs/source/api/oauth.rst
new file mode 100644
index 00000000..003ad492
--- /dev/null
+++ b/docs/source/api/oauth.rst
@@ -0,0 +1,36 @@
+.. MediaGoblin Documentation
+
+   Written in 2011, 2012 by MediaGoblin contributors
+
+   To the extent possible under law, the author(s) have dedicated all
+   copyright and related and neighboring rights to this software to
+   the public domain worldwide. This software is distributed without
+   any warranty.
+
+   You should have received a copy of the CC0 Public Domain
+   Dedication along with this software. If not, see
+   <http://creativecommons.org/publicdomain/zero/1.0/>.
+
+==============
+Authentication
+==============
+
+GNU MediaGoblin uses OAuth1 to authenticate requests to the API. There are many
+libraries out there for OAuth1, you're likely not going to have to do much. There
+is a library for the GNU MediaGoblin called `PyPump <https://github.com/xray7224/PyPump>`_.
+We are not using OAuth2 as we want to stay completely compatable with GNU MediaGoblin.
+
+
+We use :doc:`client_register` to get the client ID and secret.
+
+Endpoints
+---------
+
+These are the endpoints you need to use for the oauth requests:
+
+`/oauth/request_token` is for getting the request token.
+
+`/oauth/authorize` is to send the user to to authorize your application.
+
+`/oauth/access_token` is for getting the access token to use in requests.
+
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.