blob: e5a1dc3aabffd74288d7aba1e61accb7830119d1 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
==============
OAuth plugin
==============
.. warning::
In its current state. This plugin has received no security audit.
Development has been entirely focused on Making It Work(TM). Use this
plugin with caution.
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* receives 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/
and if you're unsure about anything, there's the `OAuth v2.25 draft
<http://tools.ietf.org/html/draft-ietf-oauth-v2-25>`_, the `OAuth plugin
source code
<http://gitorious.org/mediagoblin/mediagoblin/trees/master/mediagoblin/plugins/oauth>`_
and the `#mediagoblin IRC channel <http://mediagoblin.org/pages/join.html#irc>`_.
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
<http://issues.mediagoblin.org/ticket/497>`_
- `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
|
