SwiftStack Auth Superusers

SwiftStack Auth User Accounts can optionally be designated Superuser. A Superuser has the capability to create, read and write to, and delete all Swift Storage Accounts on the cluster.


Superusers' password should be well-secured, as these credentials give unlimited access to all accounts managed by SwiftStack Auth (accounts that start with AUTH_).

Use Case

One example to use a superuser would be an app that stores files for millions of end-users. This app expects each user's files to be stored in a separate Swift Storage Account. The SwiftStack Controller is limited to 4,096 User Accounts per cluster. A single SwiftStack Auth User Account with Superuser privileges may be used to manage the storage of millions of users' files into millions of Swift Storage Accounts.

The Cluster Account Manager (or Controller Administrator), would use the SwiftStack Controller interface to create a single SwiftStack Auth User Account with superuser privileges. The app will use the Superuser's username and password to authenticate, receiving a token it will use to perform actions on behalf of the end-users. The app would be responsible for authenticating and authorizing the end-users as well as tracking the relationship between the end-users and the Swift Storage Accounts.

Superuser Usage Examples

In these examples we'll use curl and swift with a superuser named 'superman' to create and delete a Swift Storage Account for end-user 'batman'. This will be followed by an example of how to do the same actions using Python.


Authentication takes USERNAME, PASSWORD, and AUTH_URL as input and returns AUTH_TOKEN and STORAGE_URL as output. Under SwiftStack Auth, the storage url always ends in a Swift Storage Account name that starts with AUTH_ followed by the username.

curl -i -H "X-Auth-User: <USERNAME>" -H "X-Auth-Key: <PASSWORD>" <AUTH_URL>

$ curl -i -H "X-Auth-User: superman" -H "X-Auth-Key: superman" \
HTTP/1.1 200 OK
X-Storage-Url: https://swift.example.com/v1/AUTH_superman
X-Auth-Token: AUTH_tke43b35e50eab4eecaf72221dc8f2f3a7
Content-Type: text/html; charset=UTF-8
X-Storage-Token: AUTH_tke43b35e50eab4eecaf72221dc8f2f3a7
X-Trans-Id: txe66f5a0dde8c41be9c487-0051f2f216
Content-Length: 0
Date: Fri, 26 Jul 2013 22:03:02 GMT

swift -A <AUTH_URL> -U <USERNAME> -K <PASSWORD> stat -v

$ swift -A http://swift.example.com/auth/v1.0 -U superman -K superman \
    stat -v
StorageURL: http://swift.example.com/v1/AUTH_superman
Auth Token: AUTH_tkb5bab9e25a274b4a853fe2587b5dc8f9
   Account: AUTH_superman
Containers: 0
   Objects: 0
     Bytes: 0
Content-Type: text/plain; charset=utf-8
X-Timestamp: 1375225766.50237
X-Trans-Id: tx88ac2ec242fd4af6a1e3d-0051f847a6
X-Put-Timestamp: 1375225766.50237

Create a Swift Account

The storage URL provided by the authentication process is for the superuser's Swift Storage Account, but the token provided to a superuser can be used to create, access, and delete any Swift Storage Account on the cluster whose name starts with AUTH_. To access a different Swift Storage Account, replace the account name at the end of the STORAGE_URL with the ACCOUNT_NAME you've chosen (keeping AUTH_ at the beginning).

curl -i -H "X-Auth-Token: <AUTH_TOKEN>" -X PUT <STORAGE_URL>

$ curl -i -H "X-Auth-Token: AUTH_tke43b35e50eab4eecaf72221dc8f2f3a7" \
    -X PUT https://swift.example.com/v1/AUTH_batman
HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx875cb083733046cd91c5c-0051f6b4b4
Date: Mon, 29 Jul 2013 18:30:12 GMT


It is not possible to list existing user accounts at this time. Seeing 201 Created in the output of the account creation command indicates that the account has been created.

Managing Containers and Objects

With the swift utility, there is no command specifically for creating accounts, but accounts can be auto-created in SwiftStack-managed clusters when mentioned in a container or object request. This command creates a container using the modified storage url.

swift --os-auth-token <AUTH_TOKEN> --os-storage-url <STORAGE_URL> post <CONTAINER_NAME>

$ swift --os-auth-token AUTH_tkb5bab9e25a274b4a853fe2587b5dc8f9 \
    --os-storage-url http://swift.example.com/v1/AUTH_robin \
    post superheroes

The auth token provided by Authentication and the modified storage url may be used with any command supported by the Swift API or swift command line tool.

swift --os-auth-token <AUTH_TOKEN> --os-storage-url <STORAGE_URL> upload <CONTAINER_NAME> <FILE_NAME>

$ swift --os-auth-token AUTH_tkb5bab9e25a274b4a853fe2587b5dc8f9 \
    --os-storage-url http://swift.example.com/v1/AUTH_batman \
    upload superheroes costume1.png

Delete a Storage Account

Deleting a storage account will delete all the data in that storage account. Do note that there is a built-in-delay for this process. The process is called account reaping. To adjust settings, navigate to Cluster Manage, then Configure and click on Tune. In Account Settings there is a section to configure account reaper settings.


curl -i -H "X-Auth-Token: <AUTH_TOKEN>" -X DELETE <STORAGE_URL>

$ curl -i -H "X-Auth-Token: AUTH_tke43b35e50eab4eecaf72221dc8f2f3a7" \
    -X DELETE https://swift.example.com/v1/AUTH_batman
HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Account-Status: Deleted
X-Trans-Id: txe7a8aeb628d1401996c95-0051f3030b
Date: Fri, 26 Jul 2013 23:15:23 GMT


As of version 1.5.0, it is not possible to delete accounts using the swift command-line tool.

Invalidate Existing Authentication Tokens

If you have deleted a SwiftStack Auth user in the controller or removed the user from LDAP, you can immediately invalidate any existing token the user may already have. This requires a valid authentication token for a super user.

curl -i -H "X-Auth-Token: <SUPERUSER_AUTH_TOKEN>" -X DELETE <AUTH_URL>/users/<USERNAME>/token

$ curl -i -H 'X-Auth-Token: AUTH_tk605604358f75444dae4f4ed2d01cb840' \
HTTP/1.1 204 No Content
Content-Type: text/html; charset=UTF-8
Content-Length: 0
X-Trans-Id: txfe64658439a34c10a6625-0052f494df
Date: Fri, 07 Feb 2014 08:10:07 GMT