Browse Source

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
tags/12.0.0.0b3
Samriddhi Jain 2 years ago
parent
commit
aba9267323

+ 74
- 0
doc/source/admin/identity-auth-token-middleware.rst View File

@@ -0,0 +1,74 @@
1
+Authentication middleware with user name and password
2
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
+
4
+You 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
+
12
+For services that have a separate paste-deploy ``.ini`` file, you can
13
+configure the authentication middleware in the ``[keystone_authtoken]``
14
+section of the main configuration file, such as ``nova.conf``. In
15
+Compute, 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
+
24
+And 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
+
51
+This 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
+

+ 128
- 0
doc/source/admin/identity-caching-layer.rst View File

@@ -0,0 +1,128 @@
1
+.. :orphan:
2
+
3
+Caching layer
4
+~~~~~~~~~~~~~
5
+
6
+OpenStack Identity supports a caching layer that is above the
7
+configurable subsystems (for example, token). OpenStack Identity uses the
8
+`oslo.cache <https://docs.openstack.org/developer/oslo.cache/>`__
9
+library which allows flexible cache back ends. The majority of the
10
+caching configuration options are set in the ``[cache]`` section of the
11
+``/etc/keystone/keystone.conf`` file. However, each section that has
12
+the capability to be cached usually has a caching boolean value that
13
+toggles caching.
14
+
15
+So 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
+
49
+Caching for tokens and tokens validation
50
+----------------------------------------
51
+
52
+All types of tokens benefit from caching, including Fernet tokens. Although
53
+Fernet tokens do not need to be persisted, they should still be cached for
54
+optimal token validation performance.
55
+
56
+The token system has a separate ``cache_time`` configuration option,
57
+that can be set to a value above or below the global ``expiration_time``
58
+default, allowing for different caching behavior from the other systems
59
+in OpenStack Identity. This option is set in the ``[token]`` section of
60
+the configuration file.
61
+
62
+The token revocation list cache time is handled by the configuration
63
+option ``revocation_cache_time`` in the ``[token]`` section. The
64
+revocation list is refreshed whenever a token is revoked. It typically
65
+sees significantly more requests than specific token retrievals or token
66
+validation calls.
67
+
68
+Here is a list of actions that are affected by the cached time: getting
69
+a new token, revoking tokens, validating tokens, checking v2 tokens, and
70
+checking v3 tokens.
71
+
72
+The delete token API calls invalidate the cache for the tokens being
73
+acted upon, as well as invalidating the cache for the revoked token list
74
+and the validate/check token calls.
75
+
76
+Token caching is configurable independently of the ``revocation_list``
77
+caching. Lifted expiration checks from the token drivers to the token
78
+manager. This ensures that cached tokens will still raise a
79
+``TokenNotFound`` flag when expired.
80
+
81
+For cache consistency, all token IDs are transformed into the short
82
+token hash at the provider and token driver level. Some methods have
83
+access to the full ID (PKI Tokens), and some methods do not. Cache
84
+invalidation is inconsistent without token ID normalization.
85
+
86
+Caching for non-token resources
87
+-------------------------------
88
+
89
+Various other keystone components have a separate ``cache_time`` configuration
90
+option, that can be set to a value above or below the global
91
+``expiration_time`` default, allowing for different caching behavior
92
+from the other systems in Identity service. This option can be set in various
93
+sections (for example, ``[role]`` and ``[resource]``) of the configuration
94
+file.
95
+The create, update, and delete actions for domains, projects and roles
96
+will perform proper invalidations of the cached methods listed above.
97
+
98
+For more information about the different back ends (and configuration
99
+options), 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
+
114
+Configure the Memcached back end example
115
+----------------------------------------
116
+
117
+The 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
+
127
+You need to specify the URL to reach the ``memcached`` instance with the
128
+``backend_argument`` parameter.

+ 237
- 0
doc/source/admin/identity-certificates-for-pki.rst View File

@@ -0,0 +1,237 @@
1
+====================
2
+Certificates for PKI
3
+====================
4
+
5
+PKI stands for Public Key Infrastructure. Tokens are documents,
6
+cryptographically signed using the X509 standard. In order to work
7
+correctly token generation requires a public/private key pair. The
8
+public key must be signed in an X509 certificate, and the certificate
9
+used to sign it must be available as a Certificate Authority (CA)
10
+certificate. These files can be generated either using the
11
+:command:`keystone-manage` utility, or externally generated. The files need to
12
+be in the locations specified by the top level Identity service
13
+configuration file ``/etc/keystone/keystone.conf`` as specified in the
14
+above section. Additionally, the private key should only be readable by
15
+the 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
+
28
+The values that specify where to read the certificates are under the
29
+``[signing]`` section of the configuration file. The configuration
30
+values 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
+
59
+When generating certificates with the :command:`keystone-manage pki_setup`
60
+command, the ``ca_key``, ``key_size``, and ``valid_days`` configuration
61
+options are used.
62
+
63
+If the :command:`keystone-manage pki_setup` command is not used to generate
64
+certificates, or you are providing your own certificates, these values
65
+do not need to be set.
66
+
67
+If ``provider=keystone.token.providers.uuid.Provider`` in the
68
+``[token]`` section of the keystone configuration file, a typical token
69
+looks like ``53f7f6ef0cc344b5be706bcc8b1479e1``. If
70
+``provider=keystone.token.providers.pki.Provider``, a typical token is a
71
+much 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
+
101
+Sign certificate issued by external CA
102
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103
+
104
+You can use a signing certificate issued by an external CA instead of
105
+generated by :command:`keystone-manage`. However, a certificate issued by an
106
+external 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
+
113
+When using a signing certificate issued by an external CA, you do not
114
+need to specify ``key_size``, ``valid_days``, and ``ca_password`` as
115
+they will be ignored.
116
+
117
+The basic workflow for using a signing certificate issued by an external
118
+CA 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
+
126
+Request a signing certificate from an external CA
127
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128
+
129
+One way to request a signing certificate from an external CA is to first
130
+generate a PKCS #10 Certificate Request Syntax (CRS) using OpenSSL CLI.
131
+
132
+Create 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
+
154
+Then generate a CRS with OpenSSL CLI. **Do not encrypt the generated
155
+private key. You must use the -nodes option.**
156
+
157
+For 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
+
164
+If 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
167
+and make sure to ask the certificate to be in PEM format. Also, make sure your
168
+trusted CA certificate chain is also in PEM format.
169
+
170
+Install an external signing certificate
171
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172
+
173
+Assuming 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
+
184
+Copy 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
+
209
+If 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
+
213
+Switching out expired signing certificates
214
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215
+
216
+The following procedure details how to switch out expired signing
217
+certificates 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.

