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 | ||
81f73707 CAW |
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 | ||
df3147b9 JW |
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). | |
4427b1be | 96 | 3. The *client* receives the request from the *user agent*, attached is the |
df3147b9 JW |
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 | |
a7b8c214 JW |
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>`_. | |
df3147b9 JW |
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`_ | |
88a9662b | 129 | - `Client Registration`_ |
df3147b9 JW |
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 | |
88a9662b | 134 | .. _`Client Registration`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-2 |
df3147b9 JW |
135 | |
136 | Incapabilities | |
137 | ============== | |
138 | ||
88a9662b | 139 | - Only `bearer tokens`_ are issued. |
df3147b9 | 140 | - `Implicit Grant`_ |
111a609d JW |
141 | - `Force TLS for token endpoint`_ - This one is up the the siteadmin |
142 | - Authorization `scope`_ and `state` | |
df3147b9 JW |
143 | - ... |
144 | ||
88a9662b | 145 | .. _`bearer tokens`: http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-08 |
111a609d | 146 | .. _`scope`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-3.3 |
df3147b9 | 147 | .. _`Implicit Grant`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-4.2 |
111a609d | 148 | .. _`Force TLS for token endpoint`: http://tools.ietf.org/html/draft-ietf-oauth-v2-25#section-3.2 |