summaryrefslogtreecommitdiffstats
path: root/doc/markdown/auth_guide.md
blob: b62774cffd62c0cd06ffd6d0421eb56707876e49 (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
# Authentication Services Start Guide

## Contents
* [Keystone](#keystone)
* [GSwauth](#gswauth)
    * [Overview](#gswauth_overview)
    * [Installing GSwauth](#gswauth_install)
    * [User roles](#gswauth_user_roles)
    * [GSwauth Tools](#gswauth_tools)
    * [Authenticating a user](#gswauth_authenticate)
* [Swiftkerbauth](#swiftkerbauth)
    * [Architecture](swiftkerbauth/architecture.md)
    * [RHEL IPA Server Guide](swiftkerbauth/ipa_server.md)
    * [RHEL IPA Client Guide](swiftkerbauth/ipa_client.md)
    * [Windows AD Server Guide](swiftkerbauth/AD_server.md)
    * [Windows AD Client Guide](swiftkerbauth/AD_client.md)
    * [Swiftkerbauth Guide](swiftkerbauth/swiftkerbauth_guide.md)

## <a name="keystone" />Keystone ##
The Standard Openstack authentication service

TBD

## <a name="gswauth" />GSwauth ##

### <a name="gswauth_overview" />Overview ###
An easily deployable GlusterFS aware authentication service based on [Swauth](http://gholt.github.com/swauth/).
GSwauth is a WSGI Middleware that uses Swift itself as a backing store to
maintain its metadata.

This model has the benefit of having the metadata available to all proxy servers
and saving the data to a GlusterFS volume. To protect the metadata, the GlusterFS
volume should only be able to be mounted by the systems running the proxy servers.

Currently, gluster-swift has a strict mapping of one account to a GlusterFS volume.
Future releases, this will be enhanced to support multiple accounts per GlusterFS
volume.

See <http://gholt.github.com/swauth/> for more information on Swauth.

### <a name="gswauth_install" />Installing GSwauth ###

1. GSwauth is installed by default with Gluster-Swift.

1. Create and start the `gsmetadata` gluster volume
~~~
gluster volume create gsmetadata <hostname>:<brick>
gluster volume start gsmetadata
~~~

1. run `gluster-swift-gen-builders` with all volumes that should be
    accessible by gluster-swift, including `gsmetadata`
~~~
gluster-swift-gen-builders gsmetadata <other volumes>
~~~

1. Change your proxy-server.conf pipeline to have gswauth instead of tempauth:

    Was:
~~~
[pipeline:main]
pipeline = catch_errors cache tempauth proxy-server
~~~
    Change To:
~~~
[pipeline:main]
pipeline = catch_errors cache gswauth proxy-server
~~~

1. Add to your proxy-server.conf the section for the GSwauth WSGI filter:
~~~
[filter:gswauth]
use = egg:gluster_swift#gswauth
set log_name = gswauth
super_admin_key = gswauthkey
metadata_volume = gsmetadata
auth_type = sha1
auth_type_salt = swauthsalt
token_life = 86400
max_token_life = 86400
~~~

1. Restart your proxy server ``swift-init proxy reload``

##### Advanced options for GSwauth WSGI filter:

* `default-swift-cluster` - default storage-URL for newly created accounts. When attempting to authenticate with a user for the first time, the return information is the access token and the storage-URL where data for the given account is stored.

* `token_life` - set default token life. The default value is 86400 (24hrs).

* `max_token_life` - The maximum token life. Users can set a token lifetime when requesting a new token with header `x-auth-token-lifetime`. If the passed in value is bigger than the `max_token_life`, then `max_token_life` will be used. 

### <a name="gswauth_user_roles" />User Roles
There are only three user roles in GSwauth:

* A regular user has basically no rights. He needs to be given both read/write priviliges to any container. 
* The `admin` user is a super-user at the account level. This user can create and delete users for the account they are members and have both write and read priviliges to all stored objects in that account.
* The `reseller admin` user is a super-user at the cluster level. This user can create and delete accounts and users and has read/write priviliges to all accounts under that cluster.


| Role/Group | get list of accounts | get Acccount Details (users, etc)| Create Account | Delete Account | Get User Details | Create admin user | Create reseller-admin user | Create regular user | Delete admin user | Delete reseller-admin user | Delete regular user | Set Service Endpoints | Get Account Groups | Modify User |
| ----------------------- |:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| .super_admin (username) |x|x|x|x|x|x|x|x|x|x|x|x|x|x|
| .reseller_admin (group) |x|x|x|x|x|x| |x|x| |x|x|x|x|
| .admin (group)          | |x| | |x|x| |x|x| |x| |x|x|
| regular user (type)     | | | | | | | | | | | | | | |


### <a name="gswauth_tools" />GSwauth Tools
GSwauth provides cli tools to facilitate managing accounts and users. All tools have some options in common:

#### Common Options:
* -A, --admin-url: The URL to the auth
    * Default: `http://127.0.0.1:8080/auth/`
* -U, --admin-user: The user with admin rights to perform action
    * Default: `.super_admin`
* -K, --admin-key: The key for the user with admin rights to perform action
    * no default value
 
#### gswauth-prep:
Prepare the gluster volume where gswauth will save its metadata.

~~~
gswauth-prep [option]
~~~

Example:

~~~
gswauth-prep -A http://10.20.30.40:8080/auth/ -K gswauthkey
~~~

#### gswauth-add-account:
Create account. Currently there's a requirement that an account must map to a gluster volume. The gluster volume must not exist at the time when the account is being created.

~~~
gswauth-add-account [option] <account_name>
~~~

Example:

~~~
gswauth-add-account -K gswauthkey <account_name>
~~~

#### gswauth-add-user:
Create user. If the provided account does not exist, it will be automatically created before creating the user.
Use the `-r` flag to create a reseller admin user and the `-a` flag to create an admin user. To change the password or make the user an admin, just run the same command with the new information.

~~~
gswauth-add-user [option] <account_name> <user> <password>
~~~

Example:

~~~
gswauth-add-user -K gswauthkey -a test ana anapwd
~~~

**Change password examples**

Command to update password/key of regular user:

~~~
gswauth-add-user -U account1:user1 -K old_pass account1 user1 new_pass
~~~

Command to update password/key of account admin:

~~~
gswauth-add-user -U account1:admin -K old_pass -a account1 admin new_pass
~~~

Command to update password/key of reseller_admin:

~~~
gswauth-add-user -U account1:radmin -K old_pass -r account1 radmin new_pass
~~~

#### gswauth-delete-account:
Delete an account. An account cannot be deleted if it still contains users, an error will be returned.

~~~
gswauth-delete-account [option] <account_name>
~~~

Example:

~~~
gswauth-delete-account -K gswauthkey test
~~~

#### gswauth-delete-user:
Delete a user.

~~~
gswauth-delete-user [option] <account_name> <user>
~~~

Example:

~~~
gswauth-delete-user -K gswauthkey test ana
~~~

#### gswauth-set-account-service:
Sets a service URL for an account. Can only be set by a reseller admin.
This command can be used to changed the default storage URL for a given account.
All accounts have the same storage-URL default value, which comes from the `default-swift-cluster` 
option.

~~~
gswauth-set-account-service [options] <account> <service> <name> <value>
~~~

Example:

~~~
gswauth-set-account-service -K gswauthkey test storage local http://newhost:8080/v1/AUTH_test
~~~

#### gswauth-list:
List information about accounts and users

* If `[account]` and `[user]` are omitted, a list of accounts will be output.
* If `[account]` is included but not `[user]`, a list of users within the account will be output.
* If `[account]` and `[user]` are included, a list of groups the user belongs to will be ouptput.
* If the `[user]` is `.groups`, the active groups for the account will be listed.

The default output format is tabular. `-p` changes the output to plain text. `-j` changes the 
output to JSON format. This will print all information about given account or user, including
stored password

~~~
gswauth-list [options] [account] [user]
~~~

Example:

~~~
gswauth-list -K gswauthkey test ana
+----------+
|  Groups  |
+----------+
| test:ana |
|   test   |
|  .admin  |
+----------+
~~~

#### gswauth-cleanup-tokens:
Delete expired tokens. Users also have the option to provide the expected life of tokens, delete all tokens or all tokens for a given account.

Options:

* `-t`, `--token-life`: The expected life of tokens, token objects modified more than this number of
seconds ago will be checked for expiration (default: 86400).
* `--purge`: Purge all tokens for a given account whether the tokens have expired or not.
* `--purge-all`: Purges all tokens for all accounts and users whether the tokens have expired or not.

~~~
gswauth-cleanup-tokens [options]
~~~

Example:

~~~
gswauth-cleanup-tokens -K gswauthkey --purge test
~~~

### <a name="gswauth_authenticate" />Authenticating a user with swift client
There are two methods of accessing data using the swift client. The first (and most simple one) is by providing the user name and password everytime. The swift client takes care of acquiring the token from gswauth. See example below:

~~~
swift -A http://127.0.0.1:8080/auth/v1.0 -U test:ana -K anapwd upload container1 README.md
~~~

The second method is a two-step process, but it allows users to only provide their username and password once. First users must authenticate with a username and password to get a token and the storage URL. Then, users can make the object requests to the storage URL with the given token.

It is important to remember that tokens expires, so the authentication process needs to be repeated every so often.

Authenticate a user with the curl command

~~~
curl -v -H 'X-Storage-User: test:ana' -H 'X-Storage-Pass: anapwd' -k http://localhost:8080/auth/v1.0
...
< X-Auth-Token: AUTH_tk7e68ef4698f14c7f95af07ab7b298610
< X-Storage-Url: http://127.0.0.1:8080/v1/AUTH_test
...
~~~
Now, the user can access the object-storage using the swift client with the given token and storage URL

~~~
bash-4.2$ swift --os-auth-token=AUTH_tk7e68ef4698f14c7f95af07ab7b298610 --os-storage-url=http://127.0.0.1:8080/v1/AUTH_test upload container1 README.md
README.md
bash-4.2$ 
bash-4.2$ swift --os-auth-token=AUTH_tk7e68ef4698f14c7f95af07ab7b298610 --os-storage-url=http://127.0.0.1:8080/v1/AUTH_test list container1
README.md
~~~
**Note:** Reseller admins must always use the second method to acquire a token, in order to be given access to other accounts different than his own. The first method of using the username and password will give them access only to their own accounts.

## <a name="swiftkerbauth" />Swiftkerbauth ##
Kerberos authentication filter

Carsten Clasohm implemented a new authentication filter for swift
that uses Kerberos tickets for single sign on authentication, and
grants administrator permissions based on the users group membership
in a directory service like Red Hat Enterprise Linux Identity Management
or Microsoft Active Directory.