+ 354
- 0
doc/source/admin/identity-concepts.rst View File

@@ -0,0 +1,354 @@
1
+=================
2
+Identity concepts
3
+=================
4
+
5
+Authentication
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
+
13
+Credentials
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
+
18
+Domain
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
+
28
+Endpoint
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
+
34
+Group
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
+
41
+OpenStackClient
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
+
48
+Project
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
+
53
+Region
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
+
60
+Role
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
+
68
+Service
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
+
74
+Token
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
+
83
+User
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
+
91
+User management
92
+~~~~~~~~~~~~~~~
93
+
94
+Identity 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
+
130
+The Identity service assigns a project and a role to a user. You might
131
+assign the ``compute-user`` role to the ``alice`` user in the ``acme``
132
+project:
133
+
134
+.. code-block:: console
135
+
136
+   $ openstack role add --project acme --user alice compute-user
137
+
138
+A user can have different roles in different projects. For example, Alice
139
+might also have the ``admin`` role in the ``Cyberdyne`` project. A user
140
+can also have multiple roles in the same project.
141
+
142
+The ``/etc/[SERVICE_CODENAME]/policy.json`` file controls the
143
+tasks that users can perform for a given service. For example, the
144
+``/etc/nova/policy.json`` file specifies the access policy for the
145
+Compute service, the ``/etc/glance/policy.json`` file specifies
146
+the access policy for the Image service, and the
147
+``/etc/keystone/policy.json`` file specifies the access policy for
148
+the Identity service.
149
+
150
+The default ``policy.json`` files in the Compute, Identity, and
151
+Image services recognize only the ``admin`` role. Any user with
152
+any role in a project can access all operations that do not require the
153
+``admin`` role.
154
+
155
+To restrict users from performing operations in, for example, the
156
+Compute service, you must create a role in the Identity service and
157
+then modify the ``/etc/nova/policy.json`` file so that this role
158
+is required for Compute operations.
159
+
160
+For example, the following line in the ``/etc/cinder/policy.json``
161
+file does not restrict which users can create volumes:
162
+
163
+.. code-block:: none
164
+
165
+   "volume:create": "",
166
+
167
+If the user has any role in a project, he can create volumes in that
168
+project.
169
+
170
+To 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
+
177
+To restrict all Compute service requests to require this role, the
178
+resulting 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
+
280
+Service management
281
+~~~~~~~~~~~~~~~~~~
282
+
283
+The Identity service provides identity, token, catalog, and policy
284
+services. 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
+
301
+The Identity service also maintains a user that corresponds to each
302
+service, such as, a user named ``nova`` for the Compute service, and a
303
+special service project called ``service``.
304
+
305
+For information about how to create services and endpoints, see the
306
+`OpenStack Administrator Guide <https://docs.openstack.org/admin-guide/
307
+cli-manage-services.html>`__.
308
+
309
+Groups
310
+~~~~~~
311
+
312
+A group is a collection of users in a domain. Administrators can
313
+create groups and add users to them. A role can then be assigned to
314
+the group, rather than individual users. Groups were introduced with
315
+the Identity API v3.
316
+
317
+Identity 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
+
346
+Here 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.

+ 69
- 0
doc/source/admin/identity-domain-specific-config.rst View File

@@ -0,0 +1,69 @@
1
+=============================
2
+Domain-specific configuration
3
+=============================
4
+
5
+The Identity service supports domain-specific Identity drivers.
6
+The drivers allow a domain to have its own LDAP or SQL back end.
7
+By default, domain-specific drivers are disabled.
8
+
9
+Domain-specific Identity configuration options can be stored in
10
+domain-specific configuration files, or in the Identity SQL
11
+database 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
+
19
+Enable drivers for domain-specific configuration files
20
+------------------------------------------------------
21
+
22
+To 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
+
31
+When 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
34
+configuration file uses options in the primary configuration file.
35
+
36
+Enable drivers for storing configuration options in SQL database
37
+----------------------------------------------------------------
38
+
39
+To 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
+
48
+Any domain-specific configuration options specified through the
49
+Identity v3 API will override domain-specific configuration files in the
50
+``/etc/keystone/domains`` directory.
51
+
52
+Migrate domain-specific configuration files to the SQL database
53
+---------------------------------------------------------------
54
+
55
+You can use the ``keystone-manage`` command to migrate configuration
56
+options in domain-specific configuration files to the SQL database:
57
+
58
+.. code-block:: console
59
+
60
+   # keystone-manage domain_config_upload --all
61
+
62
+To upload options from a specific domain-configuration file, specify the
63
+domain name:
64
+
65
+.. code-block:: console
66
+
67
+   # keystone-manage domain_config_upload --domain-name DOMAIN_NAME
68
+
69
+

+ 41
- 0
doc/source/admin/identity-external-authentication.rst View File

