mediagoblin/plugins/oauth/README.rst

   1 ==============
   2  OAuth plugin
   3 ==============
   4
   5 .. warning::
   6     In its current state. This plugin has received no security audit.
   7     Development has been entirely focused on Making It Work(TM). Use this
   8     plugin with caution.
   9
  10     Additionally, this and the API may break... consider it pre-alpha.
  11     There's also a known issue that the OAuth client doesn't do
  12     refresh tokens so this might result in issues for users.
  13
  14 The OAuth plugin enables third party web applications to authenticate as one or
  15 more GNU MediaGoblin users in a safe way in order retrieve, create and update
  16 content stored on the GNU MediaGoblin instance.
  17
  18 The OAuth plugin is based on the `oauth v2.25 draft`_ and is pointing by using
  19 the ``oauthlib.oauth2.draft25.WebApplicationClient`` from oauthlib_ to a
  20 mediagoblin instance and building the OAuth 2 provider logic around the client.
  21
  22 There are surely some aspects of the OAuth v2.25 draft that haven't made it
  23 into this plugin due to the technique used to develop it.
  24
  25 .. _`oauth v2.25 draft`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25
  26 .. _oauthlib: http://pypi.python.org/pypi/oauthlib
  27
  28
  29 Set up the OAuth plugin
  30 =======================
  31
  32 1. Add the following to your MediaGoblin .ini file in the ``[plugins]`` section::
  33
  34     [[mediagoblin.plugins.oauth]]
  35
  36 2. Run::
  37
  38         gmg dbupdate
  39
  40    in order to create and apply migrations to any database tables that the
  41    plugin requires.
  42
  43 .. note::
  44     This only enables the OAuth plugin. To be able to let clients fetch data
  45     from the MediaGoblin instance you should also enable the API plugin or some
  46     other plugin that supports authenticating with OAuth credentials.
  47
  48
  49 Authenticate against GNU MediaGoblin
  50 ====================================
  51
  52 .. note::
  53     As mentioned in `capabilities`_ GNU MediaGoblin currently only supports the
  54     `Authorization Code Grant`_ procedure for obtaining an OAuth access token.
  55
  56 Authorization Code Grant
  57 ------------------------
  58
  59 .. note::
  60     As mentioned in `incapabilities`_ GNU MediaGoblin currently does not
  61     support `client registration`_
  62
  63 The `authorization code grant`_ works in the following way:
  64
  65 `Definitions`
  66
  67     Authorization server
  68         The GNU MediaGoblin instance
  69     Resource server
  70         Also the GNU MediaGoblin instance ;)
  71     Client
  72         The web application intended to use the data
  73     Redirect uri
  74         An URI pointing to a page controlled by the *client*
  75     Resource owner
  76         The GNU MediaGoblin user who's resources the client requests access to
  77     User agent
  78         Commonly the GNU MediaGoblin user's web browser
  79     Authorization code
  80         An intermediate token that is exchanged for an *access token*
  81     Access token
  82         A secret token that the *client* uses to authenticate itself agains the
  83         *resource server* as a specific *resource owner*.
  84
  85
  86 Brief description of the procedure
  87 ++++++++++++++++++++++++++++++++++
  88
  89 1. The *client* requests an *authorization code* from the *authorization
  90    server* by redirecting the *user agent* to the `Authorization Endpoint`_.
  91    Which parameters should be included in the redirect are covered later in
  92    this document.
  93 2. The *authorization server* authenticates the *resource owner* and redirects
  94    the *user agent* back to the *redirect uri* (covered later in this
  95    document).
  96 3. The *client* receives the request from the *user agent*, attached is the
  97    *authorization code*.
  98 4. The *client* requests an *access token* from the *authorization server*
  99 5. \?\?\?\?\?
 100 6. Profit!
 101
 102
 103 Detailed description of the procedure
 104 +++++++++++++++++++++++++++++++++++++
 105
 106 TBD, in the meantime here is a proof-of-concept GNU MediaGoblin client:
 107
 108 https://github.com/jwandborg/omgmg/
 109
 110 and here are some detailed descriptions from other OAuth 2
 111 providers:
 112
 113 - https://developers.google.com/accounts/docs/OAuth2WebServer
 114 - https://developers.facebook.com/docs/authentication/server-side/
 115
 116 and if you're unsure about anything, there's the `OAuth v2.25 draft
 117 <http://tools.ietf.org/html/draft-ietf-oauth-v2-25>`_, the `OAuth plugin
 118 source code
 119 <http://gitorious.org/mediagoblin/mediagoblin/trees/master/mediagoblin/plugins/oauth>`_
 120 and the `#mediagoblin IRC channel <http://mediagoblin.org/pages/join.html#irc>`_.
 121
 122
 123 Capabilities
 124 ============
 125
 126 - `Authorization endpoint`_ - Located at ``/oauth/authorize``
 127 - `Token endpoint`_ - Located at ``/oauth/access_token``
 128 - `Authorization Code Grant`_
 129 - `Client Registration`_
 130
 131 .. _`Authorization endpoint`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-3.1
 132 .. _`Token endpoint`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-3.2
 133 .. _`Authorization Code Grant`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-4.1
 134 .. _`Client Registration`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-2
 135
 136 Incapabilities
 137 ==============
 138
 139 - Only `bearer tokens`_ are issued.
 140 - `Implicit Grant`_
 141 - `Force TLS for token endpoint`_ - This one is up the the siteadmin
 142 - Authorization `scope`_ and `state`
 143 - ...
 144
 145 .. _`bearer tokens`: http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-08
 146 .. _`scope`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-3.3
 147 .. _`Implicit Grant`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-4.2
 148 .. _`Force TLS for token endpoint`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-3.2