1. Overview

The Auth Service provides support for creating, manipulating, and using user authentication realms. It stores information about users, groups, and their permissions.

2. Installing

Just download the jar-file installer and then either double-click on the jar file or issue the following command:

   java -jar authservice-0.3.7.jar

You should get a GUI-based installer for installing the server.

3. Configuring and Running

3.1 Getting Started

The auth service stores data locally. To get started, just run the server with a directory name:

   server /opt/authdb

To create a new database, just create an empty directory. Otherwise, the server expects certain configuration files to already exist (e.g. conf.xml).

3.2 Configuring Interfaces and Host

When an instance of the service is configured, a file called conf.xml is created as well as a default key store for the SSL certificates. By default, this file looks like:

<server xmlns='http://www.atomojo.org/Vocabulary/Auth/Service/2007/1/0'>
   <keystore password='atomojo' href='keystore'/>
   <interface address='*' port='8080' secure='false'>
      <host name='*'/>
   </interface>
</server>

The same set of services are provided on whatever interfaces and hosts are configured. An interface is a specific bind address on which the service runs. If the secure attribute is true, the https protocol is used.

Each host element defines a specific host name to which the server responds. A single wildcard host entry can be used for all hosts by using a asterisk () for the name.

3.3 Setting up SSL and Host Certificates

In the database directory a 'keystore' file is created. This is a keystore that can be mained by the keytool command-line tool from the JDK. By default, it contains a certificate for localhost.

You can add your own host names to this keystore by the keytool command as follows:

keytool -keystore {path-to-keystore} -genkey -alias {host}

where {path-to-keystore} is the keystore file in database directory.

All the standard methods for maintaining and importing certificates to a keystore via the keytool program apply.

There is a lot of good information about generating a real certificate out there on the web. Most SSL certificate providers have instructions for Apache's Tomcat server (e.g. creating a CSR from GoDaddy or general information on SSL and certificates from Sun). Just follow those instructions as Tomcat users the JDK's keystore/keytool system as well.

Keep in mind that the auth service ships with a self-signed certificate. Certain programs will have an issue with that certificate and may not allow you to interact with the server without first approving the self-signed certificate.

You have several options for development testing:

1. In the browser you can approve the certificate once by going to the https address of the atomojo server.
2. You can create a real certificate for testing and set up an alias in your hosts file.
3. You can disable SSL by setting 'secure' to 'false'.
4. In Java, you can import the certificate as a trusted certificate. See http://java.sun.com/docs/books/tutorial/security/index.html or http://java.sun.com/j2ee/1.4/docs/tutorial/doc/Security6.html for tutorials on this.

3.4 Configuring the Atomojo Content Server

If you want your Atomojo Content Server to use an auth service you need to use a specific authentication realm's URI in the Atomojo Content Server's configuration. You can either use this URI in the auto-configuration feed or insert and auth element that looks like:

<auth name="myauth"  class="org.atomojo.app.auth.AuthProtocolService" 
      href="http://localhost:8080/realms/n/myauth/"/>

4. Concepts

4.1 Global Users

All users have a global user id. Some global users have alias and authentication information and can be used for cross-realm or service authentication.

A user may also have an name and email.

4.2 Permissions

A permission is an abstract concept for an action or authorization associated with a resource. A permission has a UUID identifier and name.

The default set is:

4.2 Roles

A role is a collection of permissions. A role has a name, a UUID identifier, and a set of permissions.

The following roles are provided by default:

• root : superuser
• realm-root : realm-superuser
• query : query
• viewer : GET, HEAD
• editor : GET, HEAD, POST, PUT, DELETE

4.3 Realms

A realm is a collection of users and groups. It has a name and a UUID identifier.

4.3.1 Realm Users

A realm user is associated with a global user account. In most cases a realm user is associated with a specific global user and that global user is not associated with any other realm user. In some cases, different realm users can be associated with the same global user to allow the user to manage different identities.

A realm user has the same facets as a global user.

4.3.2 Groups

A group is an association between roles and realm users. A group has an alias and a UUID identifier.

5. Service Interfaces

Every aspect of the database can be maintained through REST-oriented services via the /admin/ resource hierarchy. Authentication is required for these services and the user must have the superuser permission.

Specific realms can be managed via the /realms/ hierarchy. The authenticated user must have either the superuser permission or the realm-superuser and be a realm user. The /realms/ hierarhcy is exactly the same as the /admin/realms/ hierarchy.

The only exception is for authentication. These services require an Authentication header and are used to authenticate user sessions.

5.1 Realm Resources

A realm is created by posting a realm document to the URI path:

/admin/realms/

The realm document is structured as:

<realm xmlns='http://www.atomojo.org/Vocabulary/Auth/2007/1/0' 
      name='{name}'/>

A realm has a name and UUID and these facets may be used to construct a URI path. The administration paths for a realm are:

/admin/realms/{uuid}
/admin/realms/n/{name}

and the realm is also available from:

/realms/{uuid}
/realms/n/{name}

A DELETE request on the /admin/realm/... URI path will delete the realm.

Realms have two main sub-resources for users and groups. All the realm users are available from:

/realms/{uuid}/users/
/realms/n/{name}/users/