@@ -0,0 +1,41 @@
1
+=====================================
2
+External authentication with Identity
3
+=====================================
4
+
5
+When Identity runs in ``apache-httpd``, you can use external
6
+authentication methods that differ from the authentication provided by
7
+the identity store back end. For example, you can use an SQL identity
8
+back end together with X.509 authentication and Kerberos, instead of
9
+using the user name and password combination.
10
+
11
+Use HTTPD authentication
12
+~~~~~~~~~~~~~~~~~~~~~~~~
13
+
14
+Web servers, like Apache HTTP, support many methods of authentication.
15
+Identity can allow the web server to perform the authentication. The web
16
+server then passes the authenticated user to Identity by using the
17
+``REMOTE_USER`` environment variable. This user must already exist in
18
+the Identity back end to get a token from the controller. To use this
19
+method, Identity should run on ``apache-httpd``.
20
+
21
+Use X.509
22
+~~~~~~~~~
23
+
24
+The following Apache configuration snippet authenticates the user based
25
+on 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>

+ 345
- 0
doc/source/admin/identity-fernet-token-faq.rst View File

@@ -0,0 +1,345 @@
1
+===================================
2
+Fernet - Frequently Asked Questions
3
+===================================
4
+
5
+The following questions have been asked periodically since the initial release
6
+of the fernet token format in Kilo.
7
+
8
+What are the different types of keys?
9
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10
+
11
+A key repository is required by keystone in order to create fernet tokens.
12
+These keys are used to encrypt and decrypt the information that makes up the
13
+payload of the token. Each key in the repository can have one of three states.
14
+The state of the key determines how keystone uses a key with fernet tokens. The
15
+different types are as follows:
16
+
17
+Primary 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.
21
+Secondary 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.
27
+Staged 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
+
36
+So, how does a staged key help me and why do I care about it?
37
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38
+
39
+The fernet keys have a natural lifecycle. Each key starts as a staged key, is
40
+promoted to be the primary key, and then demoted to be a secondary key. New
41
+tokens can only be encrypted with a primary key. Secondary and staged keys are
42
+never used to encrypt token. The staged key is a special key given the order of
43
+events and the attributes of each type of key. The staged key is the only key
44
+in the repository that has not had a chance to encrypt any tokens yet, but it
45
+is still allowed to decrypt tokens. As an operator, this gives you the chance
46
+to perform a key rotation on one keystone node, and distribute the new key set
47
+over a span of time. This does not require the distribution to take place in an
48
+ultra short period of time. Tokens encrypted with a primary key can be
49
+decrypted, and validated, on other nodes where that key is still staged.
50
+
51
+Where do I put my key repository?
52
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53
+
54
+The key repository is specified using the ``key_repository`` option in the
55
+keystone configuration file. The keystone process should be able to read and
56
+write to this location but it should be kept secret otherwise. Currently,
57
+keystone only supports file-backed key repositories.
58
+
59
+.. code-block:: ini
60
+
61
+   [fernet_tokens]
62
+   key_repository = /etc/keystone/fernet-keys/
63
+
64
+What is the recommended way to rotate and distribute keys?
65
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66
+
67
+The :command:`keystone-manage` command line utility includes a key rotation
68
+mechanism. This mechanism will initialize and rotate keys but does not make
69
+an effort to distribute keys across keystone nodes. The distribution of keys
70
+across a keystone deployment is best handled through configuration management
71
+tooling. Use :command:`keystone-manage fernet_rotate` to rotate the key
72
+repository.
73
+
74
+Do fernet tokens still expire?
75
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76
+
77
+Yes, fernet tokens can expire just like any other keystone token formats.
78
+
79
+Why should I choose fernet tokens over UUID tokens?
80
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
81
+
82
+Even though fernet tokens operate very similarly to UUID tokens, they do not
83
+require persistence. The keystone token database no longer suffers bloat as a
84
+side effect of authentication. Pruning expired tokens from the token database
85
+is no longer required when using fernet tokens. Because fernet tokens do not
86
+require persistence, they do not have to be replicated. As long as each
87
+keystone node shares the same key repository, fernet tokens can be created and
88
+validated instantly across nodes.
89
+
90
+Why should I choose fernet tokens over PKI or PKIZ tokens?
91
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92
+
93
+The arguments for using fernet over PKI and PKIZ remain the same as UUID, in
94
+addition to the fact that fernet tokens are much smaller than PKI and PKIZ
95
+tokens. PKI and PKIZ tokens still require persistent storage and can sometimes
96
+cause issues due to their size. This issue is mitigated when switching to
97
+fernet because fernet tokens are kept under a 250 byte limit. PKI and PKIZ
98
+tokens typically exceed 1600 bytes in length. The length of a PKI or PKIZ token
99
+is dependent on the size of the deployment. Bigger service catalogs will result
100
+in longer token lengths. This pattern does not exist with fernet tokens because
101
+the contents of the encrypted payload is kept to a minimum.
102
+
103
+Should I rotate and distribute keys from the same keystone node every rotation?
104
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
+
106
+No, but the relationship between rotation and distribution should be lock-step.
107
+Once you rotate keys on one keystone node, the key repository from that node
108
+should be distributed to the rest of the cluster. Once you confirm that each
109
+node has the same key repository state, you could rotate and distribute from
110
+any other node in the cluster.
111
+
112
+If the rotation and distribution are not lock-step, a single keystone node in
113
+the deployment will create tokens with a primary key that no other node has as
114
+a staged key. This will cause tokens generated from one keystone node to fail
115
+validation on other keystone nodes.
116
+
117
+How do I add new keystone nodes to a deployment?
118
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119
+
120
+The keys used to create fernet tokens should be treated like super secret
121
+configuration files, similar to an SSL secret key. Before a node is allowed to
122
+join an existing cluster, issuing and validating tokens, it should have the
123
+same key repository as the rest of the nodes in the cluster.
124
+
125
+How should I approach key distribution?
126
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127
+
128
+Remember that key distribution is only required in multi-node keystone
129
+deployments. If you only have one keystone node serving requests in your
130
+deployment, key distribution is unnecessary.
131
+
132
+Key distribution is a problem best approached from the deployment's current
133
+configuration management system. Since not all deployments use the same
134
+configuration management systems, it makes sense to explore options around what
135
+is already available for managing keys, while keeping the secrecy of the keys
136
+in mind. Many configuration management tools can leverage something like
137
+``rsync`` to manage key distribution.
138
+
139
+Key rotation is a single operation that promotes the current staged key to
140
+primary, creates a new staged key, and prunes old secondary keys. It is easiest
141
+to do this on a single node and verify the rotation took place properly before
142
+distributing the key repository to the rest of the cluster. The concept behind
143
+the staged key breaks the expectation that key rotation and key distribution
144
+have to be done in a single step. With the staged key, we have time to inspect
145
+the new key repository before syncing state with the rest of the cluster. Key
146
+distribution should be an operation that can run in succession until it
147
+succeeds. The following might help illustrate the isolation between key
148
+rotation 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
+
192
+How long should I keep my keys around?
193
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
194
+
195
+The fernet tokens that keystone creates are only secure as the keys creating
196
+them. With staged keys the penalty of key rotation is low, allowing you to err
197
+on the side of security and rotate weekly, daily, or even hourly.  Ultimately,
198
+this should be less time than it takes an attacker to break a ``AES256`` key
199
+and a ``SHA256 HMAC``.
200
+
201
+Is a fernet token still a bearer token?
202
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
203
+
204
+Yes, and they follow exactly the same validation path as UUID tokens, with the
205
+exception of being written to, and read from, a back end. If someone
206
+compromises your fernet token, they have the power to do all the operations you
207
+are allowed to do.
208
+
209
+What if I need to revoke all my tokens?
210
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211
+
212
+To invalidate every token issued from keystone and start fresh, remove the
213
+current key repository, create a new key set, and redistribute it to all nodes
214
+in the cluster. This will render every token issued from keystone as invalid
215
+regardless if the token has actually expired. When a client goes to
216
+re-authenticate, the new token will have been created with a new fernet key.
217
+
218
+What can an attacker do if they compromise a fernet key in my deployment?
219
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220
+
221
+If any key used in the key repository is compromised, an attacker will be able
222
+to build their own tokens. If they know the ID of an administrator on a
223
+project, they could generate administrator tokens for the project. They will be
224
+able to generate their own tokens until the compromised key has been removed
225
+from from the repository.
226
+
227
+I rotated keys and now tokens are invalidating early, what did I do?
228
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
229
+
230
+Using fernet tokens requires some awareness around token expiration and the key
231
+lifecycle. You do not want to rotate so often that secondary keys are removed
232
+that might still be needed to decrypt unexpired tokens. If this happens, you
233
+will not be able to decrypt the token because the key the was used to encrypt
234
+it is now gone. Only remove keys that you know are not being used to encrypt or
235
+decrypt tokens.
236
+
237
+For example, your token is valid for 24 hours and we want to rotate keys every
238
+six hours. We will need to make sure tokens that were created at 08:00 AM on
239
+Monday are still valid at 07:00 AM on Tuesday, assuming they were not
240
+prematurely 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
242
+hold all keys that might still be required to validate a previous token, but
243
+keeps the key repository limited to only the keys that are needed.
244
+
245
+The number of ``max_active_keys`` for a deployment can be determined by
246
+dividing the token lifetime, in hours, by the frequency of rotation in hours
247
+and adding two. Better illustrated as::
248
+
249
+    token_expiration = 24
250
+    rotation_frequency = 6
251
+    max_active_keys = (token_expiration / rotation_frequency) + 2
252
+
253
+The reason for adding two additional keys to the count is to include the staged
254
+key and a buffer key. This can be shown based on the previous example. We
255
+initially setup the key repository at 6:00 AM on Monday, and the initial state
256
+looks 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
+
266
+All tokens created after 6:00 AM are encrypted with key ``1``. At 12:00 PM we
267
+will 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
+
278
+We are still able to validate tokens created between 6:00 - 11:59 AM because
279
+the ``1`` key still exists as a secondary key. All tokens issued after 12:00 PM
280
+will be encrypted with key ``2``. At 6:00 PM we do our next rotation, resulting
281
+in:
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
+
293
+It is still possible to validate tokens issued from 6:00 AM - 5:59 PM because
294
+keys ``1`` and ``2`` exist as secondary keys. Every token issued until 11:59 PM
295
+will 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
+
308
+Just like before, we can still validate tokens issued from 6:00 AM the previous
309
+day until 5:59 AM today because keys ``1`` - ``4`` are present. At 6:00 AM,
310
+tokens issued from the previous day will start to expire and we do our next
311
+scheduled 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
+
325
+Tokens will naturally expire after 6:00 AM, but we will not be able to remove
326
+key ``1`` until the next rotation because it encrypted all tokens from 6:00 AM
327
+to 12:00 PM the day before. Once we do our next rotation, which is at 12:00 PM,
328
+the ``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
+
342
+If keystone were to receive a token that was created between 6:00 AM and 12:00
343
+PM the day before, encrypted with the ``1`` key, it would not be valid because
344
+it was already expired. This makes it possible for us to remove the ``1`` key
345
+from the repository without negative validation side-effects.

