Cosmo Management Protocol (CMP) 0.2

The Cosmo Management Protocol is a RESTful HTTP-based protocol for management of the Cosmo server. Using CMP, clients can get and put XML representations of Cosmo entities for such tasks as creating, updating and deleting user accounts in Cosmo.

Examples of tools that might use CMP:

• Post-installation script for changing the server administrator password and email address
• Bulk loading tool for populating the server with user accounts
• User interface for an external user directory that synchronizes accounts in the directory and Cosmo

Protocol Specification

This document specifies version 0.2 of CMP.

XML Namespaces

The namespace http://osafoundation.org/cosmo is reserved for elements defined in all Cosmo specifications. By convention, the prefix cosmo is used to denote this namespace.

URI Space

All CMP URIs occur in the /api URI space. This is expected to change to /cmp in a future version of the specification.

Character Encoding

All data sent by clients, including XML entity representations and usernames embedded in operation URLs, MUST be encoded in UTF-8.

Operation Preconditions

Preconditions describe the state of the server and/or of a request that must be true in order for the operation to be performed. Unless otherwise noted either in this section or for a specific operation, if a precondition is not fulfilled, the request is discarded and the response status is set to either 403 (Forbidden) if the request should not be repeated because it will always fail, or 409 (Conflict) if it is expected that the requester might be able to resolve the conflict and resubmit the request.

Authentication and Access Control

All administrative CMP operations are available to existing Cosmo accounts with administrative privileges. As Cosmo uses the Basic authentication scheme, clients must provide credentials with every request. Requests for these operations without credentials are handled as per RFC 2617.

Authenticated CMP operations are available to all existing Cosmo accounts that provide valid credentials.

Anonymous CMP operations do not require authentication. In fact, if authentication credentials are provided, these requests will be rejected with 403 (Forbidden) responses.

Request Content Headers for =PUT Requests

PUT requests that transfer XML representations of Cosmo entities must set the Content-Type header to text/xml. Nonconformant requests 415 (Unsupported Media Type) responses. They must also set the Content-Length header to the number of bytes in the request content; those that do not receive (411 Length Required responses).

Cosmo does not handle the Content-Transfer-Encoding, Content-Encoding, Content-Base, Content-Location, Content-MD5, and Content-Range headers. As per RFC 2616, PUT requests containing one or more of those headers are discarded and generate 501 (Not Implemented) responses.

Cosmo ignores the Content-Language request header when handling PUT requests.

Data Model

The following Cosmo entities are exposed by CMP:

User

The User entity represents a Cosmo user account. The following attributes are defined for User:

username

the unique identifier for a user account, presented as a credential when an a user attempts to access the account; must be between 3 and 32 bytes; may contain alphanumeric and whitespace characters as well as - and '

password

the secret token for a user account, presented as a credential when a user attempts to access the account; must be between 5 and 16 bytes; may contain any character

firstName

the given name of the user associated with the account; must be between 1 and 128 bytes; may contain alphanumeric and whitespace characters as well as - and '

lastName

the surname of the user associated with the account; must be between 1 and 128 bytes; may contain alphanumeric and whitespace characters as well as - and '

email

the email address of the user associated with the account; unique to the server (1:1 correspondence between user account and email address); must be between 1 and 128 bytes; must be a valid RFC2822 address

Server Administrator User Account

Cosmo comes preloaded with a "server administrator" user account that has special semantics. This is a bootstrap user account with administrative privileges that can be used to populate the server with additional user accounts. The username of this account is root. Its username, first name and last name may not be changed, and the account may not be deleted.

Administrative Operations

These operations are available to clients that include authentication credentials linked to an administrative account.

Listing User Accounts

To list all user accounts known by Cosmo, GET the URI /api/users.

The response is an XML representation of a list of user accounts. The root element of the XML document is users. Contained within are user elements for each user account. An individual user element contains username, firstName, lastName, email, url and homedirUrl elements.

The url element contains a URL that can be used to access the user account directly, enabling the CMP view, modify and delete operations on it.

The homedirUrl element contains a URL that references the home directory for the user account for WebDAV and CalDAV operations. As the root user account does not have a home directory, this element is not included for that account.

