Scyld Cloud Controller Documentation

User API

The User API presents an interface for creating, modifying, and deleting system accounts. These are real UNIX system accounts and are generally the first thing that needs to be created when getting a user up and running within the Scyld Cloud Controller. Having a system account is prerequisite to creating server-instance and storage-volumes.

User Object

A user object has the following properties:

  • user-id – string. A UUID uniquely identifying this User object.
  • cloudauth-id – string. A UUID identifying the Scyld Cloud Auth user ID associated with this user.
  • system-name – string. The UNIX account name associated with this user.
  • system-primary-group – string. The primary UNIX group for the user.
  • ssh-public-keys – list. A list of SSH keys present for the user.
  • system-groups – list. A list of groups the user is a member of. The primary group is not repeated here.
  • server-instances – list. A list of server-instance UUIDs that this user has been granted access to.

Some of the properties are optional, and may not be returned if they are empty/unset.

API Methods

The /user URI accepts HTTP GET and HTTP POST.

GET

An HTTP GET on /user will return a list of User objects that the requester has permission to see.

A requester with the superuser role in Scyld Cloud Auth would see all User objects in the system. A requester with no special permissions, and who does not have any managed users will only see User accounts owned by themselves. A requester that has managed users will see their own Users, plus the Users belonging to their managed users.

The following querystring parameters can be specified to further limit the results:

  • system-name – Search for accessible Users that have a matching system-name property (i.e. “johndoe”).
  • cloudauth-id – Search for accessible Users that are owned by the given cloudauth-id.

system-name and cloudauth-id parameters may not be used at the same time.

User Response Schema

The response from the GET /user is governed by the following JSON-Schema:

{
    "name": "User reponse data",
    "description": "Response data for user requests. Contains details of one or more users",
    "type": "array",
    "items": {
        "title": "A user object",
        "type": "object",
        "properties": {
            "user-id": {
                "description": "UUID for user",
                "type": "string",
                "required": True
            },
            "cloudauth-id": {
                "description": "CloudAuth User ID that owns this user",
                "type": "string",
                "required": True
            },
            "system-name": {
                "description": "UNIX account name",
                "type": "string",
                "required": True
            },
            "system-primary-group": {
                "description": "Primary group for system-name",
                "type": "string",
                "required": True
            },
            "ssh-public-keys": {
                "description": "List of public keys attached to system account for login purposes",
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "key-fingerprint": {
                            "description": "SSH key fingerprint",
                            "type": "string",
                            "required": True
                        },
                        "comment": {
                            "description": "Optional key comment",
                            "type": "string",
                            "required": False
                        }
                    }
                },
                "additionalItems": False,
                "minItems": 0,
                "required": False
            },
            "system-groups": {
                "description": "List of secondary UNIX groups the user is a member of",
                "type": "array",
                "items": {
                    "type": "string",
                },
                "additionalItems": False,
                "minItems": 0,
                "required": False
            },
            "server-instances": {
                "description": "List of server-instance UUIDs user has been granted access to",
                "type": "array",
                "items": {
                    "type": "string",
                },
                "additionalItems": False,
                "minItems": 0,
                "required": False
            }
        },
        "additionalProperties": False,
        "required": True
    },
    "additionalItems": False,
    "minItems": 1
}
Examples

Get a list of users you have access to:

# curl -X GET -H "X-Auth-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Auth-Cloudauth-Id: 00000000000000000000000000000000" https://localhost/v1/user | python -m json.tool
{
    "data": [
        {
            "cloudauth-id": "00000000000000000000000000000000",
            "server-instances": [
                "3f668083a8a44b788d173042aefd24ba"
            ],
            "ssh-public-keys": [
                {
                    "comment": "sometest@user",
                    "key-fingerprint": "ef:3b:4a:f7:76:59:cc:41:15:28:94:78:3a:ff:88:d8"
                }
            ],
            "system-groups": [
                "demodemo"
            ],
            "system-name": "demodemo",
            "system-primary-group": "demodemo",
            "user-id": "3081076fb99b43579aa3d29b23e16c5a"
        }
    ],
    "msg": "",
    "success": true
}

POST

An HTTP POST on /user will create a new user.

Only one user can be created per Scyld Cloud Auth user. If a user already exists for the referenced Scyld Cloud Auth user, then the request will be rejected. When creating a new user, one must provide the UNIX system-name that the user will have. You may optionally specify a list of Groups to add the new user to (presuming you have the permissions to add members to the groups).

User POST Schema

The data format for POST /user is governed by the following JSON-Schema:

{
    "name": "User POST data",
    "description": "Create a new USER on the system",
    "type": "object",
    "properties": {
        "system-name": {
            "description": "UNIX account name to create",
            "type": "string",
            "required": True
        },
        "system-groups": {
            "description": "List of secondary UNIX groups to add the user to",
            "type": "array",
            "items": {
                "type": "string",
            },
            "minItems": 0,
            "required": False
        }
    },
    "additionalProperties": False
}

/user/<id>

The /user/<id> URI accepts HTTP GET, HTTP PUT, and HTTP DELETE.

The <id> field is a UUID that identifies a specific User object.

GET

An HTTP GET on /user/<id> will return data in the exact same format as /user (see User Response Schema), but will contain at most one item – the user referenced by UUID.

PUT

An HTTP PUT on /user/<id> will attempt to modify the properties of the User.

There are two properties of a user that can be modified

  • ssh-public-keys – The OpenSSH public keys attached to this system account.
  • system-groups – The secondary UNIX groups this user is a member of. The user’s primary group cannot be modified.

There are three “actions” that can be taken when modifying a user property.

  • add – This will add the given items to the property, leaving the existing ones intact.
  • delete – This will delete the given items from the property.
  • replace – This will delete all existing items from the property, and replace them with the given items.
User PUT Schema

The data format for PUT /user/<id> is governed by the following JSON-Schema:

{
    "name": "User PUT data",
    "description": "Make changes to an existing user on the system",
    "type": "object",
    "properties": {
        "action": {
            "description": "what type of operation to perform",
            "type": "string",
            "enum": ["add", "replace", "delete"],
            "required": True
        },
        "ssh-public-keys": {
            "description": "List of public keys attached to system account for login purposes",
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "key": {
                        "description": "SSH key text (add) or fingerprint (replace/delete)",
                        "type": "string",
                        "required": True
                    }
                }
            },
            "minItems": 0,
            "required": False
        },
        "system-groups": {
            "description": "List of secondary UNIX groups to take action on. Admin permissions required.",
            "type": "array",
            "items": {
                "type": "string",
            },
            "minItems": 0,
            "required": False
        }
    },
    "additionalProperties": False
}

DELETE

An HTTP DELETE on an existing User object will delete that user from the system, removing their system-name and primary group. A user cannot be deleted while they still own any storage-volume, group, or server-instance objects.





Scyld Cloud Controller

SCM API Documentation