diff options
| author |   RHE <rebirthmonkey@gmail.com> | 2017-11-24 13:54:26 +0100 |
|---|---|---|
| committer | RHE <rebirthmonkey@gmail.com> | 2017-11-24 13:54:26 +0100 |
| commit | 920a49cfa055733d575282973e23558c33087a4a (patch) | |
| tree | d371dab34efa5028600dad2e7ca58063626e7ba4 /keystone-moon/doc | |
| parent | ef3eefca70d8abb4a00dafb9419ad32738e934b2 (diff) | |
remove keystone-moon
Change-Id: I80d7c9b669f19d5f6607e162de8e0e55c2f80fdd
Signed-off-by: RHE <rebirthmonkey@gmail.com>
Diffstat (limited to 'keystone-moon/doc')
52 files changed, 0 insertions, 12601 deletions
diff --git a/keystone-moon/doc/Makefile b/keystone-moon/doc/Makefile deleted file mode 100644 index 79861705..00000000 --- a/keystone-moon/doc/Makefile +++ /dev/null @@ -1,159 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build -SOURCEDIR = source -SPHINXAPIDOC = sphinx-apidoc - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make <target>' where <target> is one of" - @echo " autodoc generate the autodoc templates" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -autodoc: - $(SPHINXAPIDOC) -f -o $(SOURCEDIR) ../keystone - -html: autodoc - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/keystone.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/keystone.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/keystone" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/keystone" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/keystone-moon/doc/README.rst b/keystone-moon/doc/README.rst deleted file mode 100644 index a9537b9a..00000000 --- a/keystone-moon/doc/README.rst +++ /dev/null @@ -1,9 +0,0 @@ -Building Docs -============= - -Developer documentation is generated using Sphinx. To build this documentation, -run the following from the root of the repository:: - - $ tox -e docs - -The documentation will be built at ``doc/build/``. diff --git a/keystone-moon/doc/ext/__init__.py b/keystone-moon/doc/ext/__init__.py deleted file mode 100644 index e69de29b..00000000 --- a/keystone-moon/doc/ext/__init__.py +++ /dev/null diff --git a/keystone-moon/doc/ext/apidoc.py b/keystone-moon/doc/ext/apidoc.py deleted file mode 100644 index 435d388f..00000000 --- a/keystone-moon/doc/ext/apidoc.py +++ /dev/null @@ -1,45 +0,0 @@ -# Copyright 2013 OpenStack Foundation -# -# Licensed under the Apache License, Version 2.0 (the "License"); you may -# not use this file except in compliance with the License. You may obtain -# a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -# License for the specific language governing permissions and limitations -# under the License. - -# NOTE(dstanek): Uncomment the [pbr] section in setup.cfg and remove this -# Sphinx extension when https://launchpad.net/bugs/1260495 is fixed. - -import os.path as path - -from sphinx import apidoc - - -# NOTE(dstanek): pbr will run Sphinx multiple times when it generates -# documentation. Once for each builder. To run this extension we use the -# 'builder-inited' hook that fires at the beginning of a Sphinx build. -# We use ``run_already`` to make sure apidocs are only generated once -# even if Sphinx is run multiple times. -run_already = False - - -def run_apidoc(app): - global run_already - if run_already: - return - run_already = True - - package_dir = path.abspath(path.join(app.srcdir, '..', '..', 'keystone')) - source_dir = path.join(app.srcdir, 'api') - apidoc.main(['apidoc', package_dir, '-f', - '-H', 'Keystone Modules', - '-o', source_dir]) - - -def setup(app): - app.connect('builder-inited', run_apidoc) diff --git a/keystone-moon/doc/keystone_compat_flows.sdx b/keystone-moon/doc/keystone_compat_flows.sdx deleted file mode 100644 index f1fcc5f0..00000000 --- a/keystone-moon/doc/keystone_compat_flows.sdx +++ /dev/null @@ -1,99 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" standalone="no"?> -<diagram> -<source><![CDATA[client:client "Client" -compat:compat "Compat" -token:token "Token Service" -identity:identity "Identity Service" -catalog:catalog "Catalog Service" - -[c "Auth, No Tenant"] -client:{token, user, service_catalog}=compat.POST /v2.0/tokens {'username': user, 'password': password} - compat:(user, password, None)=identity.authenticate(user, password, tenant=None) - compat:(id, user, password, None)=token.create_token(user, password, tenant=None) - compat:{service_catalog (includes all tenants)}=catalog.get_catalog(user, None) -[/c] - -[c "Auth, With Tenant"] -client:{scoped_token, user, service_catalog}=compat.POST /v2.0/tokens {'username': user, 'password': password, 'tenant': tenant} - compat:(user, password, tenant)=identity.authenticate(user, password, tenant) - compat:(id, user, password, tenant)=token.create_token(user, password, tenant) - compat:{service_catalog (includes all tenants)}=catalog.get_catalog(user, tenant) -[/c] - -[c "Validate Token, Unscoped"] -client:{token, user, tenant=None}=compat.GET /v2.0/tokens/$token -compat:{token, user, tenant}=token.get_token($token) -[/c] - -[c "Validate Token, With Tenant"] -client:{token, user, tenant}=compat.GET /v2.0/tokens/$token?belongs_to=$tenant -compat:{token, user, tenant}=token.get_token($token) -[/c] - -[c "Tenants for Token"] -client:{tenants}=compat.(X-Auth-Token: $token) GET /v2.0/tenants -compat:{token, user, tenant}=token.get_token($token) -compat:{token, user, tenant}=identity.get_tenants($user) -[/c]]]></source> -<configuration> -<property name="activationBarBorderThickness" value="1"/> -<property name="actorWidth" value="25"/> -<property name="arrowColor" value="-14803256"/> -<property name="arrowSize" value="6"/> -<property name="arrowThickness" value="1"/> -<property name="colorizeThreads" value="true"/> -<property name="destructorWidth" value="30"/> -<property name="explicitReturns" value="false"/> -<property family="Dialog" name="font" size="12" style="0"/> -<property name="fragmentBorderThickness" value="2"/> -<property name="fragmentEdgeColor" value="-16751616"/> -<property name="fragmentLabelBgColor" value="-36"/> -<property name="fragmentMargin" value="8"/> -<property name="fragmentPadding" value="10"/> -<property name="fragmentTextPadding" value="3"/> -<property name="glue" value="10"/> -<property name="headHeight" value="35"/> -<property name="headLabelPadding" value="5"/> -<property name="headWidth" value="100"/> -<property name="initialSpace" value="10"/> -<property name="labeledBoxBgColor" value="-76"/> -<property name="leftMargin" value="5"/> -<property name="lifelineThickness" value="1"/> -<property name="lineWrap" value="false"/> -<property name="lowerMargin" value="5"/> -<property name="mainLifelineWidth" value="8"/> -<property name="messageLabelSpace" value="3"/> -<property name="messagePadding" value="6"/> -<property name="noteBgColor" value="-76"/> -<property name="noteBorderThickness" value="1"/> -<property name="noteMargin" value="6"/> -<property name="notePadding" value="6"/> -<property name="opaqueMessageText" value="false"/> -<property name="returnArrowVisible" value="true"/> -<property name="rightMargin" value="5"/> -<property name="selfMessageHorizontalSpace" value="15"/> -<property name="separatorBottomMargin" value="8"/> -<property name="separatorTopMargin" value="15"/> -<property name="shouldShadowParticipants" value="true"/> -<property name="slackMode" value="false"/> -<property name="spaceBeforeActivation" value="2"/> -<property name="spaceBeforeAnswerToSelf" value="10"/> -<property name="spaceBeforeConstruction" value="6"/> -<property name="spaceBeforeSelfMessage" value="7"/> -<property name="subLifelineWidth" value="6"/> -<property name="tc0" value="-1118482"/> -<property name="tc1" value="-256"/> -<property name="tc2" value="-65536"/> -<property name="tc3" value="-16776961"/> -<property name="tc4" value="-16711936"/> -<property name="tc5" value="-4144960"/> -<property name="tc6" value="-65281"/> -<property name="tc7" value="-14336"/> -<property name="tc8" value="-20561"/> -<property name="tc9" value="-12566464"/> -<property name="threadNumbersVisible" value="false"/> -<property name="threaded" value="true"/> -<property name="upperMargin" value="5"/> -<property name="verticallySplit" value="true"/> -</configuration> -</diagram> diff --git a/keystone-moon/doc/source/apache-httpd.rst b/keystone-moon/doc/source/apache-httpd.rst deleted file mode 100644 index 1436ddad..00000000 --- a/keystone-moon/doc/source/apache-httpd.rst +++ /dev/null @@ -1,152 +0,0 @@ - -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -========================= -Running Keystone in HTTPD -========================= - -mod_proxy_uwsgi ---------------- - -The recommended keystone deployment is to have a real web server such as Apache -HTTPD or nginx handle the HTTP connections and proxy requests to an independent -keystone server (or servers) running under a wsgi container such as uwsgi or -gunicorn. The typical deployment will have several applications proxied by the -web server (for example horizon on /dashboard and keystone on /identity, -/identity_admin, port :5000, and :35357). Proxying allows the applications to -be shut down and restarted independently, and a problem in one application -isn't going to affect the web server or other applications. The servers can -easily be run in their own virtualenvs. - -The httpd/ directory contains sample files for configuring HTTPD to proxy -requests to keystone servers running under uwsgi. - -Copy the `httpd/uwsgi-keystone.conf` sample configuration file to the -appropriate location for your Apache server, on Debian/Ubuntu systems it is:: - - /etc/apache2/sites-available/uwsgi-keystone.conf - -On Red Hat based systems it is:: - - /etc/httpd/conf.d/uwsgi-keystone.conf - -Update the file to match your system configuration. Enable TLS by supplying the -correct certificates. - -Enable mod_proxy_uwsgi. - -* On Ubuntu the required package is libapache2-mod-proxy-uwsgi; enable using - ``sudo a2enmod proxy`` -* On Fedora the required package is mod_proxy_uwsgi; enable by creating a file - ``/etc/httpd/conf.modules.d/11-proxy_uwsgi.conf`` containing - ``LoadModule proxy_uwsgi_module modules/mod_proxy_uwsgi.so`` - -Enable the site by creating a symlink from the file in ``sites-available`` to -``sites-enabled``, for example, on Debian/Ubuntu systems -(not required on Red Hat based systems):: - - ln -s /etc/apache2/sites-available/uwsgi-keystone.conf /etc/apache2/sites-enabled/ - -Start or restart HTTPD to pick up the new configuration. - -Now configure and start the uwsgi services. Copy the -`httpd/keystone-uwsgi-admin.ini` and `httpd/keystone-uwsgi-public.ini` files to -`/etc/keystone`. Update the files to match your system configuration (for -example, you'll want to set the number of threads for the public and admin -servers). - -Start up the keystone servers using uwsgi:: - - $ sudo pip install uwsgi - $ uwsgi /etc/keystone/keystone-uwsgi-admin.ini - $ uwsgi /etc/keystone/keystone-uwsgi-public.ini - - -mod_wsgi --------- - -.. WARNING:: - - Running Keystone under HTTPD in this configuration does not support the use - of ``Transfer-Encoding: chunked``. This is due to a limitation with the - WSGI spec and the implementation used by ``mod_wsgi``. It is recommended - that all clients assume Keystone will not support - ``Transfer-Encoding: chunked``. - -Copy the ``httpd/wsgi-keystone.conf`` sample configuration file to the -appropriate location for your Apache server, on Debian/Ubuntu systems -it is:: - - /etc/apache2/sites-available/wsgi-keystone.conf - -On Red Hat based systems it is:: - - /etc/httpd/conf.d/wsgi-keystone.conf - -Update the file to match your system configuration. Note the following: - -* Make sure the correct log directory is used. Some distributions put httpd - server logs in the ``apache2`` directory and some in the ``httpd`` directory. -* Enable TLS by supplying the correct certificates. - -Keystone's primary configuration file (``etc/keystone.conf``) and the -PasteDeploy configuration file (``etc/keystone-paste.ini``) must be readable to -HTTPD in one of the default locations described in :doc:`configuration`. - -Enable the site by creating a symlink from the file in ``sites-available`` to -``sites-enabled``, for example, on Debian/Ubuntu systems -(not required on Red Hat based systems):: - - ln -s /etc/apache2/sites-available/wsgi-keystone.conf /etc/apache2/sites-enabled/ - -Restart Apache to have it start serving keystone. - - -Access Control --------------- - -If you are running with Linux kernel security module enabled (for example -SELinux or AppArmor) make sure that the file has the appropriate context to -access the linked file. - -Keystone Configuration ----------------------- - -Make sure that when using a token format that requires persistence, you use a -token persistence driver that can be shared between processes. The SQL and -memcached token persistence drivers provided with keystone can be shared -between processes. - -.. WARNING:: - - The KVS (``kvs``) token persistence driver cannot be shared between - processes so must not be used when running keystone under HTTPD (the tokens - will not be shared between the processes of the server and validation will - fail). - -For SQL, in ``/etc/keystone/keystone.conf`` set:: - - [token] - driver = sql - -For memcached, in ``/etc/keystone/keystone.conf`` set:: - - [token] - driver = memcache - -All servers that are storing tokens need a shared backend. This means that -either all servers use the same database server or use a common memcached pool. diff --git a/keystone-moon/doc/source/api_curl_examples.rst b/keystone-moon/doc/source/api_curl_examples.rst deleted file mode 100644 index 066efe97..00000000 --- a/keystone-moon/doc/source/api_curl_examples.rst +++ /dev/null @@ -1,1188 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======================= -API Examples using Curl -======================= - --------------------------- -v3 API Examples Using Curl --------------------------- - -Tokens -====== - -Default scope -------------- - -Get a token with default scope (may be unscoped): - -.. code-block:: bash - - curl -i \ - -H "Content-Type: application/json" \ - -d ' - { "auth": { - "identity": { - "methods": ["password"], - "password": { - "user": { - "name": "admin", - "domain": { "id": "default" }, - "password": "adminpwd" - } - } - } - } - }' \ - http://localhost:5000/v3/auth/tokens ; echo - -Example response:: - - HTTP/1.1 201 Created - X-Subject-Token: MIIFvgY... - Vary: X-Auth-Token - Content-Type: application/json - Content-Length: 1025 - Date: Tue, 10 Jun 2014 20:55:16 GMT - - {"token": {"methods": ["password"], "roles": [{"id": - "9fe2ff9ee4384b1894a90878d3e92bab", "name": "_member_"}, {"id": - "c703057be878458588961ce9a0ce686b", "name": "admin"}], "expires_at": - "2014-06-10T2:55:16.806001Z", "project": {"domain": {"id": "default", "name": - "Default"}, "id": "8538a3f13f9541b28c2620eb19065e45", "name": "admin"}, - "catalog": [{"endpoints": [{"url": "http://localhost:3537/v2.0", "region": - "RegionOne", "interface": "admin", "id": "29beb2f1567642eb810b042b6719ea88"}, - {"url": "http://localhost:5000/v2.0", "region": "RegionOne", "interface": - "internal", "id": "8707e3735d4415c97ae231b4841eb1c"}, {"url": - "http://localhost:5000/v2.0", "region": "RegionOne", "interface": "public", - "id": "ef303187fc8d41668f25199c298396a5"}], "type": "identity", "id": - "bd73972c0e14fb69bae8ff76e112a90", "name": "keystone"}], "extras": {}, - "user": {"domain": {"id": "default", "name": "Default"}, "id": - "3ec3164f750146be97f21559ee4d9c51", "name": "admin"}, "audit_ids": - ["yRt0UrxJSs6-WYJgwEMMmg"], "issued_at": "201406-10T20:55:16.806027Z"}} - - -Project-scoped --------------- - -Get a project-scoped token: - -.. code-block:: bash - - curl -i \ - -H "Content-Type: application/json" \ - -d ' - { "auth": { - "identity": { - "methods": ["password"], - "password": { - "user": { - "name": "admin", - "domain": { "id": "default" }, - "password": "adminpwd" - } - } - }, - "scope": { - "project": { - "name": "demo", - "domain": { "id": "default" } - } - } - } - }' \ - http://localhost:5000/v3/auth/tokens ; echo - -Example response:: - - HTTP/1.1 201 Created - X-Subject-Token: MIIFfQ... - Vary: X-Auth-Token - Content-Type: application/json - Content-Length: 960 - Date: Tue, 10 Jun 2014 20:40:14 GMT - - {"token": {"audit_ids": ["ECwrVNWbSCqmEgPnu0YCRw"], "methods": ["password"], - "roles": [{"id": "c703057be878458588961ce9a0ce686b", "name": "admin"}], - "expires_at": "2014-06-10T21:40:14.360795Z", "project": {"domain": {"id": - "default", "name": "Default"}, "id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c", - "name": "demo"}, "catalog": [{"endpoints": [{"url": - "http://localhost:35357/v2.0", "region": "RegionOne", "interface": "admin", - "id": "29beb2f1567642eb810b042b6719ea88"}, {"url": - "http://localhost:5000/v2.0", "region": "RegionOne", "interface": - "internal", "id": "87057e3735d4415c97ae231b4841eb1c"}, {"url": - "http://localhost:5000/v2.0", "region": "RegionOne", "interface": "public", - "id": "ef303187fc8d41668f25199c298396a5"}], "type": "identity", "id": - "bd7397d2c0e14fb69bae8ff76e112a90", "name": "keystone"}], "extras": {}, - "user": {"domain": {"id": "default", "name": "Default"}, "id": - "3ec3164f750146be97f21559ee4d9c51", "name": "admin"}, "issued_at": - "2014-06-10T20:40:14.360822Z"}} - - -Domain-Scoped -------------- - -Get a domain-scoped token (Note that you're going to need a role-assignment on -the domain first!): - -.. code-block:: bash - - curl -i \ - -H "Content-Type: application/json" \ - -d ' - { "auth": { - "identity": { - "methods": ["password"], - "password": { - "user": { - "name": "admin", - "domain": { "id": "default" }, - "password": "adminpwd" - } - } - }, - "scope": { - "domain": { - "id": "default" - } - } - } - }' \ - http://localhost:5000/v3/auth/tokens ; echo - -Example response:: - - HTTP/1.1 201 Created - X-Subject-Token: MIIFNg... - Vary: X-Auth-Token - Content-Type: application/json - Content-Length: 889 - Date: Tue, 10 Jun 2014 20:52:59 GMT - - {"token": {"domain": {"id": "default", "name": "Default"}, "methods": - ["password"], "roles": [{"id": "c703057be878458588961ce9a0ce686b", "name": - "admin"}], "expires_at": "2014-06-10T21:52:58.852167Z", "catalog": - [{"endpoints": [{"url": "http://localhost:35357/v2.0", "region": "RegionOne", - "interface": "admin", "id": "29beb2f1567642eb810b042b6719ea88"}, {"url": - "http://localhost:5000/v2.0", "region": "RegionOne", "interface": "internal", - "id": "87057e3735d4415c97ae231b4841eb1c"}, {"url": - "http://localhost:5000/v2.0", "region": "RegionOne", "interface": "public", - "id": "ef303187fc8d41668f25199c298396a5"}], "type": "identity", "id": - "bd7397d2c0e14fb69bae8ff76e112a90", "name": "keystone"}], "extras": {}, - "user": {"domain": {"id": "default", "name": "Default"}, "id": - "3ec3164f750146be97f21559ee4d9c51", "name": "admin"}, - "audit_ids": ["Xpa6Uyn-T9S6mTREudUH3w"], "issued_at": - "2014-06-10T20:52:58.852194Z"}} - - -Getting a token from a token ----------------------------- - -Get a token from a token: - -.. code-block:: bash - - curl -i \ - -H "Content-Type: application/json" \ - -d ' - { "auth": { - "identity": { - "methods": ["token"], - "token": { - "id": "'$OS_TOKEN'" - } - } - } - }' \ - http://localhost:5000/v3/auth/tokens ; echo - - -Example response:: - - HTTP/1.1 201 Created - X-Subject-Token: MIIFxw... - Vary: X-Auth-Token - Content-Type: application/json - Content-Length: 1034 - Date: Tue, 10 Jun 2014 21:00:05 GMT - - {"token": {"methods": ["token", "password"], "expires_at": - "2015-05-28T07:43:44.808209Z", "extras": {}, "user": {"domain": {"id": - "default", "name": "Default"}, "id": "753867c25c3340ffad1abc22d488c31a", - "name": "admin"}, "audit_ids": ["ZE0OPSuzTmCXHo0eIOYltw", - "xxIQCkHOQOywL0oY6CTppQ"], "issued_at": "2015-05-28T07:19:23.763532Z"}} - -.. note:: - - If a scope was included in the request body then this would get a token - with the new scope. - - -DELETE /v3/auth/tokens ----------------------- - -Revoke a token: - -.. code-block:: bash - - curl -i -X DELETE \ - -H "X-Auth-Token: $OS_TOKEN" \ - -H "X-Subject-Token: $OS_TOKEN" \ - http://localhost:5000/v3/auth/tokens - -If there's no error then the response is empty. - - -Domains -======= - -GET /v3/domains ---------------- - -List domains: - -.. code-block:: bash - - curl -s \ - -H "X-Auth-Token: $OS_TOKEN" \ - http://localhost:5000/v3/domains | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "domains": [ - { - "description": "Owns users and tenants (i.e. projects) available on Identity API v2.", - "enabled": true, - "id": "default", - "links": { - "self": "http://identity-server:5000/v3/domains/default" - }, - "name": "Default" - } - ], - "links": { - "next": null, - "previous": null, - "self": "http://identity-server:5000/v3/domains" - } - } - - -POST /v3/domains ----------------- - -Create a domain: - -.. code-block:: bash - - curl -s \ - -H "X-Auth-Token: $OS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ "domain": { "name": "newdomain"}}' \ - http://localhost:5000/v3/domains | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "domain": { - "enabled": true, - "id": "3a5140aecd974bf08041328b53a62458", - "links": { - "self": "http://identity-server:5000/v3/domains/3a5140aecd974bf08041328b53a62458" - }, - "name": "newdomain" - } - } - - -Projects -======== - -GET /v3/projects ----------------- - -List projects: - -.. code-block:: bash - - curl -s \ - -H "X-Auth-Token: $OS_TOKEN" \ - http://localhost:5000/v3/projects | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "links": { - "next": null, - "previous": null, - "self": "http://localhost:5000/v3/projects" - }, - "projects": [ - { - "description": null, - "domain_id": "default", - "enabled": true, - "id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c", - "links": { - "self": "http://localhost:5000/v3/projects/3d4c2c82bd5948f0bcab0cf3a7c9b48c" - }, - "name": "demo" - } - ] - } - - -PATCH /v3/projects/{id} ------------------------ - -Disable a project: - -.. code-block:: bash - - curl -s -X PATCH \ - -H "X-Auth-Token: $OS_TOKEN" \ - -H "Content-Type: application/json" \ - -d ' - { - "project": { - "enabled": false - } - }'\ - http://localhost:5000/v3/projects/$PROJECT_ID | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "project": { - "description": null, - "domain_id": "default", - "enabled": false, - "extra": {}, - "id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c", - "links": { - "self": "http://localhost:5000/v3/projects/3d4c2c82bd5948f0bcab0cf3a7c9b48c" - }, - "name": "demo" - } - } - - -GET /v3/services -================ - -List the services: - -.. code-block:: bash - - curl -s \ - -H "X-Auth-Token: $OS_TOKEN" \ - http://localhost:5000/v3/services | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "links": { - "next": null, - "previous": null, - "self": "http://localhost:5000/v3/services" - }, - "services": [ - { - "description": "Keystone Identity Service", - "enabled": true, - "id": "bd7397d2c0e14fb69bae8ff76e112a90", - "links": { - "self": "http://localhost:5000/v3/services/bd7397d2c0e14fb69bae8ff76e112a90" - }, - "name": "keystone", - "type": "identity" - } - ] - } - - - -GET /v3/endpoints -================= - -List the endpoints: - -.. code-block:: bash - - curl -s \ - -H "X-Auth-Token: $OS_TOKEN" \ - http://localhost:5000/v3/endpoints | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "endpoints": [ - { - "enabled": true, - "id": "29beb2f1567642eb810b042b6719ea88", - "interface": "admin", - "links": { - "self": "http://localhost:5000/v3/endpoints/29beb2f1567642eb810b042b6719ea88" - }, - "region": "RegionOne", - "service_id": "bd7397d2c0e14fb69bae8ff76e112a90", - "url": "http://localhost:35357/v2.0" - } - ], - "links": { - "next": null, - "previous": null, - "self": "http://localhost:5000/v3/endpoints" - } - } - - -Users -===== - -GET /v3/users -------------- - -List users: - -.. code-block:: bash - - curl -s \ - -H "X-Auth-Token: $OS_TOKEN" \ - http://localhost:5000/v3/users | python -mjson.tool - -POST /v3/users --------------- - -Create a user: - -.. code-block:: bash - - curl -s \ - -H "X-Auth-Token: $OS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"user": {"name": "newuser", "password": "changeme"}}' \ - http://localhost:5000/v3/users | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "user": { - "domain_id": "default", - "enabled": true, - "id": "ec8fc20605354edd91873f2d66bf4fc4", - "links": { - "self": "http://identity-server:5000/v3/users/ec8fc20605354edd91873f2d66bf4fc4" - }, - "name": "newuser" - } - } - -GET /v3/users/{user_id} ------------------------ - -Show details for a user: - -.. code-block:: bash - - USER_ID=ec8fc20605354edd91873f2d66bf4fc4 - - curl -s \ - -H "X-Auth-Token: $OS_TOKEN" \ - http://localhost:5000/v3/users/$USER_ID | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "user": { - "domain_id": "default", - "enabled": true, - "id": "ec8fc20605354edd91873f2d66bf4fc4", - "links": { - "self": "http://localhost:5000/v3/users/ec8fc20605354edd91873f2d66bf4fc4" - }, - "name": "newuser" - } - } - -POST /v3/users/{user_id}/password ---------------------------------- - -Change password (using the default policy, this can be done as the user): - -.. code-block:: bash - - USER_ID=b7793000f8d84c79af4e215e9da78654 - ORIG_PASS=userpwd - NEW_PASS=newuserpwd - - curl \ - -H "X-Auth-Token: $OS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ "user": {"password": "'$NEW_PASS'", "original_password": "'$ORIG_PASS'"} }' \ - http://localhost:5000/v3/users/$USER_ID/password - -.. note:: - - This command doesn't print anything if the request was successful. - -PATCH /v3/users/{user_id} -------------------------- - -Reset password (using the default policy, this requires admin): - -.. code-block:: bash - - USER_ID=b7793000f8d84c79af4e215e9da78654 - NEW_PASS=newuserpwd - - curl -s -X PATCH \ - -H "X-Auth-Token: $OS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ "user": {"password": "'$NEW_PASS'"} }' \ - http://localhost:5000/v3/users/$USER_ID | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "user": { - "default_project_id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c", - "domain_id": "default", - "email": "demo@example.com", - "enabled": true, - "extra": { - "email": "demo@example.com" - }, - "id": "269348fdd9374b8885da1418e0730af1", - "links": { - "self": "http://localhost:5000/v3/users/269348fdd9374b8885da1418e0730af1" - }, - "name": "demo" - } - } - - -PUT /v3/projects/{project_id}/groups/{group_id}/roles/{role_id} -=============================================================== - -Create group role assignment on project: - -.. code-block:: bash - - curl -s -X PUT \ - -H "X-Auth-Token: $OS_TOKEN" \ - http://localhost:5000/v3/projects/$PROJECT_ID/groups/$GROUP_ID/roles/$ROLE_ID | - python -mjson.tool - -There's no data in the response if the operation is successful. - - -POST /v3/OS-TRUST/trusts -======================== - -Create a trust: - -.. code-block:: bash - - curl -s \ - -H "X-Auth-Token: $OS_TOKEN" \ - -H "Content-Type: application/json" \ - -d ' - { "trust": { - "expires_at": "2014-12-30T23:59:59.999999Z", - "impersonation": false, - "project_id": "'$PROJECT_ID'", - "roles": [ - { "name": "admin" } - ], - "trustee_user_id": "'$DEMO_USER_ID'", - "trustor_user_id": "'$ADMIN_USER_ID'" - }}'\ - http://localhost:5000/v3/OS-TRUST/trusts | python -mjson.tool - -Example response: - -.. code-block:: javascript - - { - "trust": { - "expires_at": "2014-12-30T23:59:59.999999Z", - "id": "394998fa61f14736b1f0c1f322882949", - "impersonation": false, - "links": { - "self": "http://localhost:5000/v3/OS-TRUST/trusts/394998fa61f14736b1f0c1f322882949" - }, - "project_id": "3d4c2c82bd5948f0bcab0cf3a7c9b48c", - "remaining_uses": null, - "roles": [ - { - "id": "c703057be878458588961ce9a0ce686b", - "links": { - "self": "http://localhost:5000/v3/roles/c703057be878458588961ce9a0ce686b" - }, - "name": "admin" - } - ], - "roles_links": { - "next": null, - "previous": null, - "self": "http://localhost:5000/v3/OS-TRUST/trusts/394998fa61f14736b1f0c1f322882949/roles" - }, - "trustee_user_id": "269348fdd9374b8885da1418e0730af1", - "trustor_user_id": "3ec3164f750146be97f21559ee4d9c51" - } - } - - -------------------------------- -Service API Examples Using Curl -------------------------------- - -The service API is defined to be a subset of the Admin API and, by -default, runs on port 5000. - -GET / -===== - -This call is identical to that documented for the Admin API, except -that it uses port 5000, instead of port 35357, by default: - -.. code-block:: bash - - $ curl http://0.0.0.0:5000 - -or: - -.. code-block:: bash - - $ curl http://0.0.0.0:5000/v2.0/ - -See the `Admin API Examples Using Curl`_ for more info. - -GET /extensions -=============== - -This call is identical to that documented for the Admin API. - -POST /tokens -============ - -This call is identical to that documented for the Admin API. - -GET /tenants -============ - -List all of the tenants your token can access: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:887665443383838" http://localhost:5000/v2.0/tenants - -Returns: - -.. code-block:: javascript - - { - "tenants_links": [], - "tenants": [ - { - "enabled": true, - "description": "None", - "name": "customer-x", - "id": "1" - } - ] - } - ------------------------------ -Admin API Examples Using Curl ------------------------------ - -These examples assume a default port value of 35357, and depend on the -``sampledata`` bundled with keystone. - -GET / -===== - -Discover API version information, links to documentation (PDF, HTML, WADL), -and supported media types: - -.. code-block:: bash - - $ curl http://0.0.0.0:35357 - -.. code-block:: javascript - - { - "versions": { - "values": [ - { - "id": "v3.4", - "links": [ - { - "href": "http://127.0.0.1:35357/v3/", - "rel": "self" - } - ], - "media-types": [ - { - "base": "application/json", - "type": "application/vnd.openstack.identity-v3+json" - } - ], - "status": "stable", - "updated": "2015-03-30T00:00:00Z" - }, - { - "id": "v2.0", - "links": [ - { - "href": "http://127.0.0.1:35357/v2.0/", - "rel": "self" - }, - { - "href": "http://docs.openstack.org/", - "rel": "describedby", - "type": "text/html" - } - ], - "media-types": [ - { - "base": "application/json", - "type": "application/vnd.openstack.identity-v2.0+json" - } - ], - "status": "stable", - "updated": "2014-04-17T00:00:00Z" - } - ] - } - } - -.. code-block:: bash - - $ curl http://0.0.0.0:35357/v2.0/ - -Returns: - -.. code-block:: javascript - - { - "version": { - "id": "v2.0", - "links": [ - { - "href": "http://127.0.0.1:35357/v2.0/", - "rel": "self" - }, - { - "href": "http://docs.openstack.org/", - "rel": "describedby", - "type": "text/html" - } - ], - "media-types": [ - { - "base": "application/json", - "type": "application/vnd.openstack.identity-v2.0+json" - } - ], - "status": "stable", - "updated": "2014-04-17T00:00:00Z" - } - } - -GET /extensions -=============== - -Discover the API extensions enabled at the endpoint: - -.. code-block:: bash - - $ curl http://localhost:35357/v2.0/extensions/ - -Returns: - -.. code-block:: javascript - - { - "extensions":{ - "values":[] - } - } - -POST /tokens -============ - -Authenticate by exchanging credentials for an access token: - -.. code-block:: bash - - $ curl -d '{"auth":{"tenantName": "customer-x", "passwordCredentials": {"username": "joeuser", "password": "secrete"}}}' -H "Content-type: application/json" http://localhost:35357/v2.0/tokens - -Returns: - -.. code-block:: javascript - - { - "access":{ - "token":{ - "expires":"2012-02-05T00:00:00", - "id":"887665443383838", - "tenant":{ - "id":"1", - "name":"customer-x" - } - }, - "serviceCatalog":[ - { - "endpoints":[ - { - "adminURL":"http://swift.admin-nets.local:8080/", - "region":"RegionOne", - "internalURL":"http://127.0.0.1:8080/v1/AUTH_1", - "publicURL":"http://swift.publicinternets.com/v1/AUTH_1" - } - ], - "type":"object-store", - "name":"swift" - }, - { - "endpoints":[ - { - "adminURL":"http://cdn.admin-nets.local/v1.1/1", - "region":"RegionOne", - "internalURL":"http://127.0.0.1:7777/v1.1/1", - "publicURL":"http://cdn.publicinternets.com/v1.1/1" - } - ], - "type":"object-store", - "name":"cdn" - } - ], - "user":{ - "id":"1", - "roles":[ - { - "tenantId":"1", - "id":"3", - "name":"Member" - } - ], - "name":"joeuser" - } - } - } - -.. note:: - - Take note of the value ['access']['token']['id'] value produced here (``887665443383838``, above), as you can use it in the calls below. - -GET /tokens/{token_id} -====================== - -.. note:: - - This call refers to a token known to be valid, ``887665443383838`` in this case. - -Validate a token: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 - -If the token is valid, returns: - -.. code-block:: javascript - - { - "access":{ - "token":{ - "expires":"2012-02-05T00:00:00", - "id":"887665443383838", - "tenant":{ - "id":"1", - "name":"customer-x" - } - }, - "user":{ - "name":"joeuser", - "tenantName":"customer-x", - "id":"1", - "roles":[ - { - "serviceId":"1", - "id":"3", - "name":"Member" - } - ], - "tenantId":"1" - } - } - } - -HEAD /tokens/{token_id} -======================= - -This is a high-performance variant of the GET call documented above, which -by definition, returns no response body: - -.. code-block:: bash - - $ curl -I -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838 - -... which returns ``200``, indicating the token is valid:: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: None - Date: Tue, 08 Nov 2011 23:07:44 GMT - -GET /tokens/{token_id}/endpoints -================================ - -List all endpoints for a token: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/887665443383838/endpoints - -Returns: - -.. code-block:: javascript - - { - "endpoints_links": [ - { - "href": "http://127.0.0.1:35357/tokens/887665443383838/endpoints?'marker=5&limit=10'", - "rel": "next" - } - ], - "endpoints": [ - { - "internalURL": "http://127.0.0.1:8080/v1/AUTH_1", - "name": "swift", - "adminURL": "http://swift.admin-nets.local:8080/", - "region": "RegionOne", - "tenantId": 1, - "type": "object-store", - "id": 1, - "publicURL": "http://swift.publicinternets.com/v1/AUTH_1" - }, - { - "internalURL": "http://localhost:8774/v1.0", - "name": "nova_compat", - "adminURL": "http://127.0.0.1:8774/v1.0", - "region": "RegionOne", - "tenantId": 1, - "type": "compute", - "id": 2, - "publicURL": "http://nova.publicinternets.com/v1.0/" - }, - { - "internalURL": "http://localhost:8774/v1.1", - "name": "nova", - "adminURL": "http://127.0.0.1:8774/v1.1", - "region": "RegionOne", - "tenantId": 1, - "type": "compute", - "id": 3, - "publicURL": "http://nova.publicinternets.com/v1.1/ - }, - { - "internalURL": "http://127.0.0.1:9292/v1.1/", - "name": "glance", - "adminURL": "http://nova.admin-nets.local/v1.1/", - "region": "RegionOne", - "tenantId": 1, - "type": "image", - "id": 4, - "publicURL": "http://glance.publicinternets.com/v1.1/" - }, - { - "internalURL": "http://127.0.0.1:7777/v1.1/1", - "name": "cdn", - "adminURL": "http://cdn.admin-nets.local/v1.1/1", - "region": "RegionOne", - "tenantId": 1, - "type": "object-store", - "id": 5, - "publicURL": "http://cdn.publicinternets.com/v1.1/1" - } - ] - } - -GET /tenants -============ - -List all of the tenants in the system (requires an Admin ``X-Auth-Token``): - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants - -Returns: - -.. code-block:: javascript - - { - "tenants_links": [], - "tenants": [ - { - "enabled": false, - "description": "None", - "name": "project-y", - "id": "3" - }, - { - "enabled": true, - "description": "None", - "name": "ANOTHER:TENANT", - "id": "2" - }, - { - "enabled": true, - "description": "None", - "name": "customer-x", - "id": "1" - } - ] - } - -GET /tenants/{tenant_id} -======================== - -Retrieve information about a tenant, by tenant ID: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1 - -Returns: - -.. code-block:: javascript - - { - "tenant":{ - "enabled":true, - "description":"None", - "name":"customer-x", - "id":"1" - } - } - -GET /tenants/{tenant_id}/users/{user_id}/roles -============================================== - -List the roles a user has been granted on a tenant: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/1/users/1/roles - -Returns: - -.. code-block:: javascript - - { - "roles_links":[], - "roles":[ - { - "id":"3", - "name":"Member" - } - ] - } - -GET /users/{user_id} -==================== - -Retrieve information about a user, by user ID: - -.. code-block:: bash - - $ curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users/1 - -Returns: - -.. code-block:: javascript - - { - "user":{ - "tenantId":"1", - "enabled":true, - "id":"1", - "name":"joeuser" - } - } - -GET /tokens/revoked -=================== - -Get the revocation list: - -.. code-block:: bash - - curl -s -H "X-Auth-Token: $OS_TOKEN" \ - http://localhost:35357/v2.0/tokens/revoked | - jq -r .signed | - openssl cms -verify \ - -certfile /etc/keystone/ssl/certs/signing_cert.pem \ - -CAfile /etc/keystone/ssl/certs/ca.pem \ - -inform PEM \ - -nosmimecap -nodetach -nocerts -noattr 2>/dev/null | - python -m json.tool - -Example response: - -.. code-block:: javascript - - { - "revoked": [ - { - "expires": "2014-06-10T21:40:14Z", - "id": "e6e2b5c9092751f88d2bcd30b09777a9" - }, - { - "expires": "2014-06-10T21:47:29Z", - "id": "883ef5d610bd1c68fbaa8ac528aa9f17" - }, - { - "expires": "2014-06-10T21:51:52Z", - "id": "41775ff4838f8f406b7bad28bea0dde6" - } - ] - } diff --git a/keystone-moon/doc/source/architecture.rst b/keystone-moon/doc/source/architecture.rst deleted file mode 100644 index 773aa6d4..00000000 --- a/keystone-moon/doc/source/architecture.rst +++ /dev/null @@ -1,317 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Keystone Architecture -===================== - -Much of the design is precipitated from the expectation that the auth backends -for most deployments will actually be shims in front of existing user systems. - - ------------- -The Services ------------- - -Keystone is organized as a group of internal services exposed on one or many -endpoints. Many of these services are used in a combined fashion by the -frontend, for example an authenticate call will validate user/project -credentials with the Identity service and, upon success, create and return a -token with the Token service. - - -Identity --------- - -The Identity service provides auth credential validation and data about Users, -Groups. - -In the basic case all this data is managed by the service, allowing the service -to manage all the CRUD associated with the data. - -In other cases from an authoritative backend service. An example of this would -be when backending on LDAP. See `LDAP Backend` below for more details. - - -Resource --------- - -The Resource service provides data about Projects and Domains. - -Like the Identity service, this data may either be managed directly by the -service or be pulled from another authoritative backend service, such as LDAP. - - -Assignment ----------- - -The Assignment service provides data about Roles and Role assignments to the -entities managed by the Identity and Resource services. Again, like these two -services, this data may either be managed directly by the Assignment service -or be pulled from another authoritative backend service, such as LDAP. - - -Token ------ - -The Token service validates and manages Tokens used for authenticating requests -once a user's credentials have already been verified. - - -Catalog -------- - -The Catalog service provides an endpoint registry used for endpoint discovery. - - -Policy ------- - -The Policy service provides a rule-based authorization engine and the -associated rule management interface. - - ------------------------- -Application Construction ------------------------- - -Keystone is an HTTP front-end to several services. Like other OpenStack -applications, this is done using python WSGI interfaces and applications are -configured together using Paste_. The application's HTTP endpoints are made up -of pipelines of WSGI middleware, such as: - -.. code-block:: ini - - [pipeline:api_v3] - pipeline = sizelimit url_normalize build_auth_context token_auth admin_token_auth - json_body ec2_extension_v3 s3_extension service_v3 - -These in turn use a subclass of :mod:`keystone.common.wsgi.ComposingRouter` to -link URLs to Controllers (a subclass of -:mod:`keystone.common.wsgi.Application`). Within each Controller, one or more -Managers are loaded (for example, see :mod:`keystone.catalog.core.Manager`), -which are thin wrapper classes which load the appropriate service driver based -on the Keystone configuration. - -* Assignment - - * :mod:`keystone.assignment.controllers.GrantAssignmentV3` - * :mod:`keystone.assignment.controllers.ProjectAssignmentV3` - * :mod:`keystone.assignment.controllers.TenantAssignment` - * :mod:`keystone.assignment.controllers.Role` - * :mod:`keystone.assignment.controllers.RoleAssignmentV2` - * :mod:`keystone.assignment.controllers.RoleAssignmentV3` - * :mod:`keystone.assignment.controllers.RoleV3` - -* Authentication - - * :mod:`keystone.auth.controllers.Auth` - -* Catalog - - * :mod:`keystone.catalog.controllers.EndpointV3` - * :mod:`keystone.catalog.controllers.RegionV3` - * :mod:`keystone.catalog.controllers.ServiceV3` - -* Identity - - * :mod:`keystone.identity.controllers.GroupV3` - * :mod:`keystone.identity.controllers.UserV3` - -* Policy - - * :mod:`keystone.policy.controllers.PolicyV3` - -* Resource - - * :mod:`keystone.resource.controllers.DomainV3` - * :mod:`keystone.resource.controllers.ProjectV3` - -* Token - - * :mod:`keystone.token.controllers.Auth` - - -.. _Paste: http://pythonpaste.org/ - - ----------------- -Service Backends ----------------- - -Each of the services can be configured to use a backend to allow Keystone to fit a -variety of environments and needs. The backend for each service is defined in -the keystone.conf file with the key ``driver`` under a group associated with -each service. - -A general class exists under each backend to provide an -abstract base class for any implementations, identifying the expected service -implementations. The classes are named after the keystone release in which -they were introduced. For eg. ``DriverV8`` for keystone release version 8. -The corresponding drivers for the services are: - -* :mod:`keystone.assignment.core.AssignmentDriverV8` -* :mod:`keystone.assignment.core.RoleDriverV8` -* :mod:`keystone.catalog.core.CatalogDriverV8` -* :mod:`keystone.credential.core.CredentialDriverV8` -* :mod:`keystone.endpoint_policy.core.EndpointPolicyDriverV8` -* :mod:`keystone.federation.core.FederationDriverV8` -* :mod:`keystone.identity.core.IdentityDriverV8` -* :mod:`keystone.identity.core.MappingDriverV8` -* :mod:`keystone.oauth1.core.Oauth1DriverV8` -* :mod:`keystone.policy.core.PolicyDriverV8` -* :mod:`keystone.resource.core.DomainConfigDriverV8` -* :mod:`keystone.resource.core.ResourceDriverV8` -* :mod:`keystone.revoke.core.RevokeDriverV8` -* :mod:`keystone.token.core.TokenDriverV8` -* :mod:`keystone.trust.core.TrustDriverV8` - -If you implement a backend driver for one of the Keystone services, you're -expected to subclass from these classes. - - -SQL Backend ------------ - -A SQL based backend using SQLAlchemy to store data persistently. The -``keystone-manage`` command introspects the backends to identify SQL based backends -when running "db_sync" to establish or upgrade schema. If the backend driver -has a method db_sync(), it will be invoked to sync and/or migrate schema. - - -Templated Backend ------------------ - -Largely designed for a common use case around service catalogs in the Keystone -project, a Catalog backend that simply expands pre-configured templates to -provide catalog data. - -Example paste.deploy config (uses $ instead of % to avoid ConfigParser's -interpolation):: - - [DEFAULT] - catalog.RegionOne.identity.publicURL = http://localhost:$(public_port)s/v2.0 - catalog.RegionOne.identity.adminURL = http://localhost:$(public_port)s/v2.0 - catalog.RegionOne.identity.internalURL = http://localhost:$(public_port)s/v2.0 - catalog.RegionOne.identity.name = 'Identity Service' - - -LDAP Backend ------------- - -The LDAP backend stores Users and Projects in separate Subtrees. Roles are recorded -as entries under the Projects. - - ----------- -Data Model ----------- - -Keystone was designed from the ground up to be amenable to multiple styles of -backends and as such many of the methods and data types will happily accept -more data than they know what to do with and pass them on to a backend. - -There are a few main data types: - - * **User**: has account credentials, is associated with one or more projects or domains - * **Group**: a collection of users, is associated with one or more projects or domains - * **Project**: unit of ownership in OpenStack, contains one or more users - * **Domain**: unit of ownership in OpenStack, contains users, groups and projects - * **Role**: a first-class piece of metadata associated with many user-project pairs. - * **Token**: identifying credential associated with a user or user and project - * **Extras**: bucket of key-value metadata associated with a user-project pair. - * **Rule**: describes a set of requirements for performing an action. - -While the general data model allows a many-to-many relationship between Users -and Groups to Projects and Domains; the actual backend implementations take -varying levels of advantage of that functionality. - - ----------------- -Approach to CRUD ----------------- - -While it is expected that any "real" deployment at a large company will manage -their users, groups, projects and domains in their existing user systems, a -variety of CRUD operations are provided for the sake of development and testing. - -CRUD is treated as an extension or additional feature to the core feature set -in that it is not required that a backend support it. It is expected that -backends for services that don't support the CRUD operations will raise a -:mod:`keystone.exception.NotImplemented`. - - ----------------------------------- -Approach to Authorization (Policy) ----------------------------------- - -Various components in the system require that different actions are allowed -based on whether the user is authorized to perform that action. - -For the purposes of Keystone there are only a couple levels of authorization -being checked for: - - * Require that the performing user is considered an admin. - * Require that the performing user matches the user being referenced. - -Other systems wishing to use the policy engine will require additional styles -of checks and will possibly write completely custom backends. By default, -Keystone leverages Policy enforcement that is maintained in Oslo-Incubator, -found in `keystone/openstack/common/policy.py`. - - -Rules ------ - -Given a list of matches to check for, simply verify that the credentials -contain the matches. For example: - -.. code-block:: python - - credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']} - - # An admin only call: - policy_api.enforce(('is_admin:1',), credentials) - - # An admin or owner call: - policy_api.enforce(('is_admin:1', 'user_id:foo'), credentials) - - # A netadmin call: - policy_api.enforce(('roles:nova:netadmin',), credentials) - -Credentials are generally built from the user metadata in the 'extras' part -of the Identity API. So, adding a 'role' to the user just means adding the role -to the user metadata. - - -Capability RBAC ---------------- - -(Not yet implemented.) - -Another approach to authorization can be action-based, with a mapping of roles -to which capabilities are allowed for that role. For example: - -.. code-block:: python - - credentials = {'user_id': 'foo', 'is_admin': 1, 'roles': ['nova:netadmin']} - - # add a policy - policy_api.add_policy('action:nova:add_network', ('roles:nova:netadmin',)) - - policy_api.enforce(('action:nova:add_network',), credentials) - -In the backend this would look up the policy for 'action:nova:add_network' and -then do what is effectively a 'Simple Match' style match against the credentials. diff --git a/keystone-moon/doc/source/auth-totp.rst b/keystone-moon/doc/source/auth-totp.rst deleted file mode 100644 index 4e81757f..00000000 --- a/keystone-moon/doc/source/auth-totp.rst +++ /dev/null @@ -1,136 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=================================== -Time-based One-time Password (TOTP) -=================================== - -Configuring TOTP -================ - -TOTP is not enabled in Keystone by default. To enable it add the ``totp`` -authentication method to the ``[auth]`` section in ``keystone.conf``: - -.. code-block:: ini - - [auth] - methods = external,password,token,oauth1,totp - -For a user to have access to TOTP, he must have configured TOTP credentials in -Keystone and a TOTP device (i.e. `Google Authenticator`_). - -.. _Google Authenticator: http://www.google.com/2step - -TOTP uses a base32 encoded string for the secret. The secret must be at least -148 bits (16 bytes). The following python code can be used to generate a TOTP -secret: - -.. code-block:: python - - import base64 - message = '1234567890123456' - print base64.b32encode(message).rstrip('=') - -Example output:: - - GEZDGNBVGY3TQOJQGEZDGNBVGY - -This generated secret can then be used to add new 'totp' credentials to a -specific user. - -Create a TOTP credential ------------------------- - -Create ``totp`` credentials for user: - -.. code-block:: bash - - USER_ID=b7793000f8d84c79af4e215e9da78654 - SECRET=GEZDGNBVGY3TQOJQGEZDGNBVGY - - curl -i \ - -H "Content-Type: application/json" \ - -d ' - { - "credential": { - "blob": "'$SECRET'", - "type": "totp", - "user_id": "'$USER_ID'" - } - }' \ - http://localhost:5000/v3/credentials ; echo - -Google Authenticator --------------------- - -On a device install Google Authenticator and inside the app click on 'Set up -account' and then click on 'Enter provided key'. In the input fields enter -account name and secret. Optionally a QR code can be generated programatically -to avoid having to type the information. - -QR code -------- - -Create TOTP QR code for device: - -.. code-block:: python - - import qrcode - - secret='GEZDGNBVGY3TQOJQGEZDGNBVGY' - uri = 'otpauth://totp/{name}?secret={secret}&issuer={issuer}'.format( - name='name', - secret=secret, - issuer='Keystone') - - img = qrcode.make(uri) - img.save('totp.png') - -In Google Authenticator app click on 'Set up account' and then click on 'Scan -a barcode', and then scan the 'totp.png' image. This should create a new TOTP -entry in the application. - -Authenticate with TOTP -====================== - -Google Authenticator will generate a 6 digit PIN (passcode) every few seconds. -Use the passcode and your user ID to authenticate using the ``totp`` method. - -Tokens ------- - -Get a token with default scope (may be unscoped) using totp: - -.. code-block:: bash - - USER_ID=b7793000f8d84c79af4e215e9da78654 - PASSCODE=012345 - - curl -i \ - -H "Content-Type: application/json" \ - -d ' - { "auth": { - "identity": { - "methods": [ - "totp" - ], - "totp": { - "user": { - "id": "'$USER_ID'", - "passcode": "'$PASSCODE'" - } - } - } - } - }' \ - http://localhost:5000/v3/auth/tokens ; echo diff --git a/keystone-moon/doc/source/cli_examples.rst b/keystone-moon/doc/source/cli_examples.rst deleted file mode 100644 index 57735db5..00000000 --- a/keystone-moon/doc/source/cli_examples.rst +++ /dev/null @@ -1,316 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=============================== -Command Line Interface Examples -=============================== - -The Keystone command line interface packaged in `python-keystoneclient`_ only -supports the Identity v2.0 API. The OpenStack common command line interface -packaged in `python-openstackclient`_ supports both v2.0 and v3 APIs. - -.. NOTE:: - - As of the Juno release, it is recommended to use ``python-openstackclient``, - as it supports both v2.0 and v3 APIs. For the purpose of backwards compatibility, - the CLI packaged in ``python-keystoneclient`` is not being removed. - -.. _`python-openstackclient`: http://docs.openstack.org/developer/python-openstackclient/ -.. _`python-keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/ - -Using python-openstackclient (v3 or v2.0) -========================================= - -A complete list of OpenStackClient commands with full examples are located at -OpenStackClient's `Command List`_ page. Additionally, for details related to -authentication, refer to OpenStackClient's `Authentication`_ page. - -.. _`Command List`: http://docs.openstack.org/developer/python-openstackclient/command-list.html -.. _`Authentication`: http://docs.openstack.org/developer/python-openstackclient/authentication.html - -Using python-keystoneclient (v2.0-only) -======================================= - -------- -Tenants -------- - -``tenant-create`` ------------------ - -keyword arguments - -* name -* description (optional, defaults to None) -* enabled (optional, defaults to True) - -example: - -.. code-block:: bash - - $ keystone tenant-create --name=demo - -creates a tenant named "demo". - -``tenant-delete`` ------------------ - -arguments - -* tenant_id - -example: - -.. code-block:: bash - - $ keystone tenant-delete f2b7b39c860840dfa47d9ee4adffa0b3 - ------ -Users ------ - -``user-create`` ---------------- - -keyword arguments - -* name -* pass -* email -* tenant_id (optional, defaults to None) -* enabled (optional, defaults to True) - -example: - -.. code-block:: bash - - $ keystone user-create - --name=admin \ - --pass=secrete \ - --tenant_id=2395953419144b67955ac4bab96b8fd2 \ - --email=admin@example.com - -``user-delete`` ---------------- - -keyword arguments - -* user_id - -example: - -.. code-block:: bash - - $ keystone user-delete f2b7b39c860840dfa47d9ee4adffa0b3 - -``user-list`` -------------- - -list users in the system, optionally by a specific tenant (identified by tenant_id) - -arguments - -* tenant_id (optional, defaults to None) - -example: - -.. code-block:: bash - - $ keystone user-list - -``user-update`` ---------------------- - -arguments - -* user_id - -keyword arguments - -* name Desired new user name (Optional) -* email Desired new email address (Optional) -* enabled <true|false> Enable or disable user (Optional) - - -example: - -.. code-block:: bash - - $ keystone user-update 03c84b51574841ba9a0d8db7882ac645 --email=newemail@example.com - -``user-password-update`` ------------------------- - -arguments - -* user_id -* password - -example: - -.. code-block:: bash - - $ keystone user-password-update --pass foo 03c84b51574841ba9a0d8db7882ac645 - ------ -Roles ------ - -``role-create`` ---------------- - -arguments - -* name - -example: - -.. code-block:: bash - - $ keystone role-create --name=demo - -``role-delete`` ---------------- - -arguments - -* role_id - -example: - -.. code-block:: bash - - $ keystone role-delete 19d1d3344873464d819c45f521ff9890 - -``role-list`` -------------- - -example: - -.. code-block:: bash - - $ keystone role-list - -``role-get`` ------------- - -arguments - -* role_id - -example: - -.. code-block:: bash - - $ keystone role-get 19d1d3344873464d819c45f521ff9890 - - -``user-role-add`` ------------------ - -keyword arguments - -* user <user-id> -* role <role-id> -* tenant_id <tenant-id> - -example: - -.. code-block:: bash - - $ keystone user-role-add \ - --user=96a6ebba0d4c441887aceaeced892585 \ - --role=f8dd5a2e4dc64a41b96add562d9a764e \ - --tenant_id=2395953419144b67955ac4bab96b8fd2 - -``user-role-remove`` --------------------- - -keyword arguments - -* user <user-id> -* role <role-id> -* tenant_id <tenant-id> - -example: - -.. code-block:: bash - - $ keystone user-role-remove \ - --user=96a6ebba0d4c441887aceaeced892585 \ - --role=f8dd5a2e4dc64a41b96add562d9a764e \ - --tenant_id=2395953419144b67955ac4bab96b8fd2 - --------- -Services --------- - -``service-create`` ------------------- - -keyword arguments - -* name -* type -* description - -example: - -.. code-block:: bash - - $ keystone service-create \ - --name=nova \ - --type=compute \ - --description="Nova Compute Service" - -``service-list`` ----------------- - -arguments - -* service_id - -example: - -.. code-block:: bash - - $ keystone service-list - -``service-get`` ---------------- - -arguments - -* service_id - -example: - -.. code-block:: bash - - $ keystone service-get 08741d8ed88242ca88d1f61484a0fe3b - -``service-delete`` ------------------- - -arguments - -* service_id - -example: - -.. code-block:: bash - - $ keystone service-delete 08741d8ed88242ca88d1f61484a0fe3b diff --git a/keystone-moon/doc/source/community.rst b/keystone-moon/doc/source/community.rst deleted file mode 100644 index f3296efb..00000000 --- a/keystone-moon/doc/source/community.rst +++ /dev/null @@ -1,99 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================ -Getting Involved -================ - -The OpenStack community is a very friendly group and there are places online to -join in with the community. Feel free to ask questions. This document points -you to some of the places where you can communicate with people. - -How to Join the Community -========================= - -Our community welcomes all people interested in open source cloud computing, -and there are no formal membership requirements. The best way to join the -community is to talk with others online or at a meetup and offer contributions -through Launchpad_, the wiki_, or blogs. We welcome all types of contributions, -from blueprint designs to documentation to testing to deployment scripts. - -.. _Launchpad: https://launchpad.net/keystone -.. _wiki: http://wiki.openstack.org/ - -#openstack-keystone on Freenode IRC Network -------------------------------------------- - -You can find Keystone folks in `<irc://freenode.net/#openstack-keystone>`_. -This is usually the best place to ask questions and find your way around. IRC -stands for Internet Relay Chat and it is a way to chat online in real time. -You can also ask a question and come back to the log files to read the answer -later. Logs for the #openstack IRC channels are stored at -`<http://eavesdrop.openstack.org/irclogs/>`_. - -For more information regarding OpenStack IRC channels please visit the -`OpenStack IRC Wiki <https://wiki.openstack.org/wiki/IRC>`_. - -OpenStack Wiki --------------- - -The wiki is a living source of knowledge. It is edited by the community, and -has collections of links and other sources of information. Typically the pages -are a good place to write drafts for specs or documentation, describe a -blueprint, or collaborate with others. - -`OpenStack Wiki <http://wiki.openstack.org/>`_ - -* `useful Keystone project links <http://wiki.openstack.org/Keystone>`_ - -Keystone on Launchpad ---------------------- - -Launchpad is a code hosting that OpenStack is using to track bugs, feature -work, and releases of OpenStack. Like other OpenStack projects, Keystone source -code is hosted on git.openstack.org - -* `Keystone Project Page on Launchpad <http://launchpad.net/keystone>`_ -* `Keystone Source Repository <https://git.openstack.org/cgit/openstack/keystone>`_ - -Within launchpad, we use -`blueprints <https://blueprints.launchpad.net/keystone>`_, to track feature -work, and track `bugs <https://bugs.launchpad.net/keystone>`_ as well. If -you are looking for a place to get started contributing to keystone, please -look at any bugs for Keystone that are tagged as `low-hanging-fruit -<https://bugs.launchpad.net/keystone/+bugs?field.tag=low-hanging-fruit>`_. - -OpenStack Blog --------------- - -The OpenStack blog includes a weekly newsletter that aggregates OpenStack news -from around the internet, as well as providing inside information on upcoming -events and posts from OpenStack contributors. - -`OpenStack Blog <http://openstack.org/blog>`_ - -See also: `Planet OpenStack <http://planet.openstack.org/>`_, an aggregation of -blogs about OpenStack from around the internet, combined into a web site and -RSS feed. If you'd like to contribute with your blog posts, there are -instructions for `adding your blog <http://wiki.openstack.org/AddingYourBlog>`_. - - -Twitter -------- - -Because all the cool kids do it: `@openstack <http://twitter.com/openstack>`_. -Also follow the `#openstack <https://twitter.com/search?q=%23openstack>`_ -tag for relevant tweets. diff --git a/keystone-moon/doc/source/conf.py b/keystone-moon/doc/source/conf.py deleted file mode 100644 index 1037c39e..00000000 --- a/keystone-moon/doc/source/conf.py +++ /dev/null @@ -1,269 +0,0 @@ -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or -# implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# -# keystone documentation build configuration file, created by -# sphinx-quickstart on Mon Jan 9 12:02:59 2012. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import subprocess - -# NOTE(dstanek): adds _ to the builtins so keystone modules can be imported -__builtins__['_'] = str - -# -- General configuration ---------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.autodoc', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.viewcode', - 'oslo_config.sphinxconfiggen', - 'oslosphinx', - ] - -config_generator_config_file = '../../config-generator/keystone.conf' -sample_config_basename = '_static/keystone' - -todo_include_todos = True - -# Add any paths that contain templates here, relative to this directory. -# if os.getenv('HUDSON_PUBLISH_DOCS'): -# templates_path = ['_ga', '_templates'] -# else: -# templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'keystone' -copyright = u'2012, OpenStack, LLC' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['old'] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -show_authors = True - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -modindex_common_prefix = ['keystone.'] - -# -- Options for man page output -------------------------------------------- - -# Grouping the document tree for man pages. -# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' - -man_pages = [ - ('man/keystone-manage', 'keystone-manage', u'Keystone Management Utility', - [u'OpenStack'], 1), - ('man/keystone-all', 'keystone-all', u'Keystone Startup Command', - [u'OpenStack'], 1), -] - - -# -- Options for HTML output -------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# html_theme_path = ["."] -# html_theme = '_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' -git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", - "-n1"] -html_last_updated_fmt = subprocess.Popen( - git_cmd, stdout=subprocess.PIPE).communicate()[0] - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'keystonedoc' - - -# -- Options for LaTeX output ------------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - #'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples (source -# start file, target name, title, author, documentclass -# [howto/manual]). -latex_documents = [ - ('index', 'keystone.tex', u'Keystone Documentation', - u'OpenStack', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for Texinfo output ----------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'keystone', u'Keystone Documentation', - u'OpenStack', 'keystone', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - - -# Example configuration for intersphinx: refer to the Python standard library. -#intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/keystone-moon/doc/source/configuration.rst b/keystone-moon/doc/source/configuration.rst deleted file mode 100644 index e78c0ac6..00000000 --- a/keystone-moon/doc/source/configuration.rst +++ /dev/null @@ -1,1924 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -==================== -Configuring Keystone -==================== - -.. toctree:: - :maxdepth: 1 - - man/keystone-manage - man/keystone-all - -Once Keystone is installed, it is configured via a primary configuration file -(``etc/keystone.conf``), a PasteDeploy configuration file -(``etc/keystone-paste.ini``), possibly a separate logging configuration file, -and initializing data into Keystone using the command line client. - -By default, Keystone starts a service on `IANA-assigned port 35357 -<http://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.txt>`_. -This may overlap with your system's ephemeral port range, so another process -may already be using this port without being explicitly configured to do so. To -prevent this scenario from occurring, it's recommended that you explicitly -exclude port 35357 from the available ephemeral port range. On a Linux system, -this would be accomplished by: - -.. code-block:: bash - - $ sysctl -w 'sys.net.ipv4.ip_local_reserved_ports=35357' - -To make the above change persistent, -``net.ipv4.ip_local_reserved_ports = 35357`` should be added to -``/etc/sysctl.conf`` or to ``/etc/sysctl.d/keystone.conf``. - -Starting and Stopping Keystone under Eventlet -============================================= - -.. WARNING:: - - Running keystone under eventlet has been deprecated as of the Kilo release. - Support for utilizing eventlet will be removed as of the M-release. The - recommended deployment is to run keystone in a WSGI server such as Apache - httpd with ``mod_wsgi``. - -Keystone can be run using either its built-in eventlet server or it can be run -embedded in a web server. While the eventlet server is convenient and easy to -use, it's lacking in security features that have been developed into Internet- -based web servers over the years. As such, running the eventlet server as -described in this section is not recommended. - -Start Keystone services using the command: - -.. code-block:: bash - - $ keystone-all - -Invoking this command starts up two ``wsgi.Server`` instances, ``admin`` (the -administration API) and ``main`` (the primary/public API interface). Both -services are configured to run in a single process. - -.. NOTE:: - - The separation into ``admin`` and ``main`` interfaces is a historical - anomaly. The new V3 API provides the same interface on both the admin and - main interfaces (this can be configured in ``keystone-paste.ini``, but the - default is to have both the same). The V2.0 API provides a limited public - API (getting and validating tokens) on ``main``, and an administrative API - (which can include creating users and such) on the ``admin`` interface. - -Stop the process using ``Control-C``. - -.. NOTE:: - - If you have not already configured Keystone, it may not start as expected. - - -Configuration Files -=================== - -The Keystone configuration files are an ``ini`` file format based on Paste_, a -common system used to configure Python WSGI based applications. The PasteDeploy -configuration entries (WSGI pipeline definitions) can be provided in a separate -``keystone-paste.ini`` file, while general and driver-specific configuration -parameters are in the primary configuration file ``keystone.conf``. - -.. NOTE:: - - Since keystone's PasteDeploy configuration file has been separated - from the main keystone configuration file, ``keystone.conf``, all - local configuration or driver-specific configuration parameters must - go in the main keystone configuration file instead of the PasteDeploy - configuration file, i.e. configuration in ``keystone-paste.ini`` - is not supported. - -The primary configuration file is organized into the following sections: - -* ``[DEFAULT]`` - General configuration -* ``[assignment]`` - Assignment system driver configuration -* ``[auth]`` - Authentication plugin configuration -* ``[cache]`` - Caching layer configuration -* ``[catalog]`` - Service catalog driver configuration -* ``[credential]`` - Credential system driver configuration -* ``[endpoint_filter]`` - Endpoint filtering configuration -* ``[endpoint_policy]`` - Endpoint policy configuration -* ``[eventlet_server]`` - Eventlet server configuration -* ``[eventlet_server_ssl]`` - Eventlet server SSL configuration -* ``[federation]`` - Federation driver configuration -* ``[identity]`` - Identity system driver configuration -* ``[identity_mapping]`` - Identity mapping system driver configuration -* ``[kvs]`` - KVS storage backend configuration -* ``[ldap]`` - LDAP configuration options -* ``[memcache]`` - Memcache configuration options -* ``[oauth1]`` - OAuth 1.0a system driver configuration -* ``[os_inherit]`` - Inherited role assignment configuration -* ``[paste_deploy]`` - Pointer to the PasteDeploy configuration file -* ``[policy]`` - Policy system driver configuration for RBAC -* ``[resource]`` - Resource system driver configuration -* ``[revoke]`` - Revocation system driver configuration -* ``[role]`` - Role system driver configuration -* ``[saml]`` - SAML configuration options -* ``[signing]`` - Cryptographic signatures for PKI based tokens -* ``[ssl]`` - SSL certificate generation configuration -* ``[token]`` - Token driver & token provider configuration -* ``[trust]`` - Trust configuration - -The Keystone primary configuration file is expected to be named -``keystone.conf``. When starting Keystone, you can specify a different -configuration file to use with ``--config-file``. If you do **not** specify a -configuration file, Keystone will look in the following directories for a -configuration file, in order: - -* ``~/.keystone/`` -* ``~/`` -* ``/etc/keystone/`` -* ``/etc/`` - -PasteDeploy configuration file is specified by the ``config_file`` parameter in -``[paste_deploy]`` section of the primary configuration file. If the parameter -is not an absolute path, then Keystone looks for it in the same directories as -above. If not specified, WSGI pipeline definitions are loaded from the primary -configuration file. - -Domain-specific Drivers ------------------------ - -Keystone supports the option (disabled by default) to specify identity driver -configurations on a domain by domain basis, allowing, for example, a specific -domain to have its own LDAP or SQL server. This is configured by specifying the -following options: - -.. code-block:: ini - - [identity] - domain_specific_drivers_enabled = True - domain_config_dir = /etc/keystone/domains - -Setting ``domain_specific_drivers_enabled`` to ``True`` will enable this -feature, causing Keystone to look in the ``domain_config_dir`` for config files -of the form:: - - keystone.<domain_name>.conf - -Options given in the domain specific configuration file will override those in -the primary configuration file for the specified domain only. Domains without a -specific configuration file will continue to use the options from the primary -configuration file. - -Keystone also supports the ability to store the domain-specific configuration -options in the keystone SQL database, managed via the Identity API, as opposed -to using domain-specific configuration files. - -.. NOTE:: - - The ability to store and manage configuration options via the Identity API - is new and experimental in Kilo. - -This capability (which is disabled by default) is enabled by specifying the -following options in the main keystone configuration file: - -.. code-block:: ini - - [identity] - domain_specific_drivers_enabled = true - domain_configurations_from_database = true - -Once enabled, any existing domain-specific configuration files in the -configuration directory will be ignored and only those domain-specific -configuration options specified via the Identity API will be used. - -Unlike the file-based method of specifying domain-specific configurations, -options specified via the Identity API will become active without needing to -restart the keystone server. For performance reasons, the current state of -configuration options for a domain are cached in the keystone server, and in -multi-process and multi-threaded keystone configurations, the new -configuration options may not become active until the cache has timed out. The -cache settings for domain config options can be adjusted in the general -keystone configuration file (option ``cache_time`` in the ``domain_config`` -group). - -.. NOTE:: - - It is important to notice that when using either of these methods of - specifying domain-specific configuration options, the main keystone - configuration file is still maintained. Only those options that relate - to the Identity driver for users and groups (i.e. specifying whether the - driver for this domain is SQL or LDAP, and, if LDAP, the options that - define that connection) are supported in a domain-specific manner. Further, - when using the configuration options via the Identity API, the driver - option must be set to an LDAP driver (attempting to set it to an SQL driver - will generate an error when it is subsequently used). - -For existing installations that already use file-based domain-specific -configurations who wish to migrate to the SQL-based approach, the -``keystone-manage`` command can be used to upload all configuration files to -the SQL database: - -.. code-block:: bash - - $ keystone-manage domain_config_upload --all - -Once uploaded, these domain-configuration options will be visible via the -Identity API as well as applied to the domain-specific drivers. It is also -possible to upload individual domain-specific configuration files by -specifying the domain name: - -.. code-block:: bash - - $ keystone-manage domain_config_upload --domain-name DOMAINA - -.. NOTE:: - - It is important to notice that by enabling either of the domain-specific - configuration methods, the operations of listing all users and listing all - groups are not supported, those calls will need either a domain filter to - be specified or usage of a domain scoped token. - -.. NOTE:: - - Keystone does not support moving the contents of a domain (i.e. "its" users - and groups) from one backend to another, nor group membership across - backend boundaries. - -.. NOTE:: - - When using the file-based domain-specific configuration method, to delete a - domain that uses a domain specific backend, it's necessary to first disable - it, remove its specific configuration file (i.e. its corresponding - keystone.<domain_name>.conf) and then restart the Identity server. When - managing configuration options via the Identity API, the domain can simply - be disabled and deleted via the Identity API; since any domain-specific - configuration options will automatically be removed. - -.. NOTE:: - - Although Keystone supports multiple LDAP backends via the above - domain-specific configuration methods, it currently only supports one SQL - backend. This could be either the default driver or a single - domain-specific backend, perhaps for storing service users in a - predominantly LDAP installation. - -Due to the need for user and group IDs to be unique across an OpenStack -installation and for Keystone to be able to deduce which domain and backend to -use from just a user or group ID, it dynamically builds a persistent identity -mapping table from a public ID to the actual domain, local ID (within that -backend) and entity type. The public ID is automatically generated by Keystone -when it first encounters the entity. If the local ID of the entity is from a -backend that does not guarantee to generate UUIDs, a hash algorithm will -generate a public ID for that entity, which is what will be exposed by -Keystone. - -The use of a hash will ensure that if the public ID needs to be regenerated -then the same public ID will be created. This is useful if you are running -multiple keystones and want to ensure the same ID would be generated whichever -server you hit. - -While Keystone will dynamically maintain the identity mapping, including -removing entries when entities are deleted via the Keystone, for those entities -in backends that are managed outside of Keystone (e.g. a Read Only LDAP), -Keystone will not know if entities have been deleted and hence will continue to -carry stale identity mappings in its table. While benign, keystone provides an -ability for operators to purge the mapping table of such stale entries using -the keystone-manage command, for example: - -.. code-block:: bash - - $ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com - -A typical usage would be for an operator to obtain a list of those entries in -an external backend that had been deleted out-of-band to Keystone, and then -call keystone-manage to purge those entries by specifying the domain and -local-id. The type of the entity (i.e. user or group) may also be specified if -this is needed to uniquely identify the mapping. - -Since public IDs can be regenerated **with the correct generator -implementation**, if the details of those entries that have been deleted are -not available, then it is safe to simply bulk purge identity mappings -periodically, for example: - -.. code-block:: bash - - $ keystone-manage mapping_purge --domain-name DOMAINA - -will purge all the mappings for DOMAINA. The entire mapping table can be purged -with the following command: - -.. code-block:: bash - - $ keystone-manage mapping_purge --all - -Public ID Generators --------------------- - -Keystone supports a customizable public ID generator and it is specified in the -``[identity_mapping]`` section of the configuration file. Keystone provides a -sha256 generator as default, which produces regeneratable public IDs. The -generator algorithm for public IDs is a balance between key size (i.e. the -length of the public ID), the probability of collision and, in some -circumstances, the security of the public ID. The maximum length of public ID -supported by Keystone is 64 characters, and the default generator (sha256) uses -this full capability. Since the public ID is what is exposed externally by -Keystone and potentially stored in external systems, some installations may -wish to make use of other generator algorithms that have a different trade-off -of attributes. A different generator can be installed by configuring the -following property: - -* ``generator`` - identity mapping generator. Defaults to ``sha256`` - (implemented by :class:`keystone.identity.id_generators.sha256.Generator`) - -.. WARNING:: - - Changing the generator may cause all existing public IDs to be become - invalid, so typically the generator selection should be considered - immutable for a given installation. - -Authentication Plugins ----------------------- - -.. NOTE:: - - This feature is only supported by Keystone for the Identity API v3 clients. - -Keystone supports authentication plugins and they are specified in the -``[auth]`` section of the configuration file. However, an authentication plugin -may also have its own section in the configuration file. It is up to the plugin -to register its own configuration options. - -* ``methods`` - comma-delimited list of authentication plugin names -* ``<plugin name>`` - specify the class which handles to authentication method, - in the same manner as one would specify a backend driver. - -Keystone provides three authentication methods by default. ``password`` handles -password authentication and ``token`` handles token authentication. -``external`` is used in conjunction with authentication performed by a -container web server that sets the ``REMOTE_USER`` environment variable. For -more details, refer to :doc:`External Authentication <external-auth>`. - -How to Implement an Authentication Plugin -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -All authentication plugins must extend the -:class:`keystone.auth.core.AuthMethodHandler` class and implement the -``authenticate()`` method. The ``authenticate()`` method expects the following -parameters. - -* ``context`` - Keystone's request context -* ``auth_payload`` - the content of the authentication for a given method -* ``auth_context`` - user authentication context, a dictionary shared by all - plugins. It contains ``method_names`` and ``extras`` by default. - ``method_names`` is a list and ``extras`` is a dictionary. - -If successful, the ``authenticate()`` method must provide a valid ``user_id`` -in ``auth_context`` and return ``None``. ``method_name`` is used to convey any -additional authentication methods in case authentication is for re-scoping. For -example, if the authentication is for re-scoping, a plugin must append the -previous method names into ``method_names``. Also, a plugin may add any -additional information into ``extras``. Anything in ``extras`` will be conveyed -in the token's ``extras`` field. - -If authentication requires multiple steps, the ``authenticate()`` method must -return the payload in the form of a dictionary for the next authentication -step. - -If authentication is unsuccessful, the ``authenticate()`` method must raise a -:class:`keystone.exception.Unauthorized` exception. - -Simply add the new plugin name to the ``methods`` list along with your plugin -class configuration in the ``[auth]`` sections of the configuration file to -deploy it. - -If the plugin requires additional configurations, it may register its own -section in the configuration file. - -Plugins are invoked in the order in which they are specified in the ``methods`` -attribute of the ``authentication`` request body. If multiple plugins are -invoked, all plugins must succeed in order to for the entire authentication to -be successful. Furthermore, all the plugins invoked must agree on the -``user_id`` in the ``auth_context``. - -The ``REMOTE_USER`` environment variable is only set from a containing -webserver. However, to ensure that a user must go through other authentication -mechanisms, even if this variable is set, remove ``external`` from the list of -plugins specified in ``methods``. This effectively disables external -authentication. For more details, refer to :doc:`ExternalAuthentication -<external-auth>`. - - -Token Persistence Driver ------------------------- - -Keystone supports customizable token persistence drivers. These can be -specified in the ``[token]`` section of the configuration file. Keystone -provides three non-test persistence backends. These can be set with the -``[token] driver`` configuration option. - -The drivers Keystone provides are: - -* ``memcache_pool`` - The pooled memcached token persistence engine. This - backend supports the concept of pooled memcache client object (allowing for - the re-use of the client objects). This backend has a number of extra tunable - options in the ``[memcache]`` section of the config. Implemented by - :class:`keystone.token.persistence.backends.memcache_pool.Token` - -* ``sql`` - The SQL-based (default) token persistence engine. Implemented by - :class:`keystone.token.persistence.backends.sql.Token` - -* ``memcache`` - The memcached based token persistence backend. This backend - relies on ``dogpile.cache`` and stores the token data in a set of memcached - servers. The servers URLs are specified in the ``[memcache] servers`` - configuration option in the Keystone config. Implemented by - :class:`keystone.token.persistence.backends.memcache.Token` - - -.. WARNING:: - It is recommended you use the ``memcache_pool`` backend instead of - ``memcache`` as the token persistence driver if you are deploying Keystone - under eventlet instead of Apache httpd with ``mod_wsgi``. This - recommendation is due to known issues with the use of ``thread.local`` - under eventlet that can allow the leaking of memcache client objects and - consumption of extra sockets. - - -Token Provider --------------- - -Keystone supports customizable token provider and it is specified in the -``[token]`` section of the configuration file. Keystone provides both UUID and -PKI token providers. However, users may register their own token provider by -configuring the following property. - -* ``provider`` - token provider driver. Defaults to ``uuid``. Implemented by - :class:`keystone.token.providers.uuid.Provider` - - -UUID, PKI, PKIZ, or Fernet? -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Each token format uses different technologies to achieve various performance, -scaling and architectural requirements. - -UUID tokens contain randomly generated UUID4 payloads that are issued and -validated by the identity service. They are encoded using their hex digest for -transport and are thus URL-friendly. They must be persisted by the identity -service in order to be later validated. Revoking them is simply a matter of -deleting them from the token persistence backend. - -Both PKI and PKIZ tokens contain JSON payloads that represent the entire token -validation response that would normally be retrieved from keystone. The payload -is then signed using `Cryptographic Message Syntax (CMS) -<http://en.wikipedia.org/wiki/Cryptographic_Message_Syntax>`_. The combination -of CMS and the exhaustive payload allows PKI and PKIZ tokens to be verified -offline using keystone's public signing key. The only reason for them to be -persisted by the identity service is to later build token revocation *lists* -(explicit lists of tokens that have been revoked), otherwise they are -theoretically ephemeral when supported by token revocation *events* (which -describe invalidated tokens rather than enumerate them). PKIZ tokens add zlib -compression after signing to achieve a smaller overall token size. To make them -URL-friendly, PKI tokens are base64 encoded and then arbitrarily manipulated to -replace unsafe characters with safe ones whereas PKIZ tokens use conventional -base64url encoding. Due to the size of the payload and the overhead incurred by -the CMS format, both PKI and PKIZ tokens may be too long to fit in either -headers or URLs if they contain extensive service catalogs or other additional -attributes. Some third-party applications such as web servers and clients may -need to be recompiled from source to customize the limitations that PKI and -PKIZ tokens would otherwise exceed). Both PKI and PKIZ tokens require signing -certificates which may be created using ``keystone-manage pki_setup`` for -demonstration purposes (this is not recommended for production deployments: use -certificates issued by an trusted CA instead). - -Fernet tokens contain a limited amount of identity and authorization data in a -`MessagePacked <http://msgpack.org/>`_ payload. The payload is then wrapped as -a `Fernet <https://github.com/fernet/spec>`_ message for transport, where -Fernet provides the required web safe characteristics for use in URLs and -headers. Fernet tokens require symmetric encryption keys which can be -established using ``keystone-manage fernet_setup`` and periodically rotated -using ``keystone-manage fernet_rotate``. - -.. WARNING:: - UUID, PKI, PKIZ, and Fernet tokens are all bearer tokens, meaning that they - must be protected from unnecessary disclosure to prevent unauthorized - access. - -Caching Layer -------------- - -Keystone supports a caching layer that is above the configurable subsystems -(e.g. ``token``, ``identity``, etc). Keystone uses the `dogpile.cache`_ library -which allows for flexible cache backends. The majority of the caching -configuration options are set in the ``[cache]`` section. However, each section -that has the capability to be cached usually has a ``caching`` boolean value -that will toggle caching for that specific section. The current default -behavior is that subsystem caching is enabled, but the global toggle is set to -disabled. - -``[cache]`` configuration section: -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -* ``enabled`` - enables/disables caching across all of keystone -* ``debug_cache_backend`` - enables more in-depth logging from the cache - backend (get, set, delete, etc) -* ``backend`` - the caching backend module to use e.g. - ``dogpile.cache.memcached`` - - .. NOTE:: - A given ``backend`` must be registered with ``dogpile.cache`` before it - can be used. The default backend is the ``Keystone`` no-op backend - (``keystone.common.cache.noop``). If caching is desired a different - backend will need to be specified. Current functional backends are: - - * ``dogpile.cache.memcached`` - Memcached backend using the standard - `python-memcached`_ library (recommended for use with Apache httpd with - ``mod_wsgi``) - * ``dogpile.cache.pylibmc`` - Memcached backend using the `pylibmc`_ - library - * ``dogpile.cache.bmemcached`` - Memcached using `python-binary-memcached`_ - library. - * ``dogpile.cache.redis`` - `Redis`_ backend - * ``dogpile.cache.dbm`` - local DBM file backend - * ``dogpile.cache.memory`` - in-memory cache - * ``keystone.cache.mongo`` - MongoDB as caching backend - * ``keystone.cache.memcache_pool`` - An eventlet-safe implementation of - ``dogpile.cache.memcached``. This implementation also provides client - connection re-use. - - .. WARNING:: - ``dogpile.cache.memory`` is not suitable for use outside of unit - testing as it does not cleanup its internal cache on cache - expiration, does not provide isolation to the cached data (values - in the store can be inadvertently changed without extra layers of - data protection added), and does not share cache between processes. - This means that caching and cache invalidation will not be - consistent or reliable when using ``Keystone`` and the - ``dogpile.cache.memory`` backend under any real workload. - - .. WARNING:: - Do not use ``dogpile.cache.memcached`` backend if you are deploying - Keystone under eventlet. There are known issues with the use of - ``thread.local`` under eventlet that can allow the leaking of - memcache client objects and consumption of extra sockets. - -* ``expiration_time`` - int, the default length of time to cache a specific - value. A value of ``0`` indicates to not cache anything. It is recommended - that the ``enabled`` option be used to disable cache instead of setting this - to ``0``. -* ``backend_argument`` - an argument passed to the backend when instantiated - ``backend_argument`` should be specified once per argument to be passed to - the backend and in the format of ``<argument name>:<argument value>``. e.g.: - ``backend_argument = host:localhost`` -* ``proxies`` - comma delimited list of `ProxyBackends`_ e.g. - ``my.example.Proxy, my.example.Proxy2`` - -Current Keystone systems that have caching capabilities: - * ``token`` - The token system has a separate ``cache_time`` configuration option, - that can be set to a value above or below the global - ``expiration_time`` default, allowing for different caching behavior - from the other systems in ``Keystone``. This option is set in the - ``[token]`` section of the configuration file. - - The Token Revocation List cache time is handled by the configuration - option ``revocation_cache_time`` in the ``[token]`` section. The - revocation list is refreshed whenever a token is revoked. It typically - sees significantly more requests than specific token retrievals or - token validation calls. - * ``resource`` - The resource system has a separate ``cache_time`` configuration option, - that can be set to a value above or below the global - ``expiration_time`` default, allowing for different caching behavior - from the other systems in ``Keystone``. This option is set in the - ``[resource]`` section of the configuration file. - - Currently ``resource`` has caching for ``project`` and ``domain`` - specific requests (primarily around the CRUD actions). The - ``list_projects`` and ``list_domains`` methods are not subject to - caching. - - .. WARNING:: - Be aware that if a read-only ``resource`` backend is in use, the - cache will not immediately reflect changes on the back end. Any - given change may take up to the ``cache_time`` (if set in the - ``[resource]`` section of the configuration) or the global - ``expiration_time`` (set in the ``[cache]`` section of the - configuration) before it is reflected. If this type of delay (when - using a read-only ``resource`` backend) is an issue, it is - recommended that caching be disabled on ``resource``. To disable - caching specifically on ``resource``, in the ``[resource]`` section - of the configuration set ``caching`` to ``False``. - * ``role`` - Currently ``role`` has caching for ``get_role``, but not for ``list_roles``. - The role system has a separate ``cache_time`` configuration option, - that can be set to a value above or below the global ``expiration_time`` - default, allowing for different caching behavior from the other systems in - ``Keystone``. This option is set in the ``[role]`` section of the - configuration file. - - .. WARNING:: - Be aware that if a read-only ``role`` backend is in use, the cache - will not immediately reflect changes on the back end. Any given change - may take up to the ``cache_time`` (if set in the ``[role]`` - section of the configuration) or the global ``expiration_time`` (set in - the ``[cache]`` section of the configuration) before it is reflected. - If this type of delay (when using a read-only ``role`` backend) is - an issue, it is recommended that caching be disabled on ``role``. - To disable caching specifically on ``role``, in the ``[role]`` - section of the configuration set ``caching`` to ``False``. - -For more information about the different backends (and configuration options): - * `dogpile.cache.backends.memory`_ - * `dogpile.cache.backends.memcached`_ - * `dogpile.cache.backends.redis`_ - * `dogpile.cache.backends.file`_ - * :py:mod:`keystone.common.cache.backends.mongo` - -.. _`dogpile.cache`: http://dogpilecache.readthedocs.org/en/latest/ -.. _`python-memcached`: http://www.tummy.com/software/python-memcached/ -.. _`pylibmc`: http://sendapatch.se/projects/pylibmc/index.html -.. _`python-binary-memcached`: https://github.com/jaysonsantos/python-binary-memcached -.. _`Redis`: http://redis.io/ -.. _`dogpile.cache.backends.memory`: http://dogpilecache.readthedocs.org/en/latest/api.html#memory-backend -.. _`dogpile.cache.backends.memcached`: http://dogpilecache.readthedocs.org/en/latest/api.html#memcached-backends -.. _`dogpile.cache.backends.redis`: http://dogpilecache.readthedocs.org/en/latest/api.html#redis-backends -.. _`dogpile.cache.backends.file`: http://dogpilecache.readthedocs.org/en/latest/api.html#file-backends -.. _`ProxyBackends`: http://dogpilecache.readthedocs.org/en/latest/api.html#proxy-backends - - -Certificates for PKI --------------------- - -PKI stands for Public Key Infrastructure. Tokens are documents, -cryptographically signed using the X509 standard. In order to work correctly -token generation requires a public/private key pair. The public key must be -signed in an X509 certificate, and the certificate used to sign it must be -available as Certificate Authority (CA) certificate. These files can be either -externally generated or generated using the ``keystone-manage`` utility. - -The files used for signing and verifying certificates are set in the Keystone -configuration file. The private key should only be readable by the system user -that will run Keystone. The values that specify the certificates are under the -``[signing]`` section of the configuration file. The configuration values are: - -* ``certfile`` - Location of certificate used to verify tokens. Default is - ``/etc/keystone/ssl/certs/signing_cert.pem`` -* ``keyfile`` - Location of private key used to sign tokens. Default is - ``/etc/keystone/ssl/private/signing_key.pem`` -* ``ca_certs`` - Location of certificate for the authority that issued the - above certificate. Default is ``/etc/keystone/ssl/certs/ca.pem`` - -Signing Certificate Issued by External CA -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You may use a signing certificate issued by an external CA instead of generated -by ``keystone-manage``. However, certificate issued by external CA must satisfy -the following conditions: - -* all certificate and key files must be in Privacy Enhanced Mail (PEM) format -* private key files must not be protected by a password - -The basic workflow for using a signing certificate issued by an external CA -involves: - -1. `Request Signing Certificate from External CA`_ -2. Convert certificate and private key to PEM if needed -3. `Install External Signing Certificate`_ - - -Request Signing Certificate from External CA -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -One way to request a signing certificate from an external CA is to first -generate a PKCS #10 Certificate Request Syntax (CRS) using OpenSSL CLI. - -First create a certificate request configuration file (e.g. ``cert_req.conf``): - -.. code-block:: ini - - [ req ] - default_bits = 2048 - default_keyfile = keystonekey.pem - default_md = default - - prompt = no - distinguished_name = distinguished_name - - [ distinguished_name ] - countryName = US - stateOrProvinceName = CA - localityName = Sunnyvale - organizationName = OpenStack - organizationalUnitName = Keystone - commonName = Keystone Signing - emailAddress = keystone@openstack.org - -Then generate a CRS with OpenSSL CLI. **Do not encrypt the generated private -key. The -nodes option must be used.** - -For example: - -.. code-block:: bash - - $ openssl req -newkey rsa:2048 -keyout signing_key.pem -keyform PEM -out signing_cert_req.pem -outform PEM -config cert_req.conf -nodes - - -If everything is successfully, you should end up with ``signing_cert_req.pem`` -and ``signing_key.pem``. Send ``signing_cert_req.pem`` to your CA to request a -token signing certificate and make sure to ask the certificate to be in PEM -format. Also, make sure your trusted CA certificate chain is also in PEM -format. - - -Install External Signing Certificate -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Assuming you have the following already: - -* ``signing_cert.pem`` - (Keystone token) signing certificate in PEM format -* ``signing_key.pem`` - corresponding (non-encrypted) private key in PEM format -* ``cacert.pem`` - trust CA certificate chain in PEM format - -Copy the above to your certificate directory. For example: - -.. code-block:: bash - - $ mkdir -p /etc/keystone/ssl/certs - $ cp signing_cert.pem /etc/keystone/ssl/certs/ - $ cp signing_key.pem /etc/keystone/ssl/certs/ - $ cp cacert.pem /etc/keystone/ssl/certs/ - $ chmod -R 700 /etc/keystone/ssl/certs - -**Make sure the certificate directory is root-protected.** - -If your certificate directory path is different from the default -``/etc/keystone/ssl/certs``, make sure it is reflected in the ``[signing]`` -section of the configuration file. - - -Generating a Signing Certificate using pki_setup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -``keystone-manage pki_setup`` is a development tool. We recommend that you do -not use ``keystone-manage pki_setup`` in a production environment. In -production, an external CA should be used instead. This is because the CA -secret key should generally be kept apart from the token signing secret keys so -that a compromise of a node does not lead to an attacker being able to generate -valid signed Keystone tokens. This is a low probability attack vector, as -compromise of a Keystone service machine's filesystem security almost certainly -means the attacker will be able to gain direct access to the token backend. - -When using the ``keystone-manage pki_setup`` to generate the certificates, the -following configuration options in the ``[signing]`` section are used: - -* ``ca_key`` - Default is ``/etc/keystone/ssl/private/cakey.pem`` -* ``key_size`` - Default is ``2048`` -* ``valid_days`` - Default is ``3650`` - -If ``keystone-manage pki_setup`` is not used then these options don't need to -be set. - - -Encryption Keys for Fernet --------------------------- - -``keystone-manage fernet_setup`` will attempt to create a key repository as -configured in the ``[fernet_tokens]`` section of ``keystone.conf`` and -bootstrap it with encryption keys. - -A single 256-bit key is actually composed of two smaller keys: a 128-bit key -used for SHA256 HMAC signing and a 128-bit key used for AES encryption. See the -`Fernet token <https://github.com/fernet/spec>`_ specification for more detail. - -``keystone-manage fernet_rotate`` will rotate encryption keys through the -following states: - -* **Staged key**: In a key rotation, a new key is introduced into the rotation - in this state. Only one key is considered to be the *staged* key at any given - time. This key will become the *primary* during the *next* key rotation. This - key is only used to validate tokens and serves to avoid race conditions in - multi-node deployments (all nodes should recognize all *primary* keys in the - deployment at all times). In a multi-node Keystone deployment this would - allow for the *staged* key to be replicated to all Keystone nodes before - being promoted to *primary* on a single node. This prevents the case where a - *primary* key is created on one Keystone node and tokens encrypted/signed with - that new *primary* are rejected on another Keystone node because the new - *primary* doesn't exist there yet. - -* **Primary key**: In a key rotation, the old *staged* key is promoted to be - the *primary*. Only one key is considered to be the *primary* key at any - given time. This is the key used to generate new tokens. This key is also - used to validate previously generated tokens. - -* **Secondary keys**: In a key rotation, the old *primary* key is demoted to be - a *secondary* key. *Secondary* keys are only used to validate previously - generated tokens. You can maintain any number of *secondary* keys, up to - ``[fernet_tokens] max_active_keys`` (where "active" refers to the sum of all - recognized keys in any state: *staged*, *primary* or *secondary*). When - ``max_active_keys`` is exceeded during a key rotation, the oldest keys are - discarded. - -When a new primary key is created, all new tokens will be encrypted using the -new primary key. The old primary key is demoted to a secondary key, which can -still be used for validating tokens. Excess secondary keys (beyond -``[fernet_tokens] max_active_keys``) are revoked. Revoked keys are permanently -deleted. - -Rotating keys too frequently, or with ``[fernet_tokens] max_active_keys`` set -too low, will cause tokens to become invalid prior to their expiration. - -Service Catalog ---------------- - -Keystone provides two configuration options for your service catalog. - -SQL-based Service Catalog (``sql.Catalog``) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A dynamic database-backed driver fully supporting persistent configuration. - -``keystone.conf`` example: - -.. code-block:: ini - - [catalog] - driver = sql - -.. NOTE:: - - A `template_file` does not need to be defined for the sql.Catalog driver. - -To build your service catalog using this driver, see the built-in help: - -.. code-block:: bash - - $ openstack --help - $ openstack help service create - $ openstack help endpoint create - -You can also refer to `an example in Keystone (tools/sample_data.sh) -<https://git.openstack.org/cgit/openstack/keystone/tree/tools/sample_data.sh>`_. - -File-based Service Catalog (``templated.Catalog``) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The templated catalog is an in-memory backend initialized from a read-only -``template_file``. Choose this option only if you know that your service -catalog will not change very much over time. - -.. NOTE:: - - Attempting to change your service catalog against this driver will result - in ``HTTP 501 Not Implemented`` errors. This is the expected behavior. If - you want to use these commands, you must instead use the SQL-based Service - Catalog driver. - -``keystone.conf`` example: - -.. code-block:: ini - - [catalog] - driver = templated - template_file = /opt/stack/keystone/etc/default_catalog.templates - -The value of ``template_file`` is expected to be an absolute path to your -service catalog configuration. An example ``template_file`` is included in -Keystone, however you should create your own to reflect your deployment. - -Another such example is `available in devstack -(files/default_catalog.templates) -<https://git.openstack.org/cgit/openstack-dev/devstack/tree/files/default_catalog.templates>`_. - -Endpoint Filtering enables creation of ad-hoc catalogs for each project-scoped -token request. - -Configure the endpoint filter catalog driver in the ``[catalog]`` section. -For example: - -.. code-block:: ini - - [catalog] - driver = catalog_sql - -In the ``[endpoint_filter]`` section, set ``return_all_endpoints_if_no_filter`` -to ``False`` to return an empty catalog if no associations are made. -For example: - -.. code-block:: ini - - [endpoint_filter] - return_all_endpoints_if_no_filter = False - -See `API Specification for Endpoint Filtering <http://specs.openstack.org/ -openstack/keystone-specs/api/v3/identity-api-v3-os-ep-filter-ext.html>`_ for -the details of API definition. - -.. NOTE:: Support status for Endpoint Filtering - - *Experimental* (Icehouse, Juno) - *Stable* (Kilo) - -Logging -------- - -Logging is configured externally to the rest of Keystone. Configure the path to -your logging configuration file using the ``[DEFAULT] log_config_append`` -option of ``keystone.conf``. If you wish to route all your logging through -syslog, set the ``[DEFAULT] use_syslog`` option. - -A sample ``log_config_append`` file is included with the project at -``etc/logging.conf.sample``. Like other OpenStack projects, Keystone uses the -`Python logging module`_, which includes extensive configuration options for -choosing the output levels and formats. - -.. _Paste: http://pythonpaste.org/ -.. _`Python logging module`: http://docs.python.org/library/logging.html - -SSL ---- - -Keystone may be configured to support SSL and 2-way SSL out-of-the-box. The -X509 certificates used by Keystone can be generated by ``keystone-manage`` -or obtained externally and configured for use with Keystone as described in -this section. Here is the description of each of them and their purpose: - -.. WARNING:: - - The SSL configuration options available to the eventlet server - (``keystone-all``) described here are severely limited. A secure - deployment should have Keystone running in a web server (such as Apache - httpd), or behind an SSL terminator. When running Keystone in a web server - or behind an SSL terminator the options described in this section have no - effect and SSL is configured in the web server or SSL terminator. - -Types of certificates -^^^^^^^^^^^^^^^^^^^^^ - -* ``cacert.pem``: Certificate Authority chain to validate against. -* ``ssl_cert.pem``: Public certificate for Keystone server. -* ``middleware.pem``: Public and private certificate for Keystone - middleware/client. -* ``cakey.pem``: Private key for the CA. -* ``ssl_key.pem``: Private key for the Keystone server. - -Note that you may choose whatever names you want for these certificates, or -combine the public/private keys in the same file if you wish. These -certificates are just provided as an example. - -Configuration -^^^^^^^^^^^^^ - -To enable SSL modify the ``etc/keystone.conf`` file under the ``[ssl]`` and -``[eventlet_server_ssl]`` sections. The following is an SSL configuration -example using the included sample certificates: - -.. code-block:: ini - - [eventlet_server_ssl] - enable = True - certfile = <path to keystone.pem> - keyfile = <path to keystonekey.pem> - ca_certs = <path to ca.pem> - cert_required = False - - [ssl] - ca_key = <path to cakey.pem> - key_size = 1024 - valid_days=3650 - cert_subject=/C=US/ST=Unset/L=Unset/O=Unset/CN=localhost - -* ``enable``: True enables SSL. Defaults to False. -* ``certfile``: Path to Keystone public certificate file. -* ``keyfile``: Path to Keystone private certificate file. If the private key is - included in the certfile, the keyfile may be omitted. -* ``ca_certs``: Path to CA trust chain. -* ``cert_required``: Requires client certificate. Defaults to False. - -When generating SSL certificates the following values are read - -* ``key_size``: Key size to create. Defaults to 1024. -* ``valid_days``: How long the certificate is valid for. Defaults to 3650 - (10 years). -* ``ca_key``: The private key for the CA. Defaults to - ``/etc/keystone/ssl/certs/cakey.pem``. -* ``cert_subject``: The subject to set in the certificate. Defaults to - ``/C=US/ST=Unset/L=Unset/O=Unset/CN=localhost``. When setting the subject it - is important to set CN to be the address of the server so client validation - will succeed. This generally means having the subject be at least - ``/CN=<keystone ip>`` - -Generating SSL certificates -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Certificates for encrypted HTTP communication can be generated by: - -.. code-block:: bash - - $ keystone-manage ssl_setup - -This will create a private key, a public key and a certificate that will be -used to encrypt communications with keystone. In the event that a Certificate -Authority is not given a testing one will be created. - -It is likely in a production environment that these certificates will be -created and provided externally. Note that ``ssl_setup`` is a development tool -and is only recommended for developments environment. We do not recommend using -``ssl_setup`` for production environments. - - -User CRUD additions for the V2.0 API ------------------------------------- - -For the V2.0 API, Keystone provides an additional capability that allows users -to use a HTTP PATCH to change their own password. - -Each user can then change their own password with a HTTP PATCH : - -.. code-block:: bash - - $ curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/<userid> -H "Content-type: application/json" \ - -H "X_Auth_Token: <authtokenid>" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}' - -In addition to changing their password all of the user's current tokens will be -revoked. - - -Inherited Role Assignments --------------------------- - -Keystone provides an optional capability to assign roles on a project or domain -that, rather than affect the project or domain itself, are instead inherited to -the project subtree or to all projects owned by that domain. This capability is -enabled by default, but can be disabled by including the following in -``keystone.conf``: - -.. code-block:: ini - - [os_inherit] - enabled = False - - -Endpoint Policy ---------------- - -The Endpoint Policy feature provides associations between service endpoints -and policies that are already stored in the Identity server and referenced -by a policy ID. - -Configure the endpoint policy backend driver in the ``[endpoint_policy]`` -section. For example: - -.. code-block:: ini - - [endpoint_policy] - driver = sql - -See `API Specification for Endpoint Policy <http://specs.openstack.org/ -openstack/keystone-specs/api/v3/identity-api-v3-os-endpoint-policy.html>`_ -for the details of API definition. - -.. NOTE:: Support status for Endpoint Policy - - *Experimental* (Juno) - *Stable* (Kilo) - - -OAuth1 1.0a ------------ - -The OAuth 1.0a feature provides the ability for Identity users to delegate -roles to third party consumers via the OAuth 1.0a specification. - -To enable OAuth1: - -1. Add the oauth1 driver to the ``[oauth1]`` section in ``keystone.conf``. For - example: - -.. code-block:: ini - - [oauth1] - driver = sql - -2. Add the ``oauth1`` authentication method to the ``[auth]`` section in - ``keystone.conf``: - -.. code-block:: ini - - [auth] - methods = external,password,token,oauth1 - -3. If deploying under Apache httpd with ``mod_wsgi``, set the - `WSGIPassAuthorization` to allow the OAuth Authorization headers to pass - through `mod_wsgi`. For example, add the following to the keystone virtual - host file: - -.. code-block:: ini - - WSGIPassAuthorization On - -See `API Specification for OAuth 1.0a <http://specs.openstack.org/openstack/ -keystone-specs/api/v3/identity-api-v3-os-oauth1-ext.html>`_ for the details of -API definition. - -.. NOTE:: Support status for OAuth 1.0a - - *Experimental* (Havana, Icehouse) - *Stable* (Juno) - - -Revocation Events ------------------ - -The Revocation Events feature provides a list of token revocations. Each event -expresses a set of criteria which describes a set of tokens that are -no longer valid. - -Add the revoke backend driver to the ``[revoke]`` section in -``keystone.conf``. For example: - -.. code-block:: ini - - [revoke] - driver = sql - -See `API Specification for Revocation Events <https://specs.openstack.org/ -openstack/keystone-specs/api/v3/identity-api-v3-os-revoke-ext.html>`_ for -the details of API definition. - -.. NOTE:: Support status for Revocation Events - - *Experimental* (Juno) - *Stable* (Kilo) - - -Token Binding -------------- - -Token binding refers to the practice of embedding information from external -authentication providers (like a company's Kerberos server) inside the token -such that a client may enforce that the token only be used in conjunction with -that specified authentication. This is an additional security mechanism as it -means that if a token is stolen it will not be usable without also providing -the external authentication. - -To activate token binding you must specify the types of authentication that -token binding should be used for in ``keystone.conf`` e.g.: - -.. code-block:: ini - - [token] - bind = kerberos - -Currently only ``kerberos`` is supported. - -To enforce checking of token binding the ``enforce_token_bind`` parameter -should be set to one of the following modes: - -* ``disabled`` disable token bind checking -* ``permissive`` enable bind checking, if a token is bound to a mechanism that - is unknown to the server then ignore it. This is the default. -* ``strict`` enable bind checking, if a token is bound to a mechanism that is - unknown to the server then this token should be rejected. -* ``required`` enable bind checking and require that at least 1 bind mechanism - is used for tokens. -* named enable bind checking and require that the specified authentication - mechanism is used. e.g.: - - .. code-block:: ini - - [token] - enforce_token_bind = kerberos - - *Do not* set ``enforce_token_bind = named`` as there is not an authentication - mechanism called ``named``. - -Limiting the number of entities returned in a collection --------------------------------------------------------- - -Keystone provides a method of setting a limit to the number of entities -returned in a collection, which is useful to prevent overly long response times -for list queries that have not specified a sufficiently narrow filter. This -limit can be set globally by setting ``list_limit`` in the default section of -``keystone.conf``, with no limit set by default. Individual driver sections may -override this global value with a specific limit, for example: - -.. code-block:: ini - - [resource] - list_limit = 100 - -If a response to ``list_{entity}`` call has been truncated, then the response -status code will still be 200 (OK), but the ``truncated`` attribute in the -collection will be set to ``true``. - - -URL safe naming of projects and domains ---------------------------------------- - -In the future, keystone may offer the ability to identify a project in a -hierarchy via a URL style of naming from the root of the hierarchy (for example -specifying 'projectA/projectB/projectC' as the project name in an -authentication request). In order to prepare for this, keystone supports the -optional ability to ensure both projects and domains are named without -including any of the reserverd characters specified in section 2.2 of -`rfc3986 <http://tools.ietf.org/html/rfc3986>`_. - -The safety of the names of projects and domains can be controlled via two -configuration options: - -.. code-block:: ini - - [resource] - project_name_url_safe = off - domain_name_url_safe = off - -When set to ``off`` (which is the default), no checking is done on the URL -safeness of names. When set to ``new``, an attempt to create a new project or -domain with an unsafe name (or update the name of a project or domain to be -unsafe) will cause a status code of 400 (Bad Request) to be returned. Setting -the configuration option to ``strict`` will, in addition to preventing the -creation and updating of entities with unsafe names, cause an authentication -attempt which specifies a project or domain name that is unsafe to return a -status code of 401 (Unauthorized). - -It is recommended that installations take the steps necessary to where they -can run with both options set to ``strict`` as soon as is practical. - -Sample Configuration Files --------------------------- - -The ``etc/`` folder distributed with Keystone contains example configuration -files for each Server application. - -* ``etc/keystone.conf.sample`` -* ``etc/keystone-paste.ini`` -* ``etc/logging.conf.sample`` -* ``etc/default_catalog.templates`` -* ``etc/sso_callback_template.html`` - -.. _`API protection with RBAC`: - -Keystone API protection with Role Based Access Control (RBAC) -============================================================= - -Like most OpenStack projects, Keystone supports the protection of its APIs by -defining policy rules based on an RBAC approach. These are stored in a JSON -policy file, the name and location of which is set in the main Keystone -configuration file. - -Each Keystone v3 API has a line in the policy file which dictates what level of -protection is applied to it, where each line is of the form:: - - <api name>: <rule statement> or <match statement> - -where: - -``<rule statement>`` can contain ``<rule statement>`` or ``<match statement>`` - -``<match statement>`` is a set of identifiers that must match between the token -provided by the caller of the API and the parameters or target entities of the -API call in question. For example: - -.. code-block:: javascript - - "identity:create_user": "role:admin and domain_id:%(user.domain_id)s" - -Indicates that to create a user you must have the admin role in your token and -in addition the domain_id in your token (which implies this must be a domain -scoped token) must match the domain_id in the user object you are trying to -create. In other words, you must have the admin role on the domain in which you -are creating the user, and the token you are using must be scoped to that -domain. - -Each component of a match statement is of the form:: - - <attribute from token>:<constant> or <attribute related to API call> - -The following attributes are available - -* Attributes from token: user_id, the domain_id or project_id depending on - the scope, and the list of roles you have within that scope - -* Attributes related to API call: Any parameters that are passed into the API - call are available, along with any filters specified in the query string. - Attributes of objects passed can be referenced using an object.attribute - syntax (e.g. user.domain_id). The target objects of an API are also available - using a target.object.attribute syntax. For instance: - - .. code-block:: javascript - - "identity:delete_user": "role:admin and domain_id:%(target.user.domain_id)s" - - would ensure that the user object that is being deleted is in the same - domain as the token provided. - -Every target object (except token) has an `id` and a `name` available as -`target.<object>.id` and `target.<object>.name`. Other attributes are retrieved -from the database and vary between object types. Moreover, some database fields -are filtered out (e.g. user passwords). - -List of object attributes: - -* role: - * target.role.domain_id - * target.role.id - * target.role.name - -* user: - * target.user.default_project_id - * target.user.description - * target.user.domain_id - * target.user.enabled - * target.user.id - * target.user.name - -* group: - * target.group.description - * target.group.domain_id - * target.group.id - * target.group.name - -* domain: - * target.domain.enabled - * target.domain.id - * target.domain.name - -* project: - * target.project.description - * target.project.domain_id - * target.project.enabled - * target.project.id - * target.project.name - -* token - * target.token.user_id - * target.token.user.domain.id - -The default policy.json file supplied provides a somewhat basic example of API -protection, and does not assume any particular use of domains. For multi-domain -configuration installations where, for example, a cloud provider wishes to -allow administration of the contents of a domain to be delegated, it is -recommended that the supplied policy.v3cloudsample.json is used as a basis for -creating a suitable production policy file. This example policy file also shows -the use of an admin_domain to allow a cloud provider to enable cloud -administrators to have wider access across the APIs. - -A clean installation would need to perhaps start with the standard policy file, -to allow creation of the admin_domain with the first users within it. The -domain_id of the admin domain would then be obtained and could be pasted into a -modified version of policy.v3cloudsample.json which could then be enabled as -the main policy file. - -.. _`prepare your deployment`: - -Preparing your deployment -========================= - -Step 1: Configure keystone.conf -------------------------------- - -Ensure that your ``keystone.conf`` is configured to use a SQL driver: - -.. code-block:: ini - - [identity] - driver = sql - -You may also want to configure your ``[database]`` settings to better reflect -your environment: - -.. code-block:: ini - - [database] - connection = sqlite:///keystone.db - idle_timeout = 200 - -.. NOTE:: - - It is important that the database that you specify be different from the - one containing your existing install. - -Step 2: Sync your new, empty database -------------------------------------- - -You should now be ready to initialize your new database without error, using: - -.. code-block:: bash - - $ keystone-manage db_sync - -To test this, you should now be able to start ``keystone-all`` and use the -OpenStack Client to list your projects (which should successfully return an -empty list from your new database): - -.. code-block:: bash - - $ openstack --os-token ADMIN --os-url http://127.0.0.1:35357/v2.0/ project list - -.. NOTE:: - - We're providing the default OS_TOKEN and OS_URL values from - ``keystone.conf`` to connect to the Keystone service. If you changed those - values, or deployed Keystone to a different endpoint, you will need to - change the provided command accordingly. - -Initializing Keystone -===================== - -``keystone-manage`` is designed to execute commands that cannot be administered -through the normal REST API. At the moment, the following calls are supported: - -* ``db_sync``: Sync the database. -* ``db_version``: Print the current migration version of the database. -* ``domain_config_upload``: Upload domain configuration file. -* ``fernet_rotate``: Rotate keys in the Fernet key repository. -* ``fernet_setup``: Setup a Fernet key repository. -* ``mapping_engine``: Test your federation mapping rules. -* ``mapping_purge``: Purge the identity mapping table. -* ``pki_setup``: Initialize the certificates used to sign tokens. -* ``saml_idp_metadata``: Generate identity provider metadata. -* ``ssl_setup``: Generate certificates for SSL. -* ``token_flush``: Purge expired tokens - -Invoking ``keystone-manage`` by itself will give you additional usage -information. - -The private key used for token signing can only be read by its owner. This -prevents unauthorized users from spuriously signing tokens. -``keystone-manage pki_setup`` Should be run as the same system user that will -be running the Keystone service to ensure proper ownership for the private key -file and the associated certificates. - -Adding Users, Projects, and Roles via Command Line Interfaces -============================================================= - -Keystone APIs are protected by the rules in the policy file. The default policy -rules require admin credentials to administer ``users``, ``projects``, and -``roles``. See section -`Keystone API protection with Role Based Access Control (RBAC)`_ for more -details on policy files. - -The Keystone command line interface packaged in `python-keystoneclient`_ only -supports the Identity v2.0 API. The OpenStack common command line interface -packaged in `python-openstackclient`_ supports both v2.0 and v3 APIs. - -With both command line interfaces there are two ways to configure the client to -use admin credentials, using either an existing token or password credentials. - -.. NOTE:: - - As of the Juno release, it is recommended to use - ``python-openstackclient``, as it supports both v2.0 and v3 APIs. For the - purpose of backwards compatibility, the CLI packaged in - ``python-keystoneclient`` is not being removed. - -.. _`python-openstackclient`: http://docs.openstack.org/developer/python-openstackclient/ -.. _`python-keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/ - -Authenticating with a Token ---------------------------- - -.. NOTE:: - - If your Keystone deployment is brand new, you will need to use this - authentication method, along with your ``[DEFAULT] admin_token``. - -To authenticate with Keystone using a token and ``python-openstackclient``, set -the following flags. - -* ``--os-url OS_URL``: Keystone endpoint the user communicates with -* ``--os-token OS_TOKEN``: User's service token - -To administer a Keystone endpoint, your token should be either belong to a user -with the ``admin`` role, or, if you haven't created one yet, should be equal to -the value defined by ``[DEFAULT] admin_token`` in your ``keystone.conf``. - -You can also set these variables in your environment so that they do not need -to be passed as arguments each time: - -.. code-block:: bash - - $ export OS_URL=http://localhost:35357/v2.0 - $ export OS_TOKEN=ADMIN - -Instead of ``python-openstackclient``, if using ``python-keystoneclient``, set -the following: - -* ``--os-endpoint OS_SERVICE_ENDPOINT``: equivalent to ``--os-url OS_URL`` -* ``--os-service-token OS_SERVICE_TOKEN``: equivalent to - ``--os-token OS_TOKEN`` - - -Authenticating with a Password ------------------------------- - -To authenticate with Keystone using a password and ``python-openstackclient``, -set the following flags, note that the following user referenced below should -be granted the ``admin`` role. - -* ``--os-username OS_USERNAME``: Name of your user -* ``--os-password OS_PASSWORD``: Password for your user -* ``--os-project-name OS_PROJECT_NAME``: Name of your project -* ``--os-auth-url OS_AUTH_URL``: URL of the Keystone authentication server - -You can also set these variables in your environment so that they do not need -to be passed as arguments each time: - -.. code-block:: bash - - $ export OS_USERNAME=my_username - $ export OS_PASSWORD=my_password - $ export OS_PROJECT_NAME=my_project - $ export OS_AUTH_URL=http://localhost:35357/v2.0 - -If using ``python-keystoneclient``, set the following instead: - -* ``--os-tenant-name OS_TENANT_NAME``: equivalent to - ``--os-project-name OS_PROJECT_NAME`` - - -Example usage -------------- - -``python-openstackclient`` is set up to expect commands in the general form of: - -.. code-block:: bash - - $ openstack [<global-options>] <object-1> <action> [<object-2>] [<command-arguments>] - -For example, the commands ``user list`` and ``project create`` can be invoked -as follows: - -.. code-block:: bash - - # Using token authentication, with environment variables - $ export OS_URL=http://127.0.0.1:35357/v2.0/ - $ export OS_TOKEN=secrete_token - $ openstack user list - $ openstack project create demo - - # Using token authentication, with flags - $ openstack --os-token=secrete --os-url=http://127.0.0.1:35357/v2.0/ user list - $ openstack --os-token=secrete --os-url=http://127.0.0.1:35357/v2.0/ project create demo - - # Using password authentication, with environment variables - $ export OS_USERNAME=admin - $ export OS_PASSWORD=secrete - $ export OS_PROJECT_NAME=admin - $ export OS_AUTH_URL=http://localhost:35357/v2.0 - $ openstack user list - $ openstack project create demo - - # Using password authentication, with flags - $ openstack --os-username=admin --os-password=secrete --os-project-name=admin --os-auth-url=http://localhost:35357/v2.0 user list - $ openstack --os-username=admin --os-password=secrete --os-project-name=admin --os-auth-url=http://localhost:35357/v2.0 project create demo - -Removing Expired Tokens -======================= - -In the SQL backend expired tokens are not automatically removed. These tokens -can be removed with: - -.. code-block:: bash - - $ keystone-manage token_flush - -The memcache backend automatically discards expired tokens and so flushing is -unnecessary and if attempted will fail with a NotImplemented error. - - -Configuring the LDAP Identity Provider -====================================== - -As an alternative to the SQL Database backing store, Keystone can use a -directory server to provide the Identity service. An example Schema for -OpenStack would look like this:: - - dn: dc=openstack,dc=org - dc: openstack - objectClass: dcObject - objectClass: organizationalUnit - ou: openstack - - dn: ou=Projects,dc=openstack,dc=org - objectClass: top - objectClass: organizationalUnit - ou: groups - - dn: ou=Users,dc=openstack,dc=org - objectClass: top - objectClass: organizationalUnit - ou: users - - dn: ou=Roles,dc=openstack,dc=org - objectClass: top - objectClass: organizationalUnit - ou: roles - -The corresponding entries in the Keystone configuration file are: - -.. code-block:: ini - - [ldap] - url = ldap://localhost - user = dc=Manager,dc=openstack,dc=org - password = badpassword - suffix = dc=openstack,dc=org - use_dumb_member = False - allow_subtree_delete = False - - user_tree_dn = ou=Users,dc=openstack,dc=org - user_objectclass = inetOrgPerson - -The default object classes and attributes are intentionally simplistic. They -reflect the common standard objects according to the LDAP RFCs. However, in a -live deployment, the correct attributes can be overridden to support a -preexisting, more complex schema. For example, in the user object, the -objectClass posixAccount from RFC2307 is very common. If this is the underlying -objectclass, then the *uid* field should probably be *uidNumber* and *username* -field either *uid* or *cn*. To change these two fields, the corresponding -entries in the Keystone configuration file are: - -.. code-block:: ini - - [ldap] - user_id_attribute = uidNumber - user_name_attribute = cn - - -There is a set of allowed actions per object type that you can modify depending -on your specific deployment. For example, the users are managed by another tool -and you have only read access, in such case the configuration is: - -.. code-block:: ini - - [ldap] - user_allow_create = False - user_allow_update = False - user_allow_delete = False - -There are some configuration options for filtering users, tenants and roles, if -the backend is providing too much output, in such case the configuration will -look like: - -.. code-block:: ini - - [ldap] - user_filter = (memberof=CN=openstack-users,OU=workgroups,DC=openstack,DC=org) - -In case that the directory server does not have an attribute enabled of type -boolean for the user, there is several configuration parameters that can be -used to extract the value from an integer attribute like in Active Directory: - -.. code-block:: ini - - [ldap] - user_enabled_attribute = userAccountControl - user_enabled_mask = 2 - user_enabled_default = 512 - -In this case the attribute is an integer and the enabled attribute is listed in -bit 1, so the if the mask configured *user_enabled_mask* is different from 0, -it gets the value from the field *user_enabled_attribute* and it makes an ADD -operation with the value indicated on *user_enabled_mask* and if the value -matches the mask then the account is disabled. - -It also saves the value without mask to the user identity in the attribute -*enabled_nomask*. This is needed in order to set it back in case that we need -to change it to enable/disable a user because it contains more information than -the status like password expiration. Last setting *user_enabled_mask* is needed -in order to create a default value on the integer attribute (512 = NORMAL -ACCOUNT on AD) - -In case of Active Directory the classes and attributes could not match the -specified classes in the LDAP module so you can configure them like: - -.. code-block:: ini - - [ldap] - user_objectclass = person - user_id_attribute = cn - user_name_attribute = cn - user_description_attribute = displayName - user_mail_attribute = mail - user_enabled_attribute = userAccountControl - user_enabled_mask = 2 - user_enabled_default = 512 - user_attribute_ignore = tenant_id,tenants - -Debugging LDAP --------------- - -For additional information on LDAP connections, performance (such as slow -response time), or field mappings, setting ``debug_level`` in the [ldap] -section is used to enable debugging: - -.. code-block:: ini - - debug_level = 4095 - -This setting in turn sets OPT_DEBUG_LEVEL in the underlying python library. -This field is a bit mask (integer), and the possible flags are documented in -the OpenLDAP manpages. Commonly used values include 255 and 4095, with 4095 -being more verbose. - -.. WARNING:: - Enabling ``debug_level`` will negatively impact performance. - -Enabled Emulation ------------------ - -Some directory servers do not provide any enabled attribute. For these servers, -the ``user_enabled_emulation`` attribute has been created. It is enabled by -setting the respective flags to True. Then the attribute -``user_enabled_emulation_dn`` may be set to specify how the enabled users are -selected. This attribute works by using a ``groupOfNames`` entry and adding -whichever users or that you want enabled to the respective group with the -``member`` attribute. For example, this will mark any user who is a member of -``enabled_users`` as enabled: - -.. code-block:: ini - - [ldap] - user_enabled_emulation = True - user_enabled_emulation_dn = cn=enabled_users,cn=groups,dc=openstack,dc=org - -The default values for user enabled emulation DN is -``cn=enabled_users,$user_tree_dn``. - - -If a different LDAP schema is used for group membership, it is possible to use -the ``group_objectclass`` and ``group_member_attribute`` attributes to -determine membership in the enabled emulation group by setting the -``user_enabled_emulation_use_group_config`` attribute to True. - -Secure Connection ------------------ - -If you are using a directory server to provide the Identity service, it is -strongly recommended that you utilize a secure connection from Keystone to the -directory server. In addition to supporting LDAP, Keystone also provides -Transport Layer Security (TLS) support. There are some basic configuration -options for enabling TLS, identifying a single file or directory that contains -certificates for all the Certificate Authorities that the Keystone LDAP client -will recognize, and declaring what checks the client should perform on server -certificates. This functionality can easily be configured as follows: - -.. code-block:: ini - - [ldap] - use_tls = True - tls_cacertfile = /etc/keystone/ssl/certs/cacert.pem - tls_cacertdir = /etc/keystone/ssl/certs/ - tls_req_cert = demand - -A few points worth mentioning regarding the above options. If both -tls_cacertfile and tls_cacertdir are set then tls_cacertfile will be used and -tls_cacertdir is ignored. Furthermore, valid options for tls_req_cert are -demand, never, and allow. These correspond to the standard options permitted by -the TLS_REQCERT TLS option. - -Read Only LDAP --------------- - -Many environments typically have user and group information in directories that -are accessible by LDAP. This information is for read-only use in a wide array -of applications. Prior to the Havana release, we could not deploy Keystone with -read-only directories as backends because Keystone also needed to store -information such as projects, roles, domains and role assignments into the -directories in conjunction with reading user and group information. - -Keystone now provides an option whereby these read-only directories can be -easily integrated as it now enables its identity entities (which comprises -users, groups, and group memberships) to be served out of directories while -resource (which comprises projects and domains), assignment and role -entities are to be served from different Keystone backends (i.e. SQL). To -enable this option, you must have the following ``keystone.conf`` options set: - -.. code-block:: ini - - [identity] - driver = ldap - - [resource] - driver = sql - - [assignment] - driver = sql - - [role] - driver = sql - -With the above configuration, Keystone will only lookup identity related -information such users, groups, and group membership from the directory, while -resources, roles and assignment related information will be provided by the SQL -backend. Also note that if there is an LDAP Identity, and no resource, -assignment or role backend is specified, they will default to LDAP. Although -this may seem counter intuitive, it is provided for backwards compatibility. -Nonetheless, the explicit option will always override the implicit option, so -specifying the options as shown above will always be correct. Finally, it is -also worth noting that whether or not the LDAP accessible directory is to be -considered read only is still configured as described in a previous section -above by setting values such as the following in the ``[ldap]`` configuration -section: - -.. code-block:: ini - - [ldap] - user_allow_create = False - user_allow_update = False - user_allow_delete = False - -.. NOTE:: - - While having identity related information backed by LDAP while other - information is backed by SQL is a supported configuration, as shown above; - the opposite is not true. If either resource or assignment drivers are - configured for LDAP, then Identity must also be configured for LDAP. - -Connection Pooling ------------------- - -Various LDAP backends in Keystone use a common LDAP module to interact with -LDAP data. By default, a new connection is established for each LDAP operation. -This can become highly expensive when TLS support is enabled, which is a likely -configuration in an enterprise setup. Reuse of connectors from a connection -pool drastically reduces overhead of initiating a new connection for every LDAP -operation. - -Keystone provides connection pool support via configuration. This will keep -LDAP connectors alive and reused for subsequent LDAP operations. The connection -lifespan is configurable as other pooling specific attributes. - -In the LDAP identity driver, Keystone authenticates end users via an LDAP bind -with the user's DN and provided password. This kind of authentication bind -can fill up the pool pretty quickly, so a separate pool is provided for end -user authentication bind calls. If a deployment does not want to use a pool for -those binds, then it can disable pooling selectively by setting -``use_auth_pool`` to false. If a deployment wants to use a pool for those -authentication binds, then ``use_auth_pool`` needs to be set to true. For the -authentication pool, a different pool size (``auth_pool_size``) and connection -lifetime (``auth_pool_connection_lifetime``) can be specified. With an enabled -authentication pool, its connection lifetime should be kept short so that the -pool frequently re-binds the connection with the provided credentials and works -reliably in the end user password change case. When ``use_pool`` is false -(disabled), then the authentication pool configuration is also not used. - -Connection pool configuration is part of the ``[ldap]`` configuration section: - -.. code-block:: ini - - [ldap] - # Enable LDAP connection pooling. (boolean value) - use_pool=false - - # Connection pool size. (integer value) - pool_size=10 - - # Maximum count of reconnect trials. (integer value) - pool_retry_max=3 - - # Time span in seconds to wait between two reconnect trials. - # (floating point value) - pool_retry_delay=0.1 - - # Connector timeout in seconds. Value -1 indicates indefinite wait for - # response. (integer value) - pool_connection_timeout=-1 - - # Connection lifetime in seconds. (integer value) - pool_connection_lifetime=600 - - # Enable LDAP connection pooling for end user authentication. If use_pool - # is disabled, then this setting is meaningless and is not used at all. - # (boolean value) - use_auth_pool=false - - # End user auth connection pool size. (integer value) - auth_pool_size=100 - - # End user auth connection lifetime in seconds. (integer value) - auth_pool_connection_lifetime=60 - -Specifying Multiple LDAP servers --------------------------------- - -Multiple LDAP server URLs can be provided to keystone to provide -high-availability support for a single LDAP backend. To specify multiple LDAP -servers, simply change the ``url`` option in the ``[ldap]`` section. The new -option should list the different servers, each separated by a comma. For -example: - -.. code-block:: ini - - [ldap] - url = "ldap://localhost,ldap://backup.localhost" diff --git a/keystone-moon/doc/source/configure_federation.rst b/keystone-moon/doc/source/configure_federation.rst deleted file mode 100644 index 644d3175..00000000 --- a/keystone-moon/doc/source/configure_federation.rst +++ /dev/null @@ -1,383 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may not - use this file except in compliance with the License. You may obtain a copy - of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=================================== -Configuring Keystone for Federation -=================================== - ------------ -Definitions ------------ -* `Service Provider (SP)`: provides a service to an end-user. -* `Identity Provider (IdP)`: service that stores information about users and - groups. -* `SAML assertion`: contains information about a user as provided by an IdP. - ------------------------------------ -Keystone as a Service Provider (SP) ------------------------------------ - -.. NOTE:: - - This feature is considered stable and supported as of the Juno release. - -Prerequisites -------------- - -This approach to federation supports keystone as a Service Provider, consuming -identity properties issued by an external Identity Provider, such as SAML -assertions or OpenID Connect claims. - -Federated users are not mirrored in the keystone identity backend -(for example, using the SQL driver). The external Identity Provider is -responsible for authenticating users, and communicates the result of -authentication to keystone using identity properties. Keystone maps these -values to keystone user groups and assignments created in keystone. - -The following configuration steps were performed on a machine running -Ubuntu 12.04 and Apache 2.2.22. - -To enable federation, you'll need to: - -1. Run keystone under Apache, rather than using ``keystone-all``. -2. Configure Apache to use a federation capable authentication method. -3. Configure ``federation`` in keystone. - -Configure Apache to use a federation capable authentication method -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There is currently support for two major federation protocols: - -* SAML - Keystone supports the following implementations: - - * Shibboleth - see `Setup Shibboleth`_. - * Mellon - see `Setup Mellon`_. - -* OpenID Connect - see `Setup OpenID Connect`_. - -.. _`Setup Shibboleth`: federation/shibboleth.html -.. _`Setup OpenID Connect`: federation/openidc.html -.. _`Setup Mellon`: federation/mellon.html - -Configure keystone and Horizon for Single Sign-On -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* To configure horizon to access a federated keystone, - follow the steps outlined at: `Keystone Federation and Horizon`_. - -.. _`Keystone Federation and Horizon`: federation/websso.html - -Configuring Federation in Keystone ------------------------------------ - -Now that the Identity Provider and keystone are communicating we can start to -configure ``federation``. - -1. Configure authentication drivers in ``keystone.conf`` -2. Add local keystone groups and roles -3. Add Identity Provider(s), Mapping(s), and Protocol(s) - -Configure authentication drivers in ``keystone.conf`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. NOTE:: - ``saml2`` has been deprecated as of the Mitaka release. Support for the - ``saml2`` wrapper will be removed as of the "O" release. The recommended authentication method - is ``mapped``, which supports ``saml2``. - -Add the authentication methods to the ``[auth]`` section in ``keystone.conf``. -Names should be equal to protocol names added via Identity API v3. Here we use -examples ``mapped`` and ``openid``. - -.. code-block:: bash - - [auth] - methods = external,password,token,mapped,openid - -Create keystone groups and assign roles -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As mentioned earlier, no new users will be added to the Identity backend, but -the Identity Service requires group-based role assignments to authorize -federated users. The federation mapping function will map the user into local -Identity Service groups objects, and hence to local role assignments. - -Thus, it is required to create the necessary Identity Service groups that -correspond to the Identity Provider's groups; additionally, these groups should -be assigned roles on one or more projects or domains. - -You may be interested in more information on `group management -<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3.html#create-group>`_ -and `role assignments -<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3.html#grant-role-to-group-on-project>`_, -both of which are exposed to the CLI via `python-openstackclient -<https://pypi.python.org/pypi/python-openstackclient/>`_. - -Add Identity Provider(s), Mapping(s), and Protocol(s) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To utilize federation the following must be created in the Identity Service: - -* Identity Provider -* Mapping -* Protocol - -More information on ``federation in keystone`` can be found `here -<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html>`__. - -~~~~~~~~~~~~~~~~~ -Identity Provider -~~~~~~~~~~~~~~~~~ - -Create an Identity Provider object in keystone, which represents the Identity -Provider we will use to authenticate end users. - -More information on identity providers can be found `here -<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#register-an-identity-provider>`__. - -~~~~~~~ -Mapping -~~~~~~~ -A mapping is a list of rules. The only Identity API objects that will support mapping are groups -and users. - -Mapping adds a set of rules to map federation protocol attributes to Identity API objects. -There are many different ways to setup as well as combine these rules. More information on -rules can be found on the :doc:`mapping_combinations` page. - -An Identity Provider has exactly one mapping specified per protocol. -Mapping objects can be used multiple times by different combinations of Identity Provider and Protocol. - -More information on mapping can be found `here -<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#create-a-mapping>`__. - -~~~~~~~~ -Protocol -~~~~~~~~ - -A protocol contains information that dictates which Mapping rules to use for an incoming -request made by an IdP. An IdP may have multiple supported protocols. - -Add `Protocol object -<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#add-a-protocol-and-attribute-mapping-to-an-identity-provider>`__ and specify the mapping id -you want to use with the combination of the IdP and Protocol. - -Performing federated authentication ------------------------------------ - -1. Authenticate externally and generate an unscoped token in keystone -2. Determine accessible resources -3. Get a scoped token - -Get an unscoped token -~~~~~~~~~~~~~~~~~~~~~ - -Unlike other authentication methods in the Identity Service, the user does not -issue an HTTP POST request with authentication data in the request body. To -start federated authentication a user must access the dedicated URL with -Identity Provider's and Protocol's identifiers stored within a protected URL. -The URL has a format of: -``/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth``. - -In this instance we follow a standard SAML2 authentication procedure, that is, -the user will be redirected to the Identity Provider's authentication webpage -and be prompted for credentials. After successfully authenticating the user -will be redirected to the Service Provider's endpoint. If using a web browser, -a token will be returned in XML format. - -In the returned unscoped token, a list of Identity Service groups the user -belongs to will be included. - -More information on getting an unscoped token can be found `here -<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#authenticating>`__. - -~~~~~~~~~~~~ -Example cURL -~~~~~~~~~~~~ - -Note that the request does not include a body. The following url would be -considered protected by ``mod_shib`` and Apache, as such a request made -to the URL would be redirected to the Identity Provider, to start the -SAML authentication procedure. - -.. code-block:: bash - - $ curl -X GET -D - http://localhost:5000/v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/auth - -Determine accessible resources -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By using the previously returned token, the user can issue requests to the list -projects and domains that are accessible. - -* List projects a federated user can access: ``GET /OS-FEDERATION/projects`` -* List domains a federated user can access: ``GET /OS-FEDERATION/domains`` - -More information on listing resources can be found `here -<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#listing-projects-and-domains>`__. - -~~~~~~~~~~~~ -Example cURL -~~~~~~~~~~~~ - -.. code-block:: bash - - $ curl -X GET -H "X-Auth-Token: <unscoped token>" http://localhost:5000/v3/OS-FEDERATION/projects - -or - -.. code-block:: bash - - $ curl -X GET -H "X-Auth-Token: <unscoped token>" http://localhost:5000/v3/OS-FEDERATION/domains - -Get a scoped token -~~~~~~~~~~~~~~~~~~ - -A federated user may request a scoped token, by using the unscoped token. A -project or domain may be specified by either ``id`` or ``name``. An ``id`` is -sufficient to uniquely identify a project or domain. - -More information on getting a scoped token can be found `here -<http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#request-a-scoped-os-federation-token>`__. - -~~~~~~~~~~~~ -Example cURL -~~~~~~~~~~~~ - -.. code-block:: bash - - $ curl -X POST -H "Content-Type: application/json" -d '{"auth":{"identity":{"methods":["mapped"],"saml2":{"id":"<unscoped_token_id>"}},"scope":{"project":{"domain": {"name": "Default"},"name":"service"}}}}' -D - http://localhost:5000/v3/auth/tokens - --------------------------------------- -Keystone as an Identity Provider (IdP) --------------------------------------- - -.. NOTE:: - - This feature is experimental and unsupported in Juno (with several issues - that will not be backported). These issues have been fixed and this feature - is considered stable and supported as of the Kilo release. - -.. NOTE:: - - This feature requires installation of the xmlsec1 tool via your - distribution packaging system (for instance apt or yum) - - Example for apt: - - .. code-block:: bash - - $ apt-get install xmlsec1 - -Configuration Options ---------------------- - -There are certain settings in ``keystone.conf`` that must be setup, prior to -attempting to federate multiple keystone deployments. - -Within ``keystone.conf``, assign values to the ``[saml]`` related fields, for -example: - -.. code-block:: ini - - [saml] - certfile=/etc/keystone/ssl/certs/ca.pem - keyfile=/etc/keystone/ssl/private/cakey.pem - idp_entity_id=https://keystone.example.com/v3/OS-FEDERATION/saml2/idp - idp_sso_endpoint=https://keystone.example.com/v3/OS-FEDERATION/saml2/sso - idp_metadata_path=/etc/keystone/saml2_idp_metadata.xml - -Though not necessary, the follow Organization configuration options should -also be setup. It is recommended that these values be URL safe. - -.. code-block:: ini - - idp_organization_name=example_company - idp_organization_display_name=Example Corp. - idp_organization_url=example.com - -As with the Organization options, the Contact options, are not necessary, but -it's advisable to set these values too. - -.. code-block:: ini - - idp_contact_company=example_company - idp_contact_name=John - idp_contact_surname=Smith - idp_contact_email=jsmith@example.com - idp_contact_telephone=555-55-5555 - idp_contact_type=technical - -Generate Metadata ------------------ - -In order to create a trust between the IdP and SP, metadata must be exchanged. -To create metadata for your keystone IdP, run the ``keystone-manage`` command -and pipe the output to a file. For example: - -.. code-block:: bash - - $ keystone-manage saml_idp_metadata > /etc/keystone/saml2_idp_metadata.xml - -.. NOTE:: - The file location should match the value of the configuration option - ``idp_metadata_path`` that was assigned in the previous section. - -Create a Service Provider (SP) ------------------------------- - -In this example we are creating a new Service Provider with an ID of ``BETA``, -a ``sp_url`` of ``http://beta.example.com/Shibboleth.sso/SAML2/ECP`` and a -``auth_url`` of ``http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth`` -. The ``sp_url`` will be used when creating a SAML assertion for ``BETA`` and -signed by the current keystone IdP. The ``auth_url`` is used to retrieve the -token for ``BETA`` once the SAML assertion is sent. Although the ``enabled`` -field is optional we are passing it set to ``true`` otherwise it will be set to -``false`` by default. - -.. code-block:: bash - - $ curl -s -X PUT \ - -H "X-Auth-Token: $OS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"service_provider": {"auth_url": "http://beta.example.com:5000/v3/OS-FEDERATION/identity_providers/beta/protocols/saml2/auth", "sp_url": "https://example.com:5000/Shibboleth.sso/SAML2/ECP", "enabled": true}}' \ - http://localhost:5000/v3/OS-FEDERATION/service_providers/BETA | python -mjson.tool - -Testing it all out ------------------- - -Lastly, if a scoped token and a Service Provider scope are presented to the -local keystone, the result will be a full ECP wrapped SAML Assertion, -specifically intended for the Service Provider keystone. - -.. NOTE:: - ECP stands for Enhanced Client or Proxy, an extension from the SAML2 - protocol used in non-browser interfaces, like in the following example - with cURL. - -.. code-block:: bash - - $ curl -s -X POST \ - -H "Content-Type: application/json" \ - -d '{"auth": {"scope": {"service_provider": {"id": "BETA"}}, "identity": {"token": {"id": "d793d935b9c343f783955cf39ee7dc3c"}, "methods": ["token"]}}}' \ - http://localhost:5000/v3/auth/OS-FEDERATION/saml2/ecp - -.. NOTE:: - Use URL http://localhost:5000/v3/auth/OS-FEDERATION/saml2 to request for - pure SAML Assertions. - -At this point the ECP wrapped SAML Assertion can be sent to the Service -Provider keystone using the provided ``auth_url`` in the ``X-Auth-Url`` header -present in the response containing the Assertion, and a valid OpenStack -token, issued by a Service Provider keystone, will be returned. - diff --git a/keystone-moon/doc/source/configure_tokenless_x509.rst b/keystone-moon/doc/source/configure_tokenless_x509.rst deleted file mode 100644 index 614b1179..00000000 --- a/keystone-moon/doc/source/configure_tokenless_x509.rst +++ /dev/null @@ -1,328 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may not - use this file except in compliance with the License. You may obtain a copy - of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================================================ -Configuring Keystone for Tokenless Authorization -================================================ - -.. NOTE:: - - This feature is experimental and unsupported in Liberty. - ------------ -Definitions ------------ - -* `X.509 Tokenless Authorization`: Provides a means to authorize client - operations within Keystone by using an X.509 SSL client certificate - without having to issue a token. For details, please refer to the specs - `Tokenless Authorization with X.509 Client SSL Certificate`_ - -.. _`Tokenless Authorization with X.509 Client SSL Certificate`: http://specs.openstack.org/openstack/keystone-specs/specs/liberty/keystone-tokenless-authz-with-x509-ssl-client-cert.html - -Prerequisites -------------- - -Keystone must be running in a web container with https enabled; tests have -been done with Apache/2.4.7 running on Ubuntu 14.04 . Please refer to -`running-keystone-in-httpd`_ and `apache-certificate-and-key-installation`_ -as references for this setup. - -.. _`running-keystone-in-httpd`: http://docs.openstack.org/developer/keystone/apache-httpd.html -.. _`apache-certificate-and-key-installation`: https://www.digitalocean.com/community/tutorials/how-to-create-a-ssl-certificate-on-apache-for-ubuntu-14-04 - --------------------- -Apache Configuration --------------------- - -To enable X.509 tokenless authorization, SSL has to be enabled and configured -in the Apache virtual host file. The Client authentication attribute -``SSLVerifyClient`` should be set as ``optional`` to allow other token -authentication methods and attribute ``SSLOptions`` needs to set as -``+StdEnvVars`` to allow certificate attributes to be passed. The following -is the sample virtual host file used for the testing. - -.. code-block:: ini - - <VirtualHost *:443> - WSGIScriptAlias / /var/www/cgi-bin/keystone/main - ErrorLog /var/log/apache2/keystone.log - LogLevel debug - CustomLog /var/log/apache2/access.log combined - SSLEngine on - SSLCertificateFile /etc/apache2/ssl/apache.cer - SSLCertificateKeyFile /etc/apache2/ssl/apache.key - SSLCACertificatePath /etc/apache2/capath - SSLOptions +StdEnvVars - SSLVerifyClient optional - </VirtualHost> - ----------------------- -Keystone Configuration ----------------------- - -The following options can be defined in `keystone.conf`: - -* ``trusted_issuer`` - The multi-str list of trusted issuers to further - filter the certificates that are allowed to participate in the X.509 - tokenless authorization. If the option is absent then no certificates - will be allowed. The naming format for the attributes of a Distinguished - Name(DN) must be separated by a comma and contain no spaces; however - spaces are allowed for the value of an attribute, like 'L=San Jose' in - the example below. This configuration option may be repeated for multiple - values. Please look at the sample below. -* ``protocol`` - The protocol name for the X.509 tokenless authorization - along with the option `issuer_attribute` below can look up its - corresponding mapping. It defaults to ``x509``. -* ``issuer_attribute`` - The issuer attribute that is served as an IdP ID for - the X.509 tokenless authorization along with the protocol to look up its - corresponding mapping. It is the environment variable in the WSGI - environment that references to the Issuer of the client certificate. It - defaults to ``SSL_CLIENT_I_DN``. - -This is a sample configuration for two `trusted_issuer` and a `protocol` set -to ``x509``. - -.. code-block:: ini - - [tokenless_auth] - trusted_issuer = emailAddress=mary@abc.com,CN=mary,OU=eng,O=abc,L=San Jose,ST=California,C=US - trusted_issuer = emailAddress=john@openstack.com,CN=john,OU=keystone,O=openstack,L=Sunnyvale,ST=California,C=US - protocol = x509 - -------------- -Setup Mapping -------------- - -Like federation, X.509 tokenless authorization also utilizes the mapping -mechanism to formulate an identity. The identity provider must correspond -to the issuer of the X.509 SSL client certificate. The protocol for the -given identity is ``x509`` by default, but can be configurable. - -Create an Identity Provider(IdP) --------------------------------- - -In order to create an IdP, the issuer DN in the client certificate needs -to be provided. The following sample is what a generic issuer DN looks -like in a certificate. - -.. code-block:: ini - - E=john@openstack.com - CN=john - OU=keystone - O=openstack - L=Sunnyvale - S=California - C=US - -The issuer DN should be constructed as a string that contains no spaces -and have the right order separated by commas like the example below. -Please be aware that ``emailAddress`` and ``ST`` should be used instead -of ``E`` and ``S`` that are shown in the above example. The following is -the sample Python code used to create the IdP ID. - -.. code-block:: python - - import hashlib - issuer_dn = 'emailAddress=john@openstack.com,CN=john,OU=keystone, - O=openstack,L=Sunnyvale,ST=California,C=US' - hashed_idp = hashlib.sha256(issuer_dn) - idp_id = hashed_idp.hexdigest() - print(idp_id) - -The output of the above Python code will be the IdP ID and the following -sample curl command should be sent to keystone to create an IdP with the -newly generated IdP ID. - -.. code-block:: bash - - curl -k -s -X PUT -H "X-Auth-Token: <TOKEN>" \ - -H "Content-Type: application/json" \ - -d '{"identity_provider": {"description": "Stores keystone IDP identities.","enabled": true}}' \ - https://<HOSTNAME>:<PORT>/v3/OS-FEDERATION/identity_providers/<IdP ID> - -Create a Map ------------- - -A mapping needs to be created to map the ``Subject DN`` in the client -certificate as a user to yield a valid local user if the user's ``type`` -defined as ``local`` in the mapping. For example, the client certificate -has ``Subject DN`` as ``CN=alex,OU=eng,O=nice-network,L=Sunnyvale, -ST=California,C=US``, in the following examples, ``user_name`` will be -mapped to``alex`` and ``domain_name`` will be mapped to ``nice-network``. -And it has user's ``type`` set to ``local``. If user's ``type`` is not -defined, it defaults to ``ephemeral``. - -Please refer to `mod_ssl`_ for the detailed mapping attributes. - -.. _`mod_ssl`: http://httpd.apache.org/docs/current/mod/mod_ssl.html - -.. code-block:: javascript - - { - "mapping": { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}", - "domain": { - "name": "{1}" - }, - "type": "local" - } - } - ], - "remote": [ - { - "type": "SSL_CLIENT_S_DN_CN" - }, - { - "type": "SSL_CLIENT_S_DN_O" - } - ] - } - ] - } - } - -When user's ``type`` is not defined or set to ``ephemeral``, the mapped user -does not have to be a valid local user but the mapping must yield at least -one valid local group. For example: - -.. code-block:: javascript - - { - "mapping": { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}", - "type": "ephemeral" - } - }, - { - "group": { - "id": "12345678" - } - } - ], - "remote": [ - { - "type": "SSL_CLIENT_S_DN_CN" - } - ] - } - ] - } - } - -The following sample curl command should be sent to keystone to create a -mapping with the provided mapping ID. The mapping ID is user designed and -it can be any string as opposed to IdP ID. - -.. code-block:: bash - - curl -k -s -H "X-Auth-Token: <TOKEN>" \ - -H "Content-Type: application/json" \ - -d '{"mapping": {"rules": [{"local": [{"user": {"name": "{0}","type": "ephemeral"}},{"group": {"id": "<GROUPID>"}}],"remote": [{"type": "SSL_CLIENT_S_DN_CN"}]}]}}' \ - -X PUT https://<HOSTNAME>:<PORT>/v3/OS-FEDERATION/mappings/<MAPPING ID> - - -Create a Protocol ------------------ - -The name of the protocol will be the one defined in `keystone.conf` as -``protocol`` which defaults to ``x509``. The protocol name is user designed -and it can be any name as opposed to IdP ID. - -A protocol name and an IdP ID will uniquely identify a mapping. - -The following sample curl command should be sent to keystone to create a -protocol with the provided protocol name that is defined in `keystone.conf`. - -.. code-block:: bash - - curl -k -s -H "X-Auth-Token: <TOKEN>" \ - -H "Content-Type: application/json" \ - -d '{"protocol": {"mapping_id": "<MAPPING ID>"}}' \ - -X PUT https://<HOSTNAME>:<PORT>/v3/OS-FEDERATION/identity_providers/<IdP ID>/protocols/<PROTOCOL NAME> - -------------------------------- -Setup ``auth_token`` middleware -------------------------------- - -In order to use ``auth_token`` middleware as the service client for X.509 -tokenless authorization, both configurable options and scope information -will need to be setup. - -Configurable Options --------------------- - -The following configurable options in ``auth_token`` middleware -should set to the correct values: - -* ``auth_protocol`` - Set to ``https``. -* ``certfile`` - Set to the full path of the certificate file. -* ``keyfile`` - Set to the full path of the private key file. -* ``cafile`` - Set to the full path of the trusted CA certificate file. - -Scope Information ------------------ - -The scope information will be passed from the headers with the following -header attributes to: - -* ``X-Project-Id`` - If specified, its the project scope. -* ``X-Project-Name`` - If specified, its the project scope. -* ``X-Project-Domain-Id`` - If specified, its the domain of project scope. -* ``X-Project-Domain-Name`` - If specified, its the domain of project scope. -* ``X-Domain-Id`` - If specified, its the domain scope. -* ``X-Domain-Name`` - If specified, its the domain scope. - ---------------------- -Test It Out with cURL ---------------------- - -Once the above configurations have been setup, the following curl command can -be used for token validation. - -.. code-block:: bash - - curl -v -k -s -X GET --cert /<PATH>/x509client.crt \ - --key /<PATH>/x509client.key \ - --cacert /<PATH>/ca.crt \ - -H "X-Project-Name: <PROJECT-NAME>" \ - -H "X-Project-Domain-Id: <PROJECT-DOMAIN-ID>" \ - -H "X-Subject-Token: <TOKEN>" \ - https://<HOST>:<PORT>/v3/auth/tokens | python -mjson.tool - -Details of the Options ----------------------- - -* ``--cert`` - The client certificate that will be presented to Keystone. - The ``Issuer`` in the certificate along with the defined ``protocol`` - in `keystone.conf` will uniquely identify the mapping. The ``Subject`` - in the certificate will be mapped to the valid local user from the - identified mapping. -* ``--key`` - The corresponding client private key. -* ``--cacert`` - It can be the Apache server certificate or its issuer - (signer) certificate. -* ``X-Project-Name`` - The project scope needs to be passed in the header. -* ``X-Project-Domain-Id`` - Its the domain of project scope. -* ``X-Subject-Token`` - The token to be validated. - diff --git a/keystone-moon/doc/source/configuringservices.rst b/keystone-moon/doc/source/configuringservices.rst deleted file mode 100644 index 40fe03a2..00000000 --- a/keystone-moon/doc/source/configuringservices.rst +++ /dev/null @@ -1,234 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -========================================== -Configuring Services to work with Keystone -========================================== - -.. toctree:: - :maxdepth: 1 - -Once Keystone is installed and running (see :doc:`configuration`), services -need to be configured to work with it. To do this, we primarily install and -configure middleware for the OpenStack service to handle authentication tasks -or otherwise interact with Keystone. - -In general: - -* Clients making calls to the service will pass in an authentication token. -* The Keystone middleware will look for and validate that token, taking the - appropriate action. -* It will also retrieve additional information from the token such as user - name, user id, project name, project id, roles, etc... - -The middleware will pass those data down to the service as headers. More -details on the architecture of that setup is described in the -`authentication middleware documentation`_. - -Setting up credentials with ``keystone-manage bootstrap`` -========================================================= - -Setting up projects, users, and roles -------------------------------------- - -The ``keystone-manage bootstrap`` command will create a user, project and role, -and will assign the newly created role to the newly created user on the newly -created project. By default, the names of these new resources will be called -``admin``. - -The defaults may be overridden by calling ``--bootstrap-username``, -``--bootstrap-project-name`` and ``--bootstrap-role-name``. Each of these have -an environment variable equivalent: ``OS_BOOTSTRAP_USERNAME``, -``OS_BOOTSTRAP_PROJECT_NAME`` and ``OS_BOOTSTRAP_ROLE_NAME``. - -A user password must also be supplied. This can be passed in as either -``--bootstrap-password``, or set as an environment variable using -``OS_BOOTSTRAP_PASSWORD``. - -Optionally, if specified by ``--bootstrap-public-url``, -``--bootstrap-admin-url`` and/or ``--bootstrap-internal-url`` or the equivalent -environment variables, the command will create an identity service with the -specified endpoint information. You may also configure the -``--bootstrap-region-id`` and ``--bootstrap-service-name`` for the endpoints to -your deployment's requirements. - -.. NOTE:: - - It is strongly encouraged to configure the identity service and its - endpoints while bootstrapping keystone. - -Minimally, keystone can be bootstrapped with: - -.. code-block:: bash - - $ keystone-manage bootstrap --bootstrap-password s3cr3t - -Verbosely, keystone can be bootstrapped with: - -.. code-block:: bash - - $ keystone-manage bootstrap --bootstrap-password s3cr3t - --bootstrap-username admin \ - --bootstrap-project-name admin \ - --bootstrap-role-name admin \ - --bootstrap-service-name keystone \ - --bootstrap-region-id RegionOne \ - --bootstrap-admin-url http://localhost:35357 \ - --bootstrap-public-url http://localhost:5000 \ - --bootstrap-internal-url http://localhost:5000 - -This will create an ``admin`` user with the ``admin`` role on the ``admin`` -project. The user will have the password specified in the command. Note that -both the user and the project will be created in the ``default`` domain. By not -creating an endpoint in the catalog users will need to provide endpoint -overrides to perform additional identity operations. - -By creating an ``admin`` user and an identity endpoint deployers may -authenticate to keystone and perform identity operations like creating -additional services and endpoints using that ``admin`` user. This will preclude -the need to ever use or configure the ``admin_token`` (described below). - -To test a proper configuration, a user can use OpenStackClient CLI: - -.. code-block:: bash - - $ openstack project list --os-username admin --os-project-name admin \ - --os-user-domain-id default --os-project-domain-id default \ - --os-identity-api-version 3 --os-auth-url http://localhost:5000 \ - --os-password s3cr3t - -Setting up credentials with Admin Token -======================================= - -Admin Token ------------ - -For a default installation of Keystone, before you can use the REST API, you -need to define an authorization token. This is configured in ``keystone.conf`` -file under the section ``[DEFAULT]``. In the sample file provided with the -Keystone project, the line defining this token is:: - - [DEFAULT] - admin_token = ADMIN - -A "shared secret" that can be used to bootstrap Keystone. This token does not -represent a user, and carries no explicit authorization. -To disable in production (highly recommended), remove AdminTokenAuthMiddleware -from your paste application pipelines (for example, in keystone-paste.ini) - -Setting up projects, users, and roles -------------------------------------- - -You need to minimally define a project, user, and role to link the project and -user as the most basic set of details to get other services authenticating -and authorizing with Keystone. - -You will also want to create service users for nova, glance, swift, etc. to -be able to use to authenticate users against Keystone. The ``auth_token`` -middleware supports using either the shared secret described above as -`admin_token` or users for each service. - -See :doc:`configuration` for a walk through on how to create projects, users, -and roles. - -Setting up services -=================== - -Creating Service Users ----------------------- - -To configure the OpenStack services with service users, we need to create -a project for all the services, and then users for each of the services. We -then assign those service users an ``admin`` role on the service project. This -allows them to validate tokens - and to authenticate and authorize other user -requests. - -Create a project for the services, typically named ``service`` (however, the -name can be whatever you choose): - -.. code-block:: bash - - $ openstack project create service - -Create service users for ``nova``, ``glance``, ``swift``, and ``neutron`` -(or whatever subset is relevant to your deployment): - -.. code-block:: bash - - $ openstack user create nova --password Sekr3tPass --project service - -Repeat this for each service you want to enable. - -Create an administrative role for the service accounts, typically named -``admin`` (however the name can be whatever you choose). For adding the -administrative role to the service accounts, you'll need to know the -name of the role you want to add. If you don't have it handy, you can look it -up quickly with: - -.. code-block:: bash - - $ openstack role list - -Once you have it, grant the administrative role to the service users. This is -all assuming that you've already created the basic roles and settings as -described in :doc:`configuration`: - -.. code-block:: bash - - $ openstack role add admin --project service --user nova - -Defining Services ------------------ - -Keystone also acts as a service catalog to let other OpenStack systems know -where relevant API endpoints exist for OpenStack Services. The OpenStack -Dashboard, in particular, uses this heavily - and this **must** be configured -for the OpenStack Dashboard to properly function. - -The endpoints for these services are defined in a template, an example of -which is in the project as the file ``etc/default_catalog.templates``. - -Keystone supports two means of defining the services, one is the catalog -template, as described above - in which case everything is detailed in that -template. - -The other is a SQL backend for the catalog service, in which case after -Keystone is online, you need to add the services to the catalog: - -.. code-block:: bash - - $ openstack service create compute --name nova \ - --description "Nova Compute Service" - $ openstack service create ec2 --name ec2 \ - --description "EC2 Compatibility Layer" - $ openstack service create image --name glance \ - --description "Glance Image Service" - $ openstack service create identity --name keystone \ - --description "Keystone Identity Service" - $ openstack service create object-store --name swift \ - --description "Swift Service" - - -Setting Up Auth-Token Middleware -================================ - -The Keystone project provides the auth-token middleware which validates that -the request is valid before passing it on to the application. This must be -installed and configured in the applications (such as Nova, Glance, Swift, -etc.). The `authentication middleware documentation`_ describes how to install -and configure this middleware. - -.. _`authentication middleware documentation`: http://docs.openstack.org/developer/keystonemiddleware/middlewarearchitecture.html diff --git a/keystone-moon/doc/source/developing.rst b/keystone-moon/doc/source/developing.rst deleted file mode 100644 index d49d1e14..00000000 --- a/keystone-moon/doc/source/developing.rst +++ /dev/null @@ -1,902 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======================== -Developing with Keystone -======================== - -Setup ------ - -Get your development environment set up according to -:doc:`devref/development.environment`. It is recommended that you install -Keystone into a virtualenv. - - -Configuring Keystone --------------------- - -Keystone requires a configuration file. There is a sample configuration file -that can be used to get started: - -.. code-block:: bash - - $ cp etc/keystone.conf.sample etc/keystone.conf - -The defaults are enough to get you going, but you can make any changes if -needed. - - -Running Keystone ----------------- - -To run the Keystone Admin and API server instances, use: - -.. code-block:: bash - - $ keystone-all - -This runs Keystone with the configuration the etc/ directory of the project. -See :doc:`configuration` for details on how Keystone is configured. By default, -Keystone is configured with SQL backends. - - -Interacting with Keystone -------------------------- - -You can interact with Keystone through the command line using -:doc:`man/keystone-manage` which allows you to initialize keystone, etc. - -You can also interact with Keystone through its REST API. There is a Python -Keystone client library `python-keystoneclient`_ which interacts exclusively -through the REST API, and which Keystone itself uses to provide its -command-line interface. - -When initially getting set up, after you've configured which databases to use, -you're probably going to need to run the following to your database schema in -place: - -.. code-block:: bash - - $ keystone-manage db_sync - -.. _`python-keystoneclient`: https://git.openstack.org/cgit/openstack/python-keystoneclient -.. _`openstackclient`: https://git.openstack.org/cgit/openstack/python-openstackclient - -If the above commands result in a ``KeyError``, or they fail on a -``.pyc`` file with the message, ``You can only have one Python script per -version``, then it is possible that there are out-of-date compiled Python -bytecode files in the Keystone directory tree that are causing problems. This -can occur if you have previously installed and ran older versions of Keystone. -These out-of-date files can be easily removed by running a command like the -following from the Keystone root project directory: - -.. code-block:: bash - - $ find . -name "*.pyc" -delete - -Database Schema Migrations --------------------------- - -Keystone uses SQLAlchemy-migrate_ to migrate the SQL database between -revisions. For core components, the migrations are kept in a central -repository under ``keystone/common/sql/migrate_repo/versions``. Each -SQL migration has a version which can be identified by the name of -the script, the version is the number before the underline. -For example, if the script is named ``001_add_X_table.py`` then the -version of the SQL migration is ``1``. - -.. _SQLAlchemy-migrate: https://git.openstack.org/cgit/openstack/sqlalchemy-migrate - -For the migration to work, both the ``migrate_repo`` and ``versions`` -subdirectories must have ``__init__.py`` files. SQLAlchemy-migrate will look -for a configuration file in the ``migrate_repo`` named ``migrate.cfg``. This -conforms to a key/value `ini` file format. A sample configuration file with -the minimal set of values is:: - - [db_settings] - repository_id=my_extension - version_table=migrate_version - required_dbs=[] - -To run a migration for upgrade, simply run: - -.. code-block:: bash - - $ keystone-manage db_sync <version> - -.. NOTE:: - - If no version is specified, then the most recent migration will be used. - -.. NOTE:: - - Schema downgrades are not supported. - -.. _online-migration: - -From Mitaka release, we are starting to write the migration scripts in a -backward compatible way to support `online schema migration`_. The following -guidelines for schema and data migrations should be followed: - -* Additive schema migrations - In general, almost all schema migrations should - be additive. Put simply, they should only create elements like columns, - indices, and tables. - -* Subtractive schema migrations - To remove an element like a column or table: - - #. Expand phase: The element must be deprecated and retained for backward - compatibility. This allows for graceful upgrade from X release to X+1. - - #. Migrate phase: Data migration must completely migrate data from the old - version of the schema to the new version. Data migrations should have the - ability to run online, while the service is operating normally, so the - keystone service implementation (typically the SQLAlchemy model) has to - be aware that data should be retrieved and/or written from/to more than - one place and format, to maintain consistency (see examples below). - - #. Contract phase: The column can then be removed with a schema migration at - the start of X+2. Contract phase can't happen if the data migration isn't - finished (see last point in this section). - -* Release notes - There should be a release note in case an operation is - "blocking", "expensive", or both. You can find information on which DDL - operations are expensive in `MySQL docs`_. Other supported SQL DBs support - `transactional DDL`_, and experienced DBA's know to take advantage of this - feature. - -* Constraints - When adding a foreign or unique key constraint, the schema - migration code needs to handle possible problems with data before applying - the constraint. For example, a unique constraint must clean up duplicate - records before applying said constraint. - -* Data migrations - should be done in an online fashion by custom code in the - SQLAlchemy layer that handles moving data between the old and new portions - of the schema. In addition, for each type of data migration performed, - a keystone-manage command can be added for the operator to manually request - that rows be migrated (see examples below, like the nova flavor migration). - -* All schema migrations should be idempotent. For example, a migration - should check if an element exists in the schema before attempting to add - it. This logic comes for free in the autogenerated workflow of - the online migrations. - -* Before running `contract` in the expand/migrate/contract schema migration - workflow, the remaining data migrations should be performed by the contract - script. Alternatively, running a relevant keystone-manage migration should - be enforced, to ensure that all remaining data migrations are completed. - It is a good practice to move data out of the old columns, and ensure they - are filled with null values before removing them. - -A good example of an online schema migration is documented in a `cinder spec`_. -See more examples in :doc:`online_schema_migration_examples`. - -.. _`online schema migration`: https://specs.openstack.org/openstack/keystone-specs/specs/mitaka/online-schema-migration.html -.. _`MySQL docs`: https://dev.mysql.com/doc/refman/5.7/en/innodb-create-index-overview.html -.. _`transactional DDL`: https://wiki.postgresql.org/wiki/Transactional_DDL_in_PostgreSQL:_A_Competitive_Analysis -.. _`cinder spec`: https://specs.openstack.org/openstack/cinder-specs/specs/mitaka/online-schema-upgrades.html - - -Initial Sample Data -------------------- - -There is an included script which is helpful in setting up some initial sample -data for use with keystone: - -.. code-block:: bash - - $ OS_TOKEN=ADMIN tools/sample_data.sh - -Notice it requires a service token read from an environment variable for -authentication. The default value "ADMIN" is from the ``admin_token`` -option in the ``[DEFAULT]`` section in ``etc/keystone.conf``. - -Once run, you can see the sample data that has been created by using the -`openstackclient`_ command-line interface: - -.. code-block:: bash - - $ openstack --os-token ADMIN --os-url http://127.0.0.1:35357/v2.0/ user list - -The `openstackclient`_ can be installed using the following: - -.. code-block:: bash - - $ pip install python-openstackclient - -Filtering responsibilities between controllers and drivers ----------------------------------------------------------- - -Keystone supports the specification of filtering on list queries as part of the -v3 identity API. By default these queries are satisfied in the controller -class when a controller calls the ``wrap_collection`` method at the end of a -``list_{entity}`` method. However, to enable optimum performance, any driver -can implement some or all of the specified filters (for example, by adding -filtering to the generated SQL statements to generate the list). - -The communication of the filter details between the controller level and its -drivers is handled by the passing of a reference to a Hints object, -which is a list of dicts describing the filters. A driver that satisfies a -filter must delete the filter from the Hints object so that when it is returned -to the controller level, it knows to only execute any unsatisfied -filters. - -The contract for a driver for ``list_{entity}`` methods is therefore: - -* It MUST return a list of entities of the specified type -* It MAY either just return all such entities, or alternatively reduce the - list by filtering for one or more of the specified filters in the passed - Hints reference, and removing any such satisfied filters. An exception to - this is that for identity drivers that support domains, then they should - at least support filtering by domain_id. - -Entity list truncation by drivers ---------------------------------- - -Keystone supports the ability for a deployment to restrict the number of -entries returned from ``list_{entity}`` methods, typically to prevent poorly -formed searches (e.g. without sufficient filters) from becoming a performance -issue. - -These limits are set in the configuration file, either for a specific driver or -across all drivers. These limits are read at the Manager level and passed into -individual drivers as part of the Hints list object. A driver should try and -honor any such limit if possible, but if it is unable to do so then it may -ignore it (and the truncation of the returned list of entities will happen at -the controller level). - -Identity entity ID management between controllers and drivers -------------------------------------------------------------- - -Keystone supports the option of having domain-specific backends for the -identity driver (i.e. for user and group storage), allowing, for example, -a different LDAP server for each domain. To ensure that Keystone can determine -to which backend it should route an API call, starting with Juno, the -identity manager will, provided that domain-specific backends are enabled, -build on-the-fly a persistent mapping table between Keystone Public IDs that -are presented to the controller and the domain that holds the entity, along -with whatever local ID is understood by the driver. This hides, for instance, -the LDAP specifics of whatever ID is being used. - -To ensure backward compatibility, the default configuration of either a -single SQL or LDAP backend for Identity will not use the mapping table, -meaning that public facing IDs will be the unchanged. If keeping these IDs -the same for the default LDAP backend is not required, then setting the -configuration variable ``backward_compatible_ids`` to ``False`` will enable -the mapping for the default LDAP driver, hence hiding the LDAP specifics of the -IDs being used. - -Testing -------- - -Running Tests -============= - -Before running tests, you should have ``tox`` installed and available in your -environment (in addition to the other external dependencies in -:doc:`devref/development.environment`): - -.. code-block:: bash - - $ pip install tox - -.. NOTE:: - - You may need to perform both the above operation and the next inside a - python virtualenv, or prefix the above command with ``sudo``, depending on - your preference. - -To execute the full suite of tests maintained within Keystone, simply run: - -.. code-block:: bash - - $ tox - -This iterates over multiple configuration variations, and uses external -projects to do light integration testing to verify the Identity API against -other projects. - -.. NOTE:: - - The first time you run ``tox``, it will take additional time to build - virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild - your virtualenv in a similar manner. - -To run tests for one or more specific test environments (for example, the most -common configuration of Python 2.7 and PEP-8), list the environments with the -``-e`` option, separated by spaces: - -.. code-block:: bash - - $ tox -e py27,pep8 - -See ``tox.ini`` for the full list of available test environments. - -Running with PDB -~~~~~~~~~~~~~~~~ - -Using PDB breakpoints with tox and testr normally doesn't work since the tests -just fail with a BdbQuit exception rather than stopping at the breakpoint. - -To run with PDB breakpoints during testing, use the ``debug`` tox environment -rather than ``py27``. Here's an example, passing the name of a test since -you'll normally only want to run the test that hits your breakpoint: - -.. code-block:: bash - - $ tox -e debug keystone.tests.unit.test_auth.AuthWithToken.test_belongs_to - -For reference, the ``debug`` tox environment implements the instructions -here: https://wiki.openstack.org/wiki/Testr#Debugging_.28pdb.29_Tests - -Disabling Stream Capture -~~~~~~~~~~~~~~~~~~~~~~~~ - -The stdout, stderr and log messages generated during a test are captured and -in the event of a test failure those streams will be printed to the terminal -along with the traceback. The data is discarded for passing tests. - -Each stream has an environment variable that can be used to force captured -data to be discarded even if the test fails: `OS_STDOUT_CAPTURE` for stdout, -`OS_STDERR_CAPTURE` for stderr and `OS_LOG_CAPTURE` for logging. If the value -of the environment variable is not one of (True, true, 1, yes) the stream will -be discarded. All three variables default to 1. - -For example, to discard logging data during a test run: - -.. code-block:: bash - - $ OS_LOG_CAPTURE=0 tox -e py27 - -Test Structure -============== - -Not all of the tests in the keystone/tests/unit directory are strictly unit -tests. Keystone intentionally includes tests that run the service locally and -drives the entire configuration to achieve basic functional testing. - -For the functional tests, an in-memory key-value store or in-memory SQLite -database is used to keep the tests fast. - -Within the tests directory, the general structure of the backend tests is a -basic set of tests represented under a test class, and then subclasses of those -tests under other classes with different configurations to drive different -backends through the APIs. - -For example, ``test_backend.py`` has a sequence of tests under the class -:class:`~keystone.tests.unit.test_backend.IdentityTests` that will work with -the default drivers as configured in this project's etc/ directory. -``test_backend_sql.py`` subclasses those tests, changing the configuration by -overriding with configuration files stored in the ``tests/unit/config_files`` -directory aimed at enabling the SQL backend for the Identity module. - -:class:`keystone.tests.unit.test_v2_keystoneclient.ClientDrivenTestCase` -uses the installed python-keystoneclient, verifying it against a temporarily -running local keystone instance to explicitly verify basic functional testing -across the API. - -Testing Schema Migrations -========================= - -The application of schema migrations can be tested using SQLAlchemy Migrate’s -built-in test runner, one migration at a time. - -.. WARNING:: - - This may leave your database in an inconsistent state; attempt this in - non-production environments only! - -This is useful for testing the *next* migration in sequence (both forward & -backward) in a database under version control: - -.. code-block:: bash - - $ python keystone/common/sql/migrate_repo/manage.py test \ - --url=sqlite:///test.db \ - --repository=keystone/common/sql/migrate_repo/ - -This command references to a SQLite database (test.db) to be used. Depending on -the migration, this command alone does not make assertions as to the integrity -of your data during migration. - - -Writing Tests -============= - -To add tests covering all drivers, update the base test class in -``test_backend.py``. - -.. NOTE:: - - The structure of backend testing is in transition, migrating from having - all classes in a single file (test_backend.py) to one where there is a - directory structure to reduce the size of the test files. See: - - - :mod:`keystone.tests.unit.backend.role` - - :mod:`keystone.tests.unit.backend.domain_config` - -To add new drivers, subclass the ``test_backend.py`` (look towards -``test_backend_sql.py`` or ``test_backend_kvs.py`` for examples) and update the -configuration of the test class in ``setUp()``. - - -Further Testing -=============== - -devstack_ is the *best* way to quickly deploy Keystone with the rest of the -OpenStack universe and should be critical step in your development workflow! - -You may also be interested in either the -`OpenStack Continuous Integration Infrastructure`_ or the -`OpenStack Integration Testing Project`_. - -.. _devstack: http://docs.openstack.org/developer/devstack/ -.. _OpenStack Continuous Integration Infrastructure: http://docs.openstack.org/infra/system-config -.. _OpenStack Integration Testing Project: https://git.openstack.org/cgit/openstack/tempest - - -LDAP Tests -========== - -LDAP has a fake backend that performs rudimentary operations. If you -are building more significant LDAP functionality, you should test against -a live LDAP server. Devstack has an option to set up a directory server for -Keystone to use. Add ldap to the ``ENABLED_SERVICES`` environment variable, -and set environment variables ``KEYSTONE_IDENTITY_BACKEND=ldap`` and -``KEYSTONE_CLEAR_LDAP=yes`` in your ``localrc`` file. - -The unit tests can be run against a live server with -``keystone/tests/unit/test_ldap_livetest.py`` and -``keystone/tests/unit/test_ldap_pool_livetest.py``. The default password is -``test`` but if you have installed devstack with a different LDAP password, -modify the file ``keystone/tests/unit/config_files/backend_liveldap.conf`` and -``keystone/tests/unit/config_files/backend_pool_liveldap.conf`` to reflect your -password. - -.. NOTE:: - To run the live tests you need to set the environment variable - ``ENABLE_LDAP_LIVE_TEST`` to a non-negative value. - - -"Work in progress" Tests -======================== - -Work in progress (WIP) tests are very useful in a variety of situations -including: - -* During a TDD process they can be used to add tests to a review while - they are not yet working and will not cause test failures. (They should - be removed before the final merge.) -* Often bug reports include small snippets of code to show broken - behaviors. Some of these can be converted into WIP tests that can later - be worked on by a developer. This allows us to take code that can be - used to catch bug regressions and commit it before any code is - written. - -The :func:`keystone.tests.unit.utils.wip` decorator can be used to mark a test -as WIP. A WIP test will always be run. If the test fails then a TestSkipped -exception is raised because we expect the test to fail. We do not pass -the test in this case so that it doesn't count toward the number of -successfully run tests. If the test passes an AssertionError exception is -raised so that the developer knows they made the test pass. This is a -reminder to remove the decorator. - -The :func:`~keystone.tests.unit.utils.wip` decorator requires that the author -provides a message. This message is important because it will tell other -developers why this test is marked as a work in progress. Reviewers will -require that these messages are descriptive and accurate. - -.. NOTE:: - The :func:`~keystone.tests.unit.utils.wip` decorator is not a replacement for - skipping tests. - -.. code-block:: python - - @wip('waiting on bug #000000') - def test(): - pass - -.. NOTE:: - Another strategy is to not use the wip decorator and instead show how the - code currently incorrectly works. Which strategy is chosen is up to the - developer. - -Generating Updated Sample Config File -------------------------------------- - -Keystone's sample configuration file ``etc/keystone.conf.sample`` is automatically -generated based upon all of the options available within Keystone. These options -are sourced from the many files around Keystone as well as some external libraries. - -The sample configuration file is now kept up to date by an infra job that -generates the config file and if there are any changes will propose a review -as the OpenStack Proposal Bot. Developers should *NOT* generate the config file -and propose it as part of their patches since the proposal bot will do this for -you. - -To generate a new sample configuration to see what it looks like, run: - -.. code-block:: bash - - $ tox -egenconfig -r - -The tox command will place an updated sample config in ``etc/keystone.conf.sample``. - -If there is a new external library (e.g. ``oslo.messaging``) that utilizes the -``oslo.config`` package for configuration, it can be added to the list of libraries -found in ``config-generator/keystone.conf``. - - -Translated responses --------------------- - -The Keystone server can provide error responses translated into the language in -the ``Accept-Language`` header of the request. In order to test this in your -development environment, there's a couple of things you need to do. - -1. Build the message files. Run the following command in your keystone - directory: - -.. code-block:: bash - - $ python setup.py compile_catalog - -This will generate .mo files like keystone/locale/[lang]/LC_MESSAGES/[lang].mo - -2. When running Keystone, set the ``KEYSTONE_LOCALEDIR`` environment variable - to the keystone/locale directory. For example: - -.. code-block:: bash - - $ KEYSTONE_LOCALEDIR=/opt/stack/keystone/keystone/locale keystone-all - -Now you can get a translated error response: - -.. code-block:: bash - - $ curl -s -H "Accept-Language: zh" http://localhost:5000/notapath | python -mjson.tool - { - "error": { - "code": 404, - "message": "\u627e\u4e0d\u5230\u8cc7\u6e90\u3002", - "title": "Not Found" - } - } - - -Caching Layer -------------- - -The caching layer is designed to be applied to any ``manager`` object within Keystone -via the use of the ``on_arguments`` decorator provided in the ``keystone.common.cache`` -module. This decorator leverages `dogpile.cache`_ caching system to provide a flexible -caching backend. - -It is recommended that each of the managers have an independent toggle within the config -file to enable caching. The easiest method to utilize the toggle within the -configuration file is to define a ``caching`` boolean option within that manager's -configuration section (e.g. ``identity``). Once that option is defined you can -pass function to the ``on_arguments`` decorator with the named argument ``should_cache_fn``. -In the ``keystone.common.cache`` module, there is a function called ``should_cache_fn``, -which will provide a reference, to a function, that will consult the global cache -``enabled`` option as well as the specific manager's caching enable toggle. - - .. NOTE:: - If a section-specific boolean option is not defined in the config section specified when - calling ``should_cache_fn``, the returned function reference will default to enabling - caching for that ``manager``. - -Example use of cache and ``should_cache_fn`` (in this example, ``token`` is the manager): - -.. code-block:: python - - from keystone.common import cache - SHOULD_CACHE = cache.should_cache_fn('token') - - @cache.on_arguments(should_cache_fn=SHOULD_CACHE) - def cacheable_function(arg1, arg2, arg3): - ... - return some_value - -With the above example, each call to the ``cacheable_function`` would check to see if -the arguments passed to it matched a currently valid cached item. If the return value -was cached, the caching layer would return the cached value; if the return value was -not cached, the caching layer would call the function, pass the value to the ``SHOULD_CACHE`` -function reference, which would then determine if caching was globally enabled and enabled -for the ``token`` manager. If either caching toggle is disabled, the value is returned but -not cached. - -It is recommended that each of the managers have an independent configurable time-to-live (TTL). -If a configurable TTL has been defined for the manager configuration section, it is possible to -pass it to the ``cache.on_arguments`` decorator with the named-argument ``expiration_time``. For -consistency, it is recommended that this option be called ``cache_time`` and default to ``None``. -If the ``expiration_time`` argument passed to the decorator is set to ``None``, the expiration -time will be set to the global default (``expiration_time`` option in the ``[cache]`` -configuration section. - -Example of using a section specific ``cache_time`` (in this example, ``identity`` is the manager): - -.. code-block:: python - - from keystone.common import cache - SHOULD_CACHE = cache.should_cache_fn('identity') - - @cache.on_arguments(should_cache_fn=SHOULD_CACHE, - expiration_time=CONF.identity.cache_time) - def cachable_function(arg1, arg2, arg3): - ... - return some_value - -For cache invalidation, the ``on_arguments`` decorator will add an ``invalidate`` method -(attribute) to your decorated function. To invalidate the cache, you pass the same arguments -to the ``invalidate`` method as you would the normal function. - -Example (using the above cacheable_function): - -.. code-block:: python - - def invalidate_cache(arg1, arg2, arg3): - cacheable_function.invalidate(arg1, arg2, arg3) - -.. WARNING:: - The ``on_arguments`` decorator does not accept keyword-arguments/named arguments. An - exception will be raised if keyword arguments are passed to a caching-decorated function. - -.. NOTE:: - In all cases methods work the same as functions except if you are attempting to invalidate - the cache on a decorated bound-method, you need to pass ``self`` to the ``invalidate`` - method as the first argument before the arguments. - -.. _`dogpile.cache`: http://dogpilecache.readthedocs.org/ - - -dogpile.cache based Key-Value-Store (KVS) ------------------------------------------ -The ``dogpile.cache`` based KVS system has been designed to allow for flexible stores for the -backend of the KVS system. The implementation allows for the use of any normal ``dogpile.cache`` -cache backends to be used as a store. All interfacing to the KVS system happens via the -``KeyValueStore`` object located at ``keystone.common.kvs.KeyValueStore``. - -To utilize the KVS system an instantiation of the ``KeyValueStore`` class is needed. To acquire -a KeyValueStore instantiation use the ``keystone.common.kvs.get_key_value_store`` factory -function. This factory will either create a new ``KeyValueStore`` object or retrieve the -already instantiated ``KeyValueStore`` object by the name passed as an argument. The object must -be configured before use. The KVS object will only be retrievable with the -``get_key_value_store`` function while there is an active reference outside of the registry. -Once all references have been removed the object is gone (the registry uses a ``weakref`` to -match the object to the name). - -Example Instantiation and Configuration: - -.. code-block:: python - - kvs_store = kvs.get_key_value_store('TestKVSRegion') - kvs_store.configure('openstack.kvs.Memory', ...) - -Any keyword arguments passed to the configure method that are not defined as part of the -KeyValueStore object configuration are passed to the backend for further configuration (e.g. -memcached servers, lock_timeout, etc). - -The memcached backend uses the Keystone manager mechanism to support the use of any of the -provided memcached backends (``bmemcached``, ``pylibmc``, and basic ``memcached``). -By default the ``memcached`` backend is used. Currently the Memcache URLs come from the -``servers`` option in the ``[memcache]`` configuration section of the Keystone config. - -The following is an example showing how to configure the KVS system to use a -KeyValueStore object named "TestKVSRegion" and a specific Memcached driver: - -.. code-block:: python - - kvs_store = kvs.get_key_value_store('TestKVSRegion') - kvs_store.configure('openstack.kvs.Memcached', memcached_backend='Memcached') - -The memcached backend supports a mechanism to supply an explicit TTL (in seconds) to all keys -set via the KVS object. This is accomplished by passing the argument ``memcached_expire_time`` -as a keyword argument to the ``configure`` method. Passing the ``memcache_expire_time`` argument -will cause the ``time`` argument to be added to all ``set`` and ``set_multi`` calls performed by -the memcached client. ``memcached_expire_time`` is an argument exclusive to the memcached dogpile -backend, and will be ignored if passed to another backend: - -.. code-block:: python - - kvs_store.configure('openstack.kvs.Memcached', memcached_backend='Memcached', - memcached_expire_time=86400) - -If an explicit TTL is configured via the ``memcached_expire_time`` argument, it is possible to -exempt specific keys from receiving the TTL by passing the argument ``no_expiry_keys`` (list) -as a keyword argument to the ``configure`` method. ``no_expiry_keys`` should be supported by -all OpenStack-specific dogpile backends (memcached) that have the ability to set an explicit TTL: - -.. code-block:: python - - kvs_store.configure('openstack.kvs.Memcached', memcached_backend='Memcached', - memcached_expire_time=86400, no_expiry_keys=['key', 'second_key', ...]) - - -.. NOTE:: - For the non-expiring keys functionality to work, the backend must support the ability for - the region to set the key_mangler on it and have the attribute ``raw_no_expiry_keys``. - In most cases, support for setting the key_mangler on the backend is handled by allowing - the region object to set the ``key_mangler`` attribute on the backend. - - The ``raw_no_expiry_keys`` attribute is expected to be used to hold the values of the - keyword argument ``no_expiry_keys`` prior to hashing. It is the responsibility of the - backend to use these raw values to determine if a key should be exempt from expiring - and not set the TTL on the non-expiring keys when the ``set`` or ``set_multi`` methods are - called. - - Typically the key will be hashed by the region using its key_mangler method - before being passed to the backend to set the value in the KeyValueStore. This - means that in most cases, the backend will need to either pre-compute the hashed versions - of the keys (when the key_mangler is set) and store a cached copy, or hash each item in - the ``raw_no_expiry_keys`` attribute on each call to ``.set()`` and ``.set_multi()``. The - ``memcached`` backend handles this hashing and caching of the keys by utilizing an - ``@property`` method for the ``.key_mangler`` attribute on the backend and utilizing the - associated ``.settr()`` method to front-load the hashing work at attribute set time. - -Once a KVS object has been instantiated the method of interacting is the same as most memcache -implementations: - -.. code-block:: python - - kvs_store = kvs.get_key_value_store('TestKVSRegion') - kvs_store.configure(...) - # Set a Value - kvs_store.set(<Key>, <Value>) - # Retrieve a value: - retrieved_value = kvs_store.get(<key>) - # Delete a key/value pair: - kvs_store.delete(<key>) - # multi-get: - kvs_store.get_multi([<key>, <key>, ...]) - # multi-set: - kvs_store.set_multi(dict(<key>=<value>, <key>=<value>, ...)) - # multi-delete - kvs_store.delete_multi([<key>, <key>, ...]) - - -There is a global configuration option to be aware of (that can be set in the ``[kvs]`` section of -the Keystone configuration file): ``enable_key_mangler`` can be set top false, disabling the use of -key_manglers (modification of the key when saving to the backend to help prevent -collisions or exceeding key size limits with memcached). - -.. NOTE:: - The ``enable_key_mangler`` option in the ``[kvs]`` section of the Keystone configuration file - is not the same option (and does not affect the cache-layer key manglers) from the option in the - ``[cache]`` section of the configuration file. Similarly the ``[cache]`` section options - relating to key manglers has no bearing on the ``[kvs]`` objects. - -.. WARNING:: - Setting the ``enable_key_mangler`` option to False can have detrimental effects on the - KeyValueStore backend. It is recommended that this value is not set to False except for - debugging issues with the ``dogpile.cache`` backend itself. - -Any backends that are to be used with the ``KeyValueStore`` system need to be registered with -dogpile. For in-tree/provided backends, the registration should occur in -``keystone/common/kvs/__init__.py``. For backends that are developed out of tree, the location -should be added to the ``backends`` option in the ``[kvs]`` section of the Keystone configuration:: - - [kvs] - backends = backend_module1.backend_class1,backend_module2.backend_class2 - -All registered backends will receive the "short name" of "openstack.kvs.<class name>" for use in the -``configure`` method on the ``KeyValueStore`` object. The ``<class name>`` of a backend must be -globally unique. - -dogpile.cache based MongoDB (NoSQL) backend --------------------------------------------- - -The ``dogpile.cache`` based MongoDB backend implementation allows for various MongoDB -configurations, e.g., standalone, a replica set, sharded replicas, with or without SSL, -use of TTL type collections, etc. - -Example of typical configuration for MongoDB backend: - -.. code-block:: python - - from dogpile.cache import region - - arguments = { - 'db_hosts': 'localhost:27017', - 'db_name': 'ks_cache', - 'cache_collection': 'cache', - 'username': 'test_user', - 'password': 'test_password', - - # optional arguments - 'son_manipulator': 'my_son_manipulator_impl' - } - - region.make_region().configure('keystone.cache.mongo', - arguments=arguments) - -The optional `son_manipulator` is used to manipulate custom data type while its saved in -or retrieved from MongoDB. If the dogpile cached values contain built-in data types and no -custom classes, then the provided implementation class is sufficient. For further details, refer -http://api.mongodb.org/python/current/examples/custom_type.html#automatic-encoding-and-decoding - -Similar to other backends, this backend can be added via Keystone configuration in -``keystone.conf``:: - - [cache] - # Global cache functionality toggle. - enabled = True - - # Referring to specific cache backend - backend = keystone.cache.mongo - - # Backend specific configuration arguments - backend_argument = db_hosts:localhost:27017 - backend_argument = db_name:ks_cache - backend_argument = cache_collection:cache - backend_argument = username:test_user - backend_argument = password:test_password - -This backend is registered in ``keystone.common.cache.core`` module. So, its usage -is similar to other dogpile caching backends as it implements the same dogpile APIs. - - -Building the Documentation --------------------------- - -The documentation is generated with Sphinx using the tox command. To create HTML docs and man pages: - -.. code-block:: bash - - $ tox -e docs - -The results are in the doc/build/html and doc/build/man directories respectively. - - -Release Notes -------------- - -The release notes for a patch should be included in the patch. If not, the -release notes should be in a follow-on review. - -If the following applies to the patch, a release note is required: - -* The deployer needs to take an action when upgrading -* The backend driver interface changes -* A new feature is implemented -* Function was removed (hopefully it was deprecated) -* Current behavior is changed -* A new config option is added that the deployer should consider changing from - the default -* A security bug is fixed - -A release note is suggested if a long-standing or important bug is fixed. -Otherwise, a release note is not required. - -Keystone uses `reno <http://docs.openstack.org/developer/reno/usage.html>`_ to -generate release notes. Please read the docs for details. In summary, use - -.. code-block:: bash - - $ tox -e venv -- reno new <bug-,bp-,whatever> - -Then edit the sample file that was created and push it with your change. - -To see the results: - -.. code-block:: bash - - $ git commit # Commit the change because reno scans git log. - - $ tox -e releasenotes - -Then look at the generated release notes files in releasenotes/build/html in -your favorite browser. diff --git a/keystone-moon/doc/source/developing_drivers.rst b/keystone-moon/doc/source/developing_drivers.rst deleted file mode 100644 index 38cd7319..00000000 --- a/keystone-moon/doc/source/developing_drivers.rst +++ /dev/null @@ -1,130 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=========================== -Developing Keystone Drivers -=========================== - -A driver, also known as a backend, is an important architectural -component of Keystone. It is an abstraction around the data access -needed by a particular subsystem. This pluggable implementation is not -only how Keystone implements its own data access, but how you can -implement your own! - -Each major subsystem (that has data access needs) implements the data access -by using drivers. Some examples of Keystone's drivers: - -- :class:`keystone.identity.backends.ldap.Identity` -- :class:`keystone.token.providers.fernet.core.Provider` -- :class:`keystone.contrib.federation.backends.sql.Federation` - -In/Out of Tree --------------- - -It's best to start developing your custom driver outside of the Keystone -development process. This means developing it in your own public or private git -repository and not worrying about getting it upstream (for now). - -This is better for you because it gives you more freedom and you are not bound -to the strict OpenStack development rules or schedule. You can iterate faster -and take whatever shortcuts you need to get your product out of the door. - -This is also good for Keystone because it will limit the amount of drivers -that must be maintained by the team. If the team had to maintain a -driver for each NoSQL DB that deployers want to use in production there -would be less time to make Keystone itself better. Not to mention that -the team would have to start gaining expertise in potentially dozens of -new technologies. - -As you'll see below there is no penalty for open sourcing your driver, -on GitHub for example, or even keeping your implementation private. We -use `Setuptools entry points`_ to load your driver from anywhere in the -Python path. - -.. _Setuptools entry points: no good resource? - -How To Make a Driver --------------------- - -The TLDR; steps (and too long didn't write yet): - -1. Determine which subsystem you would like write a driver for -2. Subclass the most current version of the driver interface -3. Implement each of the abstract methods for that driver - - a. We are currently not documenting the exact input/outputs of the - driver methods. The best approach right now is to use an existing - driver as an example of what data your driver will receive and - what data your driver will be required to return. - b. There is a plan in place to document these APIs in more detail. - -4. Register your new driver as an entry point -5. Configure your new driver in ``keystone.conf`` -6. Sit back and enjoy! - -Driver Versioning ------------------ - -In the past the driver class was named ``Driver`` and changes would -sometimes be devastating to developers that depend on our driver -contracts. To help alleviate some of the issues we are now creating -version driver classes, e.g. ``DriverV8``. - -We'll be supporting the current driver version for at least one version back. -This gives developers a full cycle to update their drivers. Some cases, such -as critical security flaws, may require a change to be introduced that breaks -compatibility. These special cases will be communicated as widely as possible -via the typical OpenStack communication channels. - -As new driver interface versions are added old ones will be moved to a -"deprecated" state and will output deprecation messages when used. When a -driver version moves from "deprecated" to "unsupported" it will be -removed from the keystone source tree. - -Removing Methods -~~~~~~~~~~~~~~~~ - -Newer driver interfaces may remove methods that are currently required. -Methods are removed when they are no longer required or invoked by Keystone. -There is no reason why methods removed from the Keystone interface need to be -removed from custom drivers. - -Adding Methods --------------- - -The most common API changes will be adding method to support new -features. We'll do our best to add methods in a way that is backward -compatible. The new version of the driver will define the new method as -an ``abc.abstractmethod`` that must be implemented by driver -implementations. When possible we'll also go back to our supported drivers and -add the method, with a default implementation. - -For example, given a ``thing.DriverV8`` that added a new method -``list_things_by_name()``, we will go back to ``thing.DriverV7`` and -implement that method. This is good because in many cases your driver -will just work, but there are a couple of unfortunate side effects. -First if you have already used that method name you will have to rename -your method and cut a new version. Second is that the default -implementation may cause a performance penalty due to its naive -implementation. - -Updating Methods -~~~~~~~~~~~~~~~~ - -We will try not to update existing methods in ways that will break old -driver implementations. That means that: - -* We will respect existing parameters and not just delete them. If they are - to be removed we will respect their behavior and deprecate them in older - versions. -* We will add new parameters as optional with backward compatible defaults. diff --git a/keystone-moon/doc/source/devref/development.environment.rst b/keystone-moon/doc/source/devref/development.environment.rst deleted file mode 100644 index 2718966a..00000000 --- a/keystone-moon/doc/source/devref/development.environment.rst +++ /dev/null @@ -1,175 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============================================= -Setting up a Keystone development environment -============================================= - -This document describes getting the source from keystone's `Git repository`_ -for development purposes. - -To install Keystone from packaging, refer instead to Keystone's `User -Documentation`_. - -.. _`Git Repository`: http://git.openstack.org/cgit/openstack/keystone -.. _`User Documentation`: http://docs.openstack.org/ - -Prerequisites -============= - -This document assumes you are using Ubuntu, Fedora or openSUSE (SLE) - -And that you have the following tools available on your system: - -- Python_ 2.7 and 3.4 -- git_ -- setuptools_ -- pip_ -- msgfmt (part of the gettext package) -- virtualenv_ -- tox_ - -**Reminder**: If you're successfully using a different platform, or a -different version of the above, please document your configuration here! - -.. _Python: http://www.python.org/ -.. _git: http://git-scm.com/ -.. _setuptools: http://pypi.python.org/pypi/setuptools -.. _tox: https://pypi.python.org/pypi/tox - -Getting the latest code -======================= - -Make a clone of the code from our `Git repository`: - -.. code-block:: bash - - $ git clone https://git.openstack.org/openstack/keystone.git - -When that is complete, you can: - -.. code-block:: bash - - $ cd keystone - -Installing dependencies -======================= - -Keystone maintains two lists of dependencies:: - - requirements.txt - test-requirements.txt - -The first is the list of dependencies needed for running keystone, the second list includes dependencies used for active development and testing of Keystone itself. - -These dependencies can be installed from PyPi_ using the Python tool pip_. - -.. _PyPi: http://pypi.python.org/ -.. _pip: http://pypi.python.org/pypi/pip - -However, your system *may* need additional dependencies that `pip` (and by -extension, PyPi) cannot satisfy. These dependencies should be installed -prior to using `pip`, and the installation method may vary depending on -your platform. - -Ubuntu 14.04, 15.10: - -.. code-block:: bash - - $ sudo apt-get install python-dev python3-dev libxml2-dev libxslt1-dev \ - libsasl2-dev libsqlite3-dev libssl-dev libldap2-dev libffi-dev - - -Fedora 19+: - -.. code-block:: bash - - $ sudo yum install python-lxml python-greenlet-devel python-ldap \ - sqlite-devel openldap-devel python-devel libxslt-devel \ - openssl-devel libffi-devel - -openSUSE 13.2 (SLE 12): - -.. code-block:: bash - - $ sudo zypper install libxslt-devel openldap2-devel libopenssl-devel \ - python-devel python-greenlet-devel python-ldap python-lxml \ - python-pysqlite sqlite3-devel - -PyPi Packages and VirtualEnv ----------------------------- - -We recommend establishing a virtualenv to run Keystone within. virtualenv -limits the Python environment to just what you're installing as dependencies, -useful to keep a clean environment for working on Keystone. - -.. code-block:: bash - - $ tox -e venv --notest - -This will create a local virtual environment in the directory ``.tox``. -Once created, you can activate this virtualenv for your current shell using: - -.. code-block:: bash - - $ source .tox/venv/bin/activate - -The virtual environment can be disabled using the command: - -.. code-block:: bash - - $ deactivate - -You can also use ``tox -e venv`` to prefix commands so that they run -within the virtual environment. For more information on virtual environments, -see virtualenv_. - -.. _virtualenv: http://www.virtualenv.org/ - -If you want to run Keystone outside of a virtualenv, you can install the -dependencies directly into your system from the requirements files: - -.. code-block:: bash - - # Install the dependencies for running keystone - $ pip install -r requirements.txt - - # Install the dependencies for developing, testing, and running keystone - $ pip install -r test-requirements.txt - - # Use 'python setup.py' to link Keystone into Python's site-packages - $ python setup.py develop - - -Verifying Keystone is set up -============================ - -Once set up, either directly or within a virtualenv, you should be able to -invoke Python and import the libraries. If you're using a virtualenv, don't -forget to activate it: - -.. code-block:: bash - - $ source .tox/venv/bin/activate - -You should then be able to `import keystone` using Python without issue: - -.. code-block:: bash - - $ python -c "import keystone" - -If you can import Keystone without a traceback, you should be ready to move on -to :doc:`../developing`. diff --git a/keystone-moon/doc/source/event_notifications.rst b/keystone-moon/doc/source/event_notifications.rst deleted file mode 100644 index d9225c56..00000000 --- a/keystone-moon/doc/source/event_notifications.rst +++ /dev/null @@ -1,439 +0,0 @@ - -.. - Copyright 2013 IBM Corp. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============================ -Keystone Event Notifications -============================ - -Keystone provides notifications about usage data so that 3rd party applications -can use the data for billing, monitoring, or quota purposes. This document -describes the current inclusions and exclusions for Keystone notifications. - -Keystone currently supports two notification formats: a Basic Notification, -and a Cloud Auditing Data Federation (`CADF`_) Notification. -The supported operations between the two types of notification formats are -documented below. - -Common Notification Structure -============================= - -Notifications generated by Keystone are generated in JSON format. An external -application can format them into ATOM format and publish them as a feed. -Currently, all notifications are immediate, meaning they are generated when a -specific event happens. Notifications all adhere to a specific top level -format: - -.. code-block:: javascript - - { - "event_type": "identity.<resource_type>.<operation>", - "message_id": "<message_id>", - "payload": {}, - "priority": "INFO", - "publisher_id": "identity.<hostname>", - "timestamp": "<timestamp>" - } - -Where ``<resource_type>`` is a Keystone resource, such as user or project, and -``<operation>`` is a Keystone operation, such as created, deleted. - -The key differences between the two notification formats (Basic and CADF), lie -within the ``payload`` portion of the notification. - -The ``priority`` of the notification being sent is not configurable through -the Keystone configuration file. This value is defaulted to INFO for all -notifications sent in Keystone's case. - -Basic Notifications -=================== - -All basic notifications contain a limited amount of information, specifically, -just the resource type, operation, and resource id. - -The ``payload`` portion of a Basic Notification is a single key-value pair. - -.. code-block:: javascript - - { - "resource_info": <resource_id> - } - -Where ``<resource_id>`` is the unique identifier assigned to the -``resource_type`` that is undergoing the ``<operation>``. - -Supported Events ----------------- - -The following table displays the compatibility between resource types and -operations. - -======================== ================================= -resource type supported operations -======================== ================================= -group create, update, delete -project create, update, delete -role create, update, delete -domain create, update, delete -user create, update, delete -trust create, delete -region create, update, delete -endpoint create, update, delete -service create, update, delete -policy create, update, delete -======================== ================================= - -Note, ``trusts`` are an immutable resource, they do not support ``update`` -operations. - -Example Notification --------------------- - -This is an example of a notification sent for a newly created user: - -.. code-block:: javascript - - { - "event_type": "identity.user.created", - "message_id": "0156ee79-b35f-4cef-ac37-d4a85f231c69", - "payload": { - "resource_info": "671da331c47d4e29bb6ea1d270154ec3" - }, - "priority": "INFO", - "publisher_id": "identity.host1234", - "timestamp": "2013-08-29 19:03:45.960280" - } - -If the operation fails, the notification won't be sent, and no special error -notification will be sent. Information about the error is handled through -normal exception paths. - -Auditing with CADF -================== - -Keystone uses the `PyCADF`_ library to emit CADF notifications, these events -adhere to the DMTF `CADF`_ specification. This standard provides auditing -capabilities for compliance with security, operational, and business processes -and supports normalized and categorized event data for federation and -aggregation. - -.. _PyCADF: http://docs.openstack.org/developer/pycadf -.. _CADF: http://www.dmtf.org/standards/cadf - -CADF notifications include additional context data around the ``resource``, -the ``action`` and the ``initiator``. - -CADF notifications may be emitted by changing the ``notification_format`` to -``cadf`` in the configuration file. - -The ``payload`` portion of a CADF Notification is a CADF ``event``, which -is represented as a JSON dictionary. For example: - -.. code-block:: javascript - - { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "initiator": { - "typeURI": "service/security/account/user", - "host": { - "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", - "address": "127.0.0.1" - }, - "id": "<initiator_id>" - }, - "target": { - "typeURI": "<target_uri>", - "id": "openstack:1c2fc591-facb-4479-a327-520dade1ea15" - }, - "observer": { - "typeURI": "service/security", - "id": "openstack:3d4a50a9-2b59-438b-bf19-c231f9c7625a" - }, - "eventType": "activity", - "eventTime": "2014-02-14T01:20:47.932842+00:00", - "action": "<action>", - "outcome": "success", - "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f", - } - -Where the following are defined: - -* ``<initiator_id>``: ID of the user that performed the operation -* ``<target_uri>``: CADF specific target URI, (i.e.: data/security/project) -* ``<action>``: The action being performed, typically: - ``<operation>``. ``<resource_type>`` - -Additionally there may be extra keys present depending on the operation being -performed, these will be discussed below. - -Note, the ``eventType`` property of the CADF payload is different from the -``event_type`` property of a notifications. The former (``eventType``) is a -CADF keyword which designates the type of event that is being measured, this -can be: `activity`, `monitor` or `control`. Whereas the latter -(``event_type``) is described in previous sections as: -`identity.<resource_type>.<operation>` - -Supported Events ----------------- - -The following table displays the compatibility between resource types and -operations. - -====================== ============================= ============================= -resource type supported operations typeURI -====================== ============================= ============================= -group create, update, delete data/security/group -project create, update, delete data/security/project -role create, update, delete data/security/role -domain create, update, delete data/security/domain -user create, update, delete data/security/account/user -trust create, delete data/security/trust -region create, update, delete data/security/region -endpoint create, update, delete data/security/endpoint -service create, update, delete data/security/service -policy create, update, delete data/security/policy -role assignment add, remove data/security/account/user -None authenticate data/security/account/user -====================== ============================= ============================= - -Example Notification - Project Create -------------------------------------- - -The following is an example of a notification that is sent when a project is -created. This example can be applied for any ``create``, ``update`` or -``delete`` event that is seen in the table above. The ``<action>`` and -``typeURI`` fields will be change. - -The difference to note is the inclusion of the ``resource_info`` field which -contains the ``<resource_id>`` that is undergoing the operation. Thus creating -a common element between the CADF and Basic notification formats. - -.. code-block:: javascript - - { - "event_type": "identity.project.created", - "message_id": "0156ee79-b35f-4cef-ac37-d4a85f231c69", - "payload": { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "initiator": { - "typeURI": "service/security/account/user", - "host": { - "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", - "address": "127.0.0.1" - }, - "id": "c9f76d3c31e142af9291de2935bde98a" - }, - "target": { - "typeURI": "data/security/project", - "id": "openstack:1c2fc591-facb-4479-a327-520dade1ea15" - }, - "observer": { - "typeURI": "service/security", - "id": "openstack:3d4a50a9-2b59-438b-bf19-c231f9c7625a" - }, - "eventType": "activity", - "eventTime": "2014-02-14T01:20:47.932842+00:00", - "action": "created.project", - "outcome": "success", - "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f", - "resource_info": "671da331c47d4e29bb6ea1d270154ec3" - } - "priority": "INFO", - "publisher_id": "identity.host1234", - "timestamp": "2013-08-29 19:03:45.960280" - } - -Example Notification - Authentication -------------------------------------- - -The following is an example of a notification that is sent when a user -authenticates with Keystone. - -Note that this notification will be emitted if a user successfully -authenticates, and when a user fails to authenticate. - -.. code-block:: javascript - - { - "event_type": "identity.authenticate", - "message_id": "1371a590-d5fd-448f-b3bb-a14dead6f4cb", - "payload": { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "initiator": { - "typeURI": "service/security/account/user", - "host": { - "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", - "address": "127.0.0.1" - }, - "id": "c9f76d3c31e142af9291de2935bde98a" - }, - "target": { - "typeURI": "service/security/account/user", - "id": "openstack:1c2fc591-facb-4479-a327-520dade1ea15" - }, - "observer": { - "typeURI": "service/security", - "id": "openstack:3d4a50a9-2b59-438b-bf19-c231f9c7625a" - }, - "eventType": "activity", - "eventTime": "2014-02-14T01:20:47.932842+00:00", - "action": "authenticate", - "outcome": "success", - "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f" - }, - "priority": "INFO", - "publisher_id": "identity.host1234", - "timestamp": "2014-02-14T01:20:47.932842" - } - -Example Notification - Federated Authentication ------------------------------------------------ - -The following is an example of a notification that is sent when a user -authenticates with Keystone via Federation. - -This example is similar to the one seen above, however the ``initiator`` -portion of the ``payload`` contains a new ``credential`` section. - -.. code-block:: javascript - - { - "event_type": "identity.authenticate", - "message_id": "1371a590-d5fd-448f-b3bb-a14dead6f4cb", - "payload": { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "initiator": { - "credential": { - "type": "http://docs.oasis-open.org/security/saml/v2.0", - "token": "671da331c47d4e29bb6ea1d270154ec3", - "identity_provider": "ACME", - "user": "c9f76d3c31e142af9291de2935bde98a", - "groups": [ - "developers" - ] - }, - "typeURI": "service/security/account/user", - "host": { - "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", - "address": "127.0.0.1" - }, - "id": "c9f76d3c31e142af9291de2935bde98a" - }, - "target": { - "typeURI": "service/security/account/user", - "id": "openstack:1c2fc591-facb-4479-a327-520dade1ea15" - }, - "observer": { - "typeURI": "service/security", - "id": "openstack:3d4a50a9-2b59-438b-bf19-c231f9c7625a" - }, - "eventType": "activity", - "eventTime": "2014-02-14T01:20:47.932842+00:00", - "action": "authenticate", - "outcome": "success", - "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f" - }, - "priority": "INFO", - "publisher_id": "identity.host1234", - "timestamp": "2014-02-14T01:20:47.932842" - } - -Example Notification - Role Assignment --------------------------------------- - -The following is an example of a notification that is sent when a role is -granted or revoked to a project or domain, for a user or group. - -It is important to note that this type of notification has many new keys -that convey the necessary information. Expect the following in the ``payload``: -``role``, ``inherited_to_project``, ``project`` or ``domain``, ``user`` or -``group``. With the exception of ``inherited_to_project``, each will represent -the unique identifier of the resource type. - -.. code-block:: javascript - - { - "event_type": "identity.role_assignment.created", - "message_id": "a5901371-d5fd-b3bb-448f-a14dead6f4cb", - "payload": { - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "initiator": { - "typeURI": "service/security/account/user", - "host": { - "agent": "curl/7.22.0(x86_64-pc-linux-gnu)", - "address": "127.0.0.1" - }, - "id": "c9f76d3c31e142af9291de2935bde98a" - }, - "target": { - "typeURI": "service/security/account/user", - "id": "openstack:1c2fc591-facb-4479-a327-520dade1ea15" - }, - "observer": { - "typeURI": "service/security", - "id": "openstack:3d4a50a9-2b59-438b-bf19-c231f9c7625a" - }, - "eventType": "activity", - "eventTime": "2014-08-20T01:20:47.932842+00:00", - "role": "0e6b990380154a2599ce6b6e91548a68", - "project": "24bdcff1aab8474895dbaac509793de1", - "inherited_to_projects": false, - "group": "c1e22dc67cbd469ea0e33bf428fe597a", - "action": "created.role_assignment", - "outcome": "success", - "id": "openstack:f5352d7b-bee6-4c22-8213-450e7b646e9f" - }, - "priority": "INFO", - "publisher_id": "identity.host1234", - "timestamp": "2014-08-20T01:20:47.932842" - } - -Recommendations for consumers -============================= - -One of the most important notifications that Keystone emits is for project -deletions (``event_type`` = ``identity.project.deleted``). This event should -indicate to the rest of OpenStack that all resources (such as virtual machines) -associated with the project should be deleted. - -Projects can also have update events (``event_type`` = -``identity.project.updated``), wherein the project has been disabled. Keystone -ensures this has an immediate impact on the accessibility of the project's -resources by revoking tokens with authorization on the project, but should -**not** have a direct impact on the projects resources (in other words, virtual -machines should **not** be deleted). - -Opting out of certain notifications -=================================== - -There are many notifications that Keystone emits and some deployers may only -care about certain events. In Keystone there is a way to opt-out of certain -notifications. In ``/etc/keystone/keystone.conf`` you can set ``opt_out`` to -the event you wish to opt-out of. It is possible to opt-out of multiple events. - -Example: - -.. code-block:: ini - - [DEFAULT] - notification_opt_out = identity.user.created - notification_opt_out = identity.role_assignment.created - notification_opt_out = identity.authenticate.pending - -This will opt-out notifications for user creation, role assignment creation and -successful authentications. For a list of event types that can be used, refer -to: `Telemetry Measurements`_. - -.. _Telemetry Measurements: http://docs.openstack.org/admin-guide-cloud/telemetry-measurements.html#openstack-identity diff --git a/keystone-moon/doc/source/extension_development.rst b/keystone-moon/doc/source/extension_development.rst deleted file mode 100644 index 0805af40..00000000 --- a/keystone-moon/doc/source/extension_development.rst +++ /dev/null @@ -1,303 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -===================================== -Keystone Extensions Development Guide -===================================== - -General -======= - -This Extension Development Guide provides some mocked code to use as an -Extension code base in the ``keystone/contrib/example`` folder. - -- All Extensions must be created in the ``keystone/contrib`` folder. -- The new Extension code must be contained in a new folder under ``contrib``. -- Whenever possible an Extension should follow the following directory - structure convention:: - - keystone/contrib/ - └── my_extension -   ├── backends (optional) -   │  ├── __init__.py (mandatory) -   │  └── sql.py (optional) -   │  └── kvs.py (optional) -   ├── migrate_repo (optional) -   │  ├── __init__.py (mandatory) -   │  ├── migrate.cfg (mandatory) -   │  └── versions (mandatory) - │    ├── 001_create_tables.py (mandatory) - │    └── __init__.py (mandatory) -   ├── __init__.py (mandatory) -   ├── core.py (mandatory) -   ├── controllers.py (mandatory for API Extension) -   └── routers.py (mandatory for API Extension) - -- If the Extension implements an API Extension the ``controllers.py`` and - ``routers.py`` must be present and correctly handle the API Extension - requests and responses. -- If the Extension implements backends a ``backends`` folder should exist. - Backends are defined to store data persistently and can use a variety of - technologies. Please see the Backends section in this document for more info. -- If the Extension adds data structures, then a ``migrate_repo`` folder should - exist. -- If configuration changes are required/introduced in the - ``keystone.conf.sample`` file, these should be kept disabled as default and - have their own section. -- If configuration changes are required/introduced in the - ``keystone-paste.ini``, the new filter must be declared. -- The module may register to listen to events by declaring the corresponding - callbacks in the ``core.py`` file. -- The new extension should be disabled by default (it should not affect the - default application pipelines). - -Modifying the `keystone.conf.sample` File -========================================= - -In the case an Extension needs to change the ``keystone.conf.sample`` file, it -must follow the config file conventions and introduce a dedicated section. - -Example:: - - [example] - driver = sql - - [my_other_extension] - extension_flag = False - -The Extension parameters expressed should be commented out since, by default, -extensions are disabled. - -Example:: - - [example] - #driver = sql - - [my_other_extension] - #extension_flag = False - -In case the Extension is overriding or re-implementing an existing portion of -Keystone, the required change should be commented in the ``configuration.rst`` -but not placed in the `keystone.conf.sample` file to avoid unnecessary -confusion. - -Modifying the ``keystone-paste.ini`` File -========================================= - -In the case an Extension is augmenting a pipeline introducing a new ``filter`` -and/or APIs in the ``OS`` namespace, a corresponding ``filter:`` section is -necessary to be introduced in the ``keystone-paste.ini`` file. The Extension -should declare the filter factory constructor in the ``ini`` file. - -Example:: - - [filter:example] - paste.filter_factory = keystone.contrib.example.routers:ExampleRouter. - factory - -The ``filter`` must not be placed in the ``pipeline`` and treated as optional. -How to add the extension in the pipeline should be specified in detail in the -``configuration.rst`` file. - -Package Constructor File -======================== - -The ``__init__.py`` file represents the package constructor. Extension needs to -import what is necessary from the ``core.py`` module. - -Example: - -.. code-block:: python - - from keystone.contrib.example.core import * - -Core -==== - -The ``core.py`` file represents the main module defining the data structure and -interface. In the ``Model View Control`` (MVC) model it represents the -``Model`` part and it delegates to the ``Backends`` the data layer -implementation. - -In case the ``core.py`` file contains a ``Manager`` and a ``Driver`` it must -provide the dependency injections for the ``Controllers`` and/or other modules -using the ``Manager``. A good practice is to call the dependency -``extension_name_api``. - -Example: - -.. code-block:: python - - @dependency.provider('example_api') - class Manager(manager.Manager): - -Routers -======= - -``routers.py`` have the objective of routing the HTTP requests and direct them to -the correct method within the ``Controllers``. Extension routers are extending -the ``wsgi.ExtensionRouter``. - -Example: - -.. code-block:: python - - from keystone.common import wsgi - from keystone.contrib.example import controllers - - - class ExampleRouter(wsgi.ExtensionRouter): - - PATH_PREFIX = '/OS-EXAMPLE' - - def add_routes(self, mapper): - example_controller = controllers.ExampleV3Controller() - mapper.connect(self.PATH_PREFIX + '/example', - controller=example_controller, - action='do_something', - conditions=dict(method=['GET'])) - -Controllers -=========== - -``controllers.py`` have the objective of handing requests and implement the -Extension logic. Controllers are consumers of 'Managers' API and must have all -the dependency injections required. ``Controllers`` are extending the -``V3Controller`` class. - -Example: - -.. code-block:: python - - @dependency.requires('identity_api', 'example_api') - class ExampleV3Controller(controller.V3Controller): - pass - -Backends -======== - -The ``backends`` folder provides the model implementations for the different -backends supported by the Extension. See General above for an example directory -structure. - -If a SQL backend is provided, in the ``sql.py`` backend implementation it is -mandatory to define the new table(s) that the Extension introduces and the -attributes they are composed of. - -For more information on backends, refer to the `Keystone Architecture -<http://docs.openstack.org/developer/keystone/architecture.html>`_ -documentation. - -Example: - -.. code-block:: python - - class ExampleSQLBackend(sql.ModelBase, sql.DictBase): - """example table description.""" - __tablename__ = 'example_table' - attributes = ['id', 'type', 'extra'] - - example_id = sql.Column(sql.String(64), - primary_key=True, - nullable=False) - ... - -SQL Migration Repository -======================== - -In case the Extension is adding SQL data structures, these must be stored in -separate tables and must not be included in the ``migrate_repo`` of the core -Keystone. Please refer to the ``migrate.cfg`` file to configure the Extension -repository. - -In order to create the Extension tables and their attributes, a ``db_sync`` -command must be executed. - -Example: - -.. code-block:: bash - - $ ./bin/keystone-manage db_sync --extension example - -Event Callbacks ---------------- - -Extensions may provide callbacks to Keystone (Identity) events. -Extensions must provide the list of events of interest and the corresponding -callbacks. Events are issued upon successful creation, modification, and -deletion of the following Keystone resources: - -- ``group`` -- ``project`` -- ``role`` -- ``user`` - -The extension's ``Manager`` class must contain the -``event_callbacks`` attribute. It is a dictionary listing as keys -those events that are of interest and the values should be the respective -callbacks. Event callback registration is done via the -dependency injection mechanism. During dependency provider registration, the -``dependency.provider`` decorator looks for the ``event_callbacks`` -class attribute. If it exists the event callbacks are registered -accordingly. In order to enable event callbacks, the extension's ``Manager`` -class must also be a dependency provider. - -Example: - -.. code-block:: python - - # Since this is a dependency provider. Any code module using this or any - # other dependency provider (uses the dependency.provider decorator) - # will be enabled for the attribute based notification - - @dependency.provider('example_api') - class ExampleManager(manager.Manager): - """Example Manager. - - See :mod:`keystone.common.manager.Manager` for more details on - how this dynamically calls the backend. - - """ - - def __init__(self): - self.event_callbacks = { - # Here we add the event_callbacks class attribute that - # calls project_deleted_callback when a project is deleted. - 'deleted': { - 'project': [ - self.project_deleted_callback]}} - super(ExampleManager, self).__init__( - 'keystone.contrib.example.core.ExampleDriver') - - def project_deleted_callback(self, context, message): - # cleanup data related to the deleted project here - -A callback must accept the following parameters: - -- ``service`` - the service information (e.g. identity) -- ``resource_type`` - the resource type (e.g. project) -- ``operation`` - the operation (updated, created, deleted) -- ``payload`` - the actual payload info of the resource that was acted on - -Current callback operations: - -- ``created`` -- ``deleted`` -- ``updated`` - -Example: - -.. code-block:: python - - def project_deleted_callback(self, service, resource_type, operation, - payload): diff --git a/keystone-moon/doc/source/extensions.rst b/keystone-moon/doc/source/extensions.rst deleted file mode 100644 index 4d171f05..00000000 --- a/keystone-moon/doc/source/extensions.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -========== -Extensions -========== - -Status -====== - -An extension may be considered ``stable``, ``experimental`` or ``out-of-tree``. - -* A `stable` status indicates that an extension is fully supported by the - OpenStack Identity team. - -* An `experimental` status indicates that although the intention is to keep - the API unchanged, we reserve the right to change it up until the point that - it is deemed `stable`. - -* An `out-of-tree` status indicates that no formal support will be provided. - -Graduation Process -================== - -By default, major new functionality that is proposed to be in-tree will start -off in `experimental` status. Typically it would take at minimum of one cycle -to transition from `experimental` to `stable`, although in special cases this -might happened within a cycle. - -Removal Process -=============== - -It is not intended that functionality should stay in experimental for a long -period, functionality that stays `experimental` for more than **two** releases -would be expected to make a transition to either `stable` or `out-of-tree`. diff --git a/keystone-moon/doc/source/extensions/endpoint_filter.rst b/keystone-moon/doc/source/extensions/endpoint_filter.rst deleted file mode 100644 index 4ab194b8..00000000 --- a/keystone-moon/doc/source/extensions/endpoint_filter.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. - Copyright 2011-2013 OpenStack, Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -====================================== -Enabling the Endpoint Filter Extension -====================================== - -To enable the endpoint filter extension: - -1. Add the endpoint filter extension catalog driver to the ``[catalog]`` section - in ``keystone.conf``. For example:: - - [catalog] - driver = catalog_sql - -2. Add the ``endpoint_filter_extension`` filter to the ``api_v3`` pipeline in - ``keystone-paste.ini``. This must be added after ``json_body`` and before - the last entry in the pipeline. For example:: - - [pipeline:api_v3] - pipeline = sizelimit url_normalize build_auth_context token_auth admin_token_auth json_body ec2_extension_v3 s3_extension simple_cert_extension revoke_extension endpoint_filter_extension service_v3 - -3. Create the endpoint filter extension tables if using the provided sql backend. For example:: - - ./bin/keystone-manage db_sync --extension endpoint_filter - -4. Optionally, change ``return_all_endpoints_if_no_filter`` the ``[endpoint_filter]`` section - in ``keystone.conf`` to return an empty catalog if no associations are made. For example:: - - [endpoint_filter] - return_all_endpoints_if_no_filter = False diff --git a/keystone-moon/doc/source/extensions/endpoint_policy.rst b/keystone-moon/doc/source/extensions/endpoint_policy.rst deleted file mode 100644 index ad403d50..00000000 --- a/keystone-moon/doc/source/extensions/endpoint_policy.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -====================================== -Enabling the Endpoint Policy Extension -====================================== - -To enable the endpoint policy extension: - -1. Optionally, add the endpoint policy extension driver to the - ``[endpoint_policy]`` section in ``keystone.conf``. For example:: - - [endpoint_policy] - driver = sql - -2. Add the ``endpoint_policy_extension`` policy to the ``api_v3`` pipeline in - ``keystone-paste.ini``. This must be added after ``json_body`` and before - the last entry in the pipeline. For example:: - - [pipeline:api_v3] - pipeline = sizelimit url_normalize build_auth_context token_auth admin_token_auth json_body ec2_extension_v3 s3_extension simple_cert_extension revoke_extension service_v3 endpoint_policy_extension service_v3 - -3. Create the endpoint policy extension tables if using the provided SQL backend. For example:: - - ./bin/keystone-manage db_sync --extension endpoint_policy diff --git a/keystone-moon/doc/source/extensions/federation.rst b/keystone-moon/doc/source/extensions/federation.rst deleted file mode 100644 index f1b5baa9..00000000 --- a/keystone-moon/doc/source/extensions/federation.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. - Copyright 2014 OpenStack, Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================================== -Enabling the Federation Extension -================================== - -To enable the federation extension: - -1. Add the federation extension driver to the ``[federation]`` section in - ``keystone.conf``. For example:: - - [federation] - driver = keystone.contrib.federation.backends.sql.Federation - -2. Add the ``saml2`` and/or ``oidc`` authentication methods to the ``[auth]`` - section in ``keystone.conf``:: - - [auth] - methods = external,password,token,saml2,oidc - saml2 = keystone.auth.plugins.mapped.Mapped - oidc = keystone.auth.plugins.mapped.Mapped - -.. NOTE:: - The ``external`` method should be dropped to avoid any interference with - some Apache + Shibboleth SP setups, where a ``REMOTE_USER`` env variable is - always set, even as an empty value. - -3. Add the ``federation_extension`` middleware to the ``api_v3`` pipeline in - ``keystone-paste.ini``. This must be added after ``json_body`` and before - the last entry in the pipeline. For example:: - - [pipeline:api_v3] - pipeline = sizelimit url_normalize build_auth_context token_auth admin_token_auth json_body ec2_extension_v3 s3_extension simple_cert_extension revoke_extension federation_extension service_v3 - -4. Create the federation extension tables if using the provided SQL backend. - For example:: - - ./bin/keystone-manage db_sync --extension federation - -5. As of the Juno release, multiple Keystone deployments can now be federated. - To do so, the `pysaml2 <https://pypi.python.org/pypi/pysaml2>`_ library is - required. Since OS-FEDERATION is an extension, ``pysaml2`` is not installed - by default, it must be installed manually. For example:: - - pip install --upgrade $(grep pysaml2 test-requirements.txt) - - Also, the `xmlsec1` command line tool is needed to sign the SAML assertions - generated by the Keystone Identity Provider: - - .. code-block:: bash - - $ apt-get install xmlsec1 diff --git a/keystone-moon/doc/source/extensions/moon/ExceptionHierarchy-v0.2.pptx b/keystone-moon/doc/source/extensions/moon/ExceptionHierarchy-v0.2.pptx Binary files differdeleted file mode 100644 index a512a98b..00000000 --- a/keystone-moon/doc/source/extensions/moon/ExceptionHierarchy-v0.2.pptx +++ /dev/null diff --git a/keystone-moon/doc/source/extensions/moon/ExceptionHierarchy.pptx b/keystone-moon/doc/source/extensions/moon/ExceptionHierarchy.pptx Binary files differdeleted file mode 100644 index af18d231..00000000 --- a/keystone-moon/doc/source/extensions/moon/ExceptionHierarchy.pptx +++ /dev/null diff --git a/keystone-moon/doc/source/extensions/moon/moon.rst b/keystone-moon/doc/source/extensions/moon/moon.rst deleted file mode 100644 index f2b3b0bc..00000000 --- a/keystone-moon/doc/source/extensions/moon/moon.rst +++ /dev/null @@ -1,147 +0,0 @@ -.. - Copyright 2015 Orange - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============ -Moon backend -============ - -Before doing anything, you must test your installation and check that your infrastructure is working. -For example, check that you can create new virtual machines with admin and demo login. - -Configuration -------------- - -Moon is a contribute backend so you have to enable it by modifying /etc/keystone/keystone-paste.ini, like this: - -.. code-block:: ini - - [pipeline:moon_pipeline] - pipeline = sizelimit url_normalize request_id build_auth_context token_auth admin_token_auth json_body ec2_extension_v3 s3_extension moon_service - - [app:moon_service] - use = egg:keystone#moon_service - - ... - - [composite:main] - use = egg:Paste#urlmap - /moon = moon_pipeline - /v2.0 = public_api - /v3 = api_v3 - / = public_version_api - - [composite:admin] - use = egg:Paste#urlmap - /moon = moon_pipeline - /v2.0 = admin_api - /v3 = api_v3 - / = admin_version_api - - ... - -You must modify /etc/keystone/keystone.conf as you need (see at the end of the file) and copy the following directories: - -.. code-block:: sh - - cp -R /opt/stack/keystone/examples/moon/policies/ /etc/keystone/ - cp -R /opt/stack/keystone/examples/moon/super_extension/ /etc/keystone/ - -You can now update the Keystone database and create the directory for logs and restart the Keystone service: - -.. code-block:: sh - - cd /opt/stack/keystone - ./bin/keystone-manage db_sync --extension moon - sudo mkdir /var/log/moon/ - sudo chown vagrant /var/log/moon/ - sudo service apache2 restart - -You have to install our version of keystonemiddleware https://github.com/rebirthmonkey/keystonemiddleware : - -.. code-block:: sh - - cd - git clone https://github.com/rebirthmonkey/keystonemiddleware.git - cd keystonemiddleware - sudo python setup.py install - -At this time, the only method to configure Moon is to use the python-moonclient which is a console based client: - -.. code-block:: sh - - cd - git clone https://github.com/rebirthmonkey/moonclient.git - cd moonclient - sudo python setup.py install - -If afterwards, you have some problem restarting nova-api, try removing the package python-six: - -.. code-block:: sh - - sudo apt-get remove python-six - - -Nova must be configured to send request to Keystone, you have to modify /etc/nova/api-paste.ini : - -.. code-block:: ini - - ... - - [composite:openstack_compute_api_v2] - use = call:nova.api.auth:pipeline_factory - noauth = compute_req_id faultwrap sizelimit noauth ratelimit osapi_compute_app_v2 - noauth2 = compute_req_id faultwrap sizelimit noauth2 ratelimit osapi_compute_app_v2 - keystone = compute_req_id faultwrap sizelimit authtoken keystonecontext moon ratelimit osapi_compute_app_v2 - keystone_nolimit = compute_req_id faultwrap sizelimit authtoken keystonecontext moon osapi_compute_app_v2 - - [composite:openstack_compute_api_v21] - use = call:nova.api.auth:pipeline_factory_v21 - noauth = compute_req_id faultwrap sizelimit noauth osapi_compute_app_v21 - noauth2 = compute_req_id faultwrap sizelimit noauth2 osapi_compute_app_v21 - keystone = compute_req_id faultwrap sizelimit authtoken keystonecontext moon osapi_compute_app_v21 - - [composite:openstack_compute_api_v3] - use = call:nova.api.auth:pipeline_factory_v21 - noauth = request_id faultwrap sizelimit noauth_v3 osapi_compute_app_v3 - noauth2 = request_id faultwrap sizelimit noauth_v3 osapi_compute_app_v3 - keystone = request_id faultwrap sizelimit authtoken keystonecontext moon osapi_compute_app_v3 - - ... - - [filter:moon] - paste.filter_factory = keystonemiddleware.authz:filter_factory - -If Swift is also installed, you have to configured it, in /etc/swift/proxy-server.conf : - -.. code-block:: ini - - ... - - [pipeline:main] - pipeline = catch_errors gatekeeper healthcheck proxy-logging cache container_sync bulk tempurl ratelimit crossdomain authtoken keystoneauth tempauth formpost staticweb container-quotas account-quotas slo dlo proxy-logging moon proxy-server - - ... - - [filter:moon] - paste.filter_factory = keystonemiddleware.authz:filter_factory - -Nova and Swift must be restarted after that, depending on your configuration, you will have to use 'screen' (if using devstack) -or 'service' on those daemons : nova-api and swift-proxy - -Usage ------ - -TODO
\ No newline at end of file diff --git a/keystone-moon/doc/source/extensions/moon/moon_api.rst b/keystone-moon/doc/source/extensions/moon/moon_api.rst deleted file mode 100644 index 210093a1..00000000 --- a/keystone-moon/doc/source/extensions/moon/moon_api.rst +++ /dev/null @@ -1,863 +0,0 @@ -Moon API -======== - -Here are Moon API with some examples of posted data and returned data. - -All requests must be prefixed with the host and port, for example: http://localhost:35357/moon/authz/123456789/123456789/servers/list - -Authz ------ - -**GET /moon/authz/{tenant_id}/{subject_k_id}/{object_name}/{action_name}** - Authorization API. - -.. code-block:: json - - return = { - "authz": "True or False" - } - - -Intra-Extension API -------------------- - -Configuration -~~~~~~~~~~~~~ - -**GET /moon/configuration/templates** - - List all policy templates. - -.. code-block:: json - - return = { - "template_id": { - "name": "name of the template", - "description": "description of the template", - } - } - - -**GET /moon/configuration/aggregation_algorithms** - - List all aggregation algorithms. - -.. code-block:: json - - return = { - "algorithm_id": { - "name": "name of the algorithm", - "description": "description of the algorithm", - } - } - - -**GET /moon/configuration/sub_meta_rule_algorithms** - - List all sub meta rule algorithms. - -.. code-block:: json - - return = { - "algorithm_id": { - "name": "name of the algorithm", - "description": "description of the algorithm", - } - } - - -Tenants -~~~~~~~ - -**GET /moon/tenants** - - List all tenants. - -.. code-block:: json - - return = { - "tenant_id": { - "name": "name of the tenant", - "description": "description of the tenant", - "intra_authz_extension_id": "id of the intra extension authz", - "intra_admin_extension_id": "id of the intra extension authz" - } - } - - -**POST /moon/tenants** - - Add a tenant. - -.. code-block:: json - - post = { - "tenant_name": "name of the tenant", - "tenant_description": "description of the tenant", - "tenant_intra_authz_extension_id": "id of the intra extension authz", - "tenant_intra_admin_extension_id": "id of the intra extension admin" - } - return = { - "tenant_id": { - "name": "name of the tenant", - "description": "description of the tenant", - "intra_authz_extension_id": "id of the intra extension authz", - "intra_admin_extension_id": "id of the intra extension authz" - } - } - - -**POST /moon/tenants/{tenant_id}** - - Show information of one tenant. - -.. code-block:: json - - return = { - "tenant_id": { - "name": "name of the tenant", - "description": "description of the tenant", - "intra_authz_extension_id": "id of the intra extension authz", - "intra_admin_extension_id": "id of the intra extension authz" - } - } - - -**POST /moon/tenants/{tenant_id}** - - Modify a tenant. - -.. code-block:: json - - post = { - "tenant_name": "name of the tenant", - "tenant_description": "description of the tenant", - "tenant_intra_authz_extension_id": "id of the intra extension authz", - "tenant_intra_admin_extension_id": "id of the intra extension admin" - } - return = { - "tenant_id": { - "name": "name of the tenant", - "description": "description of the tenant", - "intra_authz_extension_id": "id of the intra extension authz", - "intra_admin_extension_id": "id of the intra extension authz" - } - } - - -**DELETE /moon/tenants/{tenant_id}** - - Delete a tenant. - -.. code-block:: json - - return = {} - - -Intra-Extension -~~~~~~~~~~~~~~~ - -**GET /moon/intra_extensions/init** - - Initialize the root Intra_Extension (if needed). - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions** - - List all Intra_Extensions. - -.. code-block:: json - - return = { - "intra_extension_id": { - "name": "name of the intra extension", - "model": "model of the intra extension" - } - } - - -**POST /moon/intra_extensions** - - Create a new Intra_Extension. - -.. code-block:: json - - post = { - "intra_extension_name": "name of the intra extension", - "intra_extension_model": "model of the intra extension (taken from /configuration/templates)", - "intra_extension_description": "description of the intra extension", - - } - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/** - - Show details about one Intra_Extension. - -.. code-block:: json - - return = { - "id": "intra_extension_id", - "name": "name of the intra extension", - "model": "model of the intra extension", - "genre": "genre of the intra extension", - "description": "model of the intra extension" - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/** - - Delete an Intra_Extension. - -.. code-block:: json - - return = {} - - -Intra-Extension Subjects -~~~~~~~~~~~~~~~~~~~~~~~~ - -**GET /moon/intra_extensions/{intra_extension_id}/subjects** - - List all subjects. - -.. code-block:: json - - return = { - "subject_id": { - "name": "name of the subject", - "keystone_id": "keystone id of the subject" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/subjects** - - List all subjects. - -.. code-block:: json - - post = { - "subject_name": "name of the subject", - "subject_description": "description of the subject", - "subject_password": "password for the subject", - "subject_email": "email address of the subject" - } - return = { - "subject_id": { - "name": "name of the subject", - "keystone_id": "keystone id of the subject" - } - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/subjects/{subject_id}** - - Delete a subject. - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/subject_categories** - - List all subject categories. - -.. code-block:: json - - return = { - "subject_category_id": { - "name": "name of the category", - "description": "description of the category" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/subject_categories** - - Add a new subject category. - -.. code-block:: json - - post = { - "subject_category_name": "name of the category", - "subject_category_description": "description of the category" - } - return = { - "subject_category_id": { - "name": "name of the category", - "description": "description of the category" - } - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/subject_categories/{subject_category_id}** - - Delete a subject category. - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/subject_scopes/{subject_category_id}** - - List all subject scopes for a specific subject category. - -.. code-block:: json - - return = { - "subject_scope_id": { - "name": "name of the scope", - "description": "description of the scope" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/subject_scopes/{subject_category_id}** - - Add a new subject scope for a specific subject category. - -.. code-block:: json - - post = { - "subject_scope_name": "name of the scope", - "subject_scope_description": "description of the scope" - } - return = { - "subject_scope_id": { - "name": "name of the scope", - "description": "description of the scope" - } - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/subject_scopes/{subject_category_id}/{subject_scope_id}** - - Delete a subject scope. - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/subject_assignments/{subject_id}/{subject_category_id}** - - List all subject assignments for a subject and for a subject category. - -.. code-block:: json - - return = [ - "subject_assignment_id1", "subject_assignment_id2" - ] - - -**POST /moon/intra_extensions/{intra_extension_id}/subject_assignments** - - Add an assignment. - -.. code-block:: json - - post = { - "subject_id": "id of the subject", - "subject_category_id": "id of the category", - "subject_scope_id": "id of the scope" - } - return = [ - "subject_assignment_id1", "subject_assignment_id2" - ] - - -**DELETE /moon/intra_extensions/{intra_extension_id}/subject_assignments/{subject_id}/{subject_category_id}/{subject_scope_id}** - - Delete a subject assignment. - -.. code-block:: json - - return = {} - - -Intra-Extension Objects -~~~~~~~~~~~~~~~~~~~~~~~ - -**GET /moon/intra_extensions/{intra_extension_id}/objects** - - List all objects. - -.. code-block:: json - - return = { - "object_id": { - "name": "name of the object", - "keystone_id": "keystone id of the object" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/objects** - - List all objects. - -.. code-block:: json - - post = { - "object_name": "name of the object", - "object_description": "description of the object" - } - return = { - "object_id": { - "name": "name of the object", - "keystone_id": "keystone id of the object" - } - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/objects/{object_id}** - - Delete a object. - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/object_categories** - - List all object categories. - -.. code-block:: json - - return = { - "object_category_id": { - "name": "name of the category", - "description": "description of the category" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/object_categories** - - Add a new object category. - -.. code-block:: json - - post = { - "object_category_name": "name of the category", - "object_category_description": "description of the category" - } - return = { - "object_category_id": { - "name": "name of the category", - "description": "description of the category" - } - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/object_categories/{object_category_id}** - - Delete a object category. - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/object_scopes/{object_category_id}** - - List all object scopes for a specific object category. - -.. code-block:: json - - return = { - "object_scope_id": { - "name": "name of the scope", - "description": "description of the scope" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/object_scopes/{object_category_id}** - - Add a new object scope for a specific object category. - -.. code-block:: json - - post = { - "object_scope_name": "name of the scope", - "object_scope_description": "description of the scope" - } - return = { - "object_scope_id": { - "name": "name of the scope", - "description": "description of the scope" - } - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/object_scopes/{object_category_id}/{object_scope_id}** - - Delete a object scope. - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/object_assignments/{object_id}/{object_category_id}** - - List all object assignments for a object and for a object category. - -.. code-block:: json - - return = [ - "object_assignment_id1", "object_assignment_id2" - ] - - -**POST /moon/intra_extensions/{intra_extension_id}/object_assignments** - - Add an assignment. - -.. code-block:: json - - post = { - "object_id": "id of the object", - "object_category_id": "id of the category", - "object_scope_id": "id of the scope" - } - return = [ - "object_assignment_id1", "object_assignment_id2" - ] - - -**DELETE /moon/intra_extensions/{intra_extension_id}/object_assignments/{object_id}/{object_category_id}/{object_scope_id}** - - Delete a object assignment. - -.. code-block:: json - - return = {} - - -Intra-Extension Actions -~~~~~~~~~~~~~~~~~~~~~~~ - -**GET /moon/intra_extensions/{intra_extension_id}/actions** - - List all actions. - -.. code-block:: json - - return = { - "action_id": { - "name": "name of the action", - "keystone_id": "keystone id of the action" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/actions** - - List all actions. - -.. code-block:: json - - post = { - "action_name": "name of the action", - "action_description": "description of the action", - "action_password": "password for the action", - "action_email": "email address of the action" - } - return = { - "action_id": { - "name": "name of the action", - "keystone_id": "keystone id of the action" - } - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/actions/{action_id}** - - Delete a action. - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/action_categories** - - List all action categories. - -.. code-block:: json - - return = { - "action_category_id": { - "name": "name of the category", - "description": "description of the category" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/action_categories** - - Add a new action category. - -.. code-block:: json - - post = { - "action_category_name": "name of the category", - "action_category_description": "description of the category" - } - return = { - "action_category_id": { - "name": "name of the category", - "description": "description of the category" - } - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/action_categories/{action_category_id}** - - Delete a action category. - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/action_scopes/{action_category_id}** - - List all action scopes for a specific action category. - -.. code-block:: json - - return = { - "action_scope_id": { - "name": "name of the scope", - "description": "description of the scope" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/action_scopes/{action_category_id}** - - Add a new action scope for a specific action category. - -.. code-block:: json - - post = { - "action_scope_name": "name of the scope", - "action_scope_description": "description of the scope" - } - return = { - "action_scope_id": { - "name": "name of the scope", - "description": "description of the scope" - } - } - - -**DELETE /moon/intra_extensions/{intra_extension_id}/action_scopes/{action_category_id}/{action_scope_id}** - - Delete a action scope. - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/action_assignments/{action_id}/{action_category_id}** - - List all action assignments for a action and for a action category. - -.. code-block:: json - - return = [ - "action_assignment_id1", "action_assignment_id2" - ] - - -**POST /moon/intra_extensions/{intra_extension_id}/action_assignments** - - Add an assignment. - -.. code-block:: json - - post = { - "action_id": "id of the action", - "action_category_id": "id of the category", - "action_scope_id": "id of the scope" - } - return = [ - "action_assignment_id1", "action_assignment_id2" - ] - - -**DELETE /moon/intra_extensions/{intra_extension_id}/action_assignments/{action_id}/{action_category_id}/{action_scope_id}** - - Delete a action assignment. - -.. code-block:: json - - return = {} - - -Intra-Extension Rules -~~~~~~~~~~~~~~~~~~~~~ - -**GET /moon/intra_extensions/{intra_extension_id}/aggregation_algorithm** - - List aggregation algorithm for an intra extension. - -.. code-block:: json - - return = { - "aggregation_algorithm_id": { - "name": "name of the aggregation algorithm", - "description": "description of the aggregation algorithm" - } - } - - -**POST /moon/intra_extensions/{intra_extension_id}/aggregation_algorithm** - - Set the current aggregation algorithm for an intra extension. - -.. code-block:: json - - post = { - "aggregation_algorithm_id": "id of the aggregation algorithm", - "aggregation_algorithm_description": "description of the aggregation algorithm" - } - return = { - "aggregation_algorithm_id": { - "name": "name of the aggregation algorithm", - "description": "description of the aggregation algorithm" - } - } - - -**GET /moon/intra_extensions/{intra_extension_id}/sub_meta_rules** - - Show the current sub meta rules. - -.. code-block:: json - - return = { - "sub_meta_rule_id": { - "name": "name of the aggregation algorithm", - "algorithm": "algorithm of the aggregation algorithm", - "subject_categories": ["subject_category_id1", "subject_category_id2"], - "object_categories": ["object_category_id1", "object_category_id2"], - "action_categories": ["action_category_id1", "action_category_id2"] - } - } - - -.. code-block:: json - - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/rule/{sub_meta_rule_id}** - - Set the current sub meta rule. - -.. code-block:: json - - post = { - "sub_meta_rule_name": "name of the sub meta rule", - "sub_meta_rule_algorithm": "name of the sub meta rule algorithm", - "sub_meta_rule_subject_categories": ["subject_category_id1", "subject_category_id2"], - "sub_meta_rule_object_categories": ["object_category_id1", "object_category_id2"], - "sub_meta_rule_action_categories": ["action_category_id1", "action_category_id2"] - } - return = {} - - -**GET /moon/intra_extensions/{intra_extension_id}/rule/{sub_meta_rule_id}** - - List all rules. - -.. code-block:: json - - return = { - "rule_id1": ["subject_scope_id1", "object_scope_id1", "action_scope_id1"], - "rule_id2": ["subject_scope_id2", "object_scope_id2", "action_scope_id2"] - } - - -**POST /moon/intra_extensions/{intra_extension_id}/rule/{sub_meta_rule_id}** - - Add a new rule. - -.. code-block:: json - - post = { - "subject_categories": ["subject_scope_id1"], - "object_categories": ["object_scope_id1"], - "action_categories": ["action_scope_id1"], - "enabled": True - } - return = {} - - -**DELETE /moon/intra_extensions/{intra_extension_id}/rule/{sub_meta_rule_id}/{rule_id}** - - Delete a rule. - -.. code-block:: json - - return = {} - - -Logs -~~~~ - -**GET /moon/logs/{options}** - - List all logs. - Options can be: - - * ``filter=<filter_characters>`` - * ``from=<show logs from this date>`` - * ``to=<show logs to this date>`` - * ``event_number=<get n logs>`` - - Time format is '%Y-%m-%d-%H:%M:%S' (eg. "2015-04-15-13:45:20") - -.. code-block:: json - - return = [ - "2015-04-15-13:45:20 ...", - "2015-04-15-13:45:21 ...", - "2015-04-15-13:45:22 ...", - "2015-04-15-13:45:23 ..." - ] - -Auth -~~~~ - -**POST /moon/auth/tokens** - - Add a tenant. - -.. code-block:: json - - post = { - "username": "name of the user to authenticate", - "password": "password of the user to authenticate" - } - return = { - "token": "NEW_TOKEN", - "message": "if authentication failed..." - } - - diff --git a/keystone-moon/doc/source/extensions/oauth1.rst b/keystone-moon/doc/source/extensions/oauth1.rst deleted file mode 100644 index 29955d74..00000000 --- a/keystone-moon/doc/source/extensions/oauth1.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. - Copyright 2011-2013 OpenStack, Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============================= -Enabling the OAuth1 Extension -============================= - -To enable the OAuth1 extension: - -1. Optionally, add the oauth1 extension driver to the ``[oauth1]`` section in ``keystone.conf``. For example:: - - [oauth1] - driver = sql - -2. Add the ``oauth1`` authentication method to the ``[auth]`` section in ``keystone.conf``:: - - [auth] - methods = external,password,token,oauth1 - -3. Add the ``oauth1_extension`` filter to the ``api_v3`` pipeline in - ``keystone-paste.ini``. This must be added after ``json_body`` and before - the last entry in the pipeline. For example:: - - [pipeline:api_v3] - pipeline = sizelimit url_normalize build_auth_context token_auth admin_token_auth json_body ec2_extension_v3 s3_extension simple_cert_extension revoke_extension oauth1_extension service_v3 - -4. Create the OAuth1 extension tables if using the provided SQL backend. For example:: - - ./bin/keystone-manage db_sync --extension oauth1 - -5. Optionally, if deploying under an HTTPD server (i.e. Apache), set the - `WSGIPassAuthorization` to allow the OAuth Authorization headers to - pass through `mod_wsgi`. For example, add the following to the Keystone - virtual host file:: - - WSGIPassAuthorization On diff --git a/keystone-moon/doc/source/extensions/openidc.rst b/keystone-moon/doc/source/extensions/openidc.rst deleted file mode 100644 index f515309e..00000000 --- a/keystone-moon/doc/source/extensions/openidc.rst +++ /dev/null @@ -1,93 +0,0 @@ -:orphan: - -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -==================== -Setup OpenID Connect -==================== - -Configuring mod_auth_openidc -============================ - -Federate Keystone (SP) and an external IdP using OpenID Connect (`mod_auth_openidc`_) - -.. _`mod_auth_openidc`: https://github.com/pingidentity/mod_auth_openidc - -To install `mod_auth_openidc` on Ubuntu, perform the following: - -.. code-block:: bash - - sudo apt-get install libapache2-mod-auth-openidc - -Note that this module is not available on Fedora/CentOS/Red Hat. - -In the keystone Apache site file, add the following as a top level option, to -load the `mod_auth_openidc` module: - -.. code-block:: xml - - LoadModule auth_openidc_module /usr/lib/apache2/modules/mod_auth_openidc.so - -Also within the same file, locate the virtual host entry and add the following -entries for OpenID Connect: - -.. code-block:: xml - - <VirtualHost *:5000> - - ... - - OIDCClaimPrefix "OIDC-" - OIDCResponseType "id_token" - OIDCScope "openid email profile" - OIDCProviderMetadataURL <url_of_provider_metadata> - OIDCClientID <openid_client_id> - OIDCClientSecret <openid_client_secret> - OIDCCryptoPassphrase openstack - OIDCRedirectURI http://localhost:5000/v3/OS-FEDERATION/identity_providers/<idp_id>/protocols/oidc/auth/redirect - - <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/oidc/auth> - AuthType openid-connect - Require valid-user - LogLevel debug - </LocationMatch> - </VirtualHost> - -Note an example of an `OIDCProviderMetadataURL` instance is: https://accounts.google.com/.well-known/openid-configuration -If not using `OIDCProviderMetadataURL`, then the following attributes -must be specified: `OIDCProviderIssuer`, `OIDCProviderAuthorizationEndpoint`, -`OIDCProviderTokenEndpoint`, `OIDCProviderTokenEndpointAuth`, -`OIDCProviderUserInfoEndpoint`, and `OIDCProviderJwksUri` - -Note, if using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` -must be specified to have only alphanumerics or a dash ("-"). This is because -mod_wsgi blocks headers that do not fit this criteria. See http://modwsgi.readthedocs.org/en/latest/release-notes/version-4.3.0.html#bugs-fixed -for more details - -Once you are done, restart your Apache daemon: - -.. code-block:: bash - - $ service apache2 restart - -Tips -==== - -1. When creating a mapping, note that the 'remote' attributes will be prefixed, - with `HTTP_`, so for instance, if you set OIDCClaimPrefix to `OIDC-`, then a - typical remote value to check for is: `HTTP_OIDC_ISS`. - -2. Don't forget to add oidc as an [auth] plugin in keystone.conf, see `Step 2`_ - -.. _`Step 2`: federation.html
\ No newline at end of file diff --git a/keystone-moon/doc/source/extensions/revoke.rst b/keystone-moon/doc/source/extensions/revoke.rst deleted file mode 100644 index a89e359d..00000000 --- a/keystone-moon/doc/source/extensions/revoke.rst +++ /dev/null @@ -1,45 +0,0 @@ - .. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================================= -Enabling the Revocation Extension -================================= - -.. NOTE:: - - As of the Juno release, the example configuration files will have the - ``OS-REVOKE`` extension enabled by default, thus it is not necessary to - perform steps 1 and 2. - Also, for new installations, the revocation extension tables are already - migrated, thus it is not necessary to perform steps 3. - -1. Optionally, add the revoke extension driver to the ``[revoke]`` section - in ``keystone.conf``. For example:: - - [revoke] - driver = sql - -2. Add the required ``filter`` to the ``pipeline`` in ``keystone-paste.ini``. - This must be added after ``json_body`` and before the last entry in the - pipeline. For example:: - - [filter:revoke_extension] - paste.filter_factory = keystone.contrib.revoke.routers:RevokeExtension.factory - - [pipeline:api_v3] - pipeline = sizelimit url_normalize build_auth_context token_auth admin_token_auth json_body ec2_extension_v3 s3_extension simple_cert_extension revoke_extension service_v3 - -3. Create the revocation extension tables if using the provided SQL backend. - For example:: - - ./bin/keystone-manage db_sync --extension revoke diff --git a/keystone-moon/doc/source/extensions/shibboleth.rst b/keystone-moon/doc/source/extensions/shibboleth.rst deleted file mode 100644 index d67cfa1a..00000000 --- a/keystone-moon/doc/source/extensions/shibboleth.rst +++ /dev/null @@ -1,279 +0,0 @@ -:orphan: - -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================ -Setup Shibboleth -================ - -Configure Apache HTTPD for mod_shibboleth -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Follow the steps outlined at: `Running Keystone in HTTPD`_. - -.. _`Running Keystone in HTTPD`: ../apache-httpd.html - -You'll also need to install `Shibboleth <https://wiki.shibboleth.net/confluence/display/SHIB2/Home>`_, for -example: - -.. code-block:: bash - - $ apt-get install libapache2-mod-shib2 - -Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow: - -Add *WSGIScriptAlias* directive to your vhost configuration:: - - WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1 - -Make sure the *wsgi-keystone.conf* contains a *<Location>* directive for the Shibboleth module and -a *<Location>* directive for each identity provider:: - - <Location /Shibboleth.sso> - SetHandler shib - </Location> - - <Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth> - ShibRequestSetting requireSession 1 - ShibRequestSetting applicationId idp_1 - AuthType shibboleth - ShibRequireAll On - ShibRequireSession On - ShibExportAssertion Off - Require valid-user - </Location> - -.. NOTE:: - * ``saml2`` may be different in your deployment, but do not use a wildcard value. - Otherwise *every* federated protocol will be handled by Shibboleth. - * ``idp_1`` has to be replaced with the name associated with the idp in Keystone. - The same name is used inside the shibboleth2.xml configuration file but they could - be different. - * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in - Apache 2.4+ and should be dropped in that specific setup. - * You are advised to carefully examine `Shibboleth Apache configuration - documentation - <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig>`_ - -Enable the Keystone virtual host, for example: - -.. code-block:: bash - - $ a2ensite wsgi-keystone.conf - -Enable the ``ssl`` and ``shib2`` modules, for example: - -.. code-block:: bash - - $ a2enmod ssl - $ a2enmod shib2 - -Restart Apache, for example: - -.. code-block:: bash - - $ service apache2 restart - -Configuring shibboleth2.xml -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once you have your Keystone vhost (virtual host) ready, it's then time to -configure Shibboleth and upload your Metadata to the Identity Provider. - -If new certificates are required, they can be easily created by executing: - -.. code-block:: bash - - $ shib-keygen -y <number of years> - -The newly created file will be stored under ``/etc/shibboleth/sp-key.pem`` - -You should fetch your Service Provider's Metadata file. Typically this can be -achieved by simply fetching a Metadata file, for example: - -.. code-block:: bash - - $ wget --no-check-certificate -O <name of the file> https://service.example.org/Shibboleth.sso/Metadata - -Upload your Service Provider's Metadata file to your Identity Provider. -This step depends on your Identity Provider choice and is not covered here. - -Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml`` -file. You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_ - -An example of your ``/etc/shibboleth/shibboleth2.xml`` may look like -(The example shown below is for reference only, not to be used in a production -environment): - -.. code-block:: xml - - <!-- - File configuration courtesy of http://testshib.org - - More information: - https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration - --> - - <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config" - xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" clockSkew="1800 "> - - <!-- The entityID is the name TestShib made for your SP. --> - <ApplicationDefaults entityID="https://<yourhosthere>/shibboleth"> - - <!-- - You should use secure cookies if at all possible. - See cookieProps in this Wiki article. - --> - <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessions --> - <Sessions lifetime="28800" timeout="3600" checkAddress="false" - relayState="ss:mem" handlerSSL="false"> - - <!-- Triggers a login request directly to the TestShib IdP. --> - <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO --> - <SSO entityID="https://<idp-url>/idp/shibboleth" ECP="true"> - SAML2 SAML1 - </SSO> - - <!-- SAML and local-only logout. --> - <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceLogout --> - <Logout>SAML2 Local</Logout> - - <!-- - Handlers allow you to interact with the SP and gather - more information. Try them out! - Attribute value s received by the SP through SAML - will be visible at: - http://<yourhosthere>/Shibboleth.sso/Session - --> - - <!-- - Extension service that generates "approximate" metadata - based on SP configuration. - --> - <Handler type="MetadataGenerator" Location="/Metadata" - signing="false"/> - - <!-- Status reporting service. --> - <Handler type="Status" Location="/Status" - acl="127.0.0.1"/> - - <!-- Session diagnostic service. --> - <Handler type="Session" Location="/Session" - showAttributeValues="true"/> - <!-- JSON feed of discovery information. --> - <Handler type="DiscoveryFeed" Location="/DiscoFeed"/> - </Sessions> - - <!-- - Error pages to display to yourself if - something goes horribly wrong. - --> - <Errors supportContact ="<admin_email_address>" - logoLocation="/shibboleth-sp/logo.jpg" - styleSheet="/shibboleth-sp/main.css"/> - - <!-- - Loads and trusts a metadata file that describes only one IdP - and how to communicate with it. - --> - <MetadataProvider type="XML" uri="<idp-metadata-file>" - backingFilePath="<local idp metadata>" - reloadInterval="180000" /> - - <!-- Attribute and trust options you shouldn't need to change. --> - <AttributeExtractor type="XML" validate="true" - path="attribute-map.xml"/> - <AttributeResolver type="Query" subjectMatch="true"/> - <AttributeFilter type="XML" validate="true" - path="attribute-policy.xml"/> - - <!-- - Your SP generated these credentials. - They're used to talk to IdP's. - --> - <CredentialResolver type="File" key="sp-key.pem" - certificate="sp-cert.pem"/> - - <ApplicationOverride id="idp_1" entityID="https://<yourhosthere>/shibboleth"> - <Sessions lifetime="28800" timeout="3600" checkAddress="false" - relayState="ss:mem" handlerSSL="false"> - - <!-- Triggers a login request directly to the TestShib IdP. --> - <SSO entityID="https://<idp_1-url>/idp/shibboleth" ECP="true"> - SAML2 SAML1 - </SSO> - - <Logout>SAML2 Local</Logout> - </Sessions> - - <MetadataProvider type="XML" uri="<idp_1-metadata-file>" - backingFilePath="<local idp_1 metadata>" - reloadInterval="180000" /> - - </ApplicationOverride> - - <ApplicationOverride id="idp_2" entityID="https://<yourhosthere>/shibboleth"> - <Sessions lifetime="28800" timeout="3600" checkAddress="false" - relayState="ss:mem" handlerSSL="false"> - - <!-- Triggers a login request directly to the TestShib IdP. --> - <SSO entityID="https://<idp_2-url>/idp/shibboleth" ECP="true"> - SAML2 SAML1 - </SSO> - - <Logout>SAML2 Local</Logout> - </Sessions> - - <MetadataProvider type="XML" uri="<idp_2-metadata-file>" - backingFilePath="<local idp_2 metadata>" - reloadInterval="180000" /> - - </ApplicationOverride> - - </ApplicationDefaults> - - <!-- - Security policies you shouldn't change unless you - know what you're doing. - --> - <SecurityPolicyProvider type="XML" validate="true" - path="security-policy.xml"/> - - <!-- - Low-level configuration about protocols and bindings - available for use. - --> - <ProtocolProvider type="XML" validate="true" reloadChanges="false" - path="protocols.xml"/> - - </SPConfig> - -Keystone enforces `external authentication`_ when the ``REMOTE_USER`` -environment variable is present so make sure Shibboleth doesn't set the -``REMOTE_USER`` environment variable. To do so, scan through the -``/etc/shibboleth/shibboleth2.xml`` configuration file and remove the -``REMOTE_USER`` directives. - -Examine your attributes map file ``/etc/shibboleth/attributes-map.xml`` and adjust -your requirements if needed. For more information see -`attributes documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_ - -Once you are done, restart your Shibboleth daemon: - -.. _`external authentication`: ../external-auth.html - -.. code-block:: bash - - $ service shibd restart - $ service apache2 restart diff --git a/keystone-moon/doc/source/external-auth.rst b/keystone-moon/doc/source/external-auth.rst deleted file mode 100644 index 4b545e4f..00000000 --- a/keystone-moon/doc/source/external-auth.rst +++ /dev/null @@ -1,154 +0,0 @@ -=========================================== -Using external authentication with Keystone -=========================================== -.. _external-auth: - -When Keystone is executed in a web server like :doc:`Apache HTTPD -<apache-httpd>` it is possible to use external authentication methods different -from the authentication provided by the identity store backend or the different -authentication plugins. For example, this makes possible to use an SQL identity -backend together with, X.509 authentication or Kerberos, for example, instead -of using the username and password combination. - -When a web server is in charge of authentication, it is normally possible to -set the ``REMOTE_USER`` environment variable so that it can be used in the -underlying application. Keystone can be configured to use that environment -variable if set, so that the authentication is handled by the web server. - -Configuration -============= - -In Identity API v2, there is no way to disable external authentication. In -order to activate the external authentication mechanism for Identity API v3, -the ``external`` method must be in the list of enabled authentication methods. -By default it is enabled, so if you don't want to use external authentication, -remove it from the ``methods`` option in the ``auth`` section. - -To configure the plugin that should be used set the ``external`` option again -in the ``auth`` section. There are two external authentication method plugins -provided by Keystone: - -* ``DefaultDomain``: This plugin won't take into account the domain information - that the external authentication method may pass down to Keystone and will - always use the configured default domain. The ``REMOTE_USER`` variable is the - username. This is the default if no plugin is given. - -* ``Domain``: This plugin expects that the ``REMOTE_DOMAIN`` variable contains - the domain for the user. If this variable is not present, the configured - default domain will be used. The ``REMOTE_USER`` variable is the username. - -Using HTTPD authentication -========================== - -Web servers like Apache HTTP support many methods of authentication. Keystone -can profit from this feature and let the authentication be done in the web -server, that will pass down the authenticated user to Keystone using the -``REMOTE_USER`` environment variable. This user must exist in advance in the -identity backend to get a token from the controller. - -To use this method, Keystone should be running on :doc:`HTTPD <apache-httpd>`. - -X.509 example -------------- - -The following snippet for the Apache conf will authenticate the user based on -a valid X.509 certificate from a known CA:: - - <VirtualHost _default_:5000> - SSLEngine on - SSLCertificateFile /etc/ssl/certs/ssl.cert - SSLCertificateKeyFile /etc/ssl/private/ssl.key - - SSLCACertificatePath /etc/ssl/allowed_cas - SSLCARevocationPath /etc/ssl/allowed_cas - SSLUserName SSL_CLIENT_S_DN_CN - SSLVerifyClient require - SSLVerifyDepth 10 - - (...) - </VirtualHost> - -Developing a WSGI middleware for authentication -=============================================== - -In addition to the method described above, it is possible to implement other -custom authentication mechanisms using the ``REMOTE_USER`` WSGI environment -variable. - -.. ATTENTION:: - - Please note that even if it is possible to develop a custom authentication - module, it is preferable to use the modules in the HTTPD server. Such - authentication modules in webservers like Apache have normally undergone - years of development and use in production systems and are actively - maintained upstream. Developing a custom authentication module that - implements the same authentication as an existing Apache module likely - introduces a higher security risk. - -If you find you must implement a custom authentication mechanism, you will need -to develop a custom WSGI middleware pipeline component. This middleware should -set the environment variable ``REMOTE_USER`` to the authenticated username. -Keystone then will assume that the user has been already authenticated upstream -and will not try to authenticate it. However, as with HTTPD authentication, the -user must exist in advance in the identity backend so that a proper token can -be issued. - -Your code should set the ``REMOTE_USER`` if the user is properly authenticated, -following the semantics below: - -.. code-block:: python - - from keystone.common import wsgi - from keystone import exception - - class MyMiddlewareAuth(wsgi.Middleware): - def __init__(self, *args, **kwargs): - super(MyMiddlewareAuth, self).__init__(*args, **kwargs) - - def process_request(self, request): - if request.environ.get('REMOTE_USER', None) is not None: - # Assume that it is authenticated upstream - return self.application - - if not self.is_auth_applicable(request): - # Not applicable - return self.application - - username = self.do_auth(request) - if username is not None: - # User is authenticated - request.environ['REMOTE_USER'] = username - else: - # User is not authenticated, render exception - raise exception.Unauthorized("Invalid user") - - -Pipeline configuration ----------------------- - -Once you have your WSGI middleware component developed you have to add it to -your pipeline. The first step is to add the middleware to your configuration -file. Assuming that your middleware module is -``keystone.middleware.MyMiddlewareAuth``, you can configure it in your -``keystone-paste.ini`` as:: - - [filter:my_auth] - paste.filter_factory = keystone.middleware.MyMiddlewareAuth.factory - -The second step is to add your middleware to the pipeline. The exact place -where you should place it will depend on your code (i.e. if you need for -example that the request body is converted from JSON before perform the -authentication you should place it after the ``json_body`` filter) but it -should be set before the ``public_service`` (for the ``public_api`` pipeline) -or ``admin_service`` (for the ``admin_api`` pipeline), since they consume -authentication. - -For example, if the original pipeline looks like this:: - - [pipeline:public_api] - pipeline = url_normalize token_auth admin_token_auth json_body debug ec2_extension user_crud_extension public_service - -Your modified pipeline might then look like this:: - - [pipeline:public_api] - pipeline = url_normalize token_auth admin_token_auth json_body my_auth debug ec2_extension user_crud_extension public_service diff --git a/keystone-moon/doc/source/federation/mellon.rst b/keystone-moon/doc/source/federation/mellon.rst deleted file mode 100644 index 9c4675b7..00000000 --- a/keystone-moon/doc/source/federation/mellon.rst +++ /dev/null @@ -1,122 +0,0 @@ -:orphan: - -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============================== -Setup Mellon (mod_auth_mellon) -============================== - -Configure Apache HTTPD for mod_auth_mellon -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Follow the steps outlined at: `Running Keystone in HTTPD`_. - -.. _`Running Keystone in HTTPD`: ../apache-httpd.html - -You'll also need to install the Apache module `mod_auth_mellon -<https://github.com/UNINETT/mod_auth_mellon>`_. For example: - -.. code-block:: bash - - $ apt-get install libapache2-mod-auth-mellon - -Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow: - -Add *WSGIScriptAlias* directive to your vhost configuration:: - - WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1 - -Make sure the *wsgi-keystone.conf* contains a *<Location>* directive for the Mellon module and -a *<Location>* directive for each identity provider:: - - <Location /v3> - MellonEnable "info" - MellonSPPrivateKeyFile /etc/httpd/mellon/http_keystone.fqdn.key - MellonSPCertFile /etc/httpd/mellon/http_keystone.fqdn.cert - MellonSPMetadataFile /etc/httpd/mellon/http_keystone.fqdn.xml - MellonIdPMetadataFile /etc/httpd/mellon/idp-metadata.xml - MellonEndpointPath /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon - MellonIdP "IDP" - </Location> - - <Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth> - AuthType "Mellon" - MellonEnable "auth" - </Location> - -.. NOTE:: - * See below for information about how to generate the values for the - `MellonSPMetadataFile`, etc. directives. - * ``saml2`` may be different in your deployment, but do not use a wildcard value. - Otherwise *every* federated protocol will be handled by Mellon. - * ``idp_1`` has to be replaced with the name associated with the IdP in Keystone. - * You are advised to carefully examine `mod_auth_mellon Apache - configuration documentation - <https://github.com/UNINETT/mod_auth_mellon>`_ - -Enable the Keystone virtual host, for example: - -.. code-block:: bash - - $ a2ensite wsgi-keystone.conf - -Enable the ``ssl`` and ``auth_mellon`` modules, for example: - -.. code-block:: bash - - $ a2enmod ssl - $ a2enmod auth_mellon - -Restart the Apache instance that is serving Keystone, for example: - -.. code-block:: bash - - $ service apache2 restart - -Configuring the Mellon SP Metadata -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Mellon provides a script called ``mellon_create_metadata.sh`` which generates the -values for the config directives `MellonSPPrivateKeyFile`, `MellonSPCertFile`, -and `MellonSPMetadataFile`. It is run like this: - -.. code-block:: bash - - $ mellon_create_metadata.sh http://keystone.fqdn:5000 \ - http://keystone.fqdn:5000/v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth/mellon - -The first parameter is used as the entity ID, a unique identifier for this -Keystone SP. You do not have to use the URL, but it is an easy way to uniquely -identify each Keystone SP. The second parameter is the full URL for the -endpoint path corresponding to the parameter `MellonEndpointPath`. - -Fetch your Service Provider's Metadata file. This corresponds to the value of -the `MellonIdPMetadataFile` directive above. For example: - -.. code-block:: bash - - $ wget --cacert /path/to/ca.crt -O /etc/httpd/mellon/idp-metadata.xml \ - https://idp.fqdn/idp/saml2/metadata - -Upload your Service Provider's Metadata file to your Identity Provider. This -is the file used as the value of the `MellonSPMetadataFile` in the config, -generated by the `mellon_create_metadata.sh` script. The IdP may provide a -webpage where you can upload the file, or you may be required to submit the -file using `wget` or `curl`. Please check your IdP documentation for details. - -Once you are done, restart the Apache instance that is serving Keystone, for example: - -.. code-block:: bash - - $ service apache2 restart diff --git a/keystone-moon/doc/source/federation/openidc.rst b/keystone-moon/doc/source/federation/openidc.rst deleted file mode 100644 index ece82d3a..00000000 --- a/keystone-moon/doc/source/federation/openidc.rst +++ /dev/null @@ -1,94 +0,0 @@ -:orphan: - -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -==================== -Setup OpenID Connect -==================== - -Configuring mod_auth_openidc -============================ - -Federate Keystone (SP) and an external IdP using OpenID Connect (`mod_auth_openidc`_) - -.. _`mod_auth_openidc`: https://github.com/pingidentity/mod_auth_openidc - -To install `mod_auth_openidc` on Ubuntu, perform the following: - -.. code-block:: bash - - sudo apt-get install libapache2-mod-auth-openidc - -This module is available for other distributions (Fedora/CentOS/Red Hat) from: -https://github.com/pingidentity/mod_auth_openidc/releases - -In the keystone Apache site file, add the following as a top level option, to -load the `mod_auth_openidc` module: - -.. code-block:: xml - - LoadModule auth_openidc_module /usr/lib/apache2/modules/mod_auth_openidc.so - -Also within the same file, locate the virtual host entry and add the following -entries for OpenID Connect: - -.. code-block:: xml - - <VirtualHost *:5000> - - ... - - OIDCClaimPrefix "OIDC-" - OIDCResponseType "id_token" - OIDCScope "openid email profile" - OIDCProviderMetadataURL <url_of_provider_metadata> - OIDCClientID <openid_client_id> - OIDCClientSecret <openid_client_secret> - OIDCCryptoPassphrase openstack - OIDCRedirectURI http://localhost:5000/v3/OS-FEDERATION/identity_providers/<idp_id>/protocols/oidc/auth/redirect - - <LocationMatch /v3/OS-FEDERATION/identity_providers/.*?/protocols/oidc/auth> - AuthType openid-connect - Require valid-user - LogLevel debug - </LocationMatch> - </VirtualHost> - -Note an example of an `OIDCProviderMetadataURL` instance is: https://accounts.google.com/.well-known/openid-configuration -If not using `OIDCProviderMetadataURL`, then the following attributes -must be specified: `OIDCProviderIssuer`, `OIDCProviderAuthorizationEndpoint`, -`OIDCProviderTokenEndpoint`, `OIDCProviderTokenEndpointAuth`, -`OIDCProviderUserInfoEndpoint`, and `OIDCProviderJwksUri` - -Note, if using a mod_wsgi version less than 4.3.0, then the `OIDCClaimPrefix` -must be specified to have only alphanumerics or a dash ("-"). This is because -mod_wsgi blocks headers that do not fit this criteria. See http://modwsgi.readthedocs.org/en/latest/release-notes/version-4.3.0.html#bugs-fixed -for more details - -Once you are done, restart your Apache daemon: - -.. code-block:: bash - - $ service apache2 restart - -Tips -==== - -1. When creating a mapping, note that the 'remote' attributes will be prefixed, - with `HTTP_`, so for instance, if you set OIDCClaimPrefix to `OIDC-`, then a - typical remote value to check for is: `HTTP_OIDC_ISS`. - -2. Don't forget to add oidc as an [auth] plugin in keystone.conf, see `Step 2`_ - -.. _`Step 2`: federation/federation.html diff --git a/keystone-moon/doc/source/federation/shibboleth.rst b/keystone-moon/doc/source/federation/shibboleth.rst deleted file mode 100644 index b82bd703..00000000 --- a/keystone-moon/doc/source/federation/shibboleth.rst +++ /dev/null @@ -1,282 +0,0 @@ -:orphan: - -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -================ -Setup Shibboleth -================ - -Configure Apache HTTPD for mod_shibboleth -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Follow the steps outlined at: `Running Keystone in HTTPD`_. - -.. _`Running Keystone in HTTPD`: ../apache-httpd.html - -You'll also need to install `Shibboleth <https://wiki.shibboleth.net/confluence/display/SHIB2/Home>`_, for -example: - -.. code-block:: bash - - $ apt-get install libapache2-mod-shib2 - -Configure your Keystone virtual host and adjust the config to properly handle SAML2 workflow: - -Add *WSGIScriptAlias* directive to your vhost configuration:: - - WSGIScriptAliasMatch ^(/v3/OS-FEDERATION/identity_providers/.*?/protocols/.*?/auth)$ /var/www/keystone/main/$1 - -Make sure the *wsgi-keystone.conf* contains a *<Location>* directive for the Shibboleth module and -a *<Location>* directive for each identity provider:: - - <Location /Shibboleth.sso> - SetHandler shib - </Location> - - <Location /v3/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/auth> - ShibRequestSetting requireSession 1 - ShibRequestSetting applicationId idp_1 - AuthType shibboleth - ShibExportAssertion Off - Require valid-user - - <IfVersion < 2.4> - ShibRequireSession On - ShibRequireAll On - </IfVersion> - </Location> - -.. NOTE:: - * ``saml2`` may be different in your deployment, but do not use a wildcard value. - Otherwise *every* federated protocol will be handled by Shibboleth. - * ``idp_1`` has to be replaced with the name associated with the idp in Keystone. - The same name is used inside the shibboleth2.xml configuration file but they could - be different. - * The ``ShibRequireSession`` and ``ShibRequireAll`` rules are invalid in - Apache 2.4+. - * You are advised to carefully examine `Shibboleth Apache configuration - documentation - <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig>`_ - -Enable the Keystone virtual host, for example: - -.. code-block:: bash - - $ a2ensite wsgi-keystone.conf - -Enable the ``ssl`` and ``shib2`` modules, for example: - -.. code-block:: bash - - $ a2enmod ssl - $ a2enmod shib2 - -Restart Apache, for example: - -.. code-block:: bash - - $ service apache2 restart - -Configuring shibboleth2.xml -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Once you have your Keystone vhost (virtual host) ready, it's then time to -configure Shibboleth and upload your Metadata to the Identity Provider. - -If new certificates are required, they can be easily created by executing: - -.. code-block:: bash - - $ shib-keygen -y <number of years> - -The newly created file will be stored under ``/etc/shibboleth/sp-key.pem`` - -You should fetch your Service Provider's Metadata file. Typically this can be -achieved by simply fetching a Metadata file, for example: - -.. code-block:: bash - - $ wget --no-check-certificate -O <name of the file> https://service.example.org/Shibboleth.sso/Metadata - -Upload your Service Provider's Metadata file to your Identity Provider. -This step depends on your Identity Provider choice and is not covered here. - -Configure your Service Provider by editing ``/etc/shibboleth/shibboleth2.xml`` -file. You are advised to examine `Shibboleth Service Provider Configuration documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/Configuration>`_ - -An example of your ``/etc/shibboleth/shibboleth2.xml`` may look like -(The example shown below is for reference only, not to be used in a production -environment): - -.. code-block:: xml - - <!-- - File configuration courtesy of http://testshib.org - - More information: - https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration - --> - - <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config" - xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" clockSkew="1800 "> - - <!-- The entityID is the name TestShib made for your SP. --> - <ApplicationDefaults entityID="https://<yourhosthere>/shibboleth"> - - <!-- - You should use secure cookies if at all possible. - See cookieProps in this Wiki article. - --> - <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPSessions --> - <Sessions lifetime="28800" timeout="3600" checkAddress="false" - relayState="ss:mem" handlerSSL="false"> - - <!-- Triggers a login request directly to the TestShib IdP. --> - <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceSSO --> - <SSO entityID="https://<idp-url>/idp/shibboleth" ECP="true"> - SAML2 SAML1 - </SSO> - - <!-- SAML and local-only logout. --> - <!-- https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPServiceLogout --> - <Logout>SAML2 Local</Logout> - - <!-- - Handlers allow you to interact with the SP and gather - more information. Try them out! - Attribute value s received by the SP through SAML - will be visible at: - http://<yourhosthere>/Shibboleth.sso/Session - --> - - <!-- - Extension service that generates "approximate" metadata - based on SP configuration. - --> - <Handler type="MetadataGenerator" Location="/Metadata" - signing="false"/> - - <!-- Status reporting service. --> - <Handler type="Status" Location="/Status" - acl="127.0.0.1"/> - - <!-- Session diagnostic service. --> - <Handler type="Session" Location="/Session" - showAttributeValues="true"/> - <!-- JSON feed of discovery information. --> - <Handler type="DiscoveryFeed" Location="/DiscoFeed"/> - </Sessions> - - <!-- - Error pages to display to yourself if - something goes horribly wrong. - --> - <Errors supportContact ="<admin_email_address>" - logoLocation="/shibboleth-sp/logo.jpg" - styleSheet="/shibboleth-sp/main.css"/> - - <!-- - Loads and trusts a metadata file that describes only one IdP - and how to communicate with it. - --> - <MetadataProvider type="XML" uri="<idp-metadata-file>" - backingFilePath="<local idp metadata>" - reloadInterval="180000" /> - - <!-- Attribute and trust options you shouldn't need to change. --> - <AttributeExtractor type="XML" validate="true" - path="attribute-map.xml"/> - <AttributeResolver type="Query" subjectMatch="true"/> - <AttributeFilter type="XML" validate="true" - path="attribute-policy.xml"/> - - <!-- - Your SP generated these credentials. - They're used to talk to IdP's. - --> - <CredentialResolver type="File" key="sp-key.pem" - certificate="sp-cert.pem"/> - - <ApplicationOverride id="idp_1" entityID="https://<yourhosthere>/shibboleth"> - <Sessions lifetime="28800" timeout="3600" checkAddress="false" - relayState="ss:mem" handlerSSL="false"> - - <!-- Triggers a login request directly to the TestShib IdP. --> - <SSO entityID="https://<idp_1-url>/idp/shibboleth" ECP="true"> - SAML2 SAML1 - </SSO> - - <Logout>SAML2 Local</Logout> - </Sessions> - - <MetadataProvider type="XML" uri="<idp_1-metadata-file>" - backingFilePath="<local idp_1 metadata>" - reloadInterval="180000" /> - - </ApplicationOverride> - - <ApplicationOverride id="idp_2" entityID="https://<yourhosthere>/shibboleth"> - <Sessions lifetime="28800" timeout="3600" checkAddress="false" - relayState="ss:mem" handlerSSL="false"> - - <!-- Triggers a login request directly to the TestShib IdP. --> - <SSO entityID="https://<idp_2-url>/idp/shibboleth" ECP="true"> - SAML2 SAML1 - </SSO> - - <Logout>SAML2 Local</Logout> - </Sessions> - - <MetadataProvider type="XML" uri="<idp_2-metadata-file>" - backingFilePath="<local idp_2 metadata>" - reloadInterval="180000" /> - - </ApplicationOverride> - - </ApplicationDefaults> - - <!-- - Security policies you shouldn't change unless you - know what you're doing. - --> - <SecurityPolicyProvider type="XML" validate="true" - path="security-policy.xml"/> - - <!-- - Low-level configuration about protocols and bindings - available for use. - --> - <ProtocolProvider type="XML" validate="true" reloadChanges="false" - path="protocols.xml"/> - - </SPConfig> - -Keystone enforces `external authentication`_ when the ``REMOTE_USER`` -environment variable is present so make sure Shibboleth doesn't set the -``REMOTE_USER`` environment variable. To do so, scan through the -``/etc/shibboleth/shibboleth2.xml`` configuration file and remove the -``REMOTE_USER`` directives. - -Examine your attributes map file ``/etc/shibboleth/attribute-map.xml`` and adjust -your requirements if needed. For more information see -`attributes documentation <https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPAddAttribute>`_ - -Once you are done, restart your Shibboleth daemon: - -.. _`external authentication`: ../external-auth.html - -.. code-block:: bash - - $ service shibd restart - $ service apache2 restart diff --git a/keystone-moon/doc/source/federation/websso.rst b/keystone-moon/doc/source/federation/websso.rst deleted file mode 100644 index 682449ac..00000000 --- a/keystone-moon/doc/source/federation/websso.rst +++ /dev/null @@ -1,300 +0,0 @@ -:orphan: - -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=============================== -Keystone Federation and Horizon -=============================== - -Keystone Changes -================ - -1. Update `trusted_dashboard` in keystone.conf. - -Specify URLs of trusted horizon servers. This value may be repeated -multiple times. This setting ensures that keystone only sends token data back -to trusted servers. This is performed as a precaution, specifically to -prevent man-in-the-middle (MITM) attacks. - -.. code-block:: ini - - [federation] - trusted_dashboard = http://acme.horizon.com/auth/websso/ - trusted_dashboard = http://beta.horizon.com/auth/websso/ - -2. Update httpd vhost file with websso information. - -The `/v3/auth/OS-FEDERATION/websso/<protocol>` and -`/v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id}/websso` -routes must be protected by the chosen httpd module. This is performed so the -request that originates from horizon will use the same identity provider that -is configured in keystone. - -.. WARNING:: - By using the IdP specific route, a user will no longer leverage the Remote - ID of a specific Identity Provider, and will be unable to verify that the - Identity Provider is trusted, the mapping will remain as the only means to - controlling authorization. - -If `mod_shib` is used, then use the following as an example: - -.. code-block:: xml - - <VirtualHost *:5000> - - ... - - <Location ~ "/v3/auth/OS-FEDERATION/websso/saml2"> - AuthType shibboleth - Require valid-user - ... - </Location> - <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/websso"> - AuthType shibboleth - Require valid-user - ... - </Location> - </VirtualHost> - -If `mod_auth_openidc` is used, then use the following as an example: - -.. code-block:: xml - - <VirtualHost *:5000> - - OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/websso/redirect - OIDCRedirectURI http://localhost:5000/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocol/oidc/websso/redirect - - ... - - <Location ~ "/v3/auth/OS-FEDERATION/websso/oidc"> - AuthType openid-connect - Require valid-user - ... - </Location> - <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/oidc/websso"> - AuthType openid-connect - Require valid-user - ... - </Location> - </VirtualHost> - -If `mod_auth_kerb` is used, then use the following as an example: - -.. code-block:: xml - - <VirtualHost *:5000> - - ... - - <Location ~ "/v3/auth/OS-FEDERATION/websso/kerberos"> - AuthType Kerberos - AuthName "Acme Corporation" - KrbMethodNegotiate on - KrbMethodK5Passwd off - Krb5Keytab /etc/apache2/http.keytab - ... - </Location> - <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/kerberos/websso"> - AuthType Kerberos - AuthName "Acme Corporation" - KrbMethodNegotiate on - KrbMethodK5Passwd off - Krb5Keytab /etc/apache2/http.keytab - ... - </Location> - </VirtualHost> - -If `mod_auth_mellon` is used, then use the following as an example: - -.. code-block:: xml - - <VirtualHost *:5000> - - ... - - <Location ~ "/v3/auth/OS-FEDERATION/websso/saml2"> - AuthType Mellon - MellonEnable auth - Require valid-user - ... - </Location> - <Location ~ "/v3/auth/OS-FEDERATION/identity_providers/idp_1/protocols/saml2/websso"> - AuthType Mellon - MellonEnable auth - Require valid-user - ... - </Location> - </VirtualHost> - -.. NOTE:: - If you are also using SSO via the API, don't forget to make the Location - settings match your configuration used for the keystone identity provider - location: - `/v3/OS-FEDERATION/identity_providers/<idp>/protocols/<protocol>/auth` - -3. Update `remote_id_attribute` in keystone.conf. - -A remote id attribute indicates the header to retrieve from the WSGI -environment. This header contains information about the identity -of the identity provider. For `mod_shib` this would be -``Shib-Identity-Provider``, for `mod_auth_openidc`, this could be -``HTTP_OIDC_ISS``. For `mod_auth_mellon`, this could be ``MELLON_IDP``. - -It is recommended that this option be set on a per-protocol basis. - -.. code-block:: ini - - [saml2] - remote_id_attribute = Shib-Identity-Provider - [oidc] - remote_id_attribute = HTTP_OIDC_ISS - -Alternatively, a generic option may be set at the `[federation]` level. - -.. code-block:: ini - - [federation] - remote_id_attribute = HTTP_OIDC_ISS - -4. Set `remote_ids` for a keystone identity provider using the API or CLI. - -A keystone identity provider may have multiple `remote_ids` specified, this -allows the same *keystone* identity provider resource to be used with multiple -external identity providers. For example, an identity provider resource -``university-idp``, may have the following `remote_ids`: -``['university-x', 'university-y', 'university-z']``. -This removes the need to configure N identity providers in keystone. - -This can be performed using the `OS-FEDERATION API`_: -``PATCH /OS-FEDERATION/identity_providers/{idp_id}`` - -Or by using the `OpenStackClient CLI`_: - -.. code-block:: bash - - $ openstack identity provider set --remote-id <remote-id> <idp-id> - -.. NOTE:: - - Remote IDs are globally unique. Two identity providers cannot be - associated with the same remote ID. Once authenticated with the external - identity provider, keystone will determine which identity provider - and mapping to use based on the protocol and the value returned from the - `remote_id_attribute` key. - - For example, if our identity provider is ``google``, the mapping used is - ``google_mapping`` and the protocol is ``oidc``. The identity provider's - remote IDs would be: [``accounts.google.com``]. - The `remote_id_attribute` value may be set to ``HTTP_OIDC_ISS``, since - this value will always be ``accounts.google.com``. - - The motivation for this approach is that there will always be some data - sent by the identity provider (in the assertion or claim) that uniquely - identifies the identity provider. This removes the requirement for horizon - to list all the identity providers that are trusted by keystone. - -.. _`OpenStackClient CLI`: http://docs.openstack.org/developer/python-openstackclient/command-objects/identity-provider.html#identity-provider-set -.. _`OS-FEDERATION API`: http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3-os-federation-ext.html#update-identity-provider - -Horizon Changes -=============== - -.. NOTE:: - - Django OpenStack Auth version 1.2.0 or higher is required for these steps. - - Identity provider and federation protocol specific webSSO is only available - in Django OpenStack Auth version 2.0.0 or higher. - -1. Set the Identity Service version to 3 - -Ensure the `OPENSTACK_API_VERSIONS` option in horizon's local_settings.py has -been updated to indicate that the `identity` version to use is `3`. - -.. code-block:: python - - OPENSTACK_API_VERSIONS = { - "identity": 3, - } - -2. Authenticate against Identity Server v3. - -Ensure the `OPENSTACK_KEYSTONE_URL` option in horizon's local_settings.py has -been updated to point to a v3 URL. - -.. code-block:: python - - OPENSTACK_KEYSTONE_URL = "http://localhost:5000/v3" - -3. Set the `WEBSSO_ENABLED` option. - -Ensure the `WEBSSO_ENABLED` option is set to True in horizon's local_settings.py file, -this will provide users with an updated login screen for horizon. - -.. code-block:: python - - WEBSSO_ENABLED = True - -4. (Optional) Create a list of authentication methods with the - `WEBSSO_CHOICES` option. - -Within horizon's settings.py file, a list of supported authentication methods can be -specified. The list includes Keystone federation protocols such as OpenID Connect and -SAML, and also keys that map to specific identity provider and federation protocol -combinations (as defined in `WEBSSO_IDP_MAPPING`). With the exception of ``credentials`` -which is reserved by horizon, and maps to the user name and password used by keystone's -identity backend. - -.. code-block:: python - - WEBSSO_CHOICES = ( - ("credentials", _("Keystone Credentials")), - ("oidc", _("OpenID Connect")), - ("saml2", _("Security Assertion Markup Language")), - ("idp_1_oidc", "Acme Corporation - OpenID Connect"), - ("idp_1_saml2", "Acme Corporation - SAML2") - ) - -5. (Optional) Create a dictionary of specific identity provider and federation - protocol combinations. - -A dictionary of specific identity provider and federation protocol combinations. -From the selected authentication mechanism, the value will be looked up as keys -in the dictionary. If a match is found, it will redirect the user to a identity -provider and federation protocol specific WebSSO endpoint in keystone, otherwise -it will use the value as the protocol_id when redirecting to the WebSSO by -protocol endpoint. - -.. code-block:: python - - WEBSSO_IDP_MAPPING = { - "idp_1_oidc": ("idp_1", "oidc"), - "idp_1_saml2": ("idp_1", "saml2") - } - -.. NOTE:: - - The value is expected to be a tuple formatted as: (<idp_id>, <protocol_id>). - -6. (Optional) Specify an initial choice with the `WEBSSO_INITIAL_CHOICE` - option. - -The list set by the `WEBSSO_CHOICES` option will be generated in a drop-down -menu in the login screen. The setting `WEBSSO_INITIAL_CHOICE` will -automatically set that choice to be highlighted by default. - -.. code-block:: python - - WEBSSO_INITIAL_CHOICE = "credentials" diff --git a/keystone-moon/doc/source/http-api.rst b/keystone-moon/doc/source/http-api.rst deleted file mode 100644 index 3b915881..00000000 --- a/keystone-moon/doc/source/http-api.rst +++ /dev/null @@ -1,227 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may not - use this file except in compliance with the License. You may obtain a copy - of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======== -HTTP API -======== - -Specifications -============== - -Keystone implements two major HTTP API versions, along with several API -extensions that build on top of each core API. The two APIs are specified as -`Identity API v2.0`_ and `Identity API v3`_. Each API is specified by a single -source of truth to avoid conflicts between documentation and implementation. -The original source of truth for the v2.0 API is defined by a set of WADL and -XSD files. The original source of truth for the v3 API is defined by -documentation. - -.. _`Identity API v2.0`: http://specs.openstack.org/openstack/keystone-specs/#v2-0-api -.. _`Identity API v3`: http://specs.openstack.org/openstack/keystone-specs/#v3-api - -History -======= - -You're probably wondering why Keystone does not implement a "v1" API. As a -matter of fact, one exists, but it actually predates OpenStack. The v1.x API -was an extremely small API documented and implemented by Rackspace for their -early public cloud products. - -With the advent of OpenStack, Keystone served to provide a superset of the -authentication and multi-tenant authorization models already implemented by -Rackspace's public cloud, Nova, and Swift. Thus, Identity API v2.0 was -introduced. - -Identity API v3 was established to introduce namespacing for users and projects -by using "domains" as a higher-level container for more flexible identity -management and fixed a security issue in the v2.0 API (bearer tokens appearing -in URLs). - -Should I use v2.0 or v3? -======================== - -Identity API v3. - -Identity API v3 is a superset of all the functionality available in v2.0 and -several of its extensions, and provides a much more consistent developer -experience to boot. We're also on the road to deprecating, and ultimately -reducing (or dropping) support for, Identity API v2.0. - -How do I migrate from v2.0 to v3? -================================= - -I am a deployer ---------------- - -You'll need to ensure the v3 API is included in your Paste pipeline, usually -``etc/keystone-paste.ini``. Our `latest sample configuration`_ includes the v3 -application pipeline. - -First define a v3 application, which refers to the v3 application factory -method: - -.. code-block:: ini - - [app:service_v3] - use = egg:keystone#service_v3 - -Then define a v3 pipeline, which terminates with the v3 application you defined -above: - -.. code-block:: ini - - [pipeline:api_v3] - pipeline = ... service_v3 - -Replace "..." with whatever middleware you'd like to run in front of the API -service. Our `latest sample configuration`_ documents our tested -recommendations, but your requirements may vary. - -Finally, include the v3 pipeline in at least one ``composite`` application (but -usually both ``[composite:main]`` and ``[composite:admin]``), for example: - -.. code-block:: ini - - [composite:main] - use = egg:Paste#urlmap - /v3 = api_v3 - ... - -Once your pipeline is configured to expose both v2.0 and v3, you need to ensure -that you've configured your service catalog in Keystone correctly. The -simplest, and most ideal, configuration would expose one identity with -unversioned endpoints (note the lack of ``/v2.0/`` or ``/v3/`` in these URLs): - -- Service (type: ``identity``) - - - Endpoint (interface: ``public``, URL: ``http://identity:5000/``) - - Endpoint (interface: ``admin``, URL: ``http://identity:35357/``) - -If you were to perform a ``GET`` against either of these endpoints, you would -be greeted by an ``HTTP/1.1 300 Multiple Choices`` response, which newer -Keystone clients can use to automatically detect available API versions. - -.. code-block:: bash - - $ curl -i http://identity:35357/ - HTTP/1.1 300 Multiple Choices - Vary: X-Auth-Token - Content-Type: application/json - Content-Length: 755 - Date: Tue, 10 Jun 2014 14:22:26 GMT - - {"versions": {"values": [ ... ]}} - -With unversioned ``identity`` endpoints in the service catalog, you should be -able to `authenticate with keystoneclient`_ successfully. - -.. _`latest sample configuration`: https://git.openstack.org/cgit/openstack/keystone/tree/etc/keystone-paste.ini -.. _`authenticate with keystoneclient`: http://docs.openstack.org/developer/python-keystoneclient/using-api-v3.html#authenticating - -I have a Python client ----------------------- - -The Keystone community provides first-class support for Python API consumers -via our client library, `python-keystoneclient`_. If you're not currently using -this library, you should, as it is intended to expose all of our HTTP API -functionality. If we're missing something you're looking for, please -contribute! - -Adopting `python-keystoneclient`_ should be the easiest way to migrate to -Identity API v3. - -.. _`python-keystoneclient`: https://pypi.python.org/pypi/python-keystoneclient/ - -I have a non-Python client --------------------------- - -You'll likely need to heavily reference our `API documentation`_ to port your -application to Identity API v3. - -.. _`API documentation`: https://git.openstack.org/cgit/openstack-attic/identity-api/tree/v3/src/markdown/identity-api-v3.md - -The most common operation would be password-based authentication including a -tenant name (i.e. project name) to specify an authorization scope. In Identity -API v2.0, this would be a request to ``POST /v2.0/tokens``: - -.. code-block:: javascript - - { - "auth": { - "passwordCredentials": { - "password": "my-password", - "username": "my-username" - }, - "tenantName": "project-x" - } - } - -And you would get back a JSON blob with an ``access`` -> ``token`` -> ``id`` -that you could pass to another web service as your ``X-Auth-Token`` header -value. - -In Identity API v3, an equivalent request would be to ``POST /v3/auth/tokens``: - -.. code-block:: javascript - - { - "auth": { - "identity": { - "methods": [ - "password" - ], - "password": { - "user": { - "domain": { - "id": "default" - }, - "name": "my-username", - "password": "my-password" - } - } - }, - "scope": { - "project": { - "domain": { - "id": "default" - }, - "name": "project-x" - } - } - } - } - -Note a few key differences when compared to the v2.0 API: - -- A "tenant" in v2.0 became a "project" in v3. -- The authentication method (``password``) is explicitly identified. -- Both the user name (``my-username``) and project name (``project-x``) are - namespaced by an owning domain (where ``id`` = ``default``). The "default" - domain exists by default in Keystone, and automatically owns the namespace - exposed by Identity API v2.0. Alternatively, you may reference users and - projects that exist outside the namespace of the default domain, which are - thus inaccessible to the v2.0 API. -- In v3, your token is returned to you in an ``X-Subject-Token`` header, - instead of as part of the request body. You should still authenticate - yourself to other services using the ``X-Auth-Token`` header. - - -HTTP/1.1 Chunked Encoding -========================= -.. WARNING:: - - Running Keystone under HTTPD in the recommended (and tested) configuration does not support - the use of ``Transfer-Encoding: chunked``. This is due to a limitation with the WSGI spec - and the implementation used by ``mod_wsgi``. Support for chunked encoding under ``eventlet`` - may or may not continue. It is recommended that all clients assume Keystone will not support - ``Transfer-Encoding: chunked``. diff --git a/keystone-moon/doc/source/index.rst b/keystone-moon/doc/source/index.rst deleted file mode 100644 index 00e55176..00000000 --- a/keystone-moon/doc/source/index.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -==================================================== -Welcome to Keystone, the OpenStack Identity Service! -==================================================== - -Keystone is an OpenStack project that provides Identity, Token, Catalog and -Policy services for use specifically by projects in the OpenStack family. -It implements `OpenStack's Identity API`_. - -This document describes Keystone for contributors of the project, and assumes -that you are already familiar with Keystone from an `end-user perspective`_. - -.. _`OpenStack's Identity API`: http://specs.openstack.org/openstack/keystone-specs/ -.. _`end-user perspective`: http://docs.openstack.org/ - -This documentation is generated by the Sphinx toolkit and lives in the source -tree. Also see the :doc:`community` page for other ways to interact with the -community. - -Related Identity Projects -========================= - -In addition to creating OpenStack's Identity Service, the Keystone team also -provides a `WSGI middleware`_, as well as `Python client library`_. - -.. _`WSGI middleware`: http://docs.openstack.org/developer/keystonemiddleware/ -.. _`Python client library`: http://docs.openstack.org/developer/python-keystoneclient/ - -Getting Started -=============== - -.. toctree:: - :maxdepth: 1 - - devref/development.environment - installing - configuration - policy_mapping - configure_federation - mapping_combinations - mapping_schema - configure_tokenless_x509 - auth-totp - configuringservices - extensions - key_terms - community - -Man Pages -========= - -.. toctree:: - :maxdepth: 1 - - man/keystone-all - man/keystone-manage - -Developers Documentation -======================== -.. toctree:: - :maxdepth: 1 - - developing - developing_drivers - architecture - middlewarearchitecture - http-api - api_curl_examples - apache-httpd - external-auth - event_notifications - services - online_schema_migration_examples - - -Sample Configuration File -========================= - -.. toctree:: - :maxdepth: 1 - - sample_config - -Code Documentation -================== -.. toctree:: - :maxdepth: 1 - - api/modules - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/keystone-moon/doc/source/installing.rst b/keystone-moon/doc/source/installing.rst deleted file mode 100644 index b00ac6d2..00000000 --- a/keystone-moon/doc/source/installing.rst +++ /dev/null @@ -1,131 +0,0 @@ -.. - Copyright 2012 OpenStack Foundation - Copyright 2012 Nebula, Inc - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=================== -Installing Keystone -=================== - -This document describes how to install Keystone in order to use it. If you are -intending to develop on or with Keystone, please read :doc:`developing` and -:doc:`devref/development.environment`. - -Installing from Source ----------------------- - -The source install instructions specifically avoid using platform specific -packages, instead using the source for the code and the Python Package Index -(PyPi_). - -.. _PyPi: http://pypi.python.org/pypi - -It's expected that your system already has python_, pip_, and git_ available. - -.. _python: http://www.python.org -.. _pip: http://www.pip-installer.org/en/latest/installing.html -.. _git: http://git-scm.com/ - -Clone the Keystone repository: - -.. code-block:: bash - - $ git clone https://git.openstack.org/openstack/keystone.git - $ cd keystone - -Install the Keystone web service: - -.. code-block:: bash - - $ pip install . - -.. NOTE:: - - This step is guaranteed to fail if you do not have the proper binary - dependencies already installed on your development system. Maintaining a - list of platform-specific dependencies is outside the scope of this - documentation, but is within scope of DEVSTACK_. - -You should have all the pieces you need to run Keystone installed on your -system. The following commands should be available on the command-line path: - -* ``keystone`` the Keystone client, used to interact with Keystone -* ``keystone-manage`` used to bootstrap Keystone data -* ``keystone-all`` used to run the Keystone services - -You will find sample configuration files in ``etc/``: - -* ``keystone.conf`` -* ``keystone-paste.ini`` -* ``logging.conf`` -* ``policy.json`` -* ``default_catalog.templates`` - -From here, refer to :doc:`configuration` to choose which backend drivers to -enable and use. Once configured, you should be able to run Keystone by issuing -the command: - -.. code-block:: bash - - $ keystone-all - -By default, this will show logging on the console from which it was started. -Once started, you can initialize data in Keystone for use with the rest of -OpenStack, as described in :doc:`configuringservices`. - -An excellent reference implementation of setting up Keystone is DEVSTACK_, -most commonly used for development and testing setup of not only Keystone, -but all of the core OpenStack projects. - -.. _DEVSTACK: http://docs.openstack.org/developer/devstack/ - -The script with the latest examples of initializing data in Keystone is a -bash script called `lib/keystone`_ - -.. _lib/keystone: https://git.openstack.org/cgit/openstack-dev/devstack/tree/lib/keystone - -Installing from packages: Ubuntu --------------------------------- - -To install keystone on Ubuntu: - -.. code-block:: bash - - $ sudo apt-get install keystone - -In using Ubuntu's packages, the packages will set up a user account for -the Keystone service (`keystone`), and place default configurations in -``/etc/keystone``. As of this writing, the defaults for Keystone backends are -all SQL based, stored locally in SQLite. - -Once installed, you still need to initialize data in Keystone, which you can -find described in :doc:`configuringservices`. - -Installing from packages: Fedora --------------------------------- - -To install Keystone on Fedora refer to the steps found in the `OpenStack -Install Guide`_. - -To install the packages: - -.. code-block:: bash - - $ sudo yum install openstack-keystone - -Once installed, you still need to initialize data in Keystone, which you can -find described in :doc:`configuringservices`. - -.. _`OpenStack Install Guide`: http://docs.openstack.org/liberty/install-guide-rdo/keystone-install.html diff --git a/keystone-moon/doc/source/key_terms.rst b/keystone-moon/doc/source/key_terms.rst deleted file mode 100644 index 11ae576e..00000000 --- a/keystone-moon/doc/source/key_terms.rst +++ /dev/null @@ -1,185 +0,0 @@ -========= -Key Terms -========= - -This document describes the different resource types that are available in -OpenStack's Identity Service. - -Identity -======== - -The Identity portion of keystone includes ``Users`` and ``Groups``, and may be -backed by SQL or more commonly LDAP. - -Users ------ - -``Users`` represent an individual API consumer. A user itself must be owned by -a specific domain, and hence all user names are **not** globally unique, but -only unique to their domain. - -Groups ------- - -``Groups`` are a container representing a collection of users. A group itself -must be owned by a specific domain, and hence all group names are **not** -globally unique, but only unique to their domain. - -Resources -========= - -The Resources portion of keystone includes ``Projects`` and ``Domains``, and -are commonly stored in an SQL backend. - -Projects (Tenants) ------------------- - -``Projects`` (known as Tenants in v2.0) represent the base unit of -``ownership`` in OpenStack, in that all resources in OpenStack should be owned -by a specific project. -A project itself must be owned by a specific domain, and hence all project -names are **not** globally unique, but unique to their domain. -If the domain for a project is not specified, then it is added to the default -domain. - -Domains -------- - -``Domains`` are a high-level container for projects, users and groups. Each is -owned by exactly one domain. Each domain defines a namespace where certain an -API-visible name attribute exists. keystone provides a default domain, aptly -named 'Default'. - -In the Identity v3 API, the uniqueness of attributes is as follows: - -- Domain Name. Globally unique across all domains. - -- Role Name. Globally unique across all domains. - -- User Name. Unique within the owning domain. - -- Project Name. Unique within the owning domain. - -- Group Name. Unique within the owning domain. - -Due to their container architecture, domains may be used as a way to delegate -management of OpenStack resources. A user in a domain may still access -resources in another domain, if an appropriate assignment is granted. - - -Assignment -========== - -Roles ------ - -``Roles`` dictate the level of authorization the end user can obtain. Roles -can be granted at either the domain or project level. Role can be assigned to -the individual user or at the group level. Role names are globally unique. - -Role Assignments ----------------- - -A 3-tuple that has a ``Role``, a ``Resource`` and an ``Identity``. - -What's needed to Authenticate? -============================== - -Two pieces of information are required to authenticate with keystone, a -bit of ``Resource`` information and a bit of ``Identity``. - -Take the following call POST data for instance: - -.. code-block:: javascript - - { - "auth": { - "identity": { - "methods": [ - "password" - ], - "password": { - "user": { - "id": "0ca8f6", - "password": "secretsecret" - } - } - }, - "scope": { - "project": { - "id": "263fd9" - } - } - } - } - -The user (ID of 0ca8f6) is attempting to retrieve a token that is scoped to -project (ID of 263fd9). - -To perform the same call with names instead of IDs, we now need to supply -information about the domain. This is because usernames are only unique within -a given domain, but user IDs are supposed to be unique across the deployment. -Thus, the auth request looks like the following: - -.. code-block:: javascript - - { - "auth": { - "identity": { - "methods": [ - "password" - ], - "password": { - "user": { - "domain": { - "name": "acme" - } - "name": "userA", - "password": "secretsecret" - } - } - }, - "scope": { - "project": { - "domain": { - "id": "1789d1" - }, - "name": "project-x" - } - } - } - } - -For both the user and the project portion, we must supply either a domain ID -or a domain name, in order to properly determine the correct user and project. - -Alternatively, if we wanted to represent this as environment variables for a -command line, it would be: - -.. code-block:: bash - - $ export OS_PROJECT_DOMAIN_ID=1789d1 - $ export OS_USER_DOMAIN_NAME=acme - $ export OS_USERNAME=userA - $ export OS_PASSWORD=secretsecret - $ export OS_PROJECT_NAME=project-x - -Note that the project the user it attempting to access must be in the same -domain as the user. - -What is Scope? -============== - -Scope is an overloaded term. - -In reference to authenticating, as seen above, scope refers to the portion -of the POST data that dictates what ``Resource`` (project or domain) the user -wants to access. - -In reference to tokens, scope refers to the effectiveness of a token, -i.e.: a `project-scoped` token is only useful on the project it was initially -granted for. A `domain-scoped` token may be used to perform domain-related -function. - -In reference to users, groups, and projects, scope often refers to the domain -that the entity is owned by. i.e.: a user in domain X is scoped to domain X. diff --git a/keystone-moon/doc/source/man/keystone-all.rst b/keystone-moon/doc/source/man/keystone-all.rst deleted file mode 100644 index b9c219b3..00000000 --- a/keystone-moon/doc/source/man/keystone-all.rst +++ /dev/null @@ -1,112 +0,0 @@ -============ -keystone-all -============ - ------------------------- -Keystone Startup Command ------------------------- - -:Author: openstack@lists.openstack.org -:Date: 2015-10-15 -:Copyright: OpenStack Foundation -:Version: 8.0.0 -:Manual section: 1 -:Manual group: cloud computing - -SYNOPSIS -======== - -:: - - keystone-all [-h] [--config-dir DIR] [--config-file PATH] [--debug] - [--log-config-append PATH] [--log-date-format DATE_FORMAT] - [--log-dir LOG_DIR] [--log-file PATH] - [--log-format FORMAT] [--nodebug] [--nostandard-threads] - [--nouse-syslog] [--nouse-syslog-rfc-format] [--noverbose] - [--pydev-debug-host PYDEV_DEBUG_HOST] - [--pydev-debug-port PYDEV_DEBUG_PORT] [--standard-threads] - [--syslog-log-facility SYSLOG_LOG_FACILITY] [--use-syslog] - [--use-syslog-rfc-format] [--verbose] [--version] - -DESCRIPTION -=========== - -keystone-all starts both the service and administrative APIs in a single -process to provide catalog, authorization, and authentication services for -OpenStack. - -OPTIONS -======= - - -h, --help show this help message and exit - --config-dir DIR Path to a config directory to pull \*.conf files from. - This file set is sorted, so as to provide a - predictable parse order if individual options are - over-ridden. The set is parsed after the file(s) - specified via previous --config-file, arguments hence - over-ridden options in the directory take precedence. - --config-file PATH Path to a config file to use. Multiple config files - can be specified, with values in later files taking - precedence. The default files used are: None. - --debug, -d Print debugging output (set logging level to DEBUG - instead of default WARNING level). - --log-config-append PATH, --log_config PATH - The name of a logging configuration file. This file is - appended to any existing logging configuration files. - For details about logging configuration files, see the - Python logging module documentation. - --log-date-format DATE_FORMAT - Format string for %(asctime)s in log records. Default: - None . - --log-dir LOG_DIR, --logdir LOG_DIR - (Optional) The base directory used for relative --log- - file paths. - --log-file PATH, --logfile PATH - (Optional) Name of log file to output to. If no - default is set, logging will go to stdout. - --log-format FORMAT DEPRECATED. A logging.Formatter log message format - string which may use any of the available - logging.LogRecord attributes. This option is - deprecated. Please use logging_context_format_string - and logging_default_format_string instead. - --nodebug The inverse of --debug - --nostandard-threads The inverse of --standard-threads - --nouse-syslog The inverse of --use-syslog - --nouse-syslog-rfc-format - The inverse of --use-syslog-rfc-format - --noverbose The inverse of --verbose - --pydev-debug-host PYDEV_DEBUG_HOST - Host to connect to for remote debugger. - --pydev-debug-port PYDEV_DEBUG_PORT - Port to connect to for remote debugger. - --standard-threads Do not monkey-patch threading system modules. - --syslog-log-facility SYSLOG_LOG_FACILITY - Syslog facility to receive log lines. - --use-syslog Use syslog for logging. Existing syslog format is - DEPRECATED during I, and will change in J to honor - RFC5424. - --use-syslog-rfc-format - (Optional) Enables or disables syslog rfc5424 format - for logging. If enabled, prefixes the MSG part of the - syslog message with APP-NAME (RFC5424). The format - without the APP-NAME is deprecated in I, and will be - removed in J. - --verbose, -v Print more verbose output (set logging level to INFO - instead of default WARNING level). - --version show program's version number and exit - -FILES -===== - -None - -SEE ALSO -======== - -* `OpenStack Keystone <http://keystone.openstack.org>`__ - -SOURCE -====== - -* Keystone source is managed in Gerrit git `Keystone <https://git.openstack.org/cgit/openstack/keystone>`__ -* Keystone bugs are managed at Launchpad `Keystone <https://bugs.launchpad.net/keystone>`__ diff --git a/keystone-moon/doc/source/man/keystone-manage.rst b/keystone-moon/doc/source/man/keystone-manage.rst deleted file mode 100644 index a69cf374..00000000 --- a/keystone-moon/doc/source/man/keystone-manage.rst +++ /dev/null @@ -1,130 +0,0 @@ -=============== -keystone-manage -=============== - ---------------------------- -Keystone Management Utility ---------------------------- - -:Author: openstack@lists.openstack.org -:Date: 2016-4-7 -:Copyright: OpenStack Foundation -:Version: 9.0.0 -:Manual section: 1 -:Manual group: cloud computing - -SYNOPSIS -======== - - keystone-manage [options] - -DESCRIPTION -=========== - -``keystone-manage`` is the command line tool which interacts with the Keystone -service to initialize and update data within Keystone. Generally, -``keystone-manage`` is only used for operations that cannot be accomplished -with the HTTP API, such data import/export and database migrations. - -USAGE -===== - - ``keystone-manage [options] action [additional args]`` - -General keystone-manage options: --------------------------------- - -* ``--help`` : display verbose help output. - -Invoking ``keystone-manage`` by itself will give you some usage information. - -Available commands: - -* ``bootstrap``: Perform the basic bootstrap process. -* ``db_sync``: Sync the database. -* ``db_version``: Print the current migration version of the database. -* ``domain_config_upload``: Upload domain configuration file. -* ``fernet_rotate``: Rotate keys in the Fernet key repository. -* ``fernet_setup``: Setup a Fernet key repository. -* ``mapping_purge``: Purge the identity mapping table. -* ``mapping_engine``: Test your federation mapping rules. -* ``pki_setup``: Initialize the certificates used to sign tokens. **deprecated** -* ``saml_idp_metadata``: Generate identity provider metadata. -* ``ssl_setup``: Generate certificates for SSL. -* ``token_flush``: Purge expired tokens. - -OPTIONS -======= - - -h, --help show this help message and exit - --config-dir DIR Path to a config directory to pull \*.conf files from. - This file set is sorted, so as to provide a - predictable parse order if individual options are - over-ridden. The set is parsed after the file(s) - specified via previous --config-file, arguments hence - over-ridden options in the directory take precedence. - --config-file PATH Path to a config file to use. Multiple config files - can be specified, with values in later files taking - precedence. The default files used are: None. - --debug, -d Print debugging output (set logging level to DEBUG - instead of default WARNING level). - --log-config-append PATH, --log_config PATH - The name of a logging configuration file. This file is - appended to any existing logging configuration files. - For details about logging configuration files, see the - Python logging module documentation. - --log-date-format DATE_FORMAT - Format string for %(asctime)s in log records. Default: - None . - --log-dir LOG_DIR, --logdir LOG_DIR - (Optional) The base directory used for relative --log- - file paths. - --log-file PATH, --logfile PATH - (Optional) Name of log file to output to. If no - default is set, logging will go to stdout. - --log-format FORMAT DEPRECATED. A logging.Formatter log message format - string which may use any of the available - logging.LogRecord attributes. This option is - deprecated. Please use logging_context_format_string - and logging_default_format_string instead. - --nodebug The inverse of --debug - --nostandard-threads The inverse of --standard-threads - --nouse-syslog The inverse of --use-syslog - --nouse-syslog-rfc-format - The inverse of --use-syslog-rfc-format - --noverbose The inverse of --verbose - --pydev-debug-host PYDEV_DEBUG_HOST - Host to connect to for remote debugger. - --pydev-debug-port PYDEV_DEBUG_PORT - Port to connect to for remote debugger. - --standard-threads Do not monkey-patch threading system modules. - --syslog-log-facility SYSLOG_LOG_FACILITY - Syslog facility to receive log lines. - --use-syslog Use syslog for logging. Existing syslog format is - DEPRECATED during I, and will change in J to honor - RFC5424. - --use-syslog-rfc-format - (Optional) Enables or disables syslog rfc5424 format - for logging. If enabled, prefixes the MSG part of the - syslog message with APP-NAME (RFC5424). The format - without the APP-NAME is deprecated in I, and will be - removed in J. - --verbose, -v Print more verbose output (set logging level to INFO - instead of default WARNING level). - --version show program's version number and exit - -FILES -===== - -None - -SEE ALSO -======== - -* `OpenStack Keystone <http://keystone.openstack.org>`__ - -SOURCE -====== - -* Keystone is sourced in Gerrit git `Keystone <https://git.openstack.org/cgit/openstack/keystone>`__ -* Keystone bugs are managed at Launchpad `Keystone <https://bugs.launchpad.net/keystone>`__ diff --git a/keystone-moon/doc/source/mapping_combinations.rst b/keystone-moon/doc/source/mapping_combinations.rst deleted file mode 100644 index 1b275a4a..00000000 --- a/keystone-moon/doc/source/mapping_combinations.rst +++ /dev/null @@ -1,650 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may not - use this file except in compliance with the License. You may obtain a copy - of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -=================================== -Mapping Combinations for Federation -=================================== - ------------ -Description ------------ - -Mapping adds a set of rules to map federation attributes to Keystone users and/or -groups. An Identity Provider has exactly one mapping specified per protocol. - -Mapping objects can be used multiple times by different combinations of Identity -Provider and Protocol. - ------------ -Definitions ------------ - -A rule hierarchy looks as follows: - -.. code-block:: javascript - - { - "rules": [ - { - "local": [ - { - "<user> or <group>" - } - ], - "remote": [ - { - "<condition>" - } - ] - } - ] - } - -* `rules`: top-level list of rules. -* `local`: a rule containing information on what local attributes will be mapped. -* `remote`: a rule containing information on what remote attributes will be mapped. -* `<condition>`: contains information on conditions that allow a rule, can only - be set in a `remote` rule. - -------------- -Mapping Rules -------------- - -Mapping Engine --------------- - -The mapping engine can be tested before creating a federated setup. It can be -tested with the ``keystone-manage mapping_engine`` command: - -.. code-block:: bash - - $ keystone-manage mapping_engine --rules <file> --input <file> - -Mapping Conditions ------------------- - -Mappings support 5 different types of conditions: - -``empty``: The rule is matched to all claims containing the remote attribute type. -This condition does not need to be specified. - -``any_one_of``: The rule is matched only if any of the specified strings appear -in the remote attribute type. Condition result is boolean, not the argument that -is passed as input. - -``not_any_of``: The rule is not matched if any of the specified strings appear -in the remote attribute type. Condition result is boolean, not the argument that -is passed as input. - -``blacklist``: The rule allows all except a specified set of groups. Condition -result is the argument(s) passed as input minus what was matched in the -blacklist. - -``whitelist``: The rules allows a specified set of groups. Condition result is -the argument(s) passed as input and is/are also present in the whitelist. - -.. NOTE:: - - ``empty``, ``blacklist`` and ``whitelist`` are the only conditions that can - be used in direct mapping ({0}, {1}, etc.) - -You can combine multiple conditions in a single rule. The schema that needs to be -followed for the mapping rules can be seen in the :doc:`mapping_schema` page. - -Mappings Examples ------------------ - -The following are all examples of mapping rule types. - -empty condition -~~~~~~~~~~~~~~~ - -.. code-block:: javascript - - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0} {1}", - "email": "{2}" - }, - "group": { - "name": "{3}" - } - } - ], - "remote": [ - { - "type": "FirstName" - }, - { - "type": "LastName" - }, - { - "type": "Email" - }, - { - "type": "OIDC_GROUPS" - } - ] - } - ] - } - -.. NOTE:: - - The numbers in braces {} are indices, they map in order. For example:: - - - Mapping to user with the name matching the value in remote attribute FirstName - - Mapping to user with the name matching the value in remote attribute LastName - - Mapping to user with the email matching value in remote attribute Email - - Mapping to a group(s) with the name matching the value(s) in remote attribute OIDC_GROUPS - - - -Groups can have multiple values. Each value must be separated by a `;` -Example: OIDC_GROUPS=developers;testers - - -other conditions -~~~~~~~~~~~~~~~~ - -In ``<other_condition>`` shown below, please supply one of the following: -``any_one_of``, or ``not_any_of``. - -.. code-block:: javascript - - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "id": "0cd5e9" - } - } - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "HTTP_OIDC_GROUPIDS", - "<other_condition>": [ - "HTTP_OIDC_EMAIL" - ] - } - ] - } - ] - } - -In ``<other_condition>`` shown below, please supply one of the following: -``blacklist``, or ``whitelist``. - -.. code-block:: javascript - - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - } - }, - { - "groups": "{1}", - "domain": { - "id": "0cd5e9" - } - } - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "HTTP_OIDC_GROUPIDS", - "<other_condition>": [ - "me@example.com" - ] - } - ] - } - ] - } - -.. NOTE:: - - If the user id and name are not specified in the mapping, the server tries to - directly map ``REMOTE_USER`` environment variable. If this variable is also - unavailable the server returns an HTTP 401 Unauthorized error. - -Group ids and names can be provided in the local section: - -.. code-block:: javascript - - { - "local": [ - { - "group": { - "id":"0cd5e9" - } - } - ] - } - -.. code-block:: javascript - - { - "local": [ - { - "group": { - "name": "developer_group", - "domain": { - "id": "abc1234" - } - } - } - ] - } - -.. code-block:: javascript - - { - "local": [ - { - "group": { - "name": "developer_group", - "domain": { - "name": "private_cloud" - } - } - } - ] - } - - -Output ------- - -If a mapping is valid you will receive the following output: - -.. code-block:: javascript - - { - "group_ids": "[<group-ids>]", - "user": - { - "domain": - { - "id": "Federated" or "<local-domain-id>" - }, - "type": "ephemeral" or "local", - "name": "<local-user-name>", - "id": "<local-user-id>" - }, - "group_names": - [ - { - "domain": - { - "name": "<domain-name>" - }, - "name": - { - "name": "[<groups-names>]" - } - } - { - "domain": - { - "name": "<domain-name>" - }, - "name": - { - "name": "[<groups-names>]" - } - } - ] - } - -The ``type`` parameter specifies the type of user being mapped. The 2 possible -user types are ``local`` and ``ephemeral``.``local`` is displayed if the user -has a domain specified. The user is treated as existing in the backend, hence -the server will fetch user details (id, name, roles, groups).``ephemeral`` is -displayed for a user that does not exist in the backend. - -The ``id`` parameter in the service domain specifies the domain a user belongs -to. ``Federated`` will be displayed if no domain is specified in the local rule. -User is deemed ephemeral and becomes a member of service domain named ``Federated``. -If the domain is specified the local domain's id will be displayed. -If the mapped user is local, mapping engine will discard further group -assigning and return set of roles configured for the user. - -.. NOTE:: - Domain ``Federated`` is a service domain - it cannot be listed, displayed, - added or deleted. There is no need to perform any operation on it prior to - federation configuration. - -Regular Expressions -------------------- - -Regular expressions can be used in a mapping by specifying the ``regex`` key, and -setting it to ``true``. - -.. code-block:: javascript - - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "id": "0cd5e9" - } - }, - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "HTTP_OIDC_GROUPIDS", - "any_one_of": [ - ".*@yeah.com$" - ] - "regex": true - } - ] - } - ] - } - -This allows any user with a claim containing a key with any value in -``HTTP_OIDC_GROUPIDS`` to be mapped to group with id ``0cd5e9``. - -Condition Combinations ----------------------- - -Combinations of mappings conditions can also be done. - -``empty``, ``any_one_of``, and ``not_any_of`` can all be used in the same rule, -but cannot be repeated within the same condition. ``any_one_of`` and -``not_any_of`` are mutually exclusive within a condition's scope. So are -``whitelist`` and ``blacklist``. - -.. code-block:: javascript - - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "id": "0cd5e9" - } - }, - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "cn=IBM_Canada_Lab", - "not_any_of": [ - ".*@naww.com$" - ], - "regex": true - }, - { - "type": "cn=IBM_USA_Lab", - "any_one_of": [ - ".*@yeah.com$" - ] - "regex": true - } - ] - } - ] - } - -As before group names and users can also be provided in the local section. - -This allows any user with the following claim information to be mapped to -group with id 0cd5e9. - -.. code-block:: javascript - - {"UserName":"<any_name>@yeah.com"} - {"cn=IBM_USA_Lab":"<any_name>@yeah.com"} - {"cn=IBM_Canada_Lab":"<any_name>@yeah.com"} - -The following claims will be mapped: - -- any claim containing the key UserName. -- any claim containing key cn=IBM_Canada_Lab that doesn't have the value <any_name>@naww.com. -- any claim containing key cn=IBM_USA_Lab that has value <any_name>@yeah.com. - -Multiple Rules --------------- - -Multiple rules can also be utilized in a mapping. - -.. code-block:: javascript - - { - "rules": [ - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "name": "non-contractors", - "domain": { - "id": "abc1234" - } - } - } - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "orgPersonType", - "not_any_of": [ - "Contractor", - "SubContractor" - ] - } - ] - }, - { - "local": [ - { - "user": { - "name": "{0}" - }, - "group": { - "name": "contractors", - "domain": { - "id": "abc1234" - } - } - } - ], - "remote": [ - { - "type": "UserName" - }, - { - "type": "orgPersonType", - "any_one_of": [ - "Contractor", - "SubContractor" - ] - } - ] - } - ] - } - - -The above assigns groups membership basing on ``orgPersonType`` values: - -- neither ``Contractor`` nor ``SubContractor`` will belong to the ``non-contractors`` group. -- either ``Contractor or ``SubContractor`` will belong to the ``contractors`` group. - -Rules are additive, so permissions will only be granted for the rules that -succeed. All the remote conditions of a rule must be valid. - -When using multiple rules you can specify more than one effective user -identification, but only the first match will be considered and the others -ignored ordered from top to bottom. - -Since rules are additive one can specify one user identification and this will -also work. The best practice for multiple rules is to create a rule for just -user and another rule for just groups. Below is rules example repeated but with -global username mapping. - - -.. code-block:: javascript - - { - "rules": [ - { - "local": [ - "user": { - "id": "{0}" - } - ], - "remote": [ - { - "type": "UserType" - } - ] - }, - { - "local": [ - { - "group": { - "name": "non-contractors", - "domain": { - "id": "abc1234" - } - } - } - ], - "remote": [ - { - "type": "orgPersonType", - "not_any_of": [ - "Contractor", - "SubContractor" - ] - } - ] - }, - { - "local": [ - { - "group": { - "name": "contractors", - "domain": { - "id": "abc1234" - } - } - } - ], - "remote": [ - { - "type": "orgPersonType", - "any_one_of": [ - "Contractor", - "SubContractor" - ] - } - ] - } - ] - } - -Keystone to Keystone --------------------- - -Keystone to Keystone federation also utilizes mappings, but has some -differences. - -An attribute file (``/etc/shibboleth/attribute-map.xml``) is used to add -attributes to the Keystone Identity Provider. Attributes look as follows: - -.. code-block:: xml - - <Attribute name="openstack_user" id="openstack_user"/> - <Attribute name="openstack_user_domain" id="openstack_user_domain"/> - -The Keystone Service Provider must contain a mapping as shown below. -``openstack_user``, and ``openstack_user_domain`` match to the attribute -names we have in the Identity Provider. It will map any user with the name -``user1`` or ``admin`` in the ``openstack_user`` attribute and -``openstack_domain`` attribute ``default`` to a group with id ``abc1234``. - -.. code-block:: javascript - - { - rules = [ - { - "local": [ - { - "group": { - "id": "abc1234" - } - } - ], - "remote": [ - { - "type": "openstack_user", - "any_one_of": [ - "user1", - "admin" - ] - }, - { - "type":"openstack_user_domain", - "any_one_of": [ - "Default" - ] - } - ] - } - ] - } - -The possible attributes that can be used in a mapping are `openstack_user`, -`openstack_user_domain`, `openstack_roles`, `openstack_project`, and -`openstack_project_domain`. diff --git a/keystone-moon/doc/source/mapping_schema.rst b/keystone-moon/doc/source/mapping_schema.rst deleted file mode 100644 index 036df827..00000000 --- a/keystone-moon/doc/source/mapping_schema.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. - Licensed under the Apache License, Version 2.0 (the "License"); you may not - use this file except in compliance with the License. You may obtain a copy - of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============================= -Mapping Schema for Federation -============================= - -Description ------------ - -The schema for mapping is a description of how a mapping should be created. -It shows all the requirements and possibilities for a JSON to be used for mapping. - -Mapping schema is validated with `JSON Schema -<http://json-schema.org/documentation.html>`__ - -Mapping Schema --------------- - -The rules supported must use the following schema: - -.. code-block:: javascript - - { - "type": "object", - "required": ['rules'], - "properties": { - "rules": { - "minItems": 1, - "type": "array", - "items": { - "type": "object", - "required": ['local', 'remote'], - "additionalProperties": False, - "properties": { - "local": { - "type": "array" - }, - "remote": { - "minItems": 1, - "type": "array", - "items": { - "type": "object", - "oneOf": [ - {"$ref": "#/definitions/empty"}, - {"$ref": "#/definitions/any_one_of"}, - {"$ref": "#/definitions/not_any_of"}, - {"$ref": "#/definitions/blacklist"}, - {"$ref": "#/definitions/whitelist"} - ], - } - } - } - } - } - }, - "definitions": { - "empty": { - "type": "object", - "required": ['type'], - "properties": { - "type": { - "type": "string" - }, - }, - "additionalProperties": False, - }, - "any_one_of": { - "type": "object", - "additionalProperties": False, - "required": ['type', 'any_one_of'], - "properties": { - "type": { - "type": "string" - }, - "any_one_of": { - "type": "array" - }, - "regex": { - "type": "boolean" - } - } - }, - "not_any_of": { - "type": "object", - "additionalProperties": False, - "required": ['type', 'not_any_of'], - "properties": { - "type": { - "type": "string" - }, - "not_any_of": { - "type": "array" - }, - "regex": { - "type": "boolean" - } - } - }, - "blacklist": { - "type": "object", - "additionalProperties": False, - "required": ['type', 'blacklist'], - "properties": { - "type": { - "type": "string" - }, - "blacklist": { - "type": "array" - } - } - }, - "whitelist": { - "type": "object", - "additionalProperties": False, - "required": ['type', 'whitelist'], - "properties": { - "type": { - "type": "string" - }, - "whitelist": { - "type": "array" - } - } - } - } - } - -.. NOTE:: - - ``"additionalProperties": False``, shows that only the properties shown can be displayed. - - .. code-block:: javascript - - "whitelist": { - "type": "object", - "additionalProperties": False, - "required": ['type', 'whitelist'], - "properties": { - "type": { - "type": "string" - }, - "whitelist": { - "type": "array" - } - } - } - - Keystone will not accept any other keys in the JSON mapping other than ``type``, and - ``whitelist``. diff --git a/keystone-moon/doc/source/middlewarearchitecture.rst b/keystone-moon/doc/source/middlewarearchitecture.rst deleted file mode 100644 index 7b958510..00000000 --- a/keystone-moon/doc/source/middlewarearchitecture.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======================= -Middleware Architecture -======================= - -Abstract -======== - -The Keystone middleware architecture supports a common authentication protocol -in use between the OpenStack projects. By using Keystone as a common -authentication and authorization mechanism, the OpenStack project can plug in -to existing authentication and authorization systems in use by existing -environments. - -The auth_token middleware is no longer hosted in Keystone and has moved to the -keystonemiddleware project. The `documentation regarding authentication -middleware`_ can be found there. - -.. _`documentation regarding authentication middleware`: http://docs.openstack.org/developer/keystonemiddleware/middlewarearchitecture.html diff --git a/keystone-moon/doc/source/online_schema_migration_examples.rst b/keystone-moon/doc/source/online_schema_migration_examples.rst deleted file mode 100644 index 0e0fb399..00000000 --- a/keystone-moon/doc/source/online_schema_migration_examples.rst +++ /dev/null @@ -1,24 +0,0 @@ - -==================================== -Online SQL schema migration examples -==================================== - -This document links to several examples implementing online SQL schema -migrations to facilitate simultaneously running OpenStack services in -different versions with the same DB schema. - - -* Nova `data migration example - <http://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/flavor-from-sysmeta-to-blob.html>`_ -* Nova `data migration enforcement example - <https://review.openstack.org/#/c/174480/15/nova/db/sqlalchemy/migrate_repo/versions/291_enforce_flavors_migrated.py>`_ - of sqlalchemy migrate/deprecated scripts -* Nova `flavor migration spec - <http://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/flavor-from-sysmeta-to-blob.html>`_ - example of data migrations in the object layer -* Cinder `online schema upgrades spec <https://specs.openstack.org/openstack/cinder-specs/specs/mitaka/online-schema-upgrades.html>`_ - example of migrating a column to a many-to-many relation table - - -For documentation on how to make online migrations move on to -:ref:`Database Schema Migrations <online-migration>`. diff --git a/keystone-moon/doc/source/policy_mapping.rst b/keystone-moon/doc/source/policy_mapping.rst deleted file mode 100644 index 2d3cd60a..00000000 --- a/keystone-moon/doc/source/policy_mapping.rst +++ /dev/null @@ -1,229 +0,0 @@ -=============================== -Mapping of policy target to API -=============================== - -The following table shows the target in the policy.json file for each API. - -========================================================= === -Target API -========================================================= === -identity:get_region GET /v3/regions/{region_id} -identity:list_regions GET /v3/regions -identity:create_region POST /v3/regions -identity:update_region PATCH /v3/regions/{region_id} -identity:delete_region DELETE /v3/regions/{region_id} - -identity:get_service GET /v3/services/{service_id} -identity:list_services GET /v3/services -identity:create_service POST /v3/services -identity:update_service PATCH /v3/services/{service__id} -identity:delete_service DELETE /v3/services/{service__id} - -identity:get_endpoint GET /v3/endpoints/{endpoint_id} -identity:list_endpoints GET /v3/endpoints -identity:create_endpoint POST /v3/endpoints -identity:update_endpoint PATCH /v3/endpoints/{endpoint_id} -identity:delete_endpoint DELETE /v3/endpoints/{endpoint_id} - -identity:get_domain GET /v3/domains/{domain_id} -identity:list_domains GET /v3/domains -identity:create_domain POST /v3/domains -identity:update_domain PATCH /v3/domains/{domain_id} -identity:delete_domain DELETE /v3/domains/{domain_id} - -identity:get_project GET /v3/projects/{project_id} -identity:list_projects GET /v3/projects -identity:list_user_projects GET /v3/users/{user_id}/projects -identity:create_project POST /v3/projects -identity:update_project PATCH /v3/projects/{project_id} -identity:delete_project DELETE /v3/projects/{project_id} - -identity:get_user GET /v3/users/{user_id} -identity:list_users GET /v3/users -identity:create_user POST /v3/users -identity:update_user PATCH /v3/users/{user_id} -identity:delete_user DELETE /v3/users/{user_id} -identity:change_password POST /v3/users/{user_id}/password - -identity:get_group GET /v3/groups/{group_id} -identity:list_groups GET /v3/groups -identity:list_groups_for_user GET /v3/users/{user_id}/groups -identity:create_group POST /v3/groups -identity:update_group PATCH /v3/groups/{group_id} -identity:delete_group DELETE /v3/groups/{group_id} -identity:list_users_in_group GET /v3/groups/{group_id}/users -identity:remove_user_from_group DELETE /v3/groups/{group_id}/users/{user_id} -identity:check_user_in_group GET /v3/groups/{group_id}/users/{user_id} -identity:add_user_to_group PUT /v3/groups/{group_id}/users/{user_id} - -identity:get_credential GET /v3/credentials/{credential_id} -identity:list_credentials GET /v3/credentials -identity:create_credential POST /v3/credentials -identity:update_credential PATCH /v3/credentials/{credential_id} -identity:delete_credential DELETE /v3/credentials/{credential_id} - -identity:ec2_get_credential GET /v3/users/{user_id}/credentials/OS-EC2/{credential_id} -identity:ec2_list_credentials GET /v3/users/{user_id}/credentials/OS-EC2 -identity:ec2_create_credential POST /v3/users/{user_id}/credentials/OS-EC2 -identity:ec2_delete_credential DELETE /v3/users/{user_id}/credentials/OS-EC2/{credential_id} - -identity:get_role GET /v3/roles/{role_id} -identity:list_roles GET /v3/roles -identity:create_role POST /v3/roles -identity:update_role PATCH /v3/roles/{role_id} -identity:delete_role DELETE /v3/roles/{role_id} - -identity:get_domain_role GET /v3/roles/{role_id} where role.domain_id is not null -identity:list_domain_roles GET /v3/roles?domain_id where role.domain_id is not null -identity:create_domain_role POST /v3/roles where role.domain_id is not null -identity:update_domain_role PATCH /v3/roles/{role_id} where role.domain_id is not null -identity:delete_domain_role DELETE /v3/roles/{role_id} where role.domain_id is not null - -identity:get_implied_role GET /v3/roles/{prior_role_id}/implies/{implied_role_id} -identity:list_implied_roles GET /v3/roles/{prior_role_id}/implies -identity:create_implied_role PUT /v3/roles/{prior_role_id}/implies/{implied_role_id} -identity:delete_implied_role DELETE /v3/roles/{prior_role_id}/implies/{implied_role_id} -identity:list_role_inference_rules GET /v3/role_inferences -identity:check_implied_role HEAD /v3/roles/{prior_role_id}/implies/{implied_role_id} - -identity:check_grant GET `grant_resources`_ -identity:list_grants GET `grant_collections`_ -identity:create_grant PUT `grant_resources`_ -identity:revoke_grant DELETE `grant_resources`_ - -identity:list_role_assignments GET /v3/role_assignments -identity:list_role_assignments_for_tree GET /v3/role_assignments?include_subtree - -identity:get_policy GET /v3/policy/{policy_id} -identity:list_policies GET /v3/policy -identity:create_policy POST /v3/policy -identity:update_policy PATCH /v3/policy/{policy_id} -identity:delete_policy DELETE /v3/policy/{policy_id} - -identity:check_token HEAD /v3/auth/tokens -identity:validate_token - GET /v2.0/tokens/{token_id} - - GET /v3/auth/tokens -identity:validate_token_head HEAD /v2.0/tokens/{token_id} -identity:revocation_list - GET /v2.0/tokens/revoked - - GET /v3/auth/tokens/OS-PKI/revoked -identity:revoke_token DELETE /v3/auth/tokens -identity:create_trust POST /v3/OS-TRUST/trusts -identity:list_trusts GET /v3/OS-TRUST/trusts -identity:list_roles_for_trust GET /v3/OS-TRUST/trusts/{trust_id}/roles -identity:get_role_for_trust GET /v3/OS-TRUST/trusts/{trust_id}/roles/{role_id} -identity:delete_trust DELETE /v3/OS-TRUST/trusts/{trust_id} - -identity:create_consumer POST /v3/OS-OAUTH1/consumers -identity:get_consumer GET /v3/OS-OAUTH1/consumers/{consumer_id} -identity:list_consumers GET /v3/OS-OAUTH1/consumers -identity:delete_consumer DELETE /v3/OS-OAUTH1/consumers/{consumer_id} -identity:update_consumer PATCH /v3/OS-OAUTH1/consumers/{consumer_id} - -identity:authorize_request_token PUT /v3/OS-OAUTH1/authorize/{request_token_id} -identity:list_access_token_roles GET /v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}/roles -identity:get_access_token_role GET /v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id}/roles/{role_id} -identity:list_access_tokens GET /v3/users/{user_id}/OS-OAUTH1/access_tokens -identity:get_access_token GET /v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id} -identity:delete_access_token DELETE /v3/users/{user_id}/OS-OAUTH1/access_tokens/{access_token_id} - -identity:list_projects_for_endpoint GET /v3/OS-EP-FILTER/endpoints/{endpoint_id}/projects -identity:add_endpoint_to_project PUT /v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id} -identity:check_endpoint_in_project GET /v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id} -identity:list_endpoints_for_project GET /v3/OS-EP-FILTER/projects/{project_id}/endpoints -identity:remove_endpoint_from_project DELETE /v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id} - -identity:create_endpoint_group POST /v3/OS-EP-FILTER/endpoint_groups -identity:list_endpoint_groups GET /v3/OS-EP-FILTER/endpoint_groups -identity:get_endpoint_group GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id} -identity:update_endpoint_group PATCH /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id} -identity:delete_endpoint_group DELETE /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id} -identity:list_projects_associated_with_endpoint_group GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects -identity:list_endpoints_associated_with_endpoint_group GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/endpoints -identity:get_endpoint_group_in_project GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id} -identity:list_endpoint_groups_for_project GET /v3/OS-EP-FILTER/projects/{project_id}/endpoint_groups -identity:add_endpoint_group_to_project PUT /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id} -identity:remove_endpoint_group_from_project DELETE /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id} - -identity:create_identity_provider PUT /v3/OS-FEDERATION/identity_providers/{idp_id} -identity:list_identity_providers GET /v3/OS-FEDERATION/identity_providers -identity:get_identity_providers GET /v3/OS-FEDERATION/identity_providers/{idp_id} -identity:update_identity_provider PATCH /v3/OS-FEDERATION/identity_providers/{idp_id} -identity:delete_identity_provider DELETE /v3/OS-FEDERATION/identity_providers/{idp_id} - -identity:create_protocol PUT /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id} -identity:update_protocol PATCH /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id} -identity:get_protocol GET /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id} -identity:list_protocols GET /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols -identity:delete_protocol DELETE /v3/OS-FEDERATION/identity_providers/{idp_id}/protocols/{protocol_id} - -identity:create_mapping PUT /v3/OS-FEDERATION/mappings/{mapping_id} -identity:get_mapping GET /v3/OS-FEDERATION/mappings/{mapping_id} -identity:list_mappings GET /v3/OS-FEDERATION/mappings -identity:delete_mapping DELETE /v3/OS-FEDERATION/mappings/{mapping_id} -identity:update_mapping PATCH /v3/OS-FEDERATION/mappings/{mapping_id} - -identity:create_service_provider PUT /v3/OS-FEDERATION/service_providers/{sp_id} -identity:list_service_providers GET /v3/OS-FEDERATION/service_providers -identity:get_service_provider GET /v3/OS-FEDERATION/service_providers/{sp_id} -identity:update_service_provider PATCH /v3/OS-FEDERATION/service_providers/{sp_id} -identity:delete_service_provider DELETE /v3/OS-FEDERATION/service_providers/{sp_id} - -identity:get_auth_catalog GET /v3/auth/catalog -identity:get_auth_projects GET /v3/auth/projects -identity:get_auth_domains GET /v3/auth/domains - -identity:list_projects_for_groups GET /v3/OS-FEDERATION/projects -identity:list_domains_for_groups GET /v3/OS-FEDERATION/domains - -identity:list_revoke_events GET /v3/OS-REVOKE/events - -identity:create_policy_association_for_endpoint PUT /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id} -identity:check_policy_association_for_endpoint GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id} -identity:delete_policy_association_for_endpoint DELETE /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id} -identity:create_policy_association_for_service PUT /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id} -identity:check_policy_association_for_service GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id} -identity:delete_policy_association_for_service DELETE /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id} -identity:create_policy_association_for_region_and_service PUT /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}/regions/{region_id} -identity:check_policy_association_for_region_and_service GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}/regions/{region_id} -identity:delete_policy_association_for_region_and_service DELETE /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}/regions/{region_id} -identity:get_policy_for_endpoint GET /v3/endpoints/{endpoint_id}/OS-ENDPOINT-POLICY/policy -identity:list_endpoints_for_policy GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints - -identity:create_domain_config PUT /v3/domains/{domain_id}/config -identity:get_domain_config - GET /v3/domains/{domain_id}/config - - GET /v3/domains/{domain_id}/config/{group} - - GET /v3/domains/{domain_id}/config/{group}/{option} -identity:update_domain_config - PATCH /v3/domains/{domain_id}/config - - PATCH /v3/domains/{domain_id}/config/{group} - - PATCH /v3/domains/{domain_id}/config/{group}/{option} -identity:delete_domain_config - DELETE /v3/domains/{domain_id}/config - - DELETE /v3/domains/{domain_id}/config/{group} - - DELETE /v3/domains/{domain_id}/config/{group}/{option} -identity:get_domain_config_default - GET /v3/domains/config/default - - GET /v3/domains/config/{group}/default - - GET /v3/domains/config/{group}/{option}/default -========================================================= === - -.. _grant_resources: - -*grant_resources* are: - -- /v3/projects/{project_id}/users/{user_id}/roles/{role_id} -- /v3/projects/{project_id}/groups/{group_id}/roles/{role_id} -- /v3/domains/{domain_id}/users/{user_id}/roles/{role_id} -- /v3/domains/{domain_id}/groups/{group_id}/roles/{role_id} -- /v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects -- /v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects -- /v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects -- /v3/OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects - -.. _grant_collections: - -*grant_collections* are: - -- /v3/projects/{project_id}/users/{user_id}/roles -- /v3/projects/{project_id}/groups/{group_id}/roles -- /v3/domains/{domain_id}/users/{user_id}/roles -- /v3/domains/{domain_id}/groups/{group_id}/role -- /v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/inherited_to_projects -- /v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/inherited_to_projects diff --git a/keystone-moon/doc/source/sample_config.rst b/keystone-moon/doc/source/sample_config.rst deleted file mode 100644 index b170f848..00000000 --- a/keystone-moon/doc/source/sample_config.rst +++ /dev/null @@ -1,12 +0,0 @@ -============================== -Keystone Configuration Options -============================== - -The following is a sample keystone configuration for adaptation and use. It is -auto-generated from keystone when this documentation is built, so if you are -having issues with an option, please compare your version of keystone with the -version of this documentation. - -The sample configuration can also be viewed in `file form <_static/keystone.conf.sample>`_. - -.. literalinclude:: _static/keystone.conf.sample diff --git a/keystone-moon/doc/source/services.rst b/keystone-moon/doc/source/services.rst deleted file mode 100644 index 2c71e450..00000000 --- a/keystone-moon/doc/source/services.rst +++ /dev/null @@ -1,200 +0,0 @@ -=========================== -Keystone for other services -=========================== - -This document provides a summary of some things that other services need to -know about how keystone works, and specifically about how they can take -advantage of the v3 API. - -The v3 API was introduced as a stable API in the Grizzly release and included -in the default pipeline ever since. Until recently, its use has been hidden -from other services because the ``auth_token`` middleware translated the token -format so that both versions look the same. Once the services need to make use -of v3 features they need to know about how it works. - - -Glossary -======== - -Service - OpenStack services like identity, compute, image, etc. - -Project - A project provides namespace and resource isolation for groups of OpenStack - entities. Users must be assigned a role on a project in order to interact - with it. Prior to the introduction of the v3 API, projects were referred to - as tenants and the term is still used in reference to the v2.0 API. - - -Domains -======= - -A major new feature in v3 is domains. Every project, user, and user group is -owned by a domain (reflected by their ``domain_id`` value) which provides them -their own namespace. For example, unlike in v2.0, usernames are no longer -unique across the deployment. You can have two users with the same name, but -they must be in different domains. However, user IDs are assigned to users by -keystone and are expected to be unique across the deployment. All of this logic -applies to both projects and user groups as well. Note that roles are *not* -namespaced by domains. - -One of the great things about domains is that you can have one domain backed by -SQL (for service users) and another backed by LDAP (the cloud is deployed into -existing infrastructure). - -The "default" domain -==================== - -Conventionally the "default" domain has a domain ID of ``default`` and a domain -name of ``Default``. It is created by ``keystone-manage db_sync`` and thus -should always exist, although the domain ID is configurable in -``keystone.conf`` and the domain name is mutable through the v3 API. - -Because only the v3 API is domain-aware, we must work to avoid perceived -namespace conflicts to v2.0 clients. The solution to this is to have a single -domain serve as the implied namespace for all user and tenant references in -v2.0. Thus, v2.0 clients can continue to be domain-unaware and avoid the -security risk posed by potential namespace conflicts. *This is the only purpose -of the default domain.* - -For example, I could otherwise create a domain in v3, create a user in that -domain called "admin", authenticate using v2.0, and a domain-unaware v2.0 -client might assume I'm the same "admin" user it has seen before and grant me -escalated privileges. Instead, users outside of the default domain simply -cannot authenticate against v2.0, nor can such tokens with references to users -and projects outside the default domain be validated on the v2.0 API. - -From a v2.0 client's perspective, there's no way to specify the domain, so v2.0 -operations implicitly work against the default domain. So if your client is -only capable of using v2.0 and you need to get a token, then you can only get -tokens for users and tenants (projects) in the default domain. In the real -world, this means that if your default domain is backed by SQL and you have a -separate domain for LDAP users, then you can't authenticate as an LDAP user -using v2.0. Conversely, if your default domain is backed by a read-only LDAP -driver, then you won't be able to create the service users using v2.0 clients -because any SQL-backed domain is unreachable. - -From a v3 client's perspective, the default domain is not special, other than -the fact that such a domain can generally be assumed to exist (assuming the -deployment is also running the v2.0 API). It would be reasonable for a v3 -client to assume a default user domain ID of ``default`` and a default project -domain ID of ``default`` unless overridden by more specific configuration. - -To summarize, avoiding namespace conflicts in the v2.0 API is achieved by -limiting the v2.0 API and its clients to working with users and projects which -are namespaced by a single, arbitrary domain in v3. - -Token differences -================= - -The keystone service runs both v2.0 and v3, where v2.0 requests go to the -``/v2.0`` endpoint and v3 requests go to the ``/v3`` endpoint. If you're using -the default pipeline that ships with keystone, then you don't need "enable" the -v3 API in keystone, as it runs by default as a parallel pipeline to the v2.0 -API. - -If you get a token using the v2.0 API, then you can use it to do v3 operations -(such as list users). The reverse, using a v3 token against v2.0, is possible -only in certain circumstances. For example, if you're using a project-scoped -token wherein the user and project are both owned by the "default" domain, -everything will work. Otherwise, token validation against the v2.0 API will -fail. - -You can get a v2.0 token using ``POST /v2.0/tokens``. You can get a v3 token -using ``POST /v3/auth/tokens``. Note that the responses are significantly -different. For example, the service catalog is in a different format, and the -v3 token conveys additional context (such as the user's domain and the -project's domain). - -Domain-scoped tokens --------------------- - -Domain-scoped tokens are scoped to a domain rather than a project. These are -useful for operating against keystone but are generally useless in other -services that don't have use cases for domain-level operations. Unless a -service has a real case for handling such authorization, they don't need to -concern themselves with domain-scoped tokens. - - -Auth Token middleware -===================== - -The ``auth_token`` middleware handles token validation for the different -services. Conceptually, what happens is that ``auth_token`` pulls the token out -of the ``X-Auth-Token`` request header, validates the token using keystone, -produces information about the identity (the API user) and authorization -context (the project, roles, etc) of the token, and sets environment variables -with that data. The services typically take the environment variables, put them -in the service's "context", and use the context for policy enforcement via -``oslo.policy``. - -Service tokens --------------- - -Service tokens are a feature where the ``auth_token`` middleware will also -accept a service token in the ``X-Service-Token`` header. It does the same -thing with the service token as the user token, but the results of the token -are passed separately in environment variables for the service token (the -service user, project, and roles). If the service knows about these then it can -put this info in its "context" and use it for policy checks. For example, -assuming there's a special policy rule called ``service_role`` that works like -the ``role`` rule except checks the service roles, you could have an -``oslo.policy`` rule like ``service_role:service and user_id:%(user_id)s`` such -that a service token is required along with the user owning the object. - -v2.0 or v3? ------------ - -By default, the ``auth_token`` middleware will use discovery to determine the -best available API to use, or can be explicitly configured to use either v2.0 -or v3. When discovery is used, ``auth_token`` will use v3 if keystone reports -that v3 is available. If ``auth_token`` is configured to use v2.0, then it will -fail when it receives a v3 token wherein the user is not in the default domain -(for example, the domain that heat creates users in). So if at all possible, -the ``auth_token`` middleware should be allowed to use v3. - -Additionally, as other services begin to utilize features which are only found -in the v3 API, you'll need to use the v3 API in order to utilize those -services. For example, heat creates users in an isolated domain, and thus -requires the v3 API. - -Do this, not that -================= - -Config options for authentication ---------------------------------- - -If you need to get a token, don't define options for username and password and -get a token using v2.0. We've got an interface for using authentication plugins -where there's an option for that supports v2.0 or v3 and potentially other -authentication mechanisms (X.509 client certs!). - -If your config file doesn't have the domain for the user, it's not going to be -able to use v3 for authentication. - -Picking the version -------------------- - -Use version discovery to figure out what version the identity server supports -rather than configuring the version. - -Use OpenStack CLI not keystone CLI ----------------------------------- - -The keystone CLI is deprecated and will be removed soon. The `OpenStack CLI -<http://docs.openstack.org/developer/python-openstackclient/>`_ has all the -keystone CLI commands and even supports v3. - - -Hierarchical Multitenancy -========================= - -This feature allows maintenance of a hierarchy of projects with "parent" -projects operating as domains. - -The token format is the same (the token doesn't contain any info about the -hierarchy). If the service needs to know the hierarchy it will have to use the -v3 API to fetch the hierarchy. - -While you can't use v2.0 to set up the hierarchy, you can get a v2.0 token -scoped to a project that's part of a hierarchy. diff --git a/keystone-moon/doc/source/setup.rst b/keystone-moon/doc/source/setup.rst deleted file mode 100644 index d1ce8f4c..00000000 --- a/keystone-moon/doc/source/setup.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. - Copyright 2011-2012 OpenStack Foundation - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -============================================= -Setting up a Keystone development environment -============================================= - -This document describes getting the source from keystone's `Git repository`_ -for development purposes. - -To install Keystone from packaging, refer instead to Keystone's `User -Documentation`_. - -.. _`Git Repository`: http://git.openstack.org/cgit/openstack/keystone -.. _`User Documentation`: http://docs.openstack.org/ - -Prerequisites -============= - -This document assumes you are using Ubuntu, Fedora or openSUSE (SLE) - -And that you have the following tools available on your system: - -- Python_ 2.7 and 3.4 -- git_ -- setuptools_ -- pip_ -- msgfmt (part of the gettext package) -- virtualenv_ - -**Reminder**: If you're successfully using a different platform, or a -different version of the above, please document your configuration here! - -.. _Python: http://www.python.org/ -.. _git: http://git-scm.com/ -.. _setuptools: http://pypi.python.org/pypi/setuptools - -Getting the latest code -======================= - -Make a clone of the code from our `Git repository`: - -.. code-block:: bash - - $ git clone https://git.openstack.org/openstack/keystone.git - -When that is complete, you can: - -.. code-block:: bash - - $ cd keystone - -Installing dependencies -======================= - -Keystone maintains two lists of dependencies:: - - requirements.txt - test-requirements.txt - -The first is the list of dependencies needed for running keystone, the second list includes dependencies used for active development and testing of Keystone itself. - -These dependencies can be installed from PyPi_ using the Python tool pip_. - -.. _PyPi: http://pypi.python.org/ -.. _pip: http://pypi.python.org/pypi/pip - -However, your system *may* need additional dependencies that `pip` (and by -extension, PyPi) cannot satisfy. These dependencies should be installed -prior to using `pip`, and the installation method may vary depending on -your platform. - -Ubuntu 14.04: - -.. code-block:: bash - - $ sudo apt-get install python-dev python3-dev libxml2-dev libxslt1-dev \ - libsasl2-dev libsqlite3-dev libssl-dev libldap2-dev libffi-dev - - -Fedora 19+: - -.. code-block:: bash - - $ sudo yum install python-lxml python-greenlet-devel python-ldap sqlite-devel openldap-devel python-devel libxslt-devel openssl-devel libffi-devel - -openSUSE 13.2 (SLE 12): - -.. code-block:: bash - - $ sudo zypper install libxslt-devel openldap2-devel libopenssl-devel python-devel python-greenlet-devel python-ldap python-lxml python-pysqlite sqlite3-devel - -PyPi Packages and VirtualEnv ----------------------------- - -We recommend establishing a virtualenv to run Keystone within. virtualenv -limits the Python environment to just what you're installing as dependencies, -useful to keep a clean environment for working on Keystone. The tools directory -in Keystone has a script already created to make this very simple: - -.. code-block:: bash - - $ python tools/install_venv.py - -This will create a local virtual environment in the directory ``.venv``. -Once created, you can activate this virtualenv for your current shell using: - -.. code-block:: bash - - $ source .venv/bin/activate - -The virtual environment can be disabled using the command: - -.. code-block:: bash - - $ deactivate - -You can also use ``tools\with_venv.sh`` to prefix commands so that they run -within the virtual environment. For more information on virtual environments, -see virtualenv_. - -.. _virtualenv: http://www.virtualenv.org/ - -If you want to run Keystone outside of a virtualenv, you can install the -dependencies directly into your system from the requirements files: - -.. code-block:: bash - - # Install the dependencies for running keystone - $ pip install -r requirements.txt - - # Install the dependencies for developing, testing, and running keystone - $ pip install -r test-requirements.txt - - # Use 'python setup.py' to link Keystone into Python's site-packages - $ python setup.py develop - - -Verifying Keystone is set up -============================ - -Once set up, either directly or within a virtualenv, you should be able to -invoke Python and import the libraries. If you're using a virtualenv, don't -forget to activate it: - -.. code-block:: bash - - $ source .venv/bin/activate - -You should then be able to `import keystone` using Python without issue: - -.. code-block:: bash - - $ python -c "import keystone" - -If you can import Keystone without a traceback, you should be ready to move on -to :doc:`developing`. |