From df3147b986b183198d6419c50ca743e4f0c1bdea Mon Sep 17 00:00:00 2001 From: Joar Wandborg Date: Tue, 18 Sep 2012 21:42:10 +0200 Subject: [PATCH] Added documentation for the OAuth plugin --- docs/source/index.rst | 1 + docs/source/plugindocs/oauth.rst | 1 + mediagoblin/plugins/oauth/README.rst | 130 +++++++++++++++++++++++++++ 3 files changed, 132 insertions(+) create mode 100644 docs/source/plugindocs/oauth.rst create mode 100644 mediagoblin/plugins/oauth/README.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 6671a6e3..ac8bd110 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -57,6 +57,7 @@ Part 2: Core plugin documentation plugindocs/flatpagesfile plugindocs/sampleplugin + plugindocs/oauth Part 3: Plugin Writer's Guide diff --git a/docs/source/plugindocs/oauth.rst b/docs/source/plugindocs/oauth.rst new file mode 100644 index 00000000..0685c9d1 --- /dev/null +++ b/docs/source/plugindocs/oauth.rst @@ -0,0 +1 @@ +.. include:: ../../../mediagoblin/plugins/oauth/README.rst diff --git a/mediagoblin/plugins/oauth/README.rst b/mediagoblin/plugins/oauth/README.rst new file mode 100644 index 00000000..cd2edc0e --- /dev/null +++ b/mediagoblin/plugins/oauth/README.rst @@ -0,0 +1,130 @@ +============== + OAuth plugin +============== + +The OAuth plugin enables third party web applications to authenticate as one or +more GNU MediaGoblin users in a safe way in order retrieve, create and update +content stored on the GNU MediaGoblin instance. + +The OAuth plugin is based on the `oauth v2.25 draft`_ and is pointing by using +the ``oauthlib.oauth2.draft25.WebApplicationClient`` from oauthlib_ to a +mediagoblin instance and building the OAuth 2 provider logic around the client. + +There are surely some aspects of the OAuth v2.25 draft that haven't made it +into this plugin due to the technique used to develop it. + +.. _`oauth v2.25 draft`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25 +.. _oauthlib: http://pypi.python.org/pypi/oauthlib + + +Set up the OAuth plugin +======================= + +1. Add the following to your MediaGoblin .ini file in the ``[plugins]`` section:: + + [[mediagoblin.plugins.oauth]] + +2. Run:: + + gmg dbupdate + + in order to create and apply migrations to any database tables that the + plugin requires. + +.. note:: + This only enables the OAuth plugin. To be able to let clients fetch data + from the MediaGoblin instance you should also enable the API plugin or some + other plugin that supports authenticating with OAuth credentials. + + +Authenticate against GNU MediaGoblin +==================================== + +.. note:: + As mentioned in `capabilities`_ GNU MediaGoblin currently only supports the + `Authorization Code Grant`_ procedure for obtaining an OAuth access token. + +Authorization Code Grant +------------------------ + +.. note:: + As mentioned in `incapabilities`_ GNU MediaGoblin currently does not + support `client registration`_ + +The `authorization code grant`_ works in the following way: + +`Definitions` + + Authorization server + The GNU MediaGoblin instance + Resource server + Also the GNU MediaGoblin instance ;) + Client + The web application intended to use the data + Redirect uri + An URI pointing to a page controlled by the *client* + Resource owner + The GNU MediaGoblin user who's resources the client requests access to + User agent + Commonly the GNU MediaGoblin user's web browser + Authorization code + An intermediate token that is exchanged for an *access token* + Access token + A secret token that the *client* uses to authenticate itself agains the + *resource server* as a specific *resource owner*. + + +Brief description of the procedure +++++++++++++++++++++++++++++++++++ + +1. The *client* requests an *authorization code* from the *authorization + server* by redirecting the *user agent* to the `Authorization Endpoint`_. + Which parameters should be included in the redirect are covered later in + this document. +2. The *authorization server* authenticates the *resource owner* and redirects + the *user agent* back to the *redirect uri* (covered later in this + document). +3. The *client* recieves the request from the *user agent*, attached is the + *authorization code*. +4. The *client* requests an *access token* from the *authorization server* +5. \?\?\?\?\? +6. Profit! + + +Detailed description of the procedure ++++++++++++++++++++++++++++++++++++++ + +TBD, in the meantime here is a proof-of-concept GNU MediaGoblin client: + +https://github.com/jwandborg/omgmg/ + +and here are some detailed descriptions from other OAuth 2 +providers: + +- https://developers.google.com/accounts/docs/OAuth2WebServer +- https://developers.facebook.com/docs/authentication/server-side/ ( + + +Capabilities +============ + +- `Authorization endpoint`_ - Located at ``/oauth/authorize`` +- `Token endpoint`_ - Located at ``/oauth/access_token`` +- `Authorization Code Grant`_ + +.. _`Authorization endpoint`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-3.1 +.. _`Token endpoint`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-3.2 +.. _`Authorization Code Grant`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-4.1 + +Incapabilities +============== + +- `Client Registration`_ - `planned feature + `_ +- `Access Token Scope`_ +- `Implicit Grant`_ +- ... + +.. _`Client Registration`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-2 +.. _`Access Token Scope`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-3.3 +.. _`Implicit Grant`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-4.2 -- 2.25.1