The realm groups are available from:

/realms/{uuid}/groups/
/realms/n/{name}/groups/

5.1.1 Realm Users

A realm user can be created by posting an XML document to the realm users resource. This document must contain an alias and password and is structure as:

<user xmlns='http://www.atomojo.org/Vocabulary/Auth/2007/1/0' 
      alias='{alias}' password='{password}'>
<name>{name}</name>
<email>{email}</email>
</user>

The 'name' and 'email' elements are optional. An 'id' attribute may be provided and must contain the UUID of a global user to associate with this realm user.

Once created, the realm user exists at the URI paths:

/realms/{uuid}/users/{user-uuid}
/realms/n/{name}/users/a/{user-alias}

A PUT to this resource can be used to change the alias, password, name, or email.

A DELETE on this resource removes the user.

5.1.2 Realm Groups

A realm group can be created by posting an XML document to the realm groups resource. This document must contain an alias is structure as:

<group xmlns='http://www.atomojo.org/Vocabulary/Auth/2007/1/0' 
      alias='{alias}'/>

Once created, the realm group exists at the URI paths:

/realms/{uuid}/groups/{group-uuid}
/realms/n/{name}/groups/a/{group-alias}

A PUT to this resource can be used to change the alias.

A DELETE on this resource removes the group.

A group has a set of roles and a set of users associated with it. The role set can be retrieved via the URI paths:

/realms/{uuid}/groups/{group-uuid}/roles/
/realms/n/{name}/groups/a/{group-alias}/roles/

A role can be added by posting an XML document to the roles resource:

<role xmlns='http://www.atomojo.org/Vocabulary/Auth/2007/1/0' 
      name='{name}'/>

Either the 'name' or 'id' attribute must be present on the role element.

Subsequently, a role can be deleted by a DELETE request on any one of the URI paths:

/realms/{uuid}/groups/{group-uuid}/roles/{role-id}
/realms/{uuid}/groups/{group-uuid}/roles/n/{role-name}
/realms/n/{name}/groups/a/{group-alias}/roles/{role-id}
/realms/n/{name}/groups/a/{group-alias}/roles/n/{role-name}

A user can be added similarly by posting an XML document to the users resource. The user element must contain either the id attribute or alias attribute of the user.

The user can be deleted from the group by a DELETE request on any one of the URI paths:

/realms/{uuid}/groups/{group-uuid}/users/{user-id}
/realms/{uuid}/groups/{group-uuid}/users/a/{user-alias}
/realms/n/{name}/groups/a/{group-alias}/users/{user-id}
/realms/n/{name}/groups/a/{group-alias}/users/a/{user-alias}

5.2 Authenticating Users

A realm user may be authenticated by using the realm authentication service at one of the two URI paths:

/realms/{uuid}/auth
/realms/n/{name}/auth

A Authentication header for BASIC authentication must be provided. If the authentication succeeds, a session is generated and stored. The result is an XML response as follows:

<session xmlns='http://www.atomojo.org/Vocabulary/Auth/2007/1/0' id='{session-id}' user-id='{user-uuid}' user-alias='{alias}'>
<group .../> ...
<role .../> ...
</session>

After successful authentication, a session may be checked via the following URI paths:

/realms/{uuid}/auth/{session}
/realms/n/{name}/auth/{session}

The response is the same XML as originally returned by the initial authentication.

A global user can be authenticated via the same procedure by using the URI path:

/auth

5.2 Global Users

Global users can be create and manipulated similar to realm users by via the resource path /admin/users/....

5.3 Permissions

All the permissions in the database are available via the resource:

/admin/permissions/

A permission can be added by posting an XML document of the following form to the above URI path:

<permission xmlns='http://www.atomojo.org/Vocabulary/Auth/2007/1/0' 
            name='{name}' id='{uuid}'/>

The id attribute may be omitted and the server will generate a UUID for the permission.

A permission has the following URI paths:

/admin/permissions/{uuid}
/admin/permissions/n/{name}

A DELETE request on the permission URI path will delete the permission.

5.4 Roles

All the roles in the database are available via the resource:

/admin/roles/

A role can be added by posting an XML document of the following form to the above URI path:

<role xmlns='http://www.atomojo.org/Vocabulary/Auth/2007/1/0' 
            name='{name}' id='{uuid}'/>

The id attribute may be omitted and the server will generate a UUID for the role.

A role has the following URI paths:

/admin/roles/{uuid}
/admin/roles/n/{name}

A DELETE request on the role URI path will delete the role.

A role has a set of permissions associated with it. A permission can be added by posting a permission document with the id attribute or the name attribute of the permission to the role's URI path.

Each role permission is available from:

/admin/roles/{uuid}/{permission-uuid}
/admin/roles/{uuid}/n/{permission-name}
/admin/roles/n/{name}/{permission-uuid}
/admin/roles/n/{name}/n/{permission-name}

A DELETE request on any of the above paths will remove the permission from the role.

6. Backup and Restore

The database can only be backed up or restored from to or from local files for security reasons. A GET request is use for either operation.

The backup resource is:

/admin/backup?location={file-path}

The restore resource is:

/admin/restore?location={file-path}