Keystone: Identity Service
==========================

Keystone is a proposed independent authentication service for [OpenStack](http://www.openstack.org).

This initial proof of concept aims to address the current use cases in Swift and Nova which are:

* REST-based, token auth for Swift
* many-to-many relationship between identity and tenant for Nova.


SERVICES:
---------

* Keystone    - authentication service
* Auth_Token  - WSGI middleware that can be used to handle token auth protocol (WSGI or remote proxy)
* Echo        - A sample service that responds by returning call details

Also included:

* Auth_Basic  - Stub for WSGI middleware that will be used to handle basic auth
* Auth_OpenID - Stub for WSGI middleware that will be used to handle openid auth protocol
* RemoteAuth  - WSGI middleware that can be used in services (like Swift, Nova, and Glance) when Auth middleware is running remotely


ENVIRONMENT & DEPENDENCIES:
---------------------------
see pip-requires for dependency list
Setup:
Install http://pypi.python.org/pypi/setuptools
    sudo easy_install pip
    sudo pip install -r pip-requires

RUNNING KEYSTONE:
-----------------

During  development, you can simply run

     $ bin/keystone-auth 

It dumps stdout and stderr onto the terminal.


RUNNING KEYSOTNE IN AS ROOT IN PRODUCTION
---------------------------------------------
In production, stdout and stderr need to be closed and all theoutput needs tobe redirected to a log file.
Once the package is installed through setup tools, RPM, deb, or ebuild keystone-control is installed 
as /usr/sbin/keystone-control. Typically, it will be started a script in /etc/init.d/keystoned

keystone-control can invoke keystone-auth and start the keystone daemon with 

     $ /usr/sbin/keystone-control auth start

It writes the process id of the daemon into /var/run/keystone/keystine-auth.pid. he daemon can be stopped with
 
     $ /usr/sbin/keystone-control auth stop

keystone-control has the infrastructure to start and stop multiple servers keystone-xxx  

DEVELOPMENT OF keystone-control
-------------------------------

During the  development of keystone-control can be started as a user instead of root

From the topdir 

     $ bin/keystone-control --pid-file pidfile auth <start|stop|restart>

config.py takes the config file from topdir/etc/keystone.conf

If the keystone package is also intalled on the system
/etc/keystone.conf or /etc/keystone/keystone.conf has higher priority
than <top_dir>/etc/keystone.conf. If you are also doing development on a
system that has keystone.conf installed in /etc/you need to disambiguate it by

     $ bin/keystone-control --confg-file etc/keystone.conf  --pid-file pidfile auth <start|stop|restart>

Also, keystone-control calls keystone-auth and it need to be in the PATH

     $ export PATH=<top_dir>/bin:$PATH


RUNNING TEST SERVICE:
---------------------

    Standalone stack (with Auth_Token)
    $ cd echo/echo
    $ python echo.py

    Distributed stack (with RemoteAuth local and Auth_Token remote)
    $ cd echo/echo
    $ python echo.py --remote

    in separate session
    $ cd keystone/auth_protocols
    $ python auth_token.py --remote

DEMO CLIENT:
---------------------
    $ cd echo/echo
    $ python echo_client.py

INSTALLING KEYSTONE:
--------------------

    $ python setup.py build
    $ sudo python setup.py install


INSTALLING TEST SERVICE:
------------------------

    $ cd echo
    $ python setup.py build
    $ sudo python setup.py install


TESTING
-------

After starting identity.py a keystone.db sql-lite database should be created.

To test setup the test database:

    $ sqlite3 keystone/keystone.db < test/test_setup.sql

To clean the test database

    $ sqlite3 keystone/keystone.db < test/kill.sql

To run client demo (with all auth middleware running locally on sample service):

    $ python echo/echo/echo.py
    $ python echo/echo/echo_client.py

To perform contract validation and load testing, use SoapUI (for now).

Using SOAPUI:

Download [SOAPUI](http://sourceforge.net/projects/soapui/files/):

To Test Identity Service:

* File->Import Project
* Select tests/IdentitySOAPUI.xml
* Double click on "Keystone Tests" and press the green play (>) button


Unit Test on Identity Services
------------------------------
In order to run the unit test on identity services start the auth sever

    $ cd test/unit
    $ ../../bin/keystone-auth

There are 8 groups of tests. They can be run individually or as an entire colection. To run the entire test suite run

    $ python test_keystone

A test can also be run individually e.g.

    $ python test_token


DATABASE SCHEMA
---------------

    CREATE TABLE groups(group_id varchar(255),group_desc varchar(255),tenant_id varchar(255),FOREIGN KEY(tenant_id) REFERENCES tenant(tenant_id));
    CREATE TABLE tenants(tenant_id varchar(255), tenant_desc varchar(255), tenant_enabled INTEGER, PRIMARY KEY(tenant_id ASC));
    CREATE TABLE token(token_id varchar(255),user_id varchar(255),expires datetime,tenant_id varchar(255));
    CREATE TABLE user_group(user_id varchar(255),group_id varchar(255), FOREIGN KEY(user_id) REFERENCES user(id), FOREIGN KEY(group_id) REFERENCES groups(group_id));
    CREATE TABLE user_tenant(tenant_id varchar(255),user_id varchar(255),FOREIGN KEY(tenant_id) REFERENCES tenant(tenant_id),FOREIGN KEY(user_id) REFERENCES user(id));
    CREATE TABLE users(id varchar(255),password varchar(255),email varchar(255),enabled integer);