Note that for security purposes, the user account's password is not included in the entity representation.

Status Codes

• 200 (OK) - the response contains an XML listing of user accounts

Example

>>> REQUEST <<<
GET /api/users HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
Content-Type: text/xml;charset=UTF-8
Content-Length: xxx

<?xml version="1.0" encoding="UTF-8"?>
<users xmlns="http://osafoundation.org/cosmo">
  <user>
    <username>root</username>
    <firstName>Cosmo</firstName>
    <lastName>Administrator</lastName>
    <email>root@localhost</email>
    <url>http://localhost:8080/api/user/root</url>
  </user>
  <user>
    <username>bcm</username>
    <firstName>Brian</firstName>
    <lastName>Moseley</lastName>
    <email>bcm@osafoundation.org</email>
    <url>http://localhost:8080/api/user/bcm</url>
    <homedirUrl>http://localhost:8080/home/bcm</homedirUrl>
  </user>
</users>

Viewing A User Account

To view an individual user account, GET the URI /api/user/<username>, where <username> is the username of the user account.

The response is an XML representation of the user account. The root element of the XML document is user. Contained within are username, firstName, lastName, email, url and homedirUrl elements. This representation is in all respects identical to the user representation described in "Listing User Accounts".

Status Codes

• 200 (OK) - the response contains an XML representation of the user account
• 404 (Not Found) - the specified user account does not exist

Example

>>> REQUEST <<<
GET /api/user/bcm HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
ETag: "1066573645-1134765540540"
Content-Type: text/xml;charset=UTF-8
Content-Length: xxx

<?xml version="1.0" encoding="UTF-8"?>
<user xmlns="http://osafoundation.org/cosmo">
  <username>bcm</username>
  <firstName>Brian</firstName>
  <lastName>Moseley</lastName>
  <email>bcm@osafoundation.org</email>
  <url>http://localhost:8080/api/user/bcm</url>
  <homedirUrl>http://localhost:8080/home/bcm</homedirUrl>
</user>

Creating A User Account

To create a user account, PUT an XML representation of a User to the URI /api/user/<username>, where <username> is the username of the user account to be created.

Preconditions

• The XML representation includes all attributes defined for User.

Status Codes

• 201 (Created) - the user account was created in its entirety
• 400 (Bad Request) - the XML representation was improperly constructed, an attribute value was missing or invalid, or the username specified in the XML does not match the username in the request URI
• 431 (Username In Use) - the specified email address is already used by an existing account
• 432 (Email In Use) - the specified email address is already used by an existing account

Example

>>> REQUEST <<<
PUT /api/user/ixjonez HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version="1.0" encoding="utf-8" ?> 
<user xmlns="http://osafoundation.org/cosmo">
  <username>ixjonez</username>
  <password>abc123</password>
  <firstName>Ix</firstName>
  <lastName>Jonez</lastName>
  <email>ix@maz.org</email>
</user>

>>> RESPONSE <<<
HTTP/1.1 201 Created
ETag: "1066573645-1134765540540"
Content-Length: 0

Modifying A User Account

To modify a user account, PUT an XML representation of a User to the URI /api/user/<username>, where <username> is the username of the user account. The only necessary elements are those that represent attributes being changed, although it is harmless to include elements for non-changing attributes as well.

All exposed User attributes may be modified, except for the root user, as discussed in "Server Administrator User Account".

To change the username of an account, send the request to the URI of the existing user account but specify the new username in the uploaded XML representation. When this happens, the response will include the Content-Location header; the value is a URL that MUST be used to for further access to the user account.

Preconditions

• If the username is being changed, the specified username is not already in use
• If the email address is being changed, the specified email address is not already in use

Status Codes

• 204 (No Content) - the user account was successfully modified
• 400 (Bad Request) - the XML representation was improperly constructed, an attribute value was invalid, or the username specified in the XML does not match the username in the request URI
• 431 (Username In Use) - the specified email address is already used by an existing account
• 432 (Email In Use) - the specified email address is already used by an existing account

Example

>>> REQUEST <<<
PUT /api/user/ixjonez HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version="1.0" encoding="utf-8" ?> 
<user xmlns="http://osafoundation.org/cosmo">
  <username>test</username>
  <password>deadbeef</password>
