From 6a93bb4ef7d832419b2c607af20384556b5cbeea Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Tue, 9 Jul 2013 12:31:01 -0700 Subject: basic_auth documentation --- docs/source/plugindocs/basic_auth.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/source/plugindocs/basic_auth.rst (limited to 'docs/source') 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 + -- cgit v1.2.3 From 2c4cdd096f77772ae1f07a163e68c033c0fe1b2c Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Tue, 9 Jul 2013 12:34:13 -0700 Subject: added openid docs --- docs/source/plugindocs/openid.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/source/plugindocs/openid.rst (limited to 'docs/source') 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 + -- cgit v1.2.3 From bd0ece0557d7ac4cbbf77617b125060b8c083892 Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Tue, 9 Jul 2013 12:57:57 -0700 Subject: added basic_auth and openid docs to index and link them together --- docs/source/index.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/source') 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 -- cgit v1.2.3 From 26d2cce85ef629a58d80def85fcda8e324d5d182 Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Tue, 9 Jul 2013 13:31:32 -0700 Subject: added docs for the persona plugin --- docs/source/index.rst | 1 + docs/source/plugindocs/persona.rst | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 docs/source/plugindocs/persona.rst (limited to 'docs/source') 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 + -- cgit v1.2.3 From d194770dd24c70cf1306d1287ec2cf82f07e2107 Mon Sep 17 00:00:00 2001 From: Rodney Ewing Date: Wed, 10 Jul 2013 13:29:58 -0700 Subject: 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 (limited to 'docs/source') 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. -- cgit v1.2.3 From be7f90b3f537190d199989625f75d334dbca7080 Mon Sep 17 00:00:00 2001 From: xray7224 Date: Mon, 1 Jul 2013 19:13:07 +0100 Subject: Adds the docs for client registration --- docs/source/api/client_register.rst | 158 ++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 docs/source/api/client_register.rst (limited to 'docs/source') diff --git a/docs/source/api/client_register.rst b/docs/source/api/client_register.rst new file mode 100644 index 00000000..088eb51d --- /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 + . + +==================== +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 `_, 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 JSON + This is caused when you have an error in your JSON, you may want to use a JSON validator to ensure that your JSON is correct. + +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 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 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 is not a valid URI + This is when your URI is invalid. + + -- cgit v1.2.3 From d41c6a5349db0ac573e8f0d29d239febc705f7c9 Mon Sep 17 00:00:00 2001 From: xray7224 Date: Mon, 8 Jul 2013 20:35:03 +0100 Subject: Adds oauth support up until authorization --- docs/source/api/client_register.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/source') diff --git a/docs/source/api/client_register.rst b/docs/source/api/client_register.rst index 088eb51d..4ad7908e 100644 --- a/docs/source/api/client_register.rst +++ b/docs/source/api/client_register.rst @@ -113,8 +113,8 @@ Errors There are a number of errors you could get back, This explains what could cause some of them: -Could not decode JSON - This is caused when you have an error in your JSON, you may want to use a JSON validator to ensure that your JSON is correct. +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. -- cgit v1.2.3 From 86ba41688332e3f71779f76c486889a7a099fa91 Mon Sep 17 00:00:00 2001 From: xray7224 Date: Tue, 16 Jul 2013 19:19:49 +0100 Subject: Adds some tests for the OAuth and some docs --- docs/source/api/oauth.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/source/api/oauth.rst (limited to 'docs/source') 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 + . + +============== +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 `_. +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. + -- cgit v1.2.3