+ 453
- 0
doc/source/admin/identity-integrate-with-ldap.rst View File

@@ -0,0 +1,453 @@
1
+.. _integrate-identity-with-ldap:
2
+
3
+============================
4
+Integrate Identity with LDAP
5
+============================
6
+
7
+The OpenStack Identity service supports integration with existing LDAP
8
+directories for authentication and authorization services. LDAP back
9
+ends require initialization before configuring the OpenStack Identity
10
+service to work with it. For more information, see `Setting up LDAP
11
+for use with Keystone <https://wiki.openstack.org/wiki/OpenLDAP>`__.
12
+
13
+When the OpenStack Identity service is configured to use LDAP back ends,
14
+you can split authentication (using the *identity* feature) and
15
+authorization (using the *assignment* feature).
16
+
17
+The *identity* feature enables administrators to manage users and groups
18
+by each domain or the OpenStack Identity service entirely.
19
+
20
+The *assignment* feature enables administrators to manage project role
21
+authorization using the OpenStack Identity service SQL database, while
22
+providing user authentication through the LDAP directory.
23
+
24
+.. _identity_ldap_server_setup:
25
+
26
+Identity 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
+
41
+The Identity configuration is split into two separate back ends; identity
42
+(back end for users and groups), and assignments (back end for domains,
43
+projects, roles, role assignments). To configure Identity, set options
44
+in the ``/etc/keystone/keystone.conf`` file. See
45
+:ref:`integrate-identity-backend-ldap` for Identity back end configuration
46
+examples. 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
+
63
+Set these options in the ``/etc/keystone/keystone.conf`` file for a
64
+single LDAP server, or ``/etc/keystone/domains/keystone.DOMAIN_NAME.conf``
65
+files for multiple back ends. Example configurations appear below each
66
+setting 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
+
91
+Use ``debug_level`` to set the LDAP debugging level for LDAP calls.
92
+A 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
+
106
+Use ``use_pool`` to enable LDAP connection pooling. Configure the
107
+connection pool size, maximum retry, reconnect trials, timeout (-1
108
+indicates 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
+
122
+Use ``use_auth_pool`` to enable LDAP connection pooling for end user
123
+authentication. Configure the connection pool size and lifetime in
124
+seconds.
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
+
133
+When you have finished the configuration, restart the OpenStack Identity
134
+service.
135
+
136
+.. warning::
137
+
138
+   During the service restart, authentication and authorization are
139
+   unavailable.
140
+
141
+.. _integrate-identity-backend-ldap:
142
+
143
+Integrate Identity back end with LDAP
144
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145
+
146
+The Identity back end contains information for users, groups, and group
147
+member lists. Integrating the Identity back end with LDAP allows
148
+administrators 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
+
317
+Set these options in the ``/etc/keystone/keystone.conf`` file for a
318
+single LDAP server, or ``/etc/keystone/domains/keystone.DOMAIN_NAME.conf``
319
+files for multiple back ends. Example configurations appear below each
320
+setting summary:
321
+
322
+Filters
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
+
331
+Identity 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
+
362
+Enabled 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
+
375
+When you have finished configuration, restart the OpenStack Identity
376
+service.
377
+
378
+.. warning::
379
+
380
+   During service restart, authentication and authorization are
381
+   unavailable.
382
+
383
+Secure the OpenStack Identity service connection to an LDAP back end
384
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
385
+
386
+The Identity service supports the use of TLS to encrypt LDAP traffic.
387
+Before configuring this, you must first verify where your certificate
388
+authority file is located. For more information, see the
389
+`OpenStack Security Guide SSL introduction <https://docs.openstack.org/
390
+security-guide/secure-communication/introduction-to-ssl-and-tls.html>`_.
391
+
392
+Once 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
+
434
+On distributions that include openstack-config, you can configure TLS
435
+encryption 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
+
446
+Where:
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``).

