Simplified README
Change-Id: I3bce24bdaed08de5bf8c103f9429022080096581
This commit is contained in:
parent
85a49ae612
commit
c3ce4b6840
273
README.md
273
README.md
@ -1,86 +1,36 @@
|
|||||||
# Keystone: OpenStack Identity Service
|
# Keystone: OpenStack Identity Service
|
||||||
|
|
||||||
Keystone is a proposed independent authentication service for [OpenStack](http://www.openstack.org).
|
Keystone is an identity 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:
|
This project aims to address the current use cases in Swift and Nova which are:
|
||||||
|
|
||||||
* REST-based, token auth for Swift
|
* RESTful token auth for Swift
|
||||||
* many-to-many relationship between identity and tenant for Nova.
|
* Many-to-many relationship between identity and tenant for Nova.
|
||||||
|
|
||||||
# For Users
|
# Documentation
|
||||||
|
|
||||||
## User Guide & Concepts
|
Learn about installing, configuring, managing, and developing the OpenStack Identity Service at the
|
||||||
|
[OpenStack Documentation](http://docs.openstack.org/) site.
|
||||||
|
|
||||||
The [`Developer Guide`](https://github.com/openstack/keystone/raw/master/keystone/content/identitydevguide.pdf)
|
NOTE: Contributors probably don't want to install keystone from packaging, and should instead follow the directions below.
|
||||||
documents the APIs to call and how to use them.
|
|
||||||
|
|
||||||
#### Core Concepts:
|
# For Contributors
|
||||||
<table>
|
|
||||||
<tr>
|
|
||||||
<th>Concept</th><th align="left">Description</th>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>User</td><td>An identity stored in the Keystone identity store used by a client to authenticate to Keystone.</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>Tenant</td><td>A container which houses multiple resources. <br/>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.</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>Role</td><td>A responsibility which is linked to a given user (and optionally scoped to a particular tenant).</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<td>Token</td><td>A 'token' describes a temporary object obtained by clients from Keystone and used to identify themselves to an OpenStack service.</td>
|
|
||||||
</tr>
|
|
||||||
</table>
|
|
||||||
|
|
||||||
## Running Keystone
|
## What's in the box?
|
||||||
|
|
||||||
#### Setup
|
### Services
|
||||||
|
|
||||||
$ sudo pip install -r tools/pip-requires
|
|
||||||
$ sudo python setup.py install
|
|
||||||
|
|
||||||
#### Starting services
|
|
||||||
Starting both Admin and Service API endpoints:
|
|
||||||
|
|
||||||
$ ./bin/keystone
|
|
||||||
|
|
||||||
### Temporary fix for Segfault
|
|
||||||
|
|
||||||
On some OSes, specifically Fedora 15, the current versions of
|
|
||||||
greenlet/eventlet segfault when running keystone. To fix this, install
|
|
||||||
the development versions of greenlet and eventlet
|
|
||||||
|
|
||||||
$ pip uninstall greenlet eventlet
|
|
||||||
$ cd <appropriate working directory>
|
|
||||||
$ hg clone https://bitbucket.org/ambroff/greenlet
|
|
||||||
$ cd greenlet
|
|
||||||
$ sudo python setup.py install
|
|
||||||
|
|
||||||
$ cd <appropriate working directory>
|
|
||||||
$ hg clone https://bitbucket.org/which_linden/eventlet
|
|
||||||
$ cd eventlet
|
|
||||||
$ sudo python setup.py install
|
|
||||||
|
|
||||||
|
|
||||||
# For Keystone Contributors
|
|
||||||
|
|
||||||
## Components
|
|
||||||
|
|
||||||
#### Services
|
|
||||||
|
|
||||||
* Keystone - identity store and authentication service
|
* Keystone - identity store and authentication service
|
||||||
* Auth_Token - WSGI middleware that can be used to handle token auth protocol (WSGI or remote proxy)
|
* 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
|
* Echo - A sample service that responds by returning call details
|
||||||
|
|
||||||
#### Also included:
|
### Also included:
|
||||||
|
|
||||||
* Keystone - Service and Admin API are available separately. Admin API allows management of tenants, roles, and users as well.
|
|
||||||
* Auth_Basic - Stub for WSGI middleware that will be used to handle basic auth
|
* 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 (to be implemented)
|
* Auth_OpenID - Stub for WSGI middleware that will be used to handle openid auth protocol (to be implemented)
|
||||||
* RemoteAuth - WSGI middleware that can be used in services (like Swift, Nova, and Glance) when Auth middleware is running remotely
|
* RemoteAuth - WSGI middleware that can be used in services (like Swift, Nova, and Glance) when Auth middleware is running remotely
|
||||||
|
|
||||||
#### Built-In commands:
|
### Built-In commands:
|
||||||
|
|
||||||
* bin/keystone - Provides HTTP API for users and administrators
|
* bin/keystone - Provides HTTP API for users and administrators
|
||||||
* bin/keystone-admin - Provides HTTP API for administrators
|
* bin/keystone-admin - Provides HTTP API for administrators
|
||||||
@ -89,20 +39,38 @@ the development versions of greenlet and eventlet
|
|||||||
|
|
||||||
By default, configuration parameters are parsed from `etc/keystone.conf`.
|
By default, configuration parameters are parsed from `etc/keystone.conf`.
|
||||||
|
|
||||||
## Dependencies
|
## Installing Dependencies
|
||||||
|
|
||||||
You may need to prefix your `pip install` commands with `sudo`, depending on your environment.
|
Keystone maintains a list of PyPi dependencies, designed for use by [pip](http://pypi.python.org/pypi/pip).
|
||||||
|
|
||||||
<pre>
|
*However*, your system may need additional dependencies that `pip` (and by extension, PyPi) cannot satisfy.
|
||||||
# Show dependencies
|
A list of such dependences is maintained in the `tools/pip-requires` file, and should be installed prior to using `pip`.
|
||||||
$ cat tools/pip-requires
|
|
||||||
|
|
||||||
# Install dependencies (for production, testing, and development)
|
You may also need to prefix `pip install` with `sudo`, depending on your environment.
|
||||||
$ pip install -r tools/pip-requires
|
|
||||||
|
|
||||||
# Optional: Install Memcache (if enabled as a backend)
|
# Describe dependencies (including non-PyPi dependencies)
|
||||||
Refer #(http://memcached.org/)
|
$ cat tools/pip-requires
|
||||||
</pre>
|
|
||||||
|
# Install all PyPi dependencies (for production, testing, and development)
|
||||||
|
$ pip install -r tools/pip-requires
|
||||||
|
|
||||||
|
## Updating your PYTHONPATH
|
||||||
|
|
||||||
|
There are a number of methods for getting Keystone into your PYTHON PATH, the easiest of which is:
|
||||||
|
|
||||||
|
# Fake-install the project by symlinking Keystone into your Python site-packages
|
||||||
|
$ python setup.py develop
|
||||||
|
|
||||||
|
You should then be able to `import keystone` from your Python shell without issue:
|
||||||
|
|
||||||
|
>>> import keystone
|
||||||
|
>>>
|
||||||
|
|
||||||
|
## Testing Keystone
|
||||||
|
|
||||||
|
To run the entire test suite, with test progress shown in realtime, use:
|
||||||
|
|
||||||
|
$ ./run_tests.sh --with-progress
|
||||||
|
|
||||||
## Running Keystone
|
## Running Keystone
|
||||||
|
|
||||||
@ -120,57 +88,31 @@ Starting the admin server only (exposes the Admin API):
|
|||||||
|
|
||||||
By default, configuration parameters (such as the IP and port binding for each service) are parsed from `etc/keystone.conf`.
|
By default, configuration parameters (such as the IP and port binding for each service) are parsed from `etc/keystone.conf`.
|
||||||
|
|
||||||
|
## Configuring Keystone
|
||||||
|
|
||||||
## Running Tests
|
Keystone gets its configuration from command-line parameters or a `.conf` file. While command line parameters take precedence,
|
||||||
|
Keystone looks in the following location to find a configuration file:
|
||||||
|
|
||||||
Before running tests, ensure you have installed the testing dependencies as described in the Dependencies section above.
|
1. Command line parameter
|
||||||
|
2. /etc/keystone.conf
|
||||||
|
3. /etc/keystone/keystone.conf
|
||||||
|
4. <topdir>/etc/keystone.conf
|
||||||
|
|
||||||
To run the test suite in a single command:
|
Additional configuration templates are maintained in `keystone/test/etc/` that may be useful as a reference.
|
||||||
|
|
||||||
$ python keystone/test/run_tests.py
|
|
||||||
|
|
||||||
|
|
||||||
#### Sample data
|
|
||||||
A set of sample data can be added by running a shell script:
|
|
||||||
|
|
||||||
$ ./bin/sampledata
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
|
|
||||||
#### 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
|
|
||||||
|
|
||||||
|
## Contributing Changes
|
||||||
|
|
||||||
|
Refer to our [Gerrit-Jenkins-Github Workflow](http://wiki.openstack.org/GerritJenkinsGithub).
|
||||||
## Writing Documentation
|
## Writing Documentation
|
||||||
|
|
||||||
### Editing and Compiling the Developer Guide
|
### Editing and Building the API Developer Guide
|
||||||
|
|
||||||
Users of the Keystone API are often developers making ReSTfull calls to Keystone. The guide to provide them
|
Users of the Keystone API are often developers making ReSTful API 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
|
information is therefore called a `Developer Guide`. Developer in this case is not to be confused with contributors
|
||||||
working on the Keystone source code itself.
|
working on the Keystone codebase itself.
|
||||||
|
|
||||||
The [dev guide](https://github.com/openstack/keystone/raw/master/keystone/content/identitydevguide.pdf) is automatically
|
The developer guides are automatically generated from XML and other artifacts that live in the
|
||||||
generated from XML and other artifacts that live in the [OpenStack Manuals project](https://launchpad.net/openstack-manuals).
|
[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:
|
To build the Developer Guide from source, you need [Maven](http://maven.apache.org/). To build the docs and publish a new PDF:
|
||||||
|
|
||||||
@ -179,48 +121,52 @@ To build the Developer Guide from source, you need [Maven](http://maven.apache.o
|
|||||||
|
|
||||||
The output will go into the `target` folder (the source is in `src`). Output generated is PDF and webhelp.
|
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
|
### Editing and Building the Admin Guide
|
||||||
|
|
||||||
The Admin guide is written in RST and compiled using sphinx. From the `keystone` folder:
|
The Admin guide is written in RST and built using sphinx. From the `keystone` folder:
|
||||||
|
|
||||||
$ python setup.py build_sphinx && firefox build/sphinx/html/index.html
|
$ python setup.py build_sphinx && firefox build/sphinx/html/index.html
|
||||||
|
|
||||||
|
# Additional Information:
|
||||||
|
|
||||||
## Additional Information:
|
## Sample data
|
||||||
|
|
||||||
#### Configuration:
|
A set of sample data can be loaded by running a shell script:
|
||||||
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 <topdir>/etc/keystone.conf
|
$ ./bin/sampledata
|
||||||
2. If the keystone package is also intalled on the system,
|
|
||||||
/etc/keystone.conf or /etc/keystone/keystone.conf have higher priority than <top_dir>/etc/keystone.conf.
|
The script calls `keystone-manage` to import the sample data.
|
||||||
|
|
||||||
|
After starting keystone or running `keystone-manage` a `keystone.db` sqlite database should be created in the keystone folder,
|
||||||
|
per the default configuration.
|
||||||
|
|
||||||
|
## Demo
|
||||||
|
|
||||||
|
To run client demo (with all auth middleware running locally on sample service):
|
||||||
|
|
||||||
|
$ ./examples/echo/bin/echod
|
||||||
|
$ python examples/echo/echo_client.py
|
||||||
|
|
||||||
|
## CURL commands
|
||||||
|
|
||||||
#### CURL commands
|
|
||||||
<pre>
|
<pre>
|
||||||
# Get an unscoped token
|
# Get an unscoped token
|
||||||
|
|
||||||
$ curl -d '{"auth": {"passwordCredentials": {"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:5000/v2.0/tokens
|
$ curl -d '{"auth": {"passwordCredentials": {"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:5000/v2.0/tokens
|
||||||
|
|
||||||
# Get a token for a tenant
|
# Get a token for a tenant
|
||||||
|
|
||||||
$ curl -d '{"auth": {"passwordCredentials": {"username": "joeuser", "password": "secrete"}, "tenantName": "customer-x"}}' -H "Content-type: application/json" http://localhost:5000/v2.0/tokens
|
$ curl -d '{"auth": {"passwordCredentials": {"username": "joeuser", "password": "secrete"}, "tenantName": "customer-x"}}' -H "Content-type: application/json" http://localhost:5000/v2.0/tokens
|
||||||
|
|
||||||
# Get an admin token
|
# Get an admin token
|
||||||
|
|
||||||
$ curl -d '{"auth": {"passwordCredentials": {"username": "admin", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens
|
$ curl -d '{"auth": {"passwordCredentials": {"username": "admin", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
#### Load Testing
|
## Load Testing
|
||||||
|
|
||||||
<pre>
|
<pre>
|
||||||
# Create post data
|
# Create post data
|
||||||
|
|
||||||
$ echo '{"auth": {"passwordCredentials": {"username": "joeuser", "password": "secrete", "tenantName": "customer-x"}}}' > post_data
|
$ echo '{"auth": {"passwordCredentials": {"username": "joeuser", "password": "secrete", "tenantName": "customer-x"}}}' > post_data
|
||||||
|
|
||||||
# Call Apache Bench
|
# Call Apache Bench
|
||||||
|
|
||||||
$ ab -c 30 -n 1000 -T "application/json" -p post_data http://127.0.0.1:35357/v2.0/tokens
|
$ ab -c 30 -n 1000 -T "application/json" -p post_data http://127.0.0.1:35357/v2.0/tokens
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
@ -335,61 +281,32 @@ account.**
|
|||||||
|
|
||||||
But, it works as a demo!
|
But, it works as a demo!
|
||||||
|
|
||||||
|
## LDAP Setup on a Mac
|
||||||
## I want OpenStack (all of it)
|
|
||||||
|
|
||||||
To get an opinionated install of nova, keystone, dashboard and glance using openstack apis:
|
|
||||||
|
|
||||||
# create a maverick cloud server
|
|
||||||
curl -O https://github.com/cloudbuilders/deploy.sh/raw/master/nova.sh
|
|
||||||
chmod 755 nova.sh
|
|
||||||
export USE_GIT=1 # checkout source using github mirror
|
|
||||||
export ENABLE_VOLUMES=0 # disable volumes
|
|
||||||
export ENABLE_DASH=1 # install & configure dashboard
|
|
||||||
export ENABLE_GLANCE=1 # install & configure glance image service
|
|
||||||
export ENABLE_KEYSTONE=1 # install & configure keystone (unified auth)
|
|
||||||
./nova.sh branch
|
|
||||||
./nova.sh install
|
|
||||||
# nova's patched libvirt ppa doesn't work on cloud servers, revert to old libvirt
|
|
||||||
apt-get install -y --force-yes libvirt0=0.8.3-1ubuntu14.1 libvirt-bin=0.8.3-1ubuntu14.1 python-libvirt=0.8.3-1ubuntu14.1
|
|
||||||
./nova.sh run
|
|
||||||
|
|
||||||
|
|
||||||
## Relevant Technologies, Standards, and Links
|
|
||||||
|
|
||||||
### Useful links
|
|
||||||
|
|
||||||
https://sites.google.com/site/oauthgoog/Overlap
|
|
||||||
|
|
||||||
|
|
||||||
### Protocols
|
|
||||||
We could potentially integrate with those:
|
|
||||||
|
|
||||||
[WebID](http://www.w3.org/2005/Incubator/webid/spec/) - See also: (http://www.w3.org/wiki/Foaf+ssl)
|
|
||||||
|
|
||||||
[OpenID](http://openid.net/) and/or [OpenIDConnect](http://openidconnect.com/)
|
|
||||||
|
|
||||||
[OAUTH2](http://oauth.net/2/)
|
|
||||||
|
|
||||||
[SAML] (http://saml.xml.org/)
|
|
||||||
|
|
||||||
### LDAP Setup
|
|
||||||
|
|
||||||
#### On a Mac
|
|
||||||
|
|
||||||
Using macports:
|
Using macports:
|
||||||
|
|
||||||
sudo port install openldap
|
sudo port install openldap
|
||||||
|
|
||||||
It appears the package `python-ldap` needs to be recompiled to work. So,
|
It appears the package `python-ldap` needs to be recompiled to work. So,
|
||||||
download it from: http://pypi.python.org/pypi/python-ldap/2.4.1
|
download it from: http://pypi.python.org/pypi/python-ldap/2.4.1
|
||||||
|
|
||||||
After unpacking, edit `setup.cfg` as shown below:
|
After unpacking, edit `setup.cfg` as shown below:
|
||||||
|
|
||||||
library_dirs = /opt/local/lib
|
library_dirs = /opt/local/lib
|
||||||
include_dirs = /opt/local/include /usr/include/sasl
|
include_dirs = /opt/local/include /usr/include/sasl
|
||||||
|
|
||||||
Then, run:
|
Then, run:
|
||||||
|
|
||||||
python setup.py build
|
python setup.py build
|
||||||
sudo python setup.py install
|
sudo python setup.py install
|
||||||
|
|
||||||
|
# Relevant Standards and Technologies
|
||||||
|
|
||||||
|
[Overlap of Identity Technologies](https://sites.google.com/site/oauthgoog/Overlap)
|
||||||
|
|
||||||
|
Keystone could potentially integrate with:
|
||||||
|
|
||||||
|
1. [WebID](http://www.w3.org/2005/Incubator/webid/spec/) (See also [FOAF+SSL](http://www.w3.org/wiki/Foaf+ssl))
|
||||||
|
2. [OpenID](http://openid.net/) and/or [OpenIDConnect](http://openidconnect.com/)
|
||||||
|
3. [OAUTH2](http://oauth.net/2/)
|
||||||
|
4. [SAML](http://saml.xml.org/)
|
||||||
|
Loading…
Reference in New Issue
Block a user