| Concept | Description |
|---|---|
| User | An identity stored in the Keystone identity store used by a client to authenticate to Keystone. |
| Tenant | A container which houses multiple resources. For example, a tenant might represent an 'account' or 'company' which contains an arbitrary number of compute resources. One or more users may be assiciated and have rights to a tenant. |
| Role | A responsibility which is linked to a given user (and optionally scoped to a particular tenant). |
| Token | A 'token' describes a temporary object obtained by clients from Keystone and used to identify themselves to an OpenStack service. |
# Show dependencies $ cat tools/pip-requires # Install dependencies $ pip install -r tools/pip-requires # Install test dependencies $ pip install -r tools/pip-requires-testing # Install development dependencies $ pip install -r tools/pip-requires-development## Running Keystone Starting both Admin and Service API endpoints: $ ./bin/keystone Starting the auth server only (exposes the Service API): $ ./bin/keystone-auth Starting the admin server only (exposes the Admin API): $ ./bin/keystone-admin By default, configuration parameters (such as the IP and port binding for each service) are parsed from `etc/keystone.conf`. ## Running Tests Before running tests, ensure you have installed the testing dependencies as described in the Dependencies section above. To run the test suite in a single command: $ python keystone/test/run_tests.py #### Test data A set of sample data can be added by running a shell script: $ ./bin/sampledata.sh The script calls `keystone-manage` to create the sample data. After starting keystone or running `keystone-manage` a `keystone.db` sqlite database should be created in the keystone folder. #### Demo To run client demo (with all auth middleware running locally on sample service): $ ./examples/echo/bin/echod $ python examples/echo/echo_client.py #### Unit Tests There are 10 groups of tests. They can be run individually or as an entire colection. To run the entire test suite run: $ python keystone/test/unit/test_keystone.py A test can also be run individually, e.g.: $ python keystone/test/unit/test_token.py For more on unit testing please refer to: $ python keystone/test/unit/test_keystone.py --help #### API Validation To perform contract validation and load testing, use SoapUI (for now). Using SOAPUI: 1. First, download [SOAPUI](http://sourceforge.net/projects/soapui/files/): 2. To Test Keystone Service: * File->Import Project * Select tests/IdentitySOAPUI.xml * Double click on "Keystone Tests" and press the green play (>) button ## Writing Documentation ### Editing and Compiling the Developer Guide Users of the Keystone API are often developers making ReSTfull calls to Keystone. The guide to provide them information is therefore called a `Developer Guide`. Developer in this case is not to be confused with developers working on the Keystone source code itself. The [dev guide](https://github.com/rackspace/keystone/raw/master/keystone/content/identitydevguide.pdf) is automatically generated from XML and other artifacts that live in the [OpenStack Manuals project](https://launchpad.net/openstack-manuals). To build the Developer Guide from source, you need [Maven](http://maven.apache.org/). To build the docs and publish a new PDF: $ cd to folder with the pom.xml file $ mvn clean generate-sources && cp target/docbkx/pdf/identitydevguide.pdf ../../keystone/content/identitydevguide.pdf The output will go into the `target` folder (the source is in `src`). Output generated is PDF and webhelp. ### Editing and Compiling the Admin Guide The Admin guide is written in RST and compiled using sphinx. From the `keystone` folder: $ python setup.py build_sphinx && firefox build/sphinx/html/index.html ## Additional Information: #### Configuration: Keystone gets its configuration from command-line parameters or a .conf file. The file can be provided explicitely on the command line otherwise the following logic applies (the conf file in use will be output to help in troubleshooting: 1. config.py takes the config file from
# Get an unscoped token
$ curl -d '{"passwordCredentials": {"username": "joeuser", "password": "secrete"}}' -H "Content-type: application/json" http://localhost:5000/v2.0/tokens
# Get a token for a tenant
$ curl -d '{"passwordCredentials": {"username": "joeuser", "password": "secrete", "tenantId": "1234"}}' -H "Content-type: application/json" http://localhost:5000/v2.0/tokens
# Get an admin token
$ curl -d '{"passwordCredentials": {"username": "admin", "password": "secrete"}}' -H "Content-type: application/json" http://localhost:5001/v2.0/tokens
#### Load Testing
# Create post data
$ echo '{"passwordCredentials": {"username": "joeuser", "password": "secrete", "tenantId": "1234"}}' > post_data
# Call Apache Bench
$ ab -c 30 -n 1000 -T "application/json" -p post_data http://127.0.0.1:5001/v2.0/tokens
## NOVA Integration
Initial support for using keystone as nova's identity component has been started.
# clone projects
bzr clone lp:nova
git clone git://github.com/rackspace/keystone.git
# link keystone into the nova root dir
ln -s keystone/keystone nova/keystone
# run nova-api based on the paste config in keystone
nova/bin/nova-api --api_paste_config=keystone/examples/paste/nova-api-paste.ini
Assuming you added the test data using bin/sampledata.sh, you can then use joeuser/secrete
## Swift Integration - Quick Start
1. Install Swift, either from trunk or version 1.4.1 (once it's released) or
higher. Do the standard SAIO install with the included TempAuth to be sure
you have a working system to start with. This step is beyond the scope of
this quick start; see http://swift.openstack.org/development_saio.html for
a Swift development set up guide. Once you have a working Swift install, go
ahead and shut it down for now (the default Swift install uses the same
ports Keystone wants):
$ swift-init all stop
2. Obtain and install a source copy of Keystone:
$ git clone https://github.com/rackspace/keystone.git ~/keystone
...
$ cd ~/keystone && sudo python setup.py develop
...
3. Start up the Keystone service:
$ cd ~/keystone/bin && ./keystone
Starting the Legacy Authentication component
Service API listening on 0.0.0.0:5000
Admin API listening on 0.0.0.0:5001
4. In another window, edit the `~/keystone/bin/sampledata.sh` file, find the
`public.cloudfiles.com` text and replace it with the URL to your Swift
cluster using the following format (note that we're going to change Swift
to run on port 8888 later): `http://127.0.0.1:8888/v1/AUTH_%tenant_id%`
5. Create the sample data entries:
$ cd ~/keystone/bin && ./sampledata.sh
...
6. Reconfigure Swift's proxy server to use Keystone instead of TempAuth.
Here's an example `/etc/swift/proxy-server.conf`:
[DEFAULT]
bind_port = 8888
user =