I’m rather new to OpenStack and have had some difficulty understanding how authentication to Swift using Keystone along with the ACLs work so I thought I’d detail some of what I’ve learnt over the last couple of days. This is probably nothing new to more experienced OpenStack users/administrators but may be of some help to newbies. I have been working with the Essex release so some of the information may be out of date if you try to use it with Folsom, which was released last week. Disclaimer: some of what is below may well be incorrect, please let me know if it is and I’ll update it. This is just what I’ve worked out from looking at various guides, forum posts, log files, code and experimentation.
This blog has some useful information about Swift. One part which was particularly useful was a clarification of terminology between Swift and Keystone which will help in translating between documentation for the different components.
- A tenant in keystone is an account in swift.
- A user in keystone is also a user in swift.
- A role in keystone is a group in swift.
Note that if you are using Horizon to create users, then a project in horizon is equivalent to a tenant.
If you haven’t already done so then follow the instructions in the Essex administration guide to enable Swift authentication using Keystone.
Check that Keystone/Swift Authentication is working
In /etc/swift/proxy-server.conf you will have set operator_role to something like:
operator_roles = admin, swiftoperator
A user must be in one of these roles in order to change the ACLs for containers belonging to a Swift account. Remember that in Keystone the role that a user has is a per-tenant property. And that a user does not necessarily have any role in a specific tenant. Specifically, if you create a user in Horizon and set which project (tenant) it belongs to this does not add the user to a role for that tenant (AFAICT). You can add a user to a role for a specific tenant in keystone by doing the following (you will need the appropriate keystone privileges):
$ keystone role-user-add --user_id user-id --tenant_id tenant-id --role_id role-id
The user, tenant and role ids can be listed using the following keystone commands
$ keystone user-list
$ keystone role-list
$ keystone tenant-list
In Essex you can not view the roles a user is in using Horizon, but the following command line argument will list them:
$ keystone role-list --user user-id --tenant tenant-id
At the end of the instructions to enable Keystone authentication for Swift is a command to verify that Swift is properly using Keystone for authentication.
$ swift -V 2 -A http://localhost:5000/v2.0 -U admin:admin -K ADMIN stat
In the command above -U admin:admin specifies the tenant and user information to pass to keystone at http://localhost:5000/v2.0 to retreive a token which is then sent in a second request to the Swift proxy server. The token is used by the server to determine if the user/tenant combination has permission to run the stat command. Because in the example above (and many other examples) the user and tenant are the same name there is some ambiguity, but note that the -U parameter is of the form -U keystone_tenant:keystone_user and not the other way around. Also, the parameter to -K should be the password for the tenant user account, not some other key or id (which is used in some other examples around).
If the swift command fails to retreive a token from the Keystone server, say because of an incorrect password, then you’ll see a response like this:
$ swift -V 2 -A http://localhost:5000/v2.0 -U admin:admin -K ADMIN_PASSWORD stat
Auth GET failed: http://localhost:5000/v2.0/tokens 401 Not Authorized
If it fails because the swift command successfully retrieved a token from Keystone but the user specified is not in a role for the specified tenant that has sufficient privileges to run the command (in this case not in operator_roles, then you’ll see a response like this:
$ swift -V 2 -A http://localhost:5000/v2.0 -U admin:admin -K ADMIN_PASSWORD stat
Account HEAD failed: http://127.0.0.1:8080/v1/AUTH_0bd26c26d3ac42f2886d327d9c8249aa 403 Forbidden
or even this if the user and password is valid, but the tenant is not:
$ swift -V 2 -A http://localhost:5000/v2.0 -U admin:admin -K ADMIN_PASSWORD stat
There is no object-store endpoint on this auth server.
Note the URL in the error message which indicates that the error occurred when it was attempting to connect to the Swift server and not that Keystone server. To run the stat command the user will need to be in a role listed in operator_roles in proxy-server.conf. If the the command runs successfully you will see something like:
$ swift -V 2 -A http://localhost:5000/v2.0 -U admin:admin -K ADMIN_PASSWORD stat
Account: AUTH_0bd26c26d3ac42f2886d327d9c8249aa
Containers: 2
Objects: 1
Bytes: 104
Accept-Ranges: bytes
X-Trans-Id: tx993e0b8ad1ee43f6ae437292eef2da44
Returned is a summary of the information for the account (the tenant in Keystone-speak) in Swift.
Upload and download a file to Swift
Rather than have to specify the authentication URL, tenant, user and password every time they can be set using environment variables:
OS_USERNAME=<username>
OS_TENANT_NAME=<tenant_name>
OS_PASSWORD=<password>
ST_AUTH=http://localhost:5000/v2.0
ST_USER=<tenant_name>:<username>
ST_KEY=<user_password>
Until the ACLs are set only a user in a role listed in operator_roles will be able to upload or download a file, or list the containers or contents of containers. So firstly, as a user that has a role for the tenant in operator_roles, to upload a file:
$ swift upload test_container test_file
test_file
The container specified will be created automatically if it does not exist. To download a file:
$ swift upload test_container test_file
test_file
To list the containers for an account (tenant):
$ swift list
test_container
To list the contents of a container:
$ swift list test_container
test_file
Setting Swift ACLs
ACLs can only be set on containers, not on individual objects. In order to view the ACLs on a container you can stat the container with a user that has a role in operator_roles for that tenant:
$ swift stat test_container
Account: AUTH_0bd26c26d3ac42f2886d327d9c8249aa
Container: test_container
Objects: 1
Bytes: 0
Read ACL:
Write ACL:
Sync To:
Sync Key:
Accept-Ranges: bytes
X-Trans-Id: txf87368f68d2a46cb93e2141554328924
Note: If you stat a container with a user that does not have a role in the operator role list, but does have read privileges on the container it will show you empty ACLs even if they are not empty.
An empty ACL means that only a user with a role in the operator role is able to read or write objects to the container or list objects in the container. In order to set the read ACL so users in the role example_role for a container can download objects:
$ swift post -r "example_role" test_container
Note that this will overwrite the current read ACL value. In order to set the read ACL so user Test1 in the account example_account (tenant in Keystone speak) can download objects:
$ swift post -r "example_account:Test1" test_container
It appears to be necessary to always specific an account/user combination. You can not just specify an account (tenant) or a username. You can combine the above two examples by separating the ACLs with a ‘,‘ character:
$ swift post -r "example_role,example_account:Test1" test_container
Read privileges alone do not allow a user to list the contents of a container. To allow this add the .rlistings directive. This will allow any user with read privileges for the container to also retrieve an object list for the container.
$ swift post -r "example_role,example_account:Test1,.rlistings" test_container
Write privileges are managed in a similar manner, although the .rlistings directive is not required.
$ swift post -w "example_role" test_container
In my version of Swift even if you have write privileges to a container an error is returned related to not having permission to create a container for the file even if it already exists. The file is however uploaded correctly. The latest definitions of ACLs for Swift are available in this document, although it doesn’t seem to quite match my experiences. It could just be a that its for a later release of Swift included in Folsom.