summaryrefslogtreecommitdiffstats
path: root/gluster/swift/common/middleware/gswauth/doc/source/api.rst
blob: d2efa0f1f43841499ecc609c32ed9c2016bd4577 (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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
.. _api_top:

----------
Swauth API
----------

Overview
========

Swauth has its own internal versioned REST API for adding, removing,
and editing accounts.  This document explains the v2 API.

Authentication
--------------

Each REST request against the swauth API requires the inclusion of a
specific authorization user and key to be passed in a specific HTTP
header.  These headers are defined as ``X-Auth-Admin-User`` and
``X-Auth-Admin-Key``.

Typically, these values are ``.super_admin`` (the site super admin
user) with the key being specified in the swauth middleware
configuration as ``super_admin_key``.

This could also be a reseller admin with the appropriate rights to
perform actions on reseller accounts.

Endpoints
---------

The swauth API endpoint is presented on the proxy servers, in the
"/auth" namespace.  In addition, the API is versioned, and the version
documented is version 2.  API versions subdivide the auth namespace by
version, specified as a version identifier like "v2".

The auth endpoint described herein is therefore located at "/auth/v2/"
as presented by the proxy servers.

Bear in mind that in order for the auth management API to be
presented, it must be enabled in the proxy server config by setting
``allow_account_managment`` to ``true`` in the ``[app:proxy-server]``
stanza of your proxy-server.conf.

Responses
---------

Responses from the auth APIs are returned as a JSON structure.
Example return values in this document are edited for readability.


Reseller/Admin Services
=======================

Operations can be performed against the endpoint itself to perform
general administrative operations.  Currently, the only operations
that can be performed is a GET operation to get reseller or site admin
information.

Get Admin Info
--------------

A GET request at the swauth endpoint will return reseller information
for the account specified in the ``X-Auth-Admin-User`` header.
Currently, the information returned is limited to a list of accounts
for the reseller or site admin.

Valid return codes:
  * 200: Success
  * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
  * 5xx: Internal error

Example Request::

    GET /auth/<api version>/ HTTP/1.1
    X-Auth-Admin-User: .super_admin
    X-Auth-Admin-Key: swauthkey

Example Curl Request::

    curl -D - https://<endpoint>/auth/v2/ \
    -H "X-Auth-Admin-User: .super_admin" \
    -H "X-Auth-Admin-Key: swauthkey"

Example Result::

    HTTP/1.1 200 OK

    { "accounts":
      [
        { "name": "account1" },
        { "name": "account2" },
        { "name": "account3" }
      ]
    }


Account Services
================

There are API request to get account details, create, and delete
accounts, mapping logically to the REST verbs GET, PUT, and DELETE.
These actions are performed against an account URI, in the following
general request structure::

    METHOD /auth/<version>/<account> HTTP/1.1

The methods that can be used are detailed below.

Get Account Details
-------------------

Account details can be retrieved by performing a GET request against
an account URI.  On success, a JSON dictionary will be returned
containing the keys `account_id`, `services`, and `users`.  The
`account_id` is the value used when creating service accounts.  The
`services` value is a dict that represents valid storage cluster
endpoints, and which endpoint is the default.  The 'users' value is a
list of dicts, each dict representing a user and currently only
containing the single key 'name'.

Valid Responses:
  * 200: Success
  * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
  * 5xx: Internal error

Example Request::

    GET /auth/<api version>/<account> HTTP/1.1
    X-Auth-Admin-User: .super_admin
    X-Auth-Admin-Key: swauthkey

Example Curl Request::

    curl -D - https://<endpoint>/auth/v2/<account> \
    -H "X-Auth-Admin-User: .super_admin" \
    -H "X-Auth-Admin-Key: swauthkey"

Example Response::

    HTTP/1.1 200 OK

    { "services":
      { "storage":
        { "default": "local",
          "local": "https://<storage endpoint>/v1/<account_id>" },
      },
      "account_id": "<account_id>",
      "users": [ { "name": "user1" },
                 { "name": "user2" } ]
    }

Create Account
--------------

An account can be created with a PUT request against a non-existent
account.  By default, a newly created UUID4 will be used with the
reseller prefix as the account ID used when creating corresponding
service accounts.  However, you can provide an X-Account-Suffix header
to replace the UUDI4 part.

Valid return codes:
  * 200: Success
  * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
  * 5xx: Internal error

Example Request::

    GET /auth/<api version>/<new_account> HTTP/1.1
    X-Auth-Admin-User: .super_admin
    X-Auth-Admin-Key: swauthkey

Example Curl Request::

    curl -D - https://<endpoint>/auth/v2/<new_account> \
    -H "X-Auth-Admin-User: .super_admin" \
    -H "X-Auth-Admin-Key: swauthkey"

Example Response::

    HTTP/1.1 201 Created


Delete Account
--------------

An account can be deleted with a DELETE request against an existing
account.

Valid Responses:
  * 204: Success
  * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
  * 404: Account not found
  * 5xx: Internal error

Example Request::

    DELETE /auth/<api version>/<account> HTTP/1.1
    X-Auth-Admin-User: .super_admin
    X-Auth-Admin-Key: swauthkey

Example Curl Request::

    curl -XDELETE -D - https://<endpoint>/auth/v2/<account> \
    -H "X-Auth-Admin-User: .super_admin" \
    -H "X-Auth-Admin-Key: swauthkey"

Example Response::

    HTTP/1.1 204 No Content


User Services
=============

Each account in swauth contains zero or more users.  These users can
be determined with the 'Get Account Details' API request against an
account.

Users in an account can be created, modified, and detailed as
described below by apply the appropriate REST verbs to a user URI, in
the following general request structure::

    METHOD /auth/<version>/<account>/<user> HTTP/1.1

The methods that can be used are detailed below.

Get User Details
----------------

User details can be retrieved by performing a GET request against
a user URI.  On success, a JSON dictionary will be returned as
described::

    {"groups": [  # List of groups the user is a member of
	{"name": "<act>:<usr>"},
	    # The first group is a unique user identifier
	{"name": "<account>"},
	    # The second group is the auth account name
	{"name": "<additional-group>"}
	    # There may be additional groups, .admin being a
	    # special group indicating an account admin and
	    # .reseller_admin indicating a reseller admin.
     ],
     "auth": "<auth-type>:<key>"
     # The auth-type and key for the user; currently only
     # plaintext and sha1 are implemented as auth types.
    }

For example::

    {"groups": [{"name": "test:tester"}, {"name": "test"},
                {"name": ".admin"}],
     "auth": "plaintext:testing"}

Valid Responses:
  * 200: Success
  * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
  * 404: Unknown account
  * 5xx: Internal error

Example Request::

    GET /auth/<api version>/<account>/<user> HTTP/1.1
    X-Auth-Admin-User: .super_admin
    X-Auth-Admin-Key: swauthkey

Example Curl Request::

    curl -D - https://<endpoint>/auth/v2/<account>/<user> \
    -H "X-Auth-Admin-User: .super_admin" \
    -H "X-Auth-Admin-Key: swauthkey"

Example Response::

    HTTP/1.1 200 Ok

    { "groups": [ { "name": "<account>:<user>" },
                  { "name": "<user>" },
                  { "name": ".admin" } ],
      "auth" : "plaintext:password" }


Create User
-----------

A user can be created with a PUT request against a non-existent
user URI.  The new user's password must be set using the
``X-Auth-User-Key`` header.  The user name MUST NOT start with a
period ('.').  This requirement is enforced by the API, and will
result in a 400 error.

Optional Headers:

 * ``X-Auth-User-Admin: true``: create the user as an account admin
 * ``X-Auth-User-Reseller-Admin: true``: create the user as a reseller
   admin

Reseller admin accounts can only be created by the site admin, while
regular accounts (or account admin accounts) can be created by an
account admin, an appropriate reseller admin, or the site admin.

Note that PUT requests are idempotent, and the PUT request serves as
both a request and modify action.

Valid Responses:
  * 200: Success
  * 400: Invalid request (missing required headers)
  * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key, or insufficient priv
  * 404: Unknown account
  * 5xx: Internal error

Example Request::

    PUT /auth/<api version>/<account>/<user> HTTP/1.1
    X-Auth-Admin-User: .super_admin
    X-Auth-Admin-Key: swauthkey
    X-Auth-User-Admin: true
    X-Auth-User-Key: secret

Example Curl Request::

    curl -XPUT -D - https://<endpoint>/auth/v2/<account>/<user> \
    -H "X-Auth-Admin-User: .super_admin" \
    -H "X-Auth-Admin-Key: swauthkey" \
    -H "X-Auth-User-Admin: true" \
    -H "X-Auth-User-Key: secret"

Example Response::

    HTTP/1.1 201 Created

Delete User
-----------

A user can be deleted by performing a DELETE request against a user
URI.  This action can only be performed by an account admin,
appropriate reseller admin, or site admin.

Valid Responses:
  * 200: Success
  * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key, or insufficient priv
  * 404: Unknown account or user
  * 5xx: Internal error

Example Request::

    DELETE /auth/<api version>/<account>/<user> HTTP/1.1
    X-Auth-Admin-User: .super_admin
    X-Auth-Admin-Key: swauthkey

Example Curl Request::

    curl -XDELETE -D - https://<endpoint>/auth/v2/<account>/<user> \
    -H "X-Auth-Admin-User: .super_admin" \
    -H "X-Auth-Admin-Key: swauthkey"

Example Response::

    HTTP/1.1 204 No Content


Other Services
==============

There are several other swauth functions that can be performed, mostly
done via "pseudo-user" accounts.  These are well-known user names that
are unable to be actually provisioned.  These pseudo-users are
described below.

.. _api_set_service_endpoints:

Set Service Endpoints
---------------------

Service endpoint information can be retrived using the _`Get Account
Details` API method.

This function allows setting values within this section for
the <account>, allowing the addition of new service end points
or updating existing ones by performing a POST to the URI
corresponding to the pseudo-user ".services".

The body of the POST request should contain a JSON dict with
the following format::

    {"service_name": {"end_point_name": "end_point_value"}}

There can be multiple services and multiple end points in the
same call.

Any new services or end points will be added to the existing
set of services and end points. Any existing services with the
same service name will be merged with the new end points. Any
existing end points with the same end point name will have
their values updated.

The updated services dictionary will be returned on success.

Valid Responses:

  * 200: Success
  * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
  * 404: Account not found
  * 5xx: Internal error

Example Request::

    POST /auth/<api version>/<account>/.services HTTP/1.0
    X-Auth-Admin-User: .super_admin
    X-Auth-Admin-Key: swauthkey
 
    {"storage": { "local": "<new endpoint>" }}

Example Curl Request::

    curl -XPOST -D - https://<endpoint>/auth/v2/<account>/.services \
    -H "X-Auth-Admin-User: .super_admin" \
    -H "X-Auth-Admin-Key: swauthkey" --data-binary \
    '{ "storage": { "local": "<new endpoint>" }}'

Example Response::

    HTTP/1.1 200 OK

    {"storage": {"default": "local", "local": "<new endpoint>" }}

Get Account Groups
------------------
    
Individual user group information can be retrieved using the `Get User Details`_ API method.

This function allows retrieving all group information for all users in
an existing account.  This can be achieved using a GET action against
a user URI with the pseudo-user ".groups".

The JSON dictionary returned will be a "groups" dictionary similar to
that documented in the `Get User Details`_ method, but representing
the summary of all groups utilized by all active users in the account.

Valid Responses:
  * 200: Success
  * 403: Invalid X-Auth-Admin-User/X-Auth-Admin-Key
  * 404: Account not found
  * 5xx: Internal error

Example Request::

    GET /auth/<api version>/<account>/.groups
    X-Auth-Admin-User: .super_admin
    X-Auth-Admin-Key: swauthkey

Example Curl Request::

    curl -D - https://<endpoint>/auth/v2/<account>/.groups \
    -H "X-Auth-Admin-User: .super_admin" \
    -H "X-Auth-Admin-Key: swauthkey"
    
Example Response::

    HTTP/1.1 200 OK

    { "groups": [ { "name": ".admin" },
                  { "name": "<account>" },
                  { "name": "<account>:user1" },
                  { "name": "<account>:user2" } ] }