+ 83
- 0
doc/source/admin/identity-keystone-usage-and-features.rst View File

@@ -0,0 +1,83 @@
1
+
2
+Example usage and Identity features
3
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
+
5
+The ``openstack`` CLI is used to interact with the Identity service.
6
+It is set up to expect commands in the general
7
+form of ``openstack command argument``, followed by flag-like keyword
8
+arguments to provide additional (often optional) information. For
9
+example, 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
+
36
+Logging
37
+-------
38
+
39
+You configure logging externally to the rest of Identity. The name of
40
+the 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,
43
+set ``use_syslog=true`` in the ``[DEFAULT]`` section.
44
+
45
+A sample logging configuration file is available with the project in
46
+``etc/logging.conf.sample``. Like other OpenStack projects, Identity
47
+uses the Python logging module, which provides extensive configuration
48
+options that let you define the output levels and formats.
49
+
50
+
51
+User CRUD
52
+---------
53
+
54
+Identity provides a user CRUD (Create, Read, Update, and Delete) filter that
55
+Administrators can add to the ``public_api`` pipeline. The user CRUD filter
56
+enables users to use a HTTP PATCH to change their own password. To enable
57
+this extension you should define a ``user_crud_extension`` filter, insert
58
+it after the ``*_body`` middleware and before the ``public_service``
59
+application 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
+
70
+Each 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
+
77
+In addition to changing their password, all current tokens for the user
78
+are invalidated.
79
+
80
+.. note::
81
+
82
+    Only use a KVS back end for tokens when testing.
83
+

+ 31
- 0
doc/source/admin/identity-management.rst View File

@@ -0,0 +1,31 @@
1
+.. _identity_management:
2
+
3
+====================
4
+Administrator Guides
5
+====================
6
+
7
+OpenStack Identity, code-named keystone, is the default Identity
8
+management system for OpenStack. After you install Identity, you
9
+configure it through the ``/etc/keystone/keystone.conf``
10
+configuration file and, possibly, a separate logging configuration
11
+file. You initialize data into Identity by using the ``keystone``
12
+command-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

+ 167
- 0
doc/source/admin/identity-security-compliance.rst View File

