Swauth has its own internal versioned REST API for adding, removing, and editing accounts. This document explains the v2 API.
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.
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 from the auth APIs are returned as a JSON structure. Example return values in this document are edited for readability.
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.
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.
Example Request:
GET /auth/<api version>/ HTTP/1.1
X-Auth-Admin-User: .super_user
X-Auth-Admin-Key: swauthkey
Example Curl Request:
curl -D - https://<endpoint>/auth/v2/ \
-H "X-Auth-Admin-User: .super_user" \
-H "X-Auth-Admin-Key: swauthkey"
Example Result:
HTTP/1.1 200 OK
{ "accounts":
[
{ "name": "account1" },
{ "name": "account2" },
{ "name": "account3" }
]
}
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.
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’.
Example Request:
GET /auth/<api version>/<account> HTTP/1.1
X-Auth-Admin-User: .super_user
X-Auth-Admin-Key: swauthkey
Example Curl Request:
curl -D - https://<endpoint>/auth/v2/<account> \
-H "X-Auth-Admin-User: .super_user" \
-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" } ]
}
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.
Example Request:
GET /auth/<api version>/<new_account> HTTP/1.1
X-Auth-Admin-User: .super_user
X-Auth-Admin-Key: swauthkey
Example Curl Request:
curl -D - https://<endpoint>/auth/v2/<new_account> \
-H "X-Auth-Admin-User: .super_user" \
-H "X-Auth-Admin-Key: swauthkey"
Example Response:
HTTP/1.1 201 Created
An account can be deleted with a DELETE request against an existing account.
Example Request:
DELETE /auth/<api version>/<account> HTTP/1.1
X-Auth-Admin-User: .super_user
X-Auth-Admin-Key: swauthkey
Example Curl Request:
curl -XDELETE -D - https://<endpoint>/auth/v2/<account> \
-H "X-Auth-Admin-User: .super_user" \
-H "X-Auth-Admin-Key: swauthkey"
Example Response:
HTTP/1.1 204 No Content
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.
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": "plaintext:<key>"
# The auth-type and key for the user; currently only
# plaintext is implemented.
}
For example:
{"groups": [{"name": "test:tester"}, {"name": "test"},
{"name": ".admin"}],
"auth": "plaintext:testing"}
Example Request:
GET /auth/<api version>/<account>/<user> HTTP/1.1
X-Auth-Admin-User: .super_user
X-Auth-Admin-Key: swauthkey
Example Curl Request:
curl -D - https://<endpoint>/auth/v2/<account>/<user> \
-H "X-Auth-Admin-User: .super_user" \
-H "X-Auth-Admin-Key: swauthkey"
Example Response:
HTTP/1.1 200 Ok
{ "groups": [ { "name": "<account>:<user>" },
{ "name": "<user>" },
{ "name": ".admin" } ],
"auth" : "plaintext:password" }
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.
Example Request:
PUT /auth/<api version>/<account>/<user> HTTP/1.1
X-Auth-Admin-User: .super_user
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_user" \
-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
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.
Example Request:
DELETE /auth/<api version>/<account>/<user> HTTP/1.1
X-Auth-Admin-User: .super_user
X-Auth-Admin-Key: swauthkey
Example Curl Request:
curl -XDELETE -D - https://<endpoint>/auth/v2/<account>/<user> \
-H "X-Auth-Admin-User: .super_user" \
-H "X-Auth-Admin-Key: swauthkey"
Example Response:
HTTP/1.1 204 No Content
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.
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_user
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_user" \
-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>" }}
Individual user group information can be retrived 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.
Example Request:
GET /auth/<api version>/<account>/.groups
X-Auth-Admin-User: .super_user
X-Auth-Admin-Key: swauthkey
Example Curl Request:
curl -D - https://<endpoint>/auth/v2/<account>/.groups \
-H "X-Auth-Admin-User: .super_user" \
-H "X-Auth-Admin-Key: swauthkey"
Example Response:
HTTP/1.1 200 OK
{ "groups": [ { "name": ".admin" },
{ "name": "<account>" },
{ "name": "<account>:user1" },
{ "name": "<account>:user2" } ] }