summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSamriddhi Jain <j.samriddhi13@gmail.com>2017-05-31 20:01:23 +0530
committerSamriddhi Jain <j.samriddhi13@gmail.com>2017-06-24 00:42:14 +0530
commitaba92673238984f98a42005bd7f27940c72cc419 (patch)
tree36e310d1d4a05b9180656a705dc49f37876e1465
parentd6160630b03d0bbfc179f6b507db1e92d57562cc (diff)
Added keystone admin guides to documentation
Currently the identity administrator guide docs are a part of general OpenStack-manuals. Migrating those docs to keystone documentation so that they can be reviewed effectively by keystone developers too. Partial-Bug #1694460 Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454 Change-Id: Id121ae1dd5bce993b4ad1219b592527ef0047063
Notes
Notes (review): Code-Review+2: Lance Bragstad <lbragstad@gmail.com> Code-Review+2: Colleen Murphy <colleen@gazlene.net> Code-Review+2: Samuel de Medeiros Queiroz <samueldmq@gmail.com> Workflow+1: Samuel de Medeiros Queiroz <samueldmq@gmail.com> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Fri, 23 Jun 2017 22:06:01 +0000 Reviewed-on: https://review.openstack.org/469515 Project: openstack/keystone Branch: refs/heads/master
-rw-r--r--doc/source/admin/identity-auth-token-middleware.rst74
-rw-r--r--doc/source/admin/identity-caching-layer.rst128
-rw-r--r--doc/source/admin/identity-certificates-for-pki.rst237
-rw-r--r--doc/source/admin/identity-concepts.rst354
-rw-r--r--doc/source/admin/identity-domain-specific-config.rst69
-rw-r--r--doc/source/admin/identity-external-authentication.rst41
-rw-r--r--doc/source/admin/identity-fernet-token-faq.rst345
-rw-r--r--doc/source/admin/identity-integrate-with-ldap.rst453
-rw-r--r--doc/source/admin/identity-keystone-usage-and-features.rst83
-rw-r--r--doc/source/admin/identity-management.rst31
-rw-r--r--doc/source/admin/identity-security-compliance.rst167
-rw-r--r--doc/source/admin/identity-service-api-protection.rst128
-rw-r--r--doc/source/admin/identity-token-binding.rst64
-rw-r--r--doc/source/admin/identity-tokens.rst108
-rw-r--r--doc/source/admin/identity-troubleshoot.rst199
-rw-r--r--doc/source/admin/identity-use-trusts.rst56
-rw-r--r--doc/source/index.rst8
17 files changed, 2545 insertions, 0 deletions
diff --git a/doc/source/admin/identity-auth-token-middleware.rst b/doc/source/admin/identity-auth-token-middleware.rst
new file mode 100644
index 0000000..291d4f7
--- /dev/null
+++ b/doc/source/admin/identity-auth-token-middleware.rst
@@ -0,0 +1,74 @@
1Authentication middleware with user name and password
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4You can also configure Identity authentication middleware using the
5``admin_user`` and ``admin_password`` options.
6
7.. note::
8
9 The ``admin_token`` option is deprecated and no longer used for
10 configuring auth_token middleware.
11
12For services that have a separate paste-deploy ``.ini`` file, you can
13configure the authentication middleware in the ``[keystone_authtoken]``
14section of the main configuration file, such as ``nova.conf``. In
15Compute, for example, you can remove the middleware parameters from
16``api-paste.ini``, as follows:
17
18.. code-block:: ini
19
20 [filter:authtoken]
21 paste.filter_factory = keystonemiddleware.auth_token:filter_factory
22
23
24And set the following values in ``nova.conf`` as follows:
25
26.. code-block:: ini
27
28 [DEFAULT]
29 # ...
30 auth_strategy=keystone
31
32 [keystone_authtoken]
33 auth_uri = http://controller:5000/v2.0
34 identity_uri = http://controller:35357
35 admin_user = admin
36 admin_password = SuperSekretPassword
37 admin_tenant_name = service
38
39.. note::
40
41 The middleware parameters in the paste config take priority. You
42 must remove them to use the values in the ``[keystone_authtoken]``
43 section.
44
45.. note::
46
47 Comment out any ``auth_host``, ``auth_port``, and
48 ``auth_protocol`` options because the ``identity_uri`` option
49 replaces them.
50
51This sample paste config filter makes use of the ``admin_user`` and
52``admin_password`` options:
53
54.. code-block:: ini
55
56 [filter:authtoken]
57 paste.filter_factory = keystonemiddleware.auth_token:filter_factory
58 auth_uri = http://controller:5000/v2.0
59 identity_uri = http://controller:35357
60 auth_token = 012345SECRET99TOKEN012345
61 admin_user = admin
62 admin_password = keystone123
63
64.. note::
65
66 Using this option requires an admin project/role relationship. The
67 admin user is granted access to the admin role on the admin project.
68
69.. note::
70
71 Comment out any ``auth_host``, ``auth_port``, and
72 ``auth_protocol`` options because the ``identity_uri`` option
73 replaces them.
74
diff --git a/doc/source/admin/identity-caching-layer.rst b/doc/source/admin/identity-caching-layer.rst
new file mode 100644
index 0000000..7fb62b1
--- /dev/null
+++ b/doc/source/admin/identity-caching-layer.rst
@@ -0,0 +1,128 @@
1.. :orphan:
2
3Caching layer
4~~~~~~~~~~~~~
5
6OpenStack Identity supports a caching layer that is above the
7configurable subsystems (for example, token). OpenStack Identity uses the
8`oslo.cache <https://docs.openstack.org/developer/oslo.cache/>`__
9library which allows flexible cache back ends. The majority of the
10caching configuration options are set in the ``[cache]`` section of the
11``/etc/keystone/keystone.conf`` file. However, each section that has
12the capability to be cached usually has a caching boolean value that
13toggles caching.
14
15So to enable only the token back end caching, set the values as follows:
16
17.. code-block:: ini
18
19 [cache]
20 enabled=true
21
22 [catalog]
23 caching=false
24
25 [domain_config]
26 caching=false
27
28 [federation]
29 caching=false
30
31 [resource]
32 caching=false
33
34 [revoke]
35 caching=false
36
37 [role]
38 caching=false
39
40 [token]
41 caching=true
42
43.. note::
44
45 Since the Newton release, the default setting is enabled for subsystem
46 caching and the global toggle. As a result, all subsystems that support
47 caching are doing this by default.
48
49Caching for tokens and tokens validation
50----------------------------------------
51
52All types of tokens benefit from caching, including Fernet tokens. Although
53Fernet tokens do not need to be persisted, they should still be cached for
54optimal token validation performance.
55
56The token system has a separate ``cache_time`` configuration option,
57that can be set to a value above or below the global ``expiration_time``
58default, allowing for different caching behavior from the other systems
59in OpenStack Identity. This option is set in the ``[token]`` section of
60the configuration file.
61
62The token revocation list cache time is handled by the configuration
63option ``revocation_cache_time`` in the ``[token]`` section. The
64revocation list is refreshed whenever a token is revoked. It typically
65sees significantly more requests than specific token retrievals or token
66validation calls.
67
68Here is a list of actions that are affected by the cached time: getting
69a new token, revoking tokens, validating tokens, checking v2 tokens, and
70checking v3 tokens.
71
72The delete token API calls invalidate the cache for the tokens being
73acted upon, as well as invalidating the cache for the revoked token list
74and the validate/check token calls.
75
76Token caching is configurable independently of the ``revocation_list``
77caching. Lifted expiration checks from the token drivers to the token
78manager. This ensures that cached tokens will still raise a
79``TokenNotFound`` flag when expired.
80
81For cache consistency, all token IDs are transformed into the short
82token hash at the provider and token driver level. Some methods have
83access to the full ID (PKI Tokens), and some methods do not. Cache
84invalidation is inconsistent without token ID normalization.
85
86Caching for non-token resources
87-------------------------------
88
89Various other keystone components have a separate ``cache_time`` configuration
90option, that can be set to a value above or below the global
91``expiration_time`` default, allowing for different caching behavior
92from the other systems in Identity service. This option can be set in various
93sections (for example, ``[role]`` and ``[resource]``) of the configuration
94file.
95The create, update, and delete actions for domains, projects and roles
96will perform proper invalidations of the cached methods listed above.
97
98For more information about the different back ends (and configuration
99options), see:
100
101- `dogpile.cache.memory <https://dogpilecache.readthedocs.io/en/latest/api.html#memory-backend>`__
102
103- `dogpile.cache.memcached <https://dogpilecache.readthedocs.io/en/latest/api.html#memcached-backends>`__
104
105 .. note::
106
107 The memory back end is not suitable for use in a production
108 environment.
109
110- `dogpile.cache.redis <https://dogpilecache.readthedocs.io/en/latest/api.html#redis-backends>`__
111
112- `dogpile.cache.dbm <https://dogpilecache.readthedocs.io/en/latest/api.html#file-backends>`__
113
114Configure the Memcached back end example
115----------------------------------------
116
117The following example shows how to configure the memcached back end:
118
119.. code-block:: ini
120
121 [cache]
122
123 enabled = true
124 backend = dogpile.cache.memcached
125 backend_argument = url:127.0.0.1:11211
126
127You need to specify the URL to reach the ``memcached`` instance with the
128``backend_argument`` parameter.
diff --git a/doc/source/admin/identity-certificates-for-pki.rst b/doc/source/admin/identity-certificates-for-pki.rst
new file mode 100644
index 0000000..2c518cc
--- /dev/null
+++ b/doc/source/admin/identity-certificates-for-pki.rst
@@ -0,0 +1,237 @@
1====================
2Certificates for PKI
3====================
4
5PKI stands for Public Key Infrastructure. Tokens are documents,
6cryptographically signed using the X509 standard. In order to work
7correctly token generation requires a public/private key pair. The
8public key must be signed in an X509 certificate, and the certificate
9used to sign it must be available as a Certificate Authority (CA)
10certificate. These files can be generated either using the
11:command:`keystone-manage` utility, or externally generated. The files need to
12be in the locations specified by the top level Identity service
13configuration file ``/etc/keystone/keystone.conf`` as specified in the
14above section. Additionally, the private key should only be readable by
15the system user that will run the Identity service.
16
17
18.. warning::
19
20 The certificates can be world readable, but the private key cannot
21 be. The private key should only be readable by the account that is
22 going to sign tokens. When generating files with the
23 :command:`keystone-manage pki_setup` command, your best option is to run
24 as the pki user. If you run :command:`keystone-manage` as root, you can
25 append ``--keystone-user`` and ``--keystone-group`` parameters
26 to set the user name and group keystone is going to run under.
27
28The values that specify where to read the certificates are under the
29``[signing]`` section of the configuration file. The configuration
30values are:
31
32- ``certfile``
33 Location of certificate used to verify tokens. Default is
34 ``/etc/keystone/ssl/certs/signing_cert.pem``.
35
36- ``keyfile``
37 Location of private key used to sign tokens. Default is
38 ``/etc/keystone/ssl/private/signing_key.pem``.
39
40- ``ca_certs``
41 Location of certificate for the authority that issued
42 the above certificate. Default is
43 ``/etc/keystone/ssl/certs/ca.pem``.
44
45- ``ca_key``
46 Location of the private key used by the CA. Default is
47 ``/etc/keystone/ssl/private/cakey.pem``.
48
49- ``key_size``
50 Default is ``2048``.
51
52- ``valid_days``
53 Default is ``3650``.
54
55- ``cert_subject``
56 Certificate subject (auto generated certificate) for token signing.
57 Default is ``/C=US/ST=Unset/L=Unset/O=Unset/CN=www.example.com``.
58
59When generating certificates with the :command:`keystone-manage pki_setup`
60command, the ``ca_key``, ``key_size``, and ``valid_days`` configuration
61options are used.
62
63If the :command:`keystone-manage pki_setup` command is not used to generate
64certificates, or you are providing your own certificates, these values
65do not need to be set.
66
67If ``provider=keystone.token.providers.uuid.Provider`` in the
68``[token]`` section of the keystone configuration file, a typical token
69looks like ``53f7f6ef0cc344b5be706bcc8b1479e1``. If
70``provider=keystone.token.providers.pki.Provider``, a typical token is a
71much longer string, such as::
72
73 MIIKtgYJKoZIhvcNAQcCoIIKpzCCCqMCAQExCTAHBgUrDgMCGjCCCY8GCSqGSIb3DQEHAaCCCYAEggl8eyJhY2Nlc3MiOiB7InRva2VuIjogeyJpc3N1ZWRfYXQiOiAiMjAxMy0wNS0z
74 MFQxNTo1MjowNi43MzMxOTgiLCAiZXhwaXJlcyI6ICIyMDEzLTA1LTMxVDE1OjUyOjA2WiIsICJpZCI6ICJwbGFjZWhvbGRlciIsICJ0ZW5hbnQiOiB7ImRlc2NyaXB0aW9uIjogbnVs
75 bCwgImVuYWJsZWQiOiB0cnVlLCAiaWQiOiAiYzJjNTliNGQzZDI4NGQ4ZmEwOWYxNjljYjE4MDBlMDYiLCAibmFtZSI6ICJkZW1vIn19LCAic2VydmljZUNhdGFsb2ciOiBbeyJlbmRw
76 b2ludHMiOiBbeyJhZG1pblVSTCI6ICJodHRwOi8vMTkyLjE2OC4yNy4xMDA6ODc3NC92Mi9jMmM1OWI0ZDNkMjg0ZDhmYTA5ZjE2OWNiMTgwMGUwNiIsICJyZWdpb24iOiAiUmVnaW9u
77 T25lIiwgImludGVybmFsVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo4Nzc0L3YyL2MyYzU5YjRkM2QyODRkOGZhMDlmMTY5Y2IxODAwZTA2IiwgImlkIjogIjFmYjMzYmM5M2Y5
78 ODRhNGNhZTk3MmViNzcwOTgzZTJlIiwgInB1YmxpY1VSTCI6ICJodHRwOi8vMTkyLjE2OC4yNy4xMDA6ODc3NC92Mi9jMmM1OWI0ZDNkMjg0ZDhmYTA5ZjE2OWNiMTgwMGUwNiJ9XSwg
79 ImVuZHBvaW50c19saW5rcyI6IFtdLCAidHlwZSI6ICJjb21wdXRlIiwgIm5hbWUiOiAibm92YSJ9LCB7ImVuZHBvaW50cyI6IFt7ImFkbWluVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3
80 LjEwMDozMzMzIiwgInJlZ2lvbiI6ICJSZWdpb25PbmUiLCAiaW50ZXJuYWxVUkwiOiAiaHR0cDovLzE5Mi4xNjguMjcuMTAwOjMzMzMiLCAiaWQiOiAiN2JjMThjYzk1NWFiNDNkYjhm
81 MGU2YWNlNDU4NjZmMzAiLCAicHVibGljVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDozMzMzIn1dLCAiZW5kcG9pbnRzX2xpbmtzIjogW10sICJ0eXBlIjogInMzIiwgIm5hbWUi
82 OiAiczMifSwgeyJlbmRwb2ludHMiOiBbeyJhZG1pblVSTCI6ICJodHRwOi8vMTkyLjE2OC4yNy4xMDA6OTI5MiIsICJyZWdpb24iOiAiUmVnaW9uT25lIiwgImludGVybmFsVVJMIjog
83 Imh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo5MjkyIiwgImlkIjogIjczODQzNTJhNTQ0MjQ1NzVhM2NkOTVkN2E0YzNjZGY1IiwgInB1YmxpY1VSTCI6ICJodHRwOi8vMTkyLjE2OC4yNy4x
84 MDA6OTI5MiJ9XSwgImVuZHBvaW50c19saW5rcyI6IFtdLCAidHlwZSI6ICJpbWFnZSIsICJuYW1lIjogImdsYW5jZSJ9LCB7ImVuZHBvaW50cyI6IFt7ImFkbWluVVJMIjogImh0dHA6
85 Ly8xOTIuMTY4LjI3LjEwMDo4Nzc2L3YxL2MyYzU5YjRkM2QyODRkOGZhMDlmMTY5Y2IxODAwZTA2IiwgInJlZ2lvbiI6ICJSZWdpb25PbmUiLCAiaW50ZXJuYWxVUkwiOiAiaHR0cDov
86 LzE5Mi4xNjguMjcuMTAwOjg3NzYvdjEvYzJjNTliNGQzZDI4NGQ4ZmEwOWYxNjljYjE4MDBlMDYiLCAiaWQiOiAiMzQ3ZWQ2ZThjMjkxNGU1MGFlMmJiNjA2YWQxNDdjNTQiLCAicHVi
87 bGljVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo4Nzc2L3YxL2MyYzU5YjRkM2QyODRkOGZhMDlmMTY5Y2IxODAwZTA2In1dLCAiZW5kcG9pbnRzX2xpbmtzIjogW10sICJ0eXBl
88 IjogInZvbHVtZSIsICJuYW1lIjogImNpbmRlciJ9LCB7ImVuZHBvaW50cyI6IFt7ImFkbWluVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo4NzczL3NlcnZpY2VzL0FkbWluIiwg
89 InJlZ2lvbiI6ICJSZWdpb25PbmUiLCAiaW50ZXJuYWxVUkwiOiAiaHR0cDovLzE5Mi4xNjguMjcuMTAwOjg3NzMvc2VydmljZXMvQ2xvdWQiLCAiaWQiOiAiMmIwZGMyYjNlY2U4NGJj
90 YWE1NDAzMDMzNzI5YzY3MjIiLCAicHVibGljVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDo4NzczL3NlcnZpY2VzL0Nsb3VkIn1dLCAiZW5kcG9pbnRzX2xpbmtzIjogW10sICJ0
91 eXBlIjogImVjMiIsICJuYW1lIjogImVjMiJ9LCB7ImVuZHBvaW50cyI6IFt7ImFkbWluVVJMIjogImh0dHA6Ly8xOTIuMTY4LjI3LjEwMDozNTM1Ny92Mi4wIiwgInJlZ2lvbiI6ICJS
92 ZWdpb25PbmUiLCAiaW50ZXJuYWxVUkwiOiAiaHR0cDovLzE5Mi4xNjguMjcuMTAwOjUwMDAvdjIuMCIsICJpZCI6ICJiNTY2Y2JlZjA2NjQ0ZmY2OWMyOTMxNzY2Yjc5MTIyOSIsICJw
93 dWJsaWNVUkwiOiAiaHR0cDovLzE5Mi4xNjguMjcuMTAwOjUwMDAvdjIuMCJ9XSwgImVuZHBvaW50c19saW5rcyI6IFtdLCAidHlwZSI6ICJpZGVudGl0eSIsICJuYW1lIjogImtleXN0
94 b25lIn1dLCAidXNlciI6IHsidXNlcm5hbWUiOiAiZGVtbyIsICJyb2xlc19saW5rcyI6IFtdLCAiaWQiOiAiZTVhMTM3NGE4YTRmNDI4NWIzYWQ3MzQ1MWU2MDY4YjEiLCAicm9sZXMi
95 OiBbeyJuYW1lIjogImFub3RoZXJyb2xlIn0sIHsibmFtZSI6ICJNZW1iZXIifV0sICJuYW1lIjogImRlbW8ifSwgIm1ldGFkYXRhIjogeyJpc19hZG1pbiI6IDAsICJyb2xlcyI6IFsi
96 YWRiODM3NDVkYzQzNGJhMzk5ODllNjBjOTIzYWZhMjgiLCAiMzM2ZTFiNjE1N2Y3NGFmZGJhNWUwYTYwMWUwNjM5MmYiXX19fTGB-zCB-AIBATBcMFcxCzAJBgNVBAYTAlVTMQ4wDAYD
97 VQQIEwVVbnNldDEOMAwGA1UEBxMFVW5zZXQxDjAMBgNVBAoTBVVuc2V0MRgwFgYDVQQDEw93d3cuZXhhbXBsZS5jb20CAQEwBwYFKw4DAhowDQYJKoZIhvcNAQEBBQAEgYCAHLpsEs2R
98 nouriuiCgFayIqCssK3SVdhOMINiuJtqv0sE-wBDFiEj-Prcudqlz-n+6q7VgV4mwMPszz39-rwp+P5l4AjrJasUm7FrO-4l02tPLaaZXU1gBQ1jUG5e5aL5jPDP08HbCWuX6wr-QQQB
99 SrWY8lF3HrTcJT23sZIleg==
100
101Sign certificate issued by external CA
102~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103
104You can use a signing certificate issued by an external CA instead of
105generated by :command:`keystone-manage`. However, a certificate issued by an
106external CA must satisfy the following conditions:
107
108- All certificate and key files must be in Privacy Enhanced Mail (PEM)
109 format
110
111- Private key files must not be protected by a password
112
113When using a signing certificate issued by an external CA, you do not
114need to specify ``key_size``, ``valid_days``, and ``ca_password`` as
115they will be ignored.
116
117The basic workflow for using a signing certificate issued by an external
118CA involves:
119
120#. Request Signing Certificate from External CA
121
122#. Convert certificate and private key to PEM if needed
123
124#. Install External Signing Certificate
125
126Request a signing certificate from an external CA
127~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128
129One way to request a signing certificate from an external CA is to first
130generate a PKCS #10 Certificate Request Syntax (CRS) using OpenSSL CLI.
131
132Create a certificate request configuration file. For example, create the
133``cert_req.conf`` file, as follows:
134
135.. code-block:: ini
136
137 [ req ]
138 default_bits = 4096
139 default_keyfile = keystonekey.pem
140 default_md = sha256
141
142 prompt = no
143 distinguished_name = distinguished_name
144
145 [ distinguished_name ]
146 countryName = US
147 stateOrProvinceName = CA
148 localityName = Sunnyvale
149 organizationName = OpenStack
150 organizationalUnitName = Keystone
151 commonName = Keystone Signing
152 emailAddress = keystone@openstack.org
153
154Then generate a CRS with OpenSSL CLI. **Do not encrypt the generated
155private key. You must use the -nodes option.**
156
157For example:
158
159.. code-block:: console
160
161 $ openssl req -newkey rsa:1024 -keyout signing_key.pem -keyform PEM \
162 -out signing_cert_req.pem -outform PEM -config cert_req.conf -nodes
163
164If everything is successful, you should end up with
165``signing_cert_req.pem`` and ``signing_key.pem``. Send
166``signing_cert_req.pem`` to your CA to request a token signing certificate
167and make sure to ask the certificate to be in PEM format. Also, make sure your
168trusted CA certificate chain is also in PEM format.
169
170Install an external signing certificate
171~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172
173Assuming you have the following already:
174
175- ``signing_cert.pem``
176 (Keystone token) signing certificate in PEM format
177
178- ``signing_key.pem``
179 Corresponding (non-encrypted) private key in PEM format
180
181- ``cacert.pem``
182 Trust CA certificate chain in PEM format
183
184Copy the above to your certificate directory. For example:
185
186.. code-block:: console
187
188 # mkdir -p /etc/keystone/ssl/certs
189 # cp signing_cert.pem /etc/keystone/ssl/certs/
190 # cp signing_key.pem /etc/keystone/ssl/certs/
191 # cp cacert.pem /etc/keystone/ssl/certs/
192 # chmod -R 700 /etc/keystone/ssl/certs
193
194.. note::
195
196 Make sure the certificate directory is only accessible by root.
197
198.. note::
199
200 The procedure of copying the key and cert files may be improved if
201 done after first running :command:`keystone-manage pki_setup` since this
202 command also creates other needed files, such as the ``index.txt``
203 and ``serial`` files.
204
205 Also, when copying the necessary files to a different server for
206 replicating the functionality, the entire directory of files is
207 needed, not just the key and cert files.
208
209If your certificate directory path is different from the default
210``/etc/keystone/ssl/certs``, make sure it is reflected in the
211``[signing]`` section of the configuration file.
212
213Switching out expired signing certificates
214~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215
216The following procedure details how to switch out expired signing
217certificates with no cloud outages.
218
219#. Generate a new signing key.
220
221#. Generate a new certificate request.
222
223#. Sign the new certificate with the existing CA to generate a new
224 ``signing_cert``.
225
226#. Append the new ``signing_cert`` to the old ``signing_cert``. Ensure the
227 old certificate is in the file first.
228
229#. Remove all signing certificates from all your hosts to force OpenStack
230 Compute to download the new ``signing_cert``.
231
232#. Replace the old signing key with the new signing key. Move the new
233 signing certificate above the old certificate in the ``signing_cert``
234 file.
235
236#. After the old certificate reads as expired, you can safely remove the
237 old signing certificate from the file.
diff --git a/doc/source/admin/identity-concepts.rst b/doc/source/admin/identity-concepts.rst
new file mode 100644
index 0000000..cc60b4f
--- /dev/null
+++ b/doc/source/admin/identity-concepts.rst
@@ -0,0 +1,354 @@
1=================
2Identity concepts
3=================
4
5Authentication
6 The process of confirming the identity of a user. To confirm an incoming
7 request, OpenStack Identity validates a set of credentials users
8 supply. Initially, these credentials are a user name and password, or a
9 user name and API key. When OpenStack Identity validates user credentials,
10 it issues an authentication token. Users provide the token in
11 subsequent requests.
12
13Credentials
14 Data that confirms the identity of the user. For example, user
15 name and password, user name and API key, or an authentication
16 token that the Identity service provides.
17
18Domain
19 An Identity service API v3 entity. Domains are a collection of
20 projects and users that define administrative boundaries for
21 managing Identity entities. Domains can represent an
22 individual, company, or operator-owned space. They expose
23 administrative activities directly to system users. Users can be
24 granted the administrator role for a domain. A domain
25 administrator can create projects, users, and groups in a domain
26 and assign roles to users and groups in a domain.
27
28Endpoint
29 A network-accessible address, usually a URL, through which you can
30 access a service. If you are using an extension for templates, you
31 can create an endpoint template that represents the templates of
32 all consumable services that are available across the regions.
33
34Group
35 An Identity service API v3 entity. Groups are a collection of
36 users owned by a domain. A group role, granted to a domain
37 or project, applies to all users in the group. Adding or removing
38 users to or from a group grants or revokes their role and
39 authentication to the associated domain or project.
40
41OpenStackClient
42 A command-line interface for several OpenStack services including
43 the Identity API. For example, a user can run the
44 :command:`openstack service create` and
45 :command:`openstack endpoint create` commands to register services
46 in their OpenStack installation.
47
48Project
49 A container that groups or isolates resources or identity objects.
50 Depending on the service operator, a project might map to a
51 customer, account, organization, or tenant.
52
53Region
54 An Identity service API v3 entity. Represents a general division
55 in an OpenStack deployment. You can associate zero or more
56 sub-regions with a region to make a tree-like structured hierarchy.
57 Although a region does not have a geographical connotation, a
58 deployment can use a geographical name for a region, such as ``us-east``.
59
60Role
61 A personality with a defined set of user rights and privileges to
62 perform a specific set of operations. The Identity service issues
63 a token to a user that includes a list of roles. When a user calls
64 a service, that service interprets the user role set, and
65 determines to which operations or resources each role grants
66 access.
67
68Service
69 An OpenStack service, such as Compute (nova), Object Storage
70 (swift), or Image service (glance), that provides one or more
71 endpoints through which users can access resources and perform
72 operations.
73
74Token
75 An alpha-numeric text string that enables access to OpenStack APIs
76 and resources. A token may be revoked at any time and is valid for
77 a finite duration. While OpenStack Identity supports token-based
78 authentication in this release, it intends to support additional
79 protocols in the future. OpenStack Identity is an integration
80 service that does not aspire to be a full-fledged identity store
81 and management solution.
82
83User
84 A digital representation of a person, system, or service that uses
85 OpenStack cloud services. The Identity service validates that
86 incoming requests are made by the user who claims to be making the
87 call. Users have a login and can access resources by using
88 assigned tokens. Users can be directly assigned to a particular
89 project and behave as if they are contained in that project.
90
91User management
92~~~~~~~~~~~~~~~
93
94Identity user management examples:
95
96* Create a user named ``alice``:
97
98 .. code-block:: console
99
100 $ openstack user create --password-prompt --email alice@example.com alice
101
102* Create a project named ``acme``:
103
104 .. code-block:: console
105
106 $ openstack project create acme --domain default
107
108* Create a domain named ``emea``:
109
110 .. code-block:: console
111
112 $ openstack --os-identity-api-version=3 domain create emea
113
114* Create a role named ``compute-user``:
115
116 .. code-block:: console
117
118 $ openstack role create compute-user
119
120 .. note::
121
122 Individual services assign meaning to roles, typically through
123 limiting or granting access to users with the role to the
124 operations that the service supports. Role access is typically
125 configured in the service's ``policy.json`` file. For example,
126 to limit Compute access to the ``compute-user`` role, edit the
127 Compute service's ``policy.json`` file to require this role for
128 Compute operations.
129
130The Identity service assigns a project and a role to a user. You might
131assign the ``compute-user`` role to the ``alice`` user in the ``acme``
132project:
133
134.. code-block:: console
135
136 $ openstack role add --project acme --user alice compute-user
137
138A user can have different roles in different projects. For example, Alice
139might also have the ``admin`` role in the ``Cyberdyne`` project. A user
140can also have multiple roles in the same project.
141
142The ``/etc/[SERVICE_CODENAME]/policy.json`` file controls the
143tasks that users can perform for a given service. For example, the
144``/etc/nova/policy.json`` file specifies the access policy for the
145Compute service, the ``/etc/glance/policy.json`` file specifies
146the access policy for the Image service, and the
147``/etc/keystone/policy.json`` file specifies the access policy for
148the Identity service.
149
150The default ``policy.json`` files in the Compute, Identity, and
151Image services recognize only the ``admin`` role. Any user with
152any role in a project can access all operations that do not require the
153``admin`` role.
154
155To restrict users from performing operations in, for example, the
156Compute service, you must create a role in the Identity service and
157then modify the ``/etc/nova/policy.json`` file so that this role
158is required for Compute operations.
159
160For example, the following line in the ``/etc/cinder/policy.json``
161file does not restrict which users can create volumes:
162
163.. code-block:: none
164
165 "volume:create": "",
166
167If the user has any role in a project, he can create volumes in that
168project.
169
170To restrict the creation of volumes to users who have the
171``compute-user`` role in a particular project, you add ``"role:compute-user"``:
172
173.. code-block:: none
174
175 "volume:create": "role:compute-user",
176
177To restrict all Compute service requests to require this role, the
178resulting file looks like:
179
180.. code-block:: json
181
182 {
183 "admin_or_owner": "role:admin or project_id:%(project_id)s",
184 "default": "rule:admin_or_owner",
185 "compute:create": "role:compute-user",
186 "compute:create:attach_network": "role:compute-user",
187 "compute:create:attach_volume": "role:compute-user",
188 "compute:get_all": "role:compute-user",
189 "compute:unlock_override": "rule:admin_api",
190 "admin_api": "role:admin",
191 "compute_extension:accounts": "rule:admin_api",
192 "compute_extension:admin_actions": "rule:admin_api",
193 "compute_extension:admin_actions:pause": "rule:admin_or_owner",
194 "compute_extension:admin_actions:unpause": "rule:admin_or_owner",
195 "compute_extension:admin_actions:suspend": "rule:admin_or_owner",
196 "compute_extension:admin_actions:resume": "rule:admin_or_owner",
197 "compute_extension:admin_actions:lock": "rule:admin_or_owner",
198 "compute_extension:admin_actions:unlock": "rule:admin_or_owner",
199 "compute_extension:admin_actions:resetNetwork": "rule:admin_api",
200 "compute_extension:admin_actions:injectNetworkInfo": "rule:admin_api",
201 "compute_extension:admin_actions:createBackup": "rule:admin_or_owner",
202 "compute_extension:admin_actions:migrateLive": "rule:admin_api",
203 "compute_extension:admin_actions:migrate": "rule:admin_api",
204 "compute_extension:aggregates": "rule:admin_api",
205 "compute_extension:certificates": "role:compute-user",
206 "compute_extension:cloudpipe": "rule:admin_api",
207 "compute_extension:console_output": "role:compute-user",
208 "compute_extension:consoles": "role:compute-user",
209 "compute_extension:createserverext": "role:compute-user",
210 "compute_extension:deferred_delete": "role:compute-user",
211 "compute_extension:disk_config": "role:compute-user",
212 "compute_extension:evacuate": "rule:admin_api",
213 "compute_extension:extended_server_attributes": "rule:admin_api",
214 "compute_extension:extended_status": "role:compute-user",
215 "compute_extension:flavorextradata": "role:compute-user",
216 "compute_extension:flavorextraspecs": "role:compute-user",
217 "compute_extension:flavormanage": "rule:admin_api",
218 "compute_extension:floating_ip_dns": "role:compute-user",
219 "compute_extension:floating_ip_pools": "role:compute-user",
220 "compute_extension:floating_ips": "role:compute-user",
221 "compute_extension:hosts": "rule:admin_api",
222 "compute_extension:keypairs": "role:compute-user",
223 "compute_extension:multinic": "role:compute-user",
224 "compute_extension:networks": "rule:admin_api",
225 "compute_extension:quotas": "role:compute-user",
226 "compute_extension:rescue": "role:compute-user",
227 "compute_extension:security_groups": "role:compute-user",
228 "compute_extension:server_action_list": "rule:admin_api",
229 "compute_extension:server_diagnostics": "rule:admin_api",
230 "compute_extension:simple_tenant_usage:show": "rule:admin_or_owner",
231 "compute_extension:simple_tenant_usage:list": "rule:admin_api",
232 "compute_extension:users": "rule:admin_api",
233 "compute_extension:virtual_interfaces": "role:compute-user",
234 "compute_extension:virtual_storage_arrays": "role:compute-user",
235 "compute_extension:volumes": "role:compute-user",
236 "compute_extension:volume_attachments:index": "role:compute-user",
237 "compute_extension:volume_attachments:show": "role:compute-user",
238 "compute_extension:volume_attachments:create": "role:compute-user",
239 "compute_extension:volume_attachments:delete": "role:compute-user",
240 "compute_extension:volumetypes": "role:compute-user",
241 "volume:create": "role:compute-user",
242 "volume:get_all": "role:compute-user",
243 "volume:get_volume_metadata": "role:compute-user",
244 "volume:get_snapshot": "role:compute-user",
245 "volume:get_all_snapshots": "role:compute-user",
246 "network:get_all_networks": "role:compute-user",
247 "network:get_network": "role:compute-user",
248 "network:delete_network": "role:compute-user",
249 "network:disassociate_network": "role:compute-user",
250 "network:get_vifs_by_instance": "role:compute-user",
251 "network:allocate_for_instance": "role:compute-user",
252 "network:deallocate_for_instance": "role:compute-user",
253 "network:validate_networks": "role:compute-user",
254 "network:get_instance_uuids_by_ip_filter": "role:compute-user",
255 "network:get_floating_ip": "role:compute-user",
256 "network:get_floating_ip_pools": "role:compute-user",
257 "network:get_floating_ip_by_address": "role:compute-user",
258 "network:get_floating_ips_by_project": "role:compute-user",
259 "network:get_floating_ips_by_fixed_address": "role:compute-user",
260 "network:allocate_floating_ip": "role:compute-user",
261 "network:deallocate_floating_ip": "role:compute-user",
262 "network:associate_floating_ip": "role:compute-user",
263 "network:disassociate_floating_ip": "role:compute-user",
264 "network:get_fixed_ip": "role:compute-user",
265 "network:add_fixed_ip_to_instance": "role:compute-user",
266 "network:remove_fixed_ip_from_instance": "role:compute-user",
267 "network:add_network_to_project": "role:compute-user",
268 "network:get_instance_nw_info": "role:compute-user",
269 "network:get_dns_domains": "role:compute-user",
270 "network:add_dns_entry": "role:compute-user",
271 "network:modify_dns_entry": "role:compute-user",
272 "network:delete_dns_entry": "role:compute-user",
273 "network:get_dns_entries_by_address": "role:compute-user",
274 "network:get_dns_entries_by_name": "role:compute-user",
275 "network:create_private_dns_domain": "role:compute-user",
276 "network:create_public_dns_domain": "role:compute-user",
277 "network:delete_dns_domain": "role:compute-user"
278 }
279
280Service management
281~~~~~~~~~~~~~~~~~~
282
283The Identity service provides identity, token, catalog, and policy
284services. It consists of:
285
286* keystone Web Server Gateway Interface (WSGI) service
287 Can be run in a WSGI-capable web server such as Apache httpd to provide
288 the Identity service. The service and administrative APIs are run as
289 separate instances of the WSGI service.
290
291* Identity service functions
292 Each has a pluggable back end that allow different ways to use the
293 particular service. Most support standard back ends like LDAP or SQL.
294
295* keystone-all
296 Starts both the service and administrative APIs in a single process.
297 Using federation with keystone-all is not supported. keystone-all is
298 deprecated in favor of the WSGI service. Also, this will be removed
299 in Newton.
300
301The Identity service also maintains a user that corresponds to each
302service, such as, a user named ``nova`` for the Compute service, and a
303special service project called ``service``.
304
305For information about how to create services and endpoints, see the
306`OpenStack Administrator Guide <https://docs.openstack.org/admin-guide/
307cli-manage-services.html>`__.
308
309Groups
310~~~~~~
311
312A group is a collection of users in a domain. Administrators can
313create groups and add users to them. A role can then be assigned to
314the group, rather than individual users. Groups were introduced with
315the Identity API v3.
316
317Identity API V3 provides the following group-related operations:
318
319* Create a group
320
321* Delete a group
322
323* Update a group (change its name or description)
324
325* Add a user to a group
326
327* Remove a user from a group
328
329* List group members
330
331* List groups for a user
332
333* Assign a role on a project to a group
334
335* Assign a role on a domain to a group
336
337* Query role assignments to groups
338
339.. note::
340
341 The Identity service server might not allow all operations. For
342 example, if you use the Identity server with the LDAP Identity
343 back end and group updates are disabled, a request to create,
344 delete, or update a group fails.
345
346Here are a couple of examples:
347
348* Group A is granted Role A on Project A. If User A is a member of Group
349 A, when User A gets a token scoped to Project A, the token also
350 includes Role A.
351
352* Group B is granted Role B on Domain B. If User B is a member of
353 Group B, when User B gets a token scoped to Domain B, the token also
354 includes Role B.
diff --git a/doc/source/admin/identity-domain-specific-config.rst b/doc/source/admin/identity-domain-specific-config.rst
new file mode 100644
index 0000000..b15f698
--- /dev/null
+++ b/doc/source/admin/identity-domain-specific-config.rst
@@ -0,0 +1,69 @@
1=============================
2Domain-specific configuration
3=============================
4
5The Identity service supports domain-specific Identity drivers.
6The drivers allow a domain to have its own LDAP or SQL back end.
7By default, domain-specific drivers are disabled.
8
9Domain-specific Identity configuration options can be stored in
10domain-specific configuration files, or in the Identity SQL
11database using API REST calls.
12
13.. note::
14
15 Storing and managing configuration options in an SQL database is
16 experimental in Kilo, and added to the Identity service in the
17 Liberty release.
18
19Enable drivers for domain-specific configuration files
20------------------------------------------------------
21
22To enable domain-specific drivers, set these options in the
23``/etc/keystone/keystone.conf`` file:
24
25.. code-block:: ini
26
27 [identity]
28 domain_specific_drivers_enabled = True
29 domain_config_dir = /etc/keystone/domains
30
31When you enable domain-specific drivers, Identity looks in the
32``domain_config_dir`` directory for configuration files that are named as
33``keystone.DOMAIN_NAME.conf``. A domain without a domain-specific
34configuration file uses options in the primary configuration file.
35
36Enable drivers for storing configuration options in SQL database
37----------------------------------------------------------------
38
39To enable domain-specific drivers, set these options in the
40``/etc/keystone/keystone.conf`` file:
41
42.. code-block:: ini
43
44 [identity]
45 domain_specific_drivers_enabled = True
46 domain_configurations_from_database = True
47
48Any domain-specific configuration options specified through the
49Identity v3 API will override domain-specific configuration files in the
50``/etc/keystone/domains`` directory.
51
52Migrate domain-specific configuration files to the SQL database
53---------------------------------------------------------------
54
55You can use the ``keystone-manage`` command to migrate configuration
56options in domain-specific configuration files to the SQL database:
57
58.. code-block:: console
59
60 # keystone-manage domain_config_upload --all
61
62To upload options from a specific domain-configuration file, specify the
63domain name:
64
65.. code-block:: console
66
67 # keystone-manage domain_config_upload --domain-name DOMAIN_NAME
68
69
diff --git a/doc/source/admin/identity-external-authentication.rst b/doc/source/admin/identity-external-authentication.rst
new file mode 100644
index 0000000..62b5571
--- /dev/null
+++ b/doc/source/admin/identity-external-authentication.rst
@@ -0,0 +1,41 @@
1=====================================
2External authentication with Identity
3=====================================
4
5When Identity runs in ``apache-httpd``, you can use external
6authentication methods that differ from the authentication provided by
7the identity store back end. For example, you can use an SQL identity
8back end together with X.509 authentication and Kerberos, instead of
9using the user name and password combination.
10
11Use HTTPD authentication
12~~~~~~~~~~~~~~~~~~~~~~~~
13
14Web servers, like Apache HTTP, support many methods of authentication.
15Identity can allow the web server to perform the authentication. The web
16server then passes the authenticated user to Identity by using the
17``REMOTE_USER`` environment variable. This user must already exist in
18the Identity back end to get a token from the controller. To use this
19method, Identity should run on ``apache-httpd``.
20
21Use X.509
22~~~~~~~~~
23
24The following Apache configuration snippet authenticates the user based
25on a valid X.509 certificate from a known CA:
26
27.. code-block:: none
28
29 <VirtualHost _default_:5000>
30 SSLEngine on
31 SSLCertificateFile /etc/ssl/certs/ssl.cert
32 SSLCertificateKeyFile /etc/ssl/private/ssl.key
33
34 SSLCACertificatePath /etc/ssl/allowed_cas
35 SSLCARevocationPath /etc/ssl/allowed_cas
36 SSLUserName SSL_CLIENT_S_DN_CN
37 SSLVerifyClient require
38 SSLVerifyDepth 10
39
40 (...)
41 </VirtualHost>
diff --git a/doc/source/admin/identity-fernet-token-faq.rst b/doc/source/admin/identity-fernet-token-faq.rst
new file mode 100644
index 0000000..2b2cdb0
--- /dev/null
+++ b/doc/source/admin/identity-fernet-token-faq.rst
@@ -0,0 +1,345 @@
1===================================
2Fernet - Frequently Asked Questions
3===================================
4
5The following questions have been asked periodically since the initial release
6of the fernet token format in Kilo.
7
8What are the different types of keys?
9~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10
11A key repository is required by keystone in order to create fernet tokens.
12These keys are used to encrypt and decrypt the information that makes up the
13payload of the token. Each key in the repository can have one of three states.
14The state of the key determines how keystone uses a key with fernet tokens. The
15different types are as follows:
16
17Primary key:
18 There is only ever one primary key in a key repository. The primary key is
19 allowed to encrypt and decrypt tokens. This key is always named as the
20 highest index in the repository.
21Secondary key:
22 A secondary key was at one point a primary key, but has been demoted in place
23 of another primary key. It is only allowed to decrypt tokens. Since it was
24 the primary at some point in time, its existence in the key repository is
25 justified. Keystone needs to be able to decrypt tokens that were created with
26 old primary keys.
27Staged key:
28 The staged key is a special key that shares some similarities with secondary
29 keys. There can only ever be one staged key in a repository and it must
30 exist. Just like secondary keys, staged keys have the ability to decrypt
31 tokens. Unlike secondary keys, staged keys have never been a primary key. In
32 fact, they are opposites since the staged key will always be the next primary
33 key. This helps clarify the name because they are the next key staged to be
34 the primary key. This key is always named as ``0`` in the key repository.
35
36So, how does a staged key help me and why do I care about it?
37~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38
39The fernet keys have a natural lifecycle. Each key starts as a staged key, is
40promoted to be the primary key, and then demoted to be a secondary key. New
41tokens can only be encrypted with a primary key. Secondary and staged keys are
42never used to encrypt token. The staged key is a special key given the order of
43events and the attributes of each type of key. The staged key is the only key
44in the repository that has not had a chance to encrypt any tokens yet, but it
45is still allowed to decrypt tokens. As an operator, this gives you the chance
46to perform a key rotation on one keystone node, and distribute the new key set
47over a span of time. This does not require the distribution to take place in an
48ultra short period of time. Tokens encrypted with a primary key can be
49decrypted, and validated, on other nodes where that key is still staged.
50
51Where do I put my key repository?
52~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53
54The key repository is specified using the ``key_repository`` option in the
55keystone configuration file. The keystone process should be able to read and
56write to this location but it should be kept secret otherwise. Currently,
57keystone only supports file-backed key repositories.
58
59.. code-block:: ini
60
61 [fernet_tokens]
62 key_repository = /etc/keystone/fernet-keys/
63
64What is the recommended way to rotate and distribute keys?
65~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66
67The :command:`keystone-manage` command line utility includes a key rotation
68mechanism. This mechanism will initialize and rotate keys but does not make
69an effort to distribute keys across keystone nodes. The distribution of keys
70across a keystone deployment is best handled through configuration management
71tooling. Use :command:`keystone-manage fernet_rotate` to rotate the key
72repository.
73
74Do fernet tokens still expire?
75~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76
77Yes, fernet tokens can expire just like any other keystone token formats.
78
79Why should I choose fernet tokens over UUID tokens?
80~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81
82Even though fernet tokens operate very similarly to UUID tokens, they do not
83require persistence. The keystone token database no longer suffers bloat as a
84side effect of authentication. Pruning expired tokens from the token database
85is no longer required when using fernet tokens. Because fernet tokens do not
86require persistence, they do not have to be replicated. As long as each
87keystone node shares the same key repository, fernet tokens can be created and
88validated instantly across nodes.
89
90Why should I choose fernet tokens over PKI or PKIZ tokens?
91~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92
93The arguments for using fernet over PKI and PKIZ remain the same as UUID, in
94addition to the fact that fernet tokens are much smaller than PKI and PKIZ
95tokens. PKI and PKIZ tokens still require persistent storage and can sometimes
96cause issues due to their size. This issue is mitigated when switching to
97fernet because fernet tokens are kept under a 250 byte limit. PKI and PKIZ
98tokens typically exceed 1600 bytes in length. The length of a PKI or PKIZ token
99is dependent on the size of the deployment. Bigger service catalogs will result
100in longer token lengths. This pattern does not exist with fernet tokens because
101the contents of the encrypted payload is kept to a minimum.
102
103Should I rotate and distribute keys from the same keystone node every rotation?
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106No, but the relationship between rotation and distribution should be lock-step.
107Once you rotate keys on one keystone node, the key repository from that node
108should be distributed to the rest of the cluster. Once you confirm that each
109node has the same key repository state, you could rotate and distribute from
110any other node in the cluster.
111
112If the rotation and distribution are not lock-step, a single keystone node in
113the deployment will create tokens with a primary key that no other node has as
114a staged key. This will cause tokens generated from one keystone node to fail
115validation on other keystone nodes.
116
117How do I add new keystone nodes to a deployment?
118~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119
120The keys used to create fernet tokens should be treated like super secret
121configuration files, similar to an SSL secret key. Before a node is allowed to
122join an existing cluster, issuing and validating tokens, it should have the
123same key repository as the rest of the nodes in the cluster.
124
125How should I approach key distribution?
126~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127
128Remember that key distribution is only required in multi-node keystone
129deployments. If you only have one keystone node serving requests in your
130deployment, key distribution is unnecessary.
131
132Key distribution is a problem best approached from the deployment's current
133configuration management system. Since not all deployments use the same
134configuration management systems, it makes sense to explore options around what
135is already available for managing keys, while keeping the secrecy of the keys
136in mind. Many configuration management tools can leverage something like
137``rsync`` to manage key distribution.
138
139Key rotation is a single operation that promotes the current staged key to
140primary, creates a new staged key, and prunes old secondary keys. It is easiest
141to do this on a single node and verify the rotation took place properly before
142distributing the key repository to the rest of the cluster. The concept behind
143the staged key breaks the expectation that key rotation and key distribution
144have to be done in a single step. With the staged key, we have time to inspect
145the new key repository before syncing state with the rest of the cluster. Key
146distribution should be an operation that can run in succession until it
147succeeds. The following might help illustrate the isolation between key
148rotation and key distribution.
149
150#. Ensure all keystone nodes in the deployment have the same key repository.
151#. Pick a keystone node in the cluster to rotate from.
152#. Rotate keys.
153
154 #. Was it successful?
155
156 #. If no, investigate issues with the particular keystone node you
157 rotated keys on. Fernet keys are small and the operation for
158 rotation is trivial. There should not be much room for error in key
159 rotation. It is possible that the user does not have the ability to
160 write new keys to the key repository. Log output from
161 ``keystone-manage fernet_rotate`` should give more information into
162 specific failures.
163
164 #. If yes, you should see a new staged key. The old staged key should
165 be the new primary. Depending on the ``max_active_keys`` limit you
166 might have secondary keys that were pruned. At this point, the node
167 that you rotated on will be creating fernet tokens with a primary
168 key that all other nodes should have as the staged key. This is why
169 we checked the state of all key repositories in Step one. All other
170 nodes in the cluster should be able to decrypt tokens created with
171 the new primary key. At this point, we are ready to distribute the
172 new key set.
173
174#. Distribute the new key repository.
175
176 #. Was it successful?
177
178 #. If yes, you should be able to confirm that all nodes in the cluster
179 have the same key repository that was introduced in Step 3. All
180 nodes in the cluster will be creating tokens with the primary key
181 that was promoted in Step 3. No further action is required until the
182 next schedule key rotation.
183
184 #. If no, try distributing again. Remember that we already rotated the
185 repository and performing another rotation at this point will
186 result in tokens that cannot be validated across certain hosts.
187 Specifically, the hosts that did not get the latest key set. You
188 should be able to distribute keys until it is successful. If certain
189 nodes have issues syncing, it could be permission or network issues
190 and those should be resolved before subsequent rotations.
191
192How long should I keep my keys around?
193~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
194
195The fernet tokens that keystone creates are only secure as the keys creating
196them. With staged keys the penalty of key rotation is low, allowing you to err
197on the side of security and rotate weekly, daily, or even hourly. Ultimately,
198this should be less time than it takes an attacker to break a ``AES256`` key
199and a ``SHA256 HMAC``.
200
201Is a fernet token still a bearer token?
202~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
203
204Yes, and they follow exactly the same validation path as UUID tokens, with the
205exception of being written to, and read from, a back end. If someone
206compromises your fernet token, they have the power to do all the operations you
207are allowed to do.
208
209What if I need to revoke all my tokens?
210~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211
212To invalidate every token issued from keystone and start fresh, remove the
213current key repository, create a new key set, and redistribute it to all nodes
214in the cluster. This will render every token issued from keystone as invalid
215regardless if the token has actually expired. When a client goes to
216re-authenticate, the new token will have been created with a new fernet key.
217
218What can an attacker do if they compromise a fernet key in my deployment?
219~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220
221If any key used in the key repository is compromised, an attacker will be able
222to build their own tokens. If they know the ID of an administrator on a
223project, they could generate administrator tokens for the project. They will be
224able to generate their own tokens until the compromised key has been removed
225from from the repository.
226
227I rotated keys and now tokens are invalidating early, what did I do?
228~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
229
230Using fernet tokens requires some awareness around token expiration and the key
231lifecycle. You do not want to rotate so often that secondary keys are removed
232that might still be needed to decrypt unexpired tokens. If this happens, you
233will not be able to decrypt the token because the key the was used to encrypt
234it is now gone. Only remove keys that you know are not being used to encrypt or
235decrypt tokens.
236
237For example, your token is valid for 24 hours and we want to rotate keys every
238six hours. We will need to make sure tokens that were created at 08:00 AM on
239Monday are still valid at 07:00 AM on Tuesday, assuming they were not
240prematurely revoked. To accomplish this, we will want to make sure we set
241``max_active_keys=6`` in our keystone configuration file. This will allow us to
242hold all keys that might still be required to validate a previous token, but
243keeps the key repository limited to only the keys that are needed.
244
245The number of ``max_active_keys`` for a deployment can be determined by
246dividing the token lifetime, in hours, by the frequency of rotation in hours
247and adding two. Better illustrated as::
248
249 token_expiration = 24
250 rotation_frequency = 6
251 max_active_keys = (token_expiration / rotation_frequency) + 2
252
253The reason for adding two additional keys to the count is to include the staged
254key and a buffer key. This can be shown based on the previous example. We
255initially setup the key repository at 6:00 AM on Monday, and the initial state
256looks like:
257
258.. code-block:: console
259
260 $ ls -la /etc/keystone/fernet-keys/
261 drwx------ 2 keystone keystone 4096 .
262 drwxr-xr-x 3 keystone keystone 4096 ..
263 -rw------- 1 keystone keystone 44 0 (staged key)
264 -rw------- 1 keystone keystone 44 1 (primary key)
265
266All tokens created after 6:00 AM are encrypted with key ``1``. At 12:00 PM we
267will rotate keys again, resulting in,
268
269.. code-block:: console
270
271 $ ls -la /etc/keystone/fernet-keys/
272 drwx------ 2 keystone keystone 4096 .
273 drwxr-xr-x 3 keystone keystone 4096 ..
274 -rw------- 1 keystone keystone 44 0 (staged key)
275 -rw------- 1 keystone keystone 44 1 (secondary key)
276 -rw------- 1 keystone keystone 44 2 (primary key)
277
278We are still able to validate tokens created between 6:00 - 11:59 AM because
279the ``1`` key still exists as a secondary key. All tokens issued after 12:00 PM
280will be encrypted with key ``2``. At 6:00 PM we do our next rotation, resulting
281in:
282
283.. code-block:: console
284
285 $ ls -la /etc/keystone/fernet-keys/
286 drwx------ 2 keystone keystone 4096 .
287 drwxr-xr-x 3 keystone keystone 4096 ..
288 -rw------- 1 keystone keystone 44 0 (staged key)
289 -rw------- 1 keystone keystone 44 1 (secondary key)
290 -rw------- 1 keystone keystone 44 2 (secondary key)
291 -rw------- 1 keystone keystone 44 3 (primary key)
292
293It is still possible to validate tokens issued from 6:00 AM - 5:59 PM because
294keys ``1`` and ``2`` exist as secondary keys. Every token issued until 11:59 PM
295will be encrypted with key ``3``, and at 12:00 AM we do our next rotation:
296
297.. code-block:: console
298
299 $ ls -la /etc/keystone/fernet-keys/
300 drwx------ 2 keystone keystone 4096 .
301 drwxr-xr-x 3 keystone keystone 4096 ..
302 -rw------- 1 keystone keystone 44 0 (staged key)
303 -rw------- 1 keystone keystone 44 1 (secondary key)
304 -rw------- 1 keystone keystone 44 2 (secondary key)
305 -rw------- 1 keystone keystone 44 3 (secondary key)
306 -rw------- 1 keystone keystone 44 4 (primary key)
307
308Just like before, we can still validate tokens issued from 6:00 AM the previous
309day until 5:59 AM today because keys ``1`` - ``4`` are present. At 6:00 AM,
310tokens issued from the previous day will start to expire and we do our next
311scheduled rotation:
312
313.. code-block:: console
314
315 $ ls -la /etc/keystone/fernet-keys/
316 drwx------ 2 keystone keystone 4096 .
317 drwxr-xr-x 3 keystone keystone 4096 ..
318 -rw------- 1 keystone keystone 44 0 (staged key)
319 -rw------- 1 keystone keystone 44 1 (secondary key)
320 -rw------- 1 keystone keystone 44 2 (secondary key)
321 -rw------- 1 keystone keystone 44 3 (secondary key)
322 -rw------- 1 keystone keystone 44 4 (secondary key)
323 -rw------- 1 keystone keystone 44 5 (primary key)
324
325Tokens will naturally expire after 6:00 AM, but we will not be able to remove
326key ``1`` until the next rotation because it encrypted all tokens from 6:00 AM
327to 12:00 PM the day before. Once we do our next rotation, which is at 12:00 PM,
328the ``1`` key will be pruned from the repository:
329
330.. code-block:: console
331
332 $ ls -la /etc/keystone/fernet-keys/
333 drwx------ 2 keystone keystone 4096 .
334 drwxr-xr-x 3 keystone keystone 4096 ..
335 -rw------- 1 keystone keystone 44 0 (staged key)
336 -rw------- 1 keystone keystone 44 2 (secondary key)
337 -rw------- 1 keystone keystone 44 3 (secondary key)
338 -rw------- 1 keystone keystone 44 4 (secondary key)
339 -rw------- 1 keystone keystone 44 5 (secondary key)
340 -rw------- 1 keystone keystone 44 6 (primary key)
341
342If keystone were to receive a token that was created between 6:00 AM and 12:00
343PM the day before, encrypted with the ``1`` key, it would not be valid because
344it was already expired. This makes it possible for us to remove the ``1`` key
345from the repository without negative validation side-effects.
diff --git a/doc/source/admin/identity-integrate-with-ldap.rst b/doc/source/admin/identity-integrate-with-ldap.rst
new file mode 100644
index 0000000..a2ad2fb
--- /dev/null
+++ b/doc/source/admin/identity-integrate-with-ldap.rst
@@ -0,0 +1,453 @@
1.. _integrate-identity-with-ldap:
2
3============================
4Integrate Identity with LDAP
5============================
6
7The OpenStack Identity service supports integration with existing LDAP
8directories for authentication and authorization services. LDAP back
9ends require initialization before configuring the OpenStack Identity
10service to work with it. For more information, see `Setting up LDAP
11for use with Keystone <https://wiki.openstack.org/wiki/OpenLDAP>`__.
12
13When the OpenStack Identity service is configured to use LDAP back ends,
14you can split authentication (using the *identity* feature) and
15authorization (using the *assignment* feature).
16
17The *identity* feature enables administrators to manage users and groups
18by each domain or the OpenStack Identity service entirely.
19
20The *assignment* feature enables administrators to manage project role
21authorization using the OpenStack Identity service SQL database, while
22providing user authentication through the LDAP directory.
23
24.. _identity_ldap_server_setup:
25
26Identity LDAP server set up
27~~~~~~~~~~~~~~~~~~~~~~~~~~~
28
29.. important::
30
31 For the OpenStack Identity service to access LDAP servers, you must
32 enable the ``authlogin_nsswitch_use_ldap`` boolean value for SELinux
33 on the server running the OpenStack Identity service. To enable and
34 make the option persistent across reboots, set the following boolean
35 value as the root user:
36
37 .. code-block:: console
38
39 # setsebool -P authlogin_nsswitch_use_ldap on
40
41The Identity configuration is split into two separate back ends; identity
42(back end for users and groups), and assignments (back end for domains,
43projects, roles, role assignments). To configure Identity, set options
44in the ``/etc/keystone/keystone.conf`` file. See
45:ref:`integrate-identity-backend-ldap` for Identity back end configuration
46examples. Modify these examples as needed.
47
48**To define the destination LDAP server**
49
50#. Define the destination LDAP server in the
51 ``/etc/keystone/keystone.conf`` file:
52
53 .. code-block:: ini
54
55 [ldap]
56 url = ldap://localhost
57 user = dc=Manager,dc=example,dc=org
58 password = samplepassword
59 suffix = dc=example,dc=org
60
61**Additional LDAP integration settings**
62
63Set these options in the ``/etc/keystone/keystone.conf`` file for a
64single LDAP server, or ``/etc/keystone/domains/keystone.DOMAIN_NAME.conf``
65files for multiple back ends. Example configurations appear below each
66setting summary:
67
68**Query option**
69
70.. hlist::
71 :columns: 1
72
73 * Use ``query_scope`` to control the scope level of data presented
74 (search only the first level or search an entire sub-tree)
75 through LDAP.
76 * Use ``page_size`` to control the maximum results per page. A value
77 of zero disables paging.
78 * Use ``alias_dereferencing`` to control the LDAP dereferencing
79 option for queries.
80
81.. code-block:: ini
82
83 [ldap]
84 query_scope = sub
85 page_size = 0
86 alias_dereferencing = default
87 chase_referrals =
88
89**Debug**
90
91Use ``debug_level`` to set the LDAP debugging level for LDAP calls.
92A value of zero means that debugging is not enabled.
93
94.. code-block:: ini
95
96 [ldap]
97 debug_level = 0
98
99.. warning::
100
101 This value is a bitmask, consult your LDAP documentation for
102 possible values.
103
104**Connection pooling**
105
106Use ``use_pool`` to enable LDAP connection pooling. Configure the
107connection pool size, maximum retry, reconnect trials, timeout (-1
108indicates indefinite wait) and lifetime in seconds.
109
110.. code-block:: ini
111
112 [ldap]
113 use_pool = true
114 pool_size = 10
115 pool_retry_max = 3
116 pool_retry_delay = 0.1
117 pool_connection_timeout = -1
118 pool_connection_lifetime = 600
119
120**Connection pooling for end user authentication**
121
122Use ``use_auth_pool`` to enable LDAP connection pooling for end user
123authentication. Configure the connection pool size and lifetime in
124seconds.
125
126.. code-block:: ini
127
128 [ldap]
129 use_auth_pool = false
130 auth_pool_size = 100
131 auth_pool_connection_lifetime = 60
132
133When you have finished the configuration, restart the OpenStack Identity
134service.
135
136.. warning::
137
138 During the service restart, authentication and authorization are
139 unavailable.
140
141.. _integrate-identity-backend-ldap:
142
143Integrate Identity back end with LDAP
144~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145
146The Identity back end contains information for users, groups, and group
147member lists. Integrating the Identity back end with LDAP allows
148administrators to use users and groups in LDAP.
149
150.. important::
151
152 For OpenStack Identity service to access LDAP servers, you must
153 define the destination LDAP server in the
154 ``/etc/keystone/keystone.conf`` file. For more information,
155 see :ref:`identity_ldap_server_setup`.
156
157**To integrate one Identity back end with LDAP**
158
159#. Enable the LDAP Identity driver in the ``/etc/keystone/keystone.conf``
160 file. This allows LDAP as an identity back end:
161
162 .. code-block:: ini
163
164 [identity]
165 #driver = sql
166 driver = ldap
167
168#. Create the organizational units (OU) in the LDAP directory, and define
169 the corresponding location in the ``/etc/keystone/keystone.conf``
170 file:
171
172 .. code-block:: ini
173
174 [ldap]
175 user_tree_dn = ou=Users,dc=example,dc=org
176 user_objectclass = inetOrgPerson
177
178 group_tree_dn = ou=Groups,dc=example,dc=org
179 group_objectclass = groupOfNames
180
181 .. note::
182
183 These schema attributes are extensible for compatibility with
184 various schemas. For example, this entry maps to the person
185 attribute in Active Directory:
186
187 .. code-block:: ini
188
189 user_objectclass = person
190
191#. A read-only implementation is recommended for LDAP integration. These
192 permissions are applied to object types in the
193 ``/etc/keystone/keystone.conf`` file:
194
195 .. code-block:: ini
196
197 [ldap]
198 user_allow_create = False
199 user_allow_update = False
200 user_allow_delete = False
201
202 group_allow_create = False
203 group_allow_update = False
204 group_allow_delete = False
205
206 Restart the OpenStack Identity service.
207
208 .. warning::
209
210 During service restart, authentication and authorization are
211 unavailable.
212
213**To integrate multiple Identity back ends with LDAP**
214
215#. Set the following options in the ``/etc/keystone/keystone.conf``
216 file:
217
218 #. Enable the LDAP driver:
219
220 .. code-block:: ini
221
222 [identity]
223 #driver = sql
224 driver = ldap
225
226 #. Enable domain-specific drivers:
227
228 .. code-block:: ini
229
230 [identity]
231 domain_specific_drivers_enabled = True
232 domain_config_dir = /etc/keystone/domains
233
234#. Restart the OpenStack Identity service.
235
236 .. warning::
237
238 During service restart, authentication and authorization are
239 unavailable.
240
241#. List the domains using the dashboard, or the OpenStackClient CLI. Refer
242 to the `Command List
243 <https://docs.openstack.org/developer/python-openstackclient/command-list.html>`__
244 for a list of OpenStackClient commands.
245
246#. Create domains using OpenStack dashboard, or the OpenStackClient CLI.
247
248#. For each domain, create a domain-specific configuration file in the
249 ``/etc/keystone/domains`` directory. Use the file naming convention
250 ``keystone.DOMAIN_NAME.conf``, where DOMAIN\_NAME is the domain name
251 assigned in the previous step.
252
253 .. note::
254
255 The options set in the
256 ``/etc/keystone/domains/keystone.DOMAIN_NAME.conf`` file will
257 override options in the ``/etc/keystone/keystone.conf`` file.
258
259#. Define the destination LDAP server in the
260 ``/etc/keystone/domains/keystone.DOMAIN_NAME.conf`` file. For example:
261
262 .. code-block:: ini
263
264 [ldap]
265 url = ldap://localhost
266 user = dc=Manager,dc=example,dc=org
267 password = samplepassword
268 suffix = dc=example,dc=org
269
270#. Create the organizational units (OU) in the LDAP directories, and define
271 their corresponding locations in the
272 ``/etc/keystone/domains/keystone.DOMAIN_NAME.conf`` file. For example:
273
274 .. code-block:: ini
275
276 [ldap]
277 user_tree_dn = ou=Users,dc=example,dc=org
278 user_objectclass = inetOrgPerson
279
280 group_tree_dn = ou=Groups,dc=example,dc=org
281 group_objectclass = groupOfNames
282
283 .. note::
284
285 These schema attributes are extensible for compatibility with
286 various schemas. For example, this entry maps to the person
287 attribute in Active Directory:
288
289 .. code-block:: ini
290
291 user_objectclass = person
292
293#. A read-only implementation is recommended for LDAP integration. These
294 permissions are applied to object types in the
295 ``/etc/keystone/domains/keystone.DOMAIN_NAME.conf`` file:
296
297 .. code-block:: ini
298
299 [ldap]
300 user_allow_create = False
301 user_allow_update = False
302 user_allow_delete = False
303
304 group_allow_create = False
305 group_allow_update = False
306 group_allow_delete = False
307
308#. Restart the OpenStack Identity service.
309
310 .. warning::
311
312 During service restart, authentication and authorization are
313 unavailable.
314
315**Additional LDAP integration settings**
316
317Set these options in the ``/etc/keystone/keystone.conf`` file for a
318single LDAP server, or ``/etc/keystone/domains/keystone.DOMAIN_NAME.conf``
319files for multiple back ends. Example configurations appear below each
320setting summary:
321
322Filters
323 Use filters to control the scope of data presented through LDAP.
324
325 .. code-block:: ini
326
327 [ldap]
328 user_filter = (memberof=cn=openstack-users,ou=workgroups,dc=example,dc=org)
329 group_filter =
330
331Identity attribute mapping
332 Mask account status values (include any additional attribute
333 mappings) for compatibility with various directory services.
334 Superfluous accounts are filtered with ``user_filter``.
335
336 Setting attribute ignore to list of attributes stripped off on
337 update.
338
339 For example, you can mask Active Directory account status attributes
340 in the ``/etc/keystone/keystone.conf`` file:
341
342 .. code-block:: ini
343
344 [ldap]
345 user_id_attribute = cn
346 user_name_attribute = sn
347 user_mail_attribute = mail
348 user_pass_attribute = userPassword
349 user_enabled_attribute = userAccountControl
350 user_enabled_mask = 2
351 user_enabled_invert = false
352 user_enabled_default = 512
353 user_default_project_id_attribute =
354 user_additional_attribute_mapping =
355
356 group_id_attribute = cn
357 group_name_attribute = ou
358 group_member_attribute = member
359 group_desc_attribute = description
360 group_additional_attribute_mapping =
361
362Enabled emulation
363 An alternative method to determine if a user is enabled or not is by
364 checking if that user is a member of the emulation group.
365
366 Use DN of the group entry to hold enabled user when using enabled
367 emulation.
368
369 .. code-block:: ini
370
371 [ldap]
372 user_enabled_emulation = false
373 user_enabled_emulation_dn = false
374
375When you have finished configuration, restart the OpenStack Identity
376service.
377
378.. warning::
379
380 During service restart, authentication and authorization are
381 unavailable.
382
383Secure the OpenStack Identity service connection to an LDAP back end
384~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
385
386The Identity service supports the use of TLS to encrypt LDAP traffic.
387Before configuring this, you must first verify where your certificate
388authority file is located. For more information, see the
389`OpenStack Security Guide SSL introduction <https://docs.openstack.org/
390security-guide/secure-communication/introduction-to-ssl-and-tls.html>`_.
391
392Once you verify the location of your certificate authority file:
393
394**To configure TLS encryption on LDAP traffic**
395
396#. Open the ``/etc/keystone/keystone.conf`` configuration file.
397
398#. Find the ``[ldap]`` section.
399
400#. In the ``[ldap]`` section, set the ``use_tls`` configuration key to
401 ``True``. Doing so will enable TLS.
402
403#. Configure the Identity service to use your certificate authorities file.
404 To do so, set the ``tls_cacertfile`` configuration key in the ``ldap``
405 section to the certificate authorities file's path.
406
407 .. note::
408
409 You can also set the ``tls_cacertdir`` (also in the ``ldap``
410 section) to the directory where all certificate authorities files
411 are kept. If both ``tls_cacertfile`` and ``tls_cacertdir`` are set,
412 then the latter will be ignored.
413
414#. Specify what client certificate checks to perform on incoming TLS
415 sessions from the LDAP server. To do so, set the ``tls_req_cert``
416 configuration key in the ``[ldap]`` section to ``demand``, ``allow``, or
417 ``never``:
418
419 .. hlist::
420 :columns: 1
421
422 * ``demand`` - The LDAP server always receives certificate
423 requests. The session terminates if no certificate
424 is provided, or if the certificate provided cannot be verified
425 against the existing certificate authorities file.
426 * ``allow`` - The LDAP server always receives certificate
427 requests. The session will proceed as normal even if a certificate
428 is not provided. If a certificate is provided but it cannot be
429 verified against the existing certificate authorities file, the
430 certificate will be ignored and the session will proceed as
431 normal.
432 * ``never`` - A certificate will never be requested.
433
434On distributions that include openstack-config, you can configure TLS
435encryption on LDAP traffic by running the following commands instead.
436
437.. code-block:: console
438
439 # openstack-config --set /etc/keystone/keystone.conf \
440 ldap use_tls True
441 # openstack-config --set /etc/keystone/keystone.conf \
442 ldap tls_cacertfile ``CA_FILE``
443 # openstack-config --set /etc/keystone/keystone.conf \
444 ldap tls_req_cert ``CERT_BEHAVIOR``
445
446Where:
447
448- ``CA_FILE`` is the absolute path to the certificate authorities file
449 that should be used to encrypt LDAP traffic.
450
451- ``CERT_BEHAVIOR`` specifies what client certificate checks to perform
452 on an incoming TLS session from the LDAP server (``demand``,
453 ``allow``, or ``never``).
diff --git a/doc/source/admin/identity-keystone-usage-and-features.rst b/doc/source/admin/identity-keystone-usage-and-features.rst
new file mode 100644
index 0000000..7a71aaa
--- /dev/null
+++ b/doc/source/admin/identity-keystone-usage-and-features.rst
@@ -0,0 +1,83 @@
1
2Example usage and Identity features
3~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
5The ``openstack`` CLI is used to interact with the Identity service.
6It is set up to expect commands in the general
7form of ``openstack command argument``, followed by flag-like keyword
8arguments to provide additional (often optional) information. For
9example, the :command:`openstack user list` and
10:command:`openstack project create` commands can be invoked as follows:
11
12.. code-block:: bash
13
14 # Using token auth env variables
15 export OS_SERVICE_ENDPOINT=http://127.0.0.1:5000/v2.0/
16 export OS_SERVICE_TOKEN=secrete_token
17 openstack user list
18 openstack project create demo --domain default
19
20 # Using token auth flags
21 openstack --os-token secrete --os-endpoint http://127.0.0.1:5000/v2.0/ user list
22 openstack --os-token secrete --os-endpoint http://127.0.0.1:5000/v2.0/ project create demo
23
24 # Using user + password + project_name env variables
25 export OS_USERNAME=admin
26 export OS_PASSWORD=secrete
27 export OS_PROJECT_NAME=admin
28 openstack user list
29 openstack project create demo --domain default
30
31 # Using user + password + project-name flags
32 openstack --os-username admin --os-password secrete --os-project-name admin user list
33 openstack --os-username admin --os-password secrete --os-project-name admin project create demo
34
35
36Logging
37-------
38
39You configure logging externally to the rest of Identity. The name of
40the file specifying the logging configuration is set using the
41``log_config`` option in the ``[DEFAULT]`` section of the
42``/etc/keystone/keystone.conf`` file. To route logging through syslog,
43set ``use_syslog=true`` in the ``[DEFAULT]`` section.
44
45A sample logging configuration file is available with the project in
46``etc/logging.conf.sample``. Like other OpenStack projects, Identity
47uses the Python logging module, which provides extensive configuration
48options that let you define the output levels and formats.
49
50
51User CRUD
52---------
53
54Identity provides a user CRUD (Create, Read, Update, and Delete) filter that
55Administrators can add to the ``public_api`` pipeline. The user CRUD filter
56enables users to use a HTTP PATCH to change their own password. To enable
57this extension you should define a ``user_crud_extension`` filter, insert
58it after the ``*_body`` middleware and before the ``public_service``
59application in the ``public_api`` WSGI pipeline in
60``keystone-paste.ini``. For example:
61
62.. code-block:: ini
63
64 [filter:user_crud_extension]
65 paste.filter_factory = keystone.contrib.user_crud:CrudExtension.factory
66
67 [pipeline:public_api]
68 pipeline = sizelimit url_normalize request_id build_auth_context token_auth admin_token_auth json_body ec2_extension user_crud_extension public_service
69
70Each user can then change their own password with a HTTP PATCH.
71
72.. code-block:: console
73
74 $ curl -X PATCH http://localhost:5000/v2.0/OS-KSCRUD/users/USERID -H "Content-type: application/json" \
75 -H "X_Auth_Token: AUTHTOKENID" -d '{"user": {"password": "ABCD", "original_password": "DCBA"}}'
76
77In addition to changing their password, all current tokens for the user
78are invalidated.
79
80.. note::
81
82 Only use a KVS back end for tokens when testing.
83
diff --git a/doc/source/admin/identity-management.rst b/doc/source/admin/identity-management.rst
new file mode 100644
index 0000000..3c740b7
--- /dev/null
+++ b/doc/source/admin/identity-management.rst
@@ -0,0 +1,31 @@
1.. _identity_management:
2
3====================
4Administrator Guides
5====================
6
7OpenStack Identity, code-named keystone, is the default Identity
8management system for OpenStack. After you install Identity, you
9configure it through the ``/etc/keystone/keystone.conf``
10configuration file and, possibly, a separate logging configuration
11file. You initialize data into Identity by using the ``keystone``
12command-line client.
13
14.. toctree::
15 :maxdepth: 1
16
17 identity-concepts.rst
18 identity-certificates-for-pki.rst
19 identity-domain-specific-config.rst
20 identity-external-authentication.rst
21 identity-integrate-with-ldap.rst
22 identity-tokens.rst
23 identity-token-binding.rst
24 identity-fernet-token-faq.rst
25 identity-use-trusts.rst
26 identity-caching-layer.rst
27 identity-security-compliance.rst
28 identity-keystone-usage-and-features.rst
29 identity-auth-token-middleware.rst
30 identity-service-api-protection.rst
31 identity-troubleshoot.rst
diff --git a/doc/source/admin/identity-security-compliance.rst b/doc/source/admin/identity-security-compliance.rst
new file mode 100644
index 0000000..aefce53
--- /dev/null
+++ b/doc/source/admin/identity-security-compliance.rst
@@ -0,0 +1,167 @@
1.. _identity_security_compliance:
2
3===============================
4Security compliance and PCI-DSS
5===============================
6
7As of the Newton release, the Identity service contains additional security
8compliance features, specifically to satisfy Payment Card Industry -
9Data Security Standard (PCI-DSS) v3.1 requirements. See
10`Security Hardening PCI-DSS`_ for more information on PCI-DSS.
11
12Security compliance features are disabled by default and most of the features
13only apply to the SQL backend for the identity driver. Other identity backends,
14such as LDAP, should implement their own security controls.
15
16Enable these features by changing the configuration settings under the
17``[security_compliance]`` section in ``keystone.conf``.
18
19Setting the account lockout threshold
20-------------------------------------
21
22The account lockout feature limits the number of incorrect password attempts.
23If a user fails to authenticate after the maximum number of attempts, the
24service disables the user. Re-enable the user by explicitly setting the
25enable user attribute with the update user API call, either
26`v2.0`_ or `v3`_.
27
28You set the maximum number of failed authentication attempts by setting
29the ``lockout_failure_attempts``:
30
31.. code-block:: ini
32
33 [security_compliance]
34 lockout_failure_attempts = 6
35
36You set the number of minutes a user would be locked out by setting
37the ``lockout_duration`` in seconds:
38
39.. code-block:: ini
40
41 [security_compliance]
42 lockout_duration = 1800
43
44If you do not set the ``lockout_duration``, users may be locked out
45indefinitely until the user is explicitly enabled via the API.
46
47Disabling inactive users
48------------------------
49
50PCI-DSS 8.1.4 requires that inactive user accounts be removed or disabled
51within 90 days. You can achieve this by setting the
52``disable_user_account_days_inactive``:
53
54.. code-block:: ini
55
56 [security_compliance]
57 disable_user_account_days_inactive = 90
58
59This above example means that users that have not authenticated (inactive) for
60the past 90 days are automatically disabled. Users can be re-enabled by
61explicitly setting the enable user attribute via the API.
62
63Configuring password expiration
64-------------------------------
65
66Passwords can be configured to expire within a certain number of days by
67setting the ``password_expires_days``:
68
69.. code-block:: ini
70
71 [security_compliance]
72 password_expires_days = 90
73
74Once set, any new password changes have an expiration date based on the
75date/time of the password change plus the number of days defined here. Existing
76passwords will not be impacted. If you want existing passwords to have an
77expiration date, you would need to run a SQL script against the password table
78in the database to update the expires_at column.
79
80In addition, you can set it so that passwords never expire for some users by
81adding their user ID to ``password_expires_ignore_user_ids`` list:
82
83.. code-block:: ini
84
85 [security_compliance]
86 password_expires_ignore_user_ids = [3a54353c9dcc44f690975ea768512f6a]
87
88In this example, the password for user ID ``3a54353c9dcc44f690975ea768512f6a``
89would never expire.
90
91Indicating password strength requirements
92-----------------------------------------
93
94You set password strength requirements, such as requiring numbers in passwords
95or setting a minimum password length, by adding a regular expression to the
96``password_regex``:
97
98.. code-block:: ini
99
100 [security_compliance]
101 password_regex = ^(?=.*\d)(?=.*[a-zA-Z]).{7,}$
102
103The above example is a regular expression that requires a password to have
104one letter, one digit, and a minimum length of seven characters.
105
106If you do set the ``password_regex``, you should provide text that
107describes your password strength requirements. You can do this by setting the
108``password_regex_description``:
109
110.. code-block:: ini
111
112 [security_compliance]
113 password_regex_description = Passwords must contain at least 1 letter, 1
114 digit, and be a minimum length of 7
115 characters.
116
117The service returns that description to users to explain why their requested
118password did not meet requirements.
119
120.. note::
121
122 You must ensure the ``password_regex_description`` accurately and
123 completely describes the ``password_regex``. If the two options are out of
124 sync, the help text could inaccurately describe the password requirements
125 being applied to the password. This would lead to poor user experience.
126
127Requiring a unique password history
128-----------------------------------
129
130The password history requirements controls the number of passwords for a user
131that must be unique before an old password can be reused. You can enforce this
132by setting the ``unique_last_password_count``:
133
134.. code-block:: ini
135
136 [security_compliance]
137 unique_last_password_count= 5
138
139The above example does not allow a user to create a new password that is the
140same as any of their last four previous passwords.
141
142Similarly, you can set the number of days that a password must be used before
143the user can change it by setting the ``minimum_password_age``:
144
145.. code-block:: ini
146
147 [security_compliance]
148 minimum_password_age = 1
149
150In the above example, once a user changes their password, they would not be
151able to change it again for one day. This prevents users from changing their
152passwords immediately in order to wipe out their password history and reuse an
153old password.
154
155.. note::
156
157 When you set ``password_expires_days``, the value for the
158 ``minimum_password_age`` should be less than the ``password_expires_days``.
159 Otherwise, users would not be able to change their passwords before they
160 expire.
161
162.. _Security Hardening PCI-DSS: https://specs.openstack.org/openstack/keystone-specs/specs/keystone/newton/pci-dss.html
163
164
165.. _v2.0: https://developer.openstack.org/api-ref/identity/v2-admin/index.html?expanded=update-user-admin-endpoint-detail#update-user-admin-endpoint
166
167.. _v3: https://developer.openstack.org/api-ref/identity/v3/index.html#update-user
diff --git a/doc/source/admin/identity-service-api-protection.rst b/doc/source/admin/identity-service-api-protection.rst
new file mode 100644
index 0000000..99e181a
--- /dev/null
+++ b/doc/source/admin/identity-service-api-protection.rst
@@ -0,0 +1,128 @@
1=============================================================
2Identity API protection with role-based access control (RBAC)
3=============================================================
4
5Like most OpenStack projects, Identity supports the protection of its
6APIs by defining policy rules based on an RBAC approach. Identity stores
7a reference to a policy JSON file in the main Identity configuration
8file, ``/etc/keystone/keystone.conf``. Typically this file is named
9``policy.json``, and contains the rules for which roles have access to
10certain actions in defined services.
11
12Each Identity API v3 call has a line in the policy file that dictates
13which level of governance of access applies.
14
15.. code-block:: none
16
17 API_NAME: RULE_STATEMENT or MATCH_STATEMENT
18
19Where:
20
21``RULE_STATEMENT`` can contain ``RULE_STATEMENT`` or
22``MATCH_STATEMENT``.
23
24``MATCH_STATEMENT`` is a set of identifiers that must match between the
25token provided by the caller of the API and the parameters or target
26entities of the API call in question. For example:
27
28.. code-block:: none
29
30 "identity:create_user": "role:admin and domain_id:%(user.domain_id)s"
31
32Indicates that to create a user, you must have the admin role in your
33token. The ``domain_id`` in your token must match the
34``domain_id`` in the user object that you are trying
35to create, which implies this must be a domain-scoped token.
36In other words, you must have the admin role on the domain
37in which you are creating the user, and the token that you use
38must be scoped to that domain.
39
40Each component of a match statement uses this format:
41
42.. code-block:: none
43
44 ATTRIB_FROM_TOKEN:CONSTANT or ATTRIB_RELATED_TO_API_CALL
45
46The Identity service expects these attributes:
47
48Attributes from token:
49
50- ``user_id``
51- ``domain_id``
52- ``project_id``
53
54The ``project_id`` attribute requirement depends on the scope, and the
55list of roles you have within that scope.
56
57Attributes related to API call:
58
59- ``user.domain_id``
60- Any parameters passed into the API call
61- Any filters specified in the query string
62
63You reference attributes of objects passed with an object.attribute
64syntax (such as, ``user.domain_id``). The target objects of an API are
65also available using a target.object.attribute syntax. For instance:
66
67.. code-block:: none
68
69 "identity:delete_user": "role:admin and domain_id:%(target.user.domain_id)s"
70
71would ensure that Identity only deletes the user object in the same
72domain as the provided token.
73
74Every target object has an ``id`` and a ``name`` available as
75``target.OBJECT.id`` and ``target.OBJECT.name``. Identity retrieves
76other attributes from the database, and the attributes vary between
77object types. The Identity service filters out some database fields,
78such as user passwords.
79
80List of object attributes:
81
82.. code-block:: yaml
83
84 role:
85 target.role.id
86 target.role.name
87
88 user:
89 target.user.default_project_id
90 target.user.description
91 target.user.domain_id
92 target.user.enabled
93 target.user.id
94 target.user.name
95
96 group:
97 target.group.description
98 target.group.domain_id
99 target.group.id
100 target.group.name
101
102 domain:
103 target.domain.enabled
104 target.domain.id
105 target.domain.name
106
107 project:
108 target.project.description
109 target.project.domain_id
110 target.project.enabled
111 target.project.id
112 target.project.name
113
114The default ``policy.json`` file supplied provides a somewhat
115basic example of API protection, and does not assume any particular
116use of domains. Refer to ``policy.v3cloudsample.json`` as an
117example of multi-domain configuration installations where a cloud
118provider wants to delegate administration of the contents of a domain
119to a particular ``admin domain``. This example policy file also
120shows the use of an ``admin_domain`` to allow a cloud provider to
121enable administrators to have wider access across the APIs.
122
123A clean installation could start with the standard policy file, to
124allow creation of the ``admin_domain`` with the first users within
125it. You could then obtain the ``domain_id`` of the admin domain,
126paste the ID into a modified version of
127``policy.v3cloudsample.json``, and then enable it as the main
128``policy file``.
diff --git a/doc/source/admin/identity-token-binding.rst b/doc/source/admin/identity-token-binding.rst
new file mode 100644
index 0000000..82a7c83
--- /dev/null
+++ b/doc/source/admin/identity-token-binding.rst
@@ -0,0 +1,64 @@
1============================================
2Configure Identity service for token binding
3============================================
4
5Token binding embeds information from an external authentication
6mechanism, such as a Kerberos server or X.509 certificate, inside a
7token. By using token binding, a client can enforce the use of a
8specified external authentication mechanism with the token. This
9additional security mechanism ensures that if a token is stolen, for
10example, it is not usable without external authentication.
11
12You configure the authentication types for a token binding in the
13``/etc/keystone/keystone.conf`` file:
14
15.. code-block:: ini
16
17 [token]
18 bind = kerberos
19
20or
21
22.. code-block:: ini
23
24 [token]
25 bind = x509
26
27Currently ``kerberos`` and ``x509`` are supported.
28
29To enforce checking of token binding, set the ``enforce_token_bind``
30option to one of these modes:
31
32- ``disabled``
33 Disables token bind checking.
34
35- ``permissive``
36 Enables bind checking. If a token is bound to an unknown
37 authentication mechanism, the server ignores it. The default is this
38 mode.
39
40- ``strict``
41 Enables bind checking. If a token is bound to an unknown
42 authentication mechanism, the server rejects it.
43
44- ``required``
45 Enables bind checking. Requires use of at least authentication
46 mechanism for tokens.
47
48- ``kerberos``
49 Enables bind checking. Requires use of kerberos as the authentication
50 mechanism for tokens:
51
52 .. code-block:: ini
53
54 [token]
55 enforce_token_bind = kerberos
56
57- ``x509``
58 Enables bind checking. Requires use of X.509 as the authentication
59 mechanism for tokens:
60
61 .. code-block:: ini
62
63 [token]
64 enforce_token_bind = x509
diff --git a/doc/source/admin/identity-tokens.rst b/doc/source/admin/identity-tokens.rst
new file mode 100644
index 0000000..2932fb3
--- /dev/null
+++ b/doc/source/admin/identity-tokens.rst
@@ -0,0 +1,108 @@
1===============
2Keystone tokens
3===============
4
5Tokens are used to authenticate and authorize your interactions with the
6various OpenStack APIs. Tokens come in many flavors, representing various
7authorization scopes and sources of identity. There are also several different
8"token providers", each with their own user experience, performance, and
9deployment characteristics.
10
11Authorization scopes
12--------------------
13
14Tokens can express your authorization in different scopes. You likely have
15different sets of roles, in different projects, and in different domains.
16While tokens always express your identity, they may only ever express one set
17of roles in one authorization scope at a time.
18
19Each level of authorization scope is useful for certain types of operations in
20certain OpenStack services, and are not interchangeable.
21
22Unscoped tokens
23~~~~~~~~~~~~~~~
24
25An unscoped token contains neither a service catalog, any roles, a project
26scope, nor a domain scope. Their primary use case is simply to prove your
27identity to keystone at a later time (usually to generate scoped tokens),
28without repeatedly presenting your original credentials.
29
30The following conditions must be met to receive an unscoped token:
31
32* You must not specify an authorization scope in your authentication request
33 (for example, on the command line with arguments such as
34 ``--os-project-name`` or ``--os-domain-id``),
35
36* Your identity must not have a "default project" associated with it that you
37 also have role assignments, and thus authorization, upon.
38
39Project-scoped tokens
40~~~~~~~~~~~~~~~~~~~~~
41
42Project-scoped tokens are the bread and butter of OpenStack. They express your
43authorization to operate in a specific tenancy of the cloud and are useful to
44authenticate yourself when working with most other services.
45
46They contain a service catalog, a set of roles, and details of the project upon
47which you have authorization.
48
49Domain-scoped tokens
50~~~~~~~~~~~~~~~~~~~~
51
52Domain-scoped tokens also have limited use cases in OpenStack. They express
53your authorization to operate a domain-level, above that of the user and
54projects contained therein (typically as a domain-level administrator).
55Depending on Keystone's configuration, they are useful for working with a
56single domain in Keystone.
57
58They contain a limited service catalog (only those services which do not
59explicitly require per-project endpoints), a set of roles, and details of the
60project upon which you have authorization.
61
62They can also be used to work with domain-level concerns in other services,
63such as to configure domain-wide quotas that apply to all users or projects in
64a specific domain.
65
66Token providers
67---------------
68
69The token type issued by keystone is configurable through the
70``/etc/keystone/keystone.conf`` file. Currently, there are four supported
71token types and they include ``UUID``, ``fernet``, ``PKI``, and ``PKIZ``.
72
73UUID tokens
74~~~~~~~~~~~
75
76UUID was the first token type supported and is currently the default token
77provider. UUID tokens are 32 bytes in length and must be persisted in a back
78end. Clients must pass their UUID token to the Identity service in order to
79validate it.
80
81Fernet tokens
82~~~~~~~~~~~~~
83
84The fernet token format was introduced in the OpenStack Kilo release. Unlike
85the other token types mentioned in this document, fernet tokens do not need to
86be persisted in a back end. ``AES256`` encryption is used to protect the
87information stored in the token and integrity is verified with a ``SHA256
88HMAC`` signature. Only the Identity service should have access to the keys used
89to encrypt and decrypt fernet tokens. Like UUID tokens, fernet tokens must be
90passed back to the Identity service in order to validate them. For more
91information on the fernet token type, see the :doc:`identity-fernet-token-faq`.
92
93PKI and PKIZ tokens
94~~~~~~~~~~~~~~~~~~~
95
96PKI tokens are signed documents that contain the authentication context, as
97well as the service catalog. Depending on the size of the OpenStack deployment,
98these tokens can be very long. The Identity service uses public/private key
99pairs and certificates in order to create and validate PKI tokens.
100
101The same concepts from PKI tokens apply to PKIZ tokens. The only difference
102between the two is PKIZ tokens are compressed to help mitigate the size issues
103of PKI. For more information on the certificate setup for PKI and PKIZ tokens,
104see the :doc:`identity-certificates-for-pki`.
105
106.. note::
107
108 PKI and PKIZ tokens are deprecated and not supported in Ocata.
diff --git a/doc/source/admin/identity-troubleshoot.rst b/doc/source/admin/identity-troubleshoot.rst
new file mode 100644
index 0000000..f8971ef
--- /dev/null
+++ b/doc/source/admin/identity-troubleshoot.rst
@@ -0,0 +1,199 @@
1=================================
2Troubleshoot the Identity service
3=================================
4
5To troubleshoot the Identity service, review the logs in the
6``/var/log/keystone/keystone.log`` file.
7
8Use the ``/etc/keystone/logging.conf`` file to configure the
9location of log files.
10
11.. note::
12
13 The ``insecure_debug`` flag is unique to the Identity service.
14 If you enable ``insecure_debug``, error messages from the API change
15 to return security-sensitive information. For example, the error message
16 on failed authentication includes information on why your authentication
17 failed.
18
19The logs show the components that have come in to the WSGI request, and
20ideally show an error that explains why an authorization request failed.
21If you do not see the request in the logs, run keystone with the
22``--debug`` parameter. Pass the ``--debug`` parameter before the
23command parameters.
24
25Debug PKI middleware
26~~~~~~~~~~~~~~~~~~~~
27
28Problem
29-------
30
31If you receive an ``Invalid OpenStack Identity Credentials`` message when
32you accessing and reaching an OpenStack service, it might be caused by
33the changeover from UUID tokens to PKI tokens in the Grizzly release.
34
35The PKI-based token validation scheme relies on certificates from
36Identity that are fetched through HTTP and stored in a local directory.
37The location for this directory is specified by the ``signing_dir``
38configuration option.
39
40Solution
41--------
42
43In your services configuration file, look for a section like this:
44
45.. code-block:: ini
46
47 [keystone_authtoken]
48 signing_dir = /var/cache/glance/api
49 auth_uri = http://controller:5000/v2.0
50 identity_uri = http://controller:35357
51 admin_tenant_name = service
52 admin_user = glance
53
54The first thing to check is that the ``signing_dir`` does, in fact,
55exist. If it does, check for certificate files:
56
57.. code-block:: console
58
59 $ ls -la /var/cache/glance/api/
60
61 total 24
62 drwx------. 2 ayoung root 4096 Jul 22 10:58 .
63 drwxr-xr-x. 4 root root 4096 Nov 7 2012 ..
64 -rw-r-----. 1 ayoung ayoung 1424 Jul 22 10:58 cacert.pem
65 -rw-r-----. 1 ayoung ayoung 15 Jul 22 10:58 revoked.pem
66 -rw-r-----. 1 ayoung ayoung 4518 Jul 22 10:58 signing_cert.pem
67
68This directory contains two certificates and the token revocation list.
69If these files are not present, your service cannot fetch them from
70Identity. To troubleshoot, try to talk to Identity to make sure it
71correctly serves files, as follows:
72
73.. code-block:: console
74
75 $ curl http://localhost:35357/v2.0/certificates/signing
76
77This command fetches the signing certificate:
78
79.. code-block:: yaml
80
81 Certificate:
82 Data:
83 Version: 3 (0x2)
84 Serial Number: 1 (0x1)
85 Signature Algorithm: sha1WithRSAEncryption
86 Issuer: C=US, ST=Unset, L=Unset, O=Unset, CN=www.example.com
87 Validity
88 Not Before: Jul 22 14:57:31 2013 GMT
89 Not After : Jul 20 14:57:31 2023 GMT
90 Subject: C=US, ST=Unset, O=Unset, CN=www.example.com
91
92Note the expiration dates of the certificate:
93
94.. code-block:: console
95
96 Not Before: Jul 22 14:57:31 2013 GMT
97 Not After : Jul 20 14:57:31 2023 GMT
98
99The token revocation list is updated once a minute, but the certificates
100are not. One possible problem is that the certificates are the wrong
101files or garbage. You can remove these files and run another command
102against your server; they are fetched on demand.
103
104The Identity service log should show the access of the certificate files. You
105might have to turn up your logging levels. Set ``debug = True`` in your
106Identity configuration file and restart the Identity server.
107
108.. code-block:: console
109
110 (keystone.common.wsgi): 2013-07-24 12:18:11,461 DEBUG wsgi __call__
111 arg_dict: {}
112 (access): 2013-07-24 12:18:11,462 INFO core __call__ 127.0.0.1 - - [24/Jul/2013:16:18:11 +0000]
113 "GET http://localhost:35357/v2.0/certificates/signing HTTP/1.0" 200 4518
114
115If the files do not appear in your directory after this, it is likely
116one of the following issues:
117
118* Your service is configured incorrectly and cannot talk to Identity.
119 Check the ``auth_port`` and ``auth_host`` values and make sure that
120 you can talk to that service through cURL, as shown previously.
121
122* Your signing directory is not writable. Use the ``chmod`` command to
123 change its permissions so that the service (POSIX) user can write to
124 it. Verify the change through ``su`` and ``touch`` commands.
125
126* The SELinux policy is denying access to the directory.
127
128SELinux troubles often occur when you use Fedora or RHEL-based packages and
129you choose configuration options that do not match the standard policy.
130Run the ``setenforce permissive`` command. If that makes a difference,
131you should relabel the directory. If you are using a sub-directory of
132the ``/var/cache/`` directory, run the following command:
133
134.. code-block:: console
135
136 # restorecon /var/cache/
137
138If you are not using a ``/var/cache`` sub-directory, you should. Modify
139the ``signing_dir`` configuration option for your service and restart.
140
141Set back to ``setenforce enforcing`` to confirm that your changes solve
142the problem.
143
144If your certificates are fetched on demand, the PKI validation is
145working properly. Most likely, the token from Identity is not valid for
146the operation you are attempting to perform, and your user needs a
147different role for the operation.
148
149Debug signing key file errors
150~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151
152Problem
153-------
154
155If an error occurs when the signing key file opens, it is possible that
156the person who ran the :command:`keystone-manage pki_setup` command to
157generate certificates and keys did not use the correct user.
158
159Solution
160--------
161
162When you run the :command:`keystone-manage pki_setup` command, Identity
163generates a set of certificates and keys in ``/etc/keystone/ssl*``, which
164is owned by ``root:root``. This can present a problem when you run the
165Identity daemon under the keystone user account (nologin) when you try
166to run PKI. Unless you run the :command:`chown` command against the
167files ``keystone:keystone``, or run the :command:`keystone-manage pki_setup`
168command with the ``--keystone-user`` and
169``--keystone-group`` parameters, you will get an error.
170For example:
171
172.. code-block:: console
173
174 2012-07-31 11:10:53 ERROR [keystone.common.cms] Error opening signing key file
175 /etc/keystone/ssl/private/signing_key.pem
176 140380567730016:error:0200100D:system library:fopen:Permission
177 denied:bss_file.c:398:fopen('/etc/keystone/ssl/private/signing_key.pem','r')
178 140380567730016:error:20074002:BIO routines:FILE_CTRL:system lib:bss_file.c:400:
179 unable to load signing key file
180
181Flush expired tokens from the token database table
182~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
183
184Problem
185-------
186
187As you generate tokens, the token database table on the Identity server
188grows.
189
190Solution
191--------
192
193To clear the token table, an administrative user must run the
194:command:`keystone-manage token_flush` command to flush the tokens. When you
195flush tokens, expired tokens are deleted and traceability is eliminated.
196
197Use ``cron`` to schedule this command to run frequently based on your
198workload. For large workloads, running it every minute is recommended.
199
diff --git a/doc/source/admin/identity-use-trusts.rst b/doc/source/admin/identity-use-trusts.rst
new file mode 100644
index 0000000..077e2e9
--- /dev/null
+++ b/doc/source/admin/identity-use-trusts.rst
@@ -0,0 +1,56 @@
1==========
2Use trusts
3==========
4
5OpenStack Identity manages authentication and authorization. A trust is
6an OpenStack Identity extension that enables delegation and, optionally,
7impersonation through ``keystone``. A trust extension defines a
8relationship between:
9
10**Trustor**
11 The user delegating a limited set of their own rights to another user.
12
13**Trustee**
14 The user trust is being delegated to, for a limited time.
15
16 The trust can eventually allow the trustee to impersonate the trustor.
17 For security reasons, some safeties are added. For example, if a trustor
18 loses a given role, any trusts the user issued with that role, and the
19 related tokens, are automatically revoked.
20
21The delegation parameters are:
22
23**User ID**
24 The user IDs for the trustor and trustee.
25
26**Privileges**
27 The delegated privileges are a combination of a project ID and a
28 number of roles that must be a subset of the roles assigned to the
29 trustor.
30
31 If you omit all privileges, nothing is delegated. You cannot
32 delegate everything.
33
34**Delegation depth**
35 Defines whether or not the delegation is recursive. If it is
36 recursive, defines the delegation chain length.
37
38 Specify one of the following values:
39
40 - ``0``. The delegate cannot delegate these permissions further.
41
42 - ``1``. The delegate can delegate the permissions to any set of
43 delegates but the latter cannot delegate further.
44
45 - ``inf``. The delegation is infinitely recursive.
46
47**Endpoints**
48 A list of endpoints associated with the delegation.
49
50 This parameter further restricts the delegation to the specified
51 endpoints only. If you omit the endpoints, the delegation is
52 useless. A special value of ``all_endpoints`` allows the trust to be
53 used by all endpoints associated with the delegated project.
54
55**Duration**
56 (Optional) Comprised of the start time and end time for the trust.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 1147fbb..75951f4 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -85,6 +85,14 @@ the keystone service.
85 advanced-topics/index.rst 85 advanced-topics/index.rst
86 sample_files/index.rst 86 sample_files/index.rst
87 87
88Administrator Guides
89~~~~~~~~~~~~~~~~~~~~
90
91.. toctree::
92 :maxdepth: 2
93
94 admin/identity-management.rst
95
88API Documentation 96API Documentation
89~~~~~~~~~~~~~~~~~ 97~~~~~~~~~~~~~~~~~
90An end user can find the specific API documentation here, `OpenStack's Identity API`_. 98An end user can find the specific API documentation here, `OpenStack's Identity API`_.