@@ -0,0 +1,167 @@
1
+.. _identity_security_compliance:
2
+
3
+===============================
4
+Security compliance and PCI-DSS
5
+===============================
6
+
7
+As of the Newton release, the Identity service contains additional security
8
+compliance features, specifically to satisfy Payment Card Industry -
9
+Data Security Standard (PCI-DSS) v3.1 requirements. See
10
+`Security Hardening PCI-DSS`_ for more information on PCI-DSS.
11
+
12
+Security compliance features are disabled by default and most of the features
13
+only apply to the SQL backend for the identity driver. Other identity backends,
14
+such as LDAP, should implement their own security controls.
15
+
16
+Enable these features by changing the configuration settings under the
17
+``[security_compliance]`` section in ``keystone.conf``.
18
+
19
+Setting the account lockout threshold
20
+-------------------------------------
21
+
22
+The account lockout feature limits the number of incorrect password attempts.
23
+If a user fails to authenticate after the maximum number of attempts, the
24
+service disables the user. Re-enable the user by explicitly setting the
25
+enable user attribute with the update user API call, either
26
+`v2.0`_ or `v3`_.
27
+
28
+You set the maximum number of failed authentication attempts by setting
29
+the ``lockout_failure_attempts``:
30
+
31
+.. code-block:: ini
32
+
33
+    [security_compliance]
34
+    lockout_failure_attempts = 6
35
+
36
+You set the number of minutes a user would be locked out by setting
37
+the ``lockout_duration`` in seconds:
38
+
39
+.. code-block:: ini
40
+
41
+    [security_compliance]
42
+    lockout_duration = 1800
43
+
44
+If you do not set the ``lockout_duration``, users may be locked out
45
+indefinitely until the user is explicitly enabled via the API.
46
+
47
+Disabling inactive users
48
+------------------------
49
+
50
+PCI-DSS 8.1.4 requires that inactive user accounts be removed or disabled
51
+within 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
+
59
+This above example means that users that have not authenticated (inactive) for
60
+the past 90 days are automatically disabled. Users can be re-enabled by
61
+explicitly setting the enable user attribute via the API.
62
+
63
+Configuring password expiration
64
+-------------------------------
65
+
66
+Passwords can be configured to expire within a certain number of days by
67
+setting the ``password_expires_days``:
68
+
69
+.. code-block:: ini
70
+
71
+    [security_compliance]
72
+    password_expires_days = 90
73
+
74
+Once set, any new password changes have an expiration date based on the
75
+date/time of the password change plus the number of days defined here. Existing
76
+passwords will not be impacted. If you want existing passwords to have an
77
+expiration date, you would need to run a SQL script against the password table
78
+in the database to update the expires_at column.
79
+
80
+In addition, you can set it so that passwords never expire for some users by
81
+adding 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
+
88
+In this example, the password for user ID ``3a54353c9dcc44f690975ea768512f6a``
89
+would never expire.
90
+
91
+Indicating password strength requirements
92
+-----------------------------------------
93
+
94
+You set password strength requirements, such as requiring numbers in passwords
95
+or 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
+
103
+The above example is a regular expression that requires a password to have
104
+one letter, one digit, and a minimum length of seven characters.
105
+
106
+If you do set the ``password_regex``, you should provide text that
107
+describes 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
+
117
+The service returns that description to users to explain why their requested
118
+password 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
+
127
+Requiring a unique password history
128
+-----------------------------------
129
+
130
+The password history requirements controls the number of passwords for a user
131
+that must be unique before an old password can be reused. You can enforce this
132
+by setting the ``unique_last_password_count``:
133
+
134
+.. code-block:: ini
135
+
136
+    [security_compliance]
137
+    unique_last_password_count= 5
138
+
139
+The above example does not allow a user to create a new password that is the
140
+same as any of their last four previous passwords.
141
+
142
+Similarly, you can set the number of days that a password must be used before
143
+the 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
+
150
+In the above example, once a user changes their password, they would not be
151
+able to change it again for one day. This prevents users from changing their
152
+passwords immediately in order to wipe out their password history and reuse an
153
+old 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

+ 128
- 0
doc/source/admin/identity-service-api-protection.rst View File

@@ -0,0 +1,128 @@
1
+=============================================================
2
+Identity API protection with role-based access control (RBAC)
3
+=============================================================
4
+
5
+Like most OpenStack projects, Identity supports the protection of its
6
+APIs by defining policy rules based on an RBAC approach. Identity stores
7
+a reference to a policy JSON file in the main Identity configuration
8
+file, ``/etc/keystone/keystone.conf``. Typically this file is named
9
+``policy.json``, and contains the rules for which roles have access to
10
+certain actions in defined services.
11
+
12
+Each Identity API v3 call has a line in the policy file that dictates
13
+which level of governance of access applies.
14
+
15
+.. code-block:: none
16
+
17
+   API_NAME: RULE_STATEMENT or MATCH_STATEMENT
18
+
19
+Where:
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
25
+token provided by the caller of the API and the parameters or target
26
+entities 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
+
32
+Indicates that to create a user, you must have the admin role in your
33
+token. The ``domain_id`` in your token must match the
34
+``domain_id`` in the user object that you are trying
35
+to create, which implies this must be a domain-scoped token.
36
+In other words, you must have the admin role on the domain
37
+in which you are creating the user, and the token that you use
38
+must be scoped to that domain.
39
+
40
+Each 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
+
46
+The Identity service expects these attributes:
47
+
48
+Attributes from token:
49
+
50
+- ``user_id``
51
+- ``domain_id``
52
+- ``project_id``
53
+
54
+The ``project_id`` attribute requirement depends on the scope, and the
55
+list of roles you have within that scope.
56
+
57
+Attributes 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
+
63
+You reference attributes of objects passed with an object.attribute
64
+syntax (such as, ``user.domain_id``). The target objects of an API are
65
+also 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
+
71
+would ensure that Identity only deletes the user object in the same
72
+domain as the provided token.
73
+
74
+Every target object has an ``id`` and a ``name`` available as
75
+``target.OBJECT.id`` and ``target.OBJECT.name``. Identity retrieves
76
+other attributes from the database, and the attributes vary between
77
+object types. The Identity service filters out some database fields,
78
+such as user passwords.
79
+
80
+List 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
+
114
+The default ``policy.json`` file supplied provides a somewhat
115
+basic example of API protection, and does not assume any particular
116
+use of domains. Refer to ``policy.v3cloudsample.json`` as an
117
+example of multi-domain configuration installations where a cloud
118
+provider wants to delegate administration of the contents of a domain
119
+to a particular ``admin domain``. This example policy file also
120
+shows the use of an ``admin_domain`` to allow a cloud provider to
121
+enable administrators to have wider access across the APIs.
122
+
123
+A clean installation could start with the standard policy file, to
124
+allow creation of the ``admin_domain`` with the first users within
125
+it. You could then obtain the ``domain_id`` of the admin domain,
126
+paste the ID into a modified version of
127
+``policy.v3cloudsample.json``, and then enable it as the main
128
+``policy file``.