</user>

>>> RESPONSE <<<
HTTP/1.1 204 No Content
ETag: "1066573645-1134765540540"
Content-Location: http://localhost:8080/api/user/test

Deleting A User Account

To delete a user account, DELETE the URI /api/user/<username>, where <username> is the username of the user account.

The root user may not be deleted, as discussed in "Server Administrator User Account".

Status Codes

• 204 (No Content) - the user account was successfully deleted
• 403 (Forbidden) - the attempt to delete the root user account was not allowed

Example

>>> REQUEST <<<
DELETE /api/user/test HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 204 No Content

Authenticated Operations

These operations are available to clients that include authentication credentials.

Viewing My Account

To view the account of the authenticated user, GET the URI /api/account.

The response is an XML representation of the user account. The root element of the XML document is user. Contained within are username, firstName, lastName, email, url and homedirUrl elements. This representation is in all respects identical to the user representation described in "Listing User Accounts".

Status Codes

• 200 (OK) - the response contains an XML representation of the user account

Example

>>> REQUEST <<<
GET /api/account HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

>>> RESPONSE <<<
HTTP/1.1 200 OK
ETag: "1066573645-1134765540540"
Content-Type: text/xml;charset=UTF-8
Content-Length: xxx

<?xml version="1.0" encoding="UTF-8"?>
<user xmlns="http://osafoundation.org/cosmo">
  <username>bcm</username>
  <firstName>Brian</firstName>
  <lastName>Moseley</lastName>
  <email>bcm@osafoundation.org</email>
  <url>http://localhost:8080/api/user/bcm</url>
  <homedirUrl>http://localhost:8080/home/bcm</homedirUrl>
</user>

Modifying My Account

To modify the account of the authenticated user, PUT an XML representation of the User to the URI /api/account>. The only necessary elements are those that represent attributes being changed, although it is harmless to include elements for non-changing attributes as well. The exception to this rule is the username, which can not be changed by an end user (only by an administrator).

Status Codes

• 204 (No Content) - the user account was successfully modified
• 400 (Bad Request) - the XML representation was improperly constructed, an attribute value was invalid, or the username specified in the XML does not match the username in the request URI
• 432 (Email In Use) - the specified email address is already used by an existing account

Example

>>> REQUEST <<<
PUT /api/accountHTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: xxx
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

<?xml version="1.0" encoding="utf-8" ?> 
<user xmlns="http://osafoundation.org/cosmo">
  <password>deadbeef</password>
</user>

>>> RESPONSE <<<
HTTP/1.1 204 No Content
ETag: "1066573645-1134765540540"

Anonymous Operations

These operations are available to clients that have not authenticated themselves to Cosmo.

Signing Up For A User Account

To sign up for a user account, PUT an XML representation of a User to the URI /api/signup. The response includes a Content-Location header that provides the URL for the user's home directory.

Preconditions

• The XML representation includes all attributes defined for User.

Status Codes

• 201 (Created) - the user account was created in its entirety
• 400 (Bad Request) - the XML representation was improperly constructed, an attribute value was missing or invalid, or the username specified in the XML does not match the username in the request URI
• 431 (Username In Use) - the specified username is already used by an existing account
• 432 (Email In Use) - the specified email address is already used by an existing account

Example

>>> REQUEST <<<
PUT /api/signup HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: xxx

<?xml version="1.0" encoding="utf-8" ?> 
<user xmlns="http://osafoundation.org/cosmo">
  <username>bmoseley</username>
  <password>abc123</password>
  <firstName>Brian</firstName>
  <lastName>Moseley</lastName>
  <email>bmoseley@maz.org</email>
</user>

>>> RESPONSE <<<
HTTP/1.1 201 Created
ETag: "1066573645-1134765540540"
Content-Length: 0
Content-Location: http://localhost:8080/home/bmoseley

Implementation Notes

400 Responses

Whenever a CMP request generates a 400 (Bad Request) response, Cosmo logs a warning containing more information about the bad request. It also includes this warning as the reason phrase in the response status line (eg 400 user not root element).