.. _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// HTTP/1.1 X-Auth-Admin-User: .super_admin X-Auth-Admin-Key: swauthkey Example Curl Request:: curl -D - https:///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// 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// HTTP/1.1 X-Auth-Admin-User: .super_admin X-Auth-Admin-Key: swauthkey Example Curl Request:: curl -D - https:///auth/v2/ \ -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:///v1/" }, }, "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// HTTP/1.1 X-Auth-Admin-User: .super_admin X-Auth-Admin-Key: swauthkey Example Curl Request:: curl -D - https:///auth/v2/ \ -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// HTTP/1.1 X-Auth-Admin-User: .super_admin X-Auth-Admin-Key: swauthkey Example Curl Request:: curl -XDELETE -D - https:///auth/v2/ \ -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/// 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": ":"}, # The first group is a unique user identifier {"name": ""}, # The second group is the auth account name {"name": ""} # There may be additional groups, .admin being a # special group indicating an account admin and # .reseller_admin indicating a reseller admin. ], "auth": ":" # 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/// HTTP/1.1 X-Auth-Admin-User: .super_admin X-Auth-Admin-Key: swauthkey Example Curl Request:: curl -D - https:///auth/v2// \ -H "X-Auth-Admin-User: .super_admin" \ -H "X-Auth-Admin-Key: swauthkey" Example Response:: HTTP/1.1 200 Ok { "groups": [ { "name": ":" }, { "name": "" }, { "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/// 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:///auth/v2// \ -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/// HTTP/1.1 X-Auth-Admin-User: .super_admin X-Auth-Admin-Key: swauthkey Example Curl Request:: curl -XDELETE -D - https:///auth/v2// \ -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 , 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///.services HTTP/1.0 X-Auth-Admin-User: .super_admin X-Auth-Admin-Key: swauthkey {"storage": { "local": "" }} Example Curl Request:: curl -XPOST -D - https:///auth/v2//.services \ -H "X-Auth-Admin-User: .super_admin" \ -H "X-Auth-Admin-Key: swauthkey" --data-binary \ '{ "storage": { "local": "" }}' Example Response:: HTTP/1.1 200 OK {"storage": {"default": "local", "local": "" }} 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///.groups X-Auth-Admin-User: .super_admin X-Auth-Admin-Key: swauthkey Example Curl Request:: curl -D - https:///auth/v2//.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": "" }, { "name": ":user1" }, { "name": ":user2" } ] }