+ 64
- 0
doc/source/admin/identity-token-binding.rst View File

@@ -0,0 +1,64 @@
1
+============================================
2
+Configure Identity service for token binding
3
+============================================
4
+
5
+Token binding embeds information from an external authentication
6
+mechanism, such as a Kerberos server or X.509 certificate, inside a
7
+token. By using token binding, a client can enforce the use of a
8
+specified external authentication mechanism with the token. This
9
+additional security mechanism ensures that if a token is stolen, for
10
+example, it is not usable without external authentication.
11
+
12
+You 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
+
20
+or
21
+
22
+.. code-block:: ini
23
+
24
+   [token]
25
+   bind = x509
26
+
27
+Currently ``kerberos`` and ``x509`` are supported.
28
+
29
+To enforce checking of token binding, set the ``enforce_token_bind``
30
+option 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

+ 108
- 0
doc/source/admin/identity-tokens.rst View File

@@ -0,0 +1,108 @@
1
+===============
2
+Keystone tokens
3
+===============
4
+
5
+Tokens are used to authenticate and authorize your interactions with the
6
+various OpenStack APIs. Tokens come in many flavors, representing various
7
+authorization scopes and sources of identity. There are also several different
8
+"token providers", each with their own user experience, performance, and
9
+deployment characteristics.
10
+
11
+Authorization scopes
12
+--------------------
13
+
14
+Tokens can express your authorization in different scopes. You likely have
15
+different sets of roles, in different projects, and in different domains.
16
+While tokens always express your identity, they may only ever express one set
17
+of roles in one authorization scope at a time.
18
+
19
+Each level of authorization scope is useful for certain types of operations in
20
+certain OpenStack services, and are not interchangeable.
21
+
22
+Unscoped tokens
23
+~~~~~~~~~~~~~~~
24
+
25
+An unscoped token contains neither a service catalog, any roles, a project
26
+scope, nor a domain scope. Their primary use case is simply to prove your
27
+identity to keystone at a later time (usually to generate scoped tokens),
28
+without repeatedly presenting your original credentials.
29
+
30
+The 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
+
39
+Project-scoped tokens
40
+~~~~~~~~~~~~~~~~~~~~~
41
+
42
+Project-scoped tokens are the bread and butter of OpenStack. They express your
43
+authorization to operate in a specific tenancy of the cloud and are useful to
44
+authenticate yourself when working with most other services.
45
+
46
+They contain a service catalog, a set of roles, and details of the project upon
47
+which you have authorization.
48
+
49
+Domain-scoped tokens
50
+~~~~~~~~~~~~~~~~~~~~
51
+
52
+Domain-scoped tokens also have limited use cases in OpenStack. They express
53
+your authorization to operate a domain-level, above that of the user and
54
+projects contained therein (typically as a domain-level administrator).
55
+Depending on Keystone's configuration, they are useful for working with a
56
+single domain in Keystone.
57
+
58
+They contain a limited service catalog (only those services which do not
59
+explicitly require per-project endpoints), a set of roles, and details of the
60
+project upon which you have authorization.
61
+
62
+They can also be used to work with domain-level concerns in other services,
63
+such as to configure domain-wide quotas that apply to all users or projects in
64
+a specific domain.
65
+
66
+Token providers
67
+---------------
68
+
69
+The token type issued by keystone is configurable through the
70
+``/etc/keystone/keystone.conf`` file. Currently, there are four supported
71
+token types and they include ``UUID``, ``fernet``, ``PKI``, and ``PKIZ``.
72
+
73
+UUID tokens
74
+~~~~~~~~~~~
75
+
76
+UUID was the first token type supported and is currently the default token
77
+provider. UUID tokens are 32 bytes in length and must be persisted in a back
78
+end. Clients must pass their UUID token to the Identity service in order to
79
+validate it.
80
+
81
+Fernet tokens
82
+~~~~~~~~~~~~~
83
+
84
+The fernet token format was introduced in the OpenStack Kilo release. Unlike
85
+the other token types mentioned in this document, fernet tokens do not need to
86
+be persisted in a back end. ``AES256`` encryption is used to protect the
87
+information stored in the token and integrity is verified with a ``SHA256
88
+HMAC`` signature. Only the Identity service should have access to the keys used
89
+to encrypt and decrypt fernet tokens. Like UUID tokens, fernet tokens must be
90
+passed back to the Identity service in order to validate them. For more
91
+information on the fernet token type, see the :doc:`identity-fernet-token-faq`.
92
+
93
+PKI and PKIZ tokens
94
+~~~~~~~~~~~~~~~~~~~
95
+
96
+PKI tokens are signed documents that contain the authentication context, as
97
+well as the service catalog. Depending on the size of the OpenStack deployment,
98
+these tokens can be very long. The Identity service uses public/private key
99
+pairs and certificates in order to create and validate PKI tokens.
100
+
101
+The same concepts from PKI tokens apply to PKIZ tokens. The only difference
102
+between the two is PKIZ tokens are compressed to help mitigate the size issues
103
+of PKI. For more information on the certificate setup for PKI and PKIZ tokens,
104
+see the :doc:`identity-certificates-for-pki`.
105
+
106
+.. note::
107
+
108
+   PKI and PKIZ tokens are deprecated and not supported in Ocata.

