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