Overview

The authentication protocol allows anyone to integrate their own identity information into an atomojo service.

XML Vocabulary

All elements used by this protocol are in the namespace http://www.atomojo.org/Vocabulary/Auth/2007/1/0.

The Basics

The protocol is designed to be a REST-oriented protocol. Every service provider must give a base URL to which the client will interact. For example, a user's information might be retrieved from the URL {base-url}/users/a/alias.

The client authenticates with its own set of credentials via BASIC authentication. These credentials allow it to browse and retrieve user and group information. The credentials may also allow the client to modify the user information--but this is not a required feature of the service provider.

Resource Structure

{base-url}/auth
{base-url}/auth/{session}
{base-url}/users/
{base-url}/users/{id}
{base-url}/users/{id}/groups
{base-url}/users/a/{alias}
{base-url}/users/a/{alias}/groups
{base-url}/groups/
{base-url}/groups/{id}
{base-url}/groups/{id}/users/
{base-url}/groups/{id}/users/{user-id}
{base-url}/groups/{id}/users/a/{user-alias}
{base-url}/groups/a/{alias}
{base-url}/groups/a/{alias/users/
{base-url}/groups/a/{alias/users/{user-id}
{base-url}/groups/a/{alias/users/{user-alias}

User Authentication

A user can be authenticated by sending an Authorization header to {base-url}/auth. If the username and password match, a session element is returned with an id attribute containing the session identifier. This session identifier may expire at some point in the future.

Once a session has been created via authentication, a client may check to see if a session is valid by passing the id query parameter with the UUID value. No Authorization header is required. If the session is still active, a 200 status code is returned along with the appropriate session element.

If the Authorization header does not match the credentials of the user or the session being checked is no longer valid, a 401 (unauthorized) status code is returned without any response entity.

The session element has the following structure:

<session id='{uuid}' user-id='{uuid}' user-alias='{alias}'/>

Sessions

A session is created when you authenticate. A user's session can be checked by GET request to:

{base-uri}/auth/{session}

If the session identifier is valid, a session element is returned.

You can delete sessions by a DELETE request on the same URI.

Admin Authentication

For all other request, an administrator must authenticate by sending an Authorization header with their requests. No session is kept by the service for administration services.

Creating Users

A user is created by a POST to the {base-url}/users/ service of a user element with content type of application/xml.

The user element has the following structure:

<user id="{uuid}" alias="{string}" password="{string}">
  <name>{string}</name>
  <email>{string}</email>
</user>

The id attribute has special meaning for this service. If the id attribute is specified, the user is associated with an pre-existing account. If the account exists, all the remain attributes and child elements may be omitted and defaulted to the existing account.

That is, for a pre-existing account, the minimal user to add is:

<user id="{uuid}"/>

This message is used to associate an existing account with a service.

Otherwise, the id attribute must be omitted. When omitted, a new account is created with the credentials specified. If the password is specified, the password is set for the user. If the password is omitted, the user may not authenticate with this service until a password exists.

The name and email child elements are optional and may be omitted.

Modifying Users

Once a user is created, it is available from the {base-url}/users/{id} or {base-url}/users/a/{alias} resources depending on whether the user UUID or alias is to be used, respectively. A GET request will return a user element without the password.

A POST request of a password element containing a new password will set the password of the user.

A PUT request containing a user element may be used to change any of the facets of the user with the exception of the user's UUID.

A DELETE request removes the user.