+ 199
- 0
doc/source/admin/identity-troubleshoot.rst View File

@@ -0,0 +1,199 @@
1
+=================================
2
+Troubleshoot the Identity service
3
+=================================
4
+
5
+To troubleshoot the Identity service, review the logs in the
6
+``/var/log/keystone/keystone.log`` file.
7
+
8
+Use the ``/etc/keystone/logging.conf`` file to configure the
9
+location 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
+
19
+The logs show the components that have come in to the WSGI request, and
20
+ideally show an error that explains why an authorization request failed.
21
+If you do not see the request in the logs, run keystone with the
22
+``--debug`` parameter. Pass the ``--debug`` parameter before the
23
+command parameters.
24
+
25
+Debug PKI middleware
26
+~~~~~~~~~~~~~~~~~~~~
27
+
28
+Problem
29
+-------
30
+
31
+If you receive an ``Invalid OpenStack Identity Credentials`` message when
32
+you accessing and reaching an OpenStack service, it might be caused by
33
+the changeover from UUID tokens to PKI tokens in the Grizzly release.
34
+
35
+The PKI-based token validation scheme relies on certificates from
36
+Identity that are fetched through HTTP and stored in a local directory.
37
+The location for this directory is specified by the ``signing_dir``
38
+configuration option.
39
+
40
+Solution
41
+--------
42
+
43
+In 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
+
54
+The first thing to check is that the ``signing_dir`` does, in fact,
55
+exist. 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
+
68
+This directory contains two certificates and the token revocation list.
69
+If these files are not present, your service cannot fetch them from
70
+Identity. To troubleshoot, try to talk to Identity to make sure it
71
+correctly serves files, as follows:
72
+
73
+.. code-block:: console
74
+
75
+   $ curl http://localhost:35357/v2.0/certificates/signing
76
+
77
+This 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
+
92
+Note 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
+
99
+The token revocation list is updated once a minute, but the certificates
100
+are not. One possible problem is that the certificates are the wrong
101
+files or garbage. You can remove these files and run another command
102
+against your server; they are fetched on demand.
103
+
104
+The Identity service log should show the access of the certificate files. You
105
+might have to turn up your logging levels. Set ``debug = True`` in your
106
+Identity 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
+
115
+If the files do not appear in your directory after this, it is likely
116
+one 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
+
128
+SELinux troubles often occur when you use Fedora or RHEL-based packages and
129
+you choose configuration options that do not match the standard policy.
130
+Run the ``setenforce permissive`` command. If that makes a difference,
131
+you should relabel the directory. If you are using a sub-directory of
132
+the ``/var/cache/`` directory, run the following command:
133
+
134
+.. code-block:: console
135
+
136
+   # restorecon /var/cache/
137
+
138
+If you are not using a ``/var/cache`` sub-directory, you should. Modify
139
+the ``signing_dir`` configuration option for your service and restart.
140
+
141
+Set back to ``setenforce enforcing`` to confirm that your changes solve
142
+the problem.
143
+
144
+If your certificates are fetched on demand, the PKI validation is
145
+working properly. Most likely, the token from Identity is not valid for
146
+the operation you are attempting to perform, and your user needs a
147
+different role for the operation.
148
+
149
+Debug signing key file errors
150
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151
+
152
+Problem
153
+-------
154
+
155
+If an error occurs when the signing key file opens, it is possible that
156
+the person who ran the :command:`keystone-manage pki_setup` command to
157
+generate certificates and keys did not use the correct user.
158
+
159
+Solution
160
+--------
161
+
162
+When you run the :command:`keystone-manage pki_setup` command, Identity
163
+generates a set of certificates and keys in ``/etc/keystone/ssl*``, which
164
+is owned by ``root:root``. This can present a problem when you run the
165
+Identity daemon under the keystone user account (nologin) when you try
166
+to run PKI. Unless you run the :command:`chown` command against the
167
+files ``keystone:keystone``, or run the :command:`keystone-manage pki_setup`
168
+command with the ``--keystone-user`` and
169
+``--keystone-group`` parameters, you will get an error.
170
+For 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
+
181
+Flush expired tokens from the token database table
182
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
183
+
184
+Problem
185
+-------
186
+
187
+As you generate tokens, the token database table on the Identity server
188
+grows.
189
+
190
+Solution
191
+--------
192
+
193
+To clear the token table, an administrative user must run the
194
+:command:`keystone-manage token_flush` command to flush the tokens. When you
195
+flush tokens, expired tokens are deleted and traceability is eliminated.
196
+
197
+Use ``cron`` to schedule this command to run frequently based on your
198
+workload. For large workloads, running it every minute is recommended.
199
+

+ 56
- 0
doc/source/admin/identity-use-trusts.rst View File

@@ -0,0 +1,56 @@
1
+==========
2
+Use trusts
3
+==========
4
+
5
+OpenStack Identity manages authentication and authorization. A trust is
6
+an OpenStack Identity extension that enables delegation and, optionally,
7
+impersonation through ``keystone``. A trust extension defines a
8
+relationship 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
+
21
+The 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.

+ 8
- 0
doc/source/index.rst View File

@@ -85,6 +85,14 @@ the keystone service.
85 85
     advanced-topics/index.rst
86 86
     sample_files/index.rst
87 87
 
88
+Administrator Guides
89
+~~~~~~~~~~~~~~~~~~~~
90
+
91
+.. toctree::
92
+    :maxdepth: 2
93
+
94
+    admin/identity-management.rst
95
+
88 96
 API Documentation
89 97
 ~~~~~~~~~~~~~~~~~
90 98
 An end user can find the specific API documentation here, `OpenStack's Identity API`_.

Loading…
Cancel
Save