summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSuramya Shah <shah.suramya@gmail.com>2018-02-23 10:38:18 +0530
committerColleen Murphy <colleen@gazlene.net>2018-11-22 21:06:21 +0100
commited6366813d2c2878ebfe2b193eeb32f51fb29635 (patch)
treeaf10aba10c4a70c36770637746292f4a0b4ec5e0
parenta32c596980a6c489849c99ab856c982a2d6b5d28 (diff)
Consolidate identity-domain-specific-config.rst
Consolidate from configuration.rst into identity-domain-specific-config.rst. Change-Id: Id989342e31be31a3c5cb946ff2177ffa5a8f47a8
Notes
Notes (review): Code-Review+2: Gage Hugo <gagehugo@gmail.com> Code-Review+2: wangxiyuan <wangxiyuan@huawei.com> Workflow+1: wangxiyuan <wangxiyuan@huawei.com> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Sat, 24 Nov 2018 03:15:27 +0000 Reviewed-on: https://review.openstack.org/547274 Project: openstack/keystone Branch: refs/heads/master
-rw-r--r--doc/source/admin/identity-domain-specific-config.rst139
-rw-r--r--doc/source/configuration.rst186
2 files changed, 140 insertions, 185 deletions
diff --git a/doc/source/admin/identity-domain-specific-config.rst b/doc/source/admin/identity-domain-specific-config.rst
index b15f698..4c6a966 100644
--- a/doc/source/admin/identity-domain-specific-config.rst
+++ b/doc/source/admin/identity-domain-specific-config.rst
@@ -49,6 +49,141 @@ Any domain-specific configuration options specified through the
49Identity v3 API will override domain-specific configuration files in the 49Identity v3 API will override domain-specific configuration files in the
50``/etc/keystone/domains`` directory. 50``/etc/keystone/domains`` directory.
51 51
52Unlike the file-based method of specifying domain-specific configurations,
53options specified via the Identity API will become active without needing to
54restart the keystone server. For performance reasons, the current state of
55configuration options for a domain are cached in the keystone server, and in
56multi-process and multi-threaded keystone configurations, the new
57configuration options may not become active until the cache has timed out. The
58cache settings for domain config options can be adjusted in the general
59keystone configuration file (option ``cache_time`` in the ``domain_config``
60group).
61
62.. NOTE::
63
64 It is important to notice that when using either of these methods of
65 specifying domain-specific configuration options, the main keystone
66 configuration file is still maintained. Only those options that relate
67 to the Identity driver for users and groups (i.e. specifying whether the
68 driver for this domain is SQL or LDAP, and, if LDAP, the options that
69 define that connection) are supported in a domain-specific manner. Further,
70 when using the configuration options via the Identity API, the driver
71 option must be set to an LDAP driver (attempting to set it to an SQL driver
72 will generate an error when it is subsequently used).
73
74For existing installations that already use file-based domain-specific
75configurations who wish to migrate to the SQL-based approach, the
76``keystone-manage`` command can be used to upload all configuration files to
77the SQL database:
78
79.. code-block:: bash
80
81 $ keystone-manage domain_config_upload --all
82
83Once uploaded, these domain-configuration options will be visible via the
84Identity API as well as applied to the domain-specific drivers. It is also
85possible to upload individual domain-specific configuration files by
86specifying the domain name:
87
88.. code-block:: bash
89
90 $ keystone-manage domain_config_upload --domain-name DOMAINA
91
92.. NOTE::
93
94 It is important to notice that by enabling either of the domain-specific
95 configuration methods, the operations of listing all users and listing all
96 groups are not supported, those calls will need either a domain filter to
97 be specified or usage of a domain scoped token.
98
99.. NOTE::
100
101 Keystone does not support moving the contents of a domain (i.e. "its" users
102 and groups) from one backend to another, nor group membership across
103 backend boundaries.
104
105.. NOTE::
106
107 When using the file-based domain-specific configuration method, to delete a
108 domain that uses a domain specific backend, it's necessary to first disable
109 it, remove its specific configuration file (i.e. its corresponding
110 keystone.<domain_name>.conf) and then restart the Identity server. When
111 managing configuration options via the Identity API, the domain can simply
112 be disabled and deleted via the Identity API; since any domain-specific
113 configuration options will automatically be removed.
114
115.. NOTE::
116
117 Although keystone supports multiple LDAP backends via the above
118 domain-specific configuration methods, it currently only supports one SQL
119 backend. This could be either the default driver or a single
120 domain-specific backend, perhaps for storing service users in a
121 predominantly LDAP installation.
122
123.. NOTE::
124
125 Keystone has deprecated the ``keystone-manage domain_config_upload``
126 option. The keystone team recommends setting domain config options via the
127 API instead.
128
129Due to the need for user and group IDs to be unique across an OpenStack
130installation and for keystone to be able to deduce which domain and backend to
131use from just a user or group ID, it dynamically builds a persistent identity
132mapping table from a public ID to the actual domain, local ID (within that
133backend) and entity type. The public ID is automatically generated by keystone
134when it first encounters the entity. If the local ID of the entity is from a
135backend that does not guarantee to generate UUIDs, a hash algorithm will
136generate a public ID for that entity, which is what will be exposed by
137keystone.
138
139The use of a hash will ensure that if the public ID needs to be regenerated
140then the same public ID will be created. This is useful if you are running
141multiple keystones and want to ensure the same ID would be generated whichever
142server you hit.
143
144While keystone will dynamically maintain the identity mapping, including
145removing entries when entities are deleted via the keystone, for those entities
146in backends that are managed outside of keystone (e.g. a read-only LDAP),
147keystone will not know if entities have been deleted and hence will continue to
148carry stale identity mappings in its table. While benign, keystone provides an
149ability for operators to purge the mapping table of such stale entries using
150the keystone-manage command, for example:
151
152.. code-block:: bash
153
154 $ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com
155
156A typical usage would be for an operator to obtain a list of those entries in
157an external backend that had been deleted out-of-band to keystone, and then
158call keystone-manage to purge those entries by specifying the domain and
159local-id. The type of the entity (i.e. user or group) may also be specified if
160this is needed to uniquely identify the mapping.
161
162Since public IDs can be regenerated **with the correct generator
163implementation**, if the details of those entries that have been deleted are
164not available, then it is safe to simply bulk purge identity mappings
165periodically, for example:
166
167.. code-block:: bash
168
169 $ keystone-manage mapping_purge --domain-name DOMAINA
170
171will purge all the mappings for DOMAINA. The entire mapping table can be purged
172with the following command:
173
174.. code-block:: bash
175
176 $ keystone-manage mapping_purge --all
177
178Generating public IDs in the first run may take a while, and most probably
179first API requests to fetch user list will fail by timeout. To prevent this,
180``mapping_populate`` command should be executed. It should be executed right after
181LDAP has been configured or after ``mapping_purge``.
182
183.. code-block:: bash
184
185 $ keystone-manage mapping_populate --domain DOMAINA
186
52Migrate domain-specific configuration files to the SQL database 187Migrate domain-specific configuration files to the SQL database
53--------------------------------------------------------------- 188---------------------------------------------------------------
54 189
@@ -64,6 +199,4 @@ domain name:
64 199
65.. code-block:: console 200.. code-block:: console
66 201
67 # keystone-manage domain_config_upload --domain-name DOMAIN_NAME 202 # keystone-manage domain_config_upload --domain-name DOMAIN_NAME \ No newline at end of file
68
69
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index 84b9be1..4f0bb8a 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -103,191 +103,13 @@ Keystone supports several different choices that will substantially impact how
103you'll configure, deploy, and interact with keystone. 103you'll configure, deploy, and interact with keystone.
104 104
105You can also mix-and-match various sources of identity (see `Domain-specific 105You can also mix-and-match various sources of identity (see `Domain-specific
106Drivers`_ below for an example). For example, you can store OpenStack service 106Configuration`_ for an example). For example, you can store OpenStack service users
107users and their passwords in SQL, manage customers in LDAP, and authenticate 107and their passwords in SQL, manage customers in LDAP, and authenticate employees
108employees via SAML federation. 108via SAML federation.
109 109
110.. _Domain-specific Configuration: admin/identity-domain-specific-config.html
110.. support_matrix:: identity-support-matrix.ini 111.. support_matrix:: identity-support-matrix.ini
111 112
112.. Domain-specific Drivers:
113
114Domain-specific Drivers
115-----------------------
116
117Keystone supports the option (disabled by default) to specify identity driver
118configurations on a domain by domain basis, allowing, for example, a specific
119domain to have its own LDAP or SQL server. This is configured by specifying the
120following options:
121
122.. code-block:: ini
123
124 [identity]
125 domain_specific_drivers_enabled = True
126 domain_config_dir = /etc/keystone/domains
127
128Setting ``domain_specific_drivers_enabled`` to ``True`` will enable this
129feature, causing keystone to look in the ``domain_config_dir`` for config files
130of the form::
131
132 keystone.<domain_name>.conf
133
134Options given in the domain specific configuration file will override those in
135the primary configuration file for the specified domain only. Domains without a
136specific configuration file will continue to use the options from the primary
137configuration file.
138
139Keystone also supports the ability to store the domain-specific configuration
140options in the keystone SQL database, managed via the Identity API, as opposed
141to using domain-specific configuration files.
142
143This capability (which is disabled by default) is enabled by specifying the
144following options in the main keystone configuration file:
145
146.. code-block:: ini
147
148 [identity]
149 domain_specific_drivers_enabled = true
150 domain_configurations_from_database = true
151
152Once enabled, any existing domain-specific configuration files in the
153configuration directory will be ignored and only those domain-specific
154configuration options specified via the Identity API will be used.
155
156Unlike the file-based method of specifying domain-specific configurations,
157options specified via the Identity API will become active without needing to
158restart the keystone server. For performance reasons, the current state of
159configuration options for a domain are cached in the keystone server, and in
160multi-process and multi-threaded keystone configurations, the new
161configuration options may not become active until the cache has timed out. The
162cache settings for domain config options can be adjusted in the general
163keystone configuration file (option ``cache_time`` in the ``domain_config``
164group).
165
166.. NOTE::
167
168 It is important to notice that when using either of these methods of
169 specifying domain-specific configuration options, the main keystone
170 configuration file is still maintained. Only those options that relate
171 to the Identity driver for users and groups (i.e. specifying whether the
172 driver for this domain is SQL or LDAP, and, if LDAP, the options that
173 define that connection) are supported in a domain-specific manner. Further,
174 when using the configuration options via the Identity API, the driver
175 option must be set to an LDAP driver (attempting to set it to an SQL driver
176 will generate an error when it is subsequently used).
177
178For existing installations that already use file-based domain-specific
179configurations who wish to migrate to the SQL-based approach, the
180``keystone-manage`` command can be used to upload all configuration files to
181the SQL database:
182
183.. code-block:: bash
184
185 $ keystone-manage domain_config_upload --all
186
187Once uploaded, these domain-configuration options will be visible via the
188Identity API as well as applied to the domain-specific drivers. It is also
189possible to upload individual domain-specific configuration files by
190specifying the domain name:
191
192.. code-block:: bash
193
194 $ keystone-manage domain_config_upload --domain-name DOMAINA
195
196.. NOTE::
197
198 It is important to notice that by enabling either of the domain-specific
199 configuration methods, the operations of listing all users and listing all
200 groups are not supported, those calls will need either a domain filter to
201 be specified or usage of a domain scoped token.
202
203.. NOTE::
204
205 Keystone does not support moving the contents of a domain (i.e. "its" users
206 and groups) from one backend to another, nor group membership across
207 backend boundaries.
208
209.. NOTE::
210
211 When using the file-based domain-specific configuration method, to delete a
212 domain that uses a domain specific backend, it's necessary to first disable
213 it, remove its specific configuration file (i.e. its corresponding
214 keystone.<domain_name>.conf) and then restart the Identity server. When
215 managing configuration options via the Identity API, the domain can simply
216 be disabled and deleted via the Identity API; since any domain-specific
217 configuration options will automatically be removed.
218
219.. NOTE::
220
221 Although keystone supports multiple LDAP backends via the above
222 domain-specific configuration methods, it currently only supports one SQL
223 backend. This could be either the default driver or a single
224 domain-specific backend, perhaps for storing service users in a
225 predominantly LDAP installation.
226
227.. NOTE::
228
229 Keystone has deprecated the ``keystone-manage domain_config_upload``
230 option. The keystone team recommends setting domain config options via the
231 API instead.
232
233Due to the need for user and group IDs to be unique across an OpenStack
234installation and for keystone to be able to deduce which domain and backend to
235use from just a user or group ID, it dynamically builds a persistent identity
236mapping table from a public ID to the actual domain, local ID (within that
237backend) and entity type. The public ID is automatically generated by keystone
238when it first encounters the entity. If the local ID of the entity is from a
239backend that does not guarantee to generate UUIDs, a hash algorithm will
240generate a public ID for that entity, which is what will be exposed by
241keystone.
242
243The use of a hash will ensure that if the public ID needs to be regenerated
244then the same public ID will be created. This is useful if you are running
245multiple keystones and want to ensure the same ID would be generated whichever
246server you hit.
247
248While keystone will dynamically maintain the identity mapping, including
249removing entries when entities are deleted via the keystone, for those entities
250in backends that are managed outside of keystone (e.g. a read-only LDAP),
251keystone will not know if entities have been deleted and hence will continue to
252carry stale identity mappings in its table. While benign, keystone provides an
253ability for operators to purge the mapping table of such stale entries using
254the keystone-manage command, for example:
255
256.. code-block:: bash
257
258 $ keystone-manage mapping_purge --domain-name DOMAINA --local-id abc@de.com
259
260A typical usage would be for an operator to obtain a list of those entries in
261an external backend that had been deleted out-of-band to keystone, and then
262call keystone-manage to purge those entries by specifying the domain and
263local-id. The type of the entity (i.e. user or group) may also be specified if
264this is needed to uniquely identify the mapping.
265
266Since public IDs can be regenerated **with the correct generator
267implementation**, if the details of those entries that have been deleted are
268not available, then it is safe to simply bulk purge identity mappings
269periodically, for example:
270
271.. code-block:: bash
272
273 $ keystone-manage mapping_purge --domain-name DOMAINA
274
275will purge all the mappings for DOMAINA. The entire mapping table can be purged
276with the following command:
277
278.. code-block:: bash
279
280 $ keystone-manage mapping_purge --all
281
282Generating public IDs in the first run may take a while, and most probably
283first API requests to fetch user list will fail by timeout. To prevent this,
284``mapping_populate`` command should be executed. It should be executed right after
285LDAP has been configured or after ``mapping_purge``.
286
287.. code-block:: bash
288
289 $ keystone-manage mapping_populate --domain DOMAINA
290
291Public ID Generators 113Public ID Generators
292-------------------- 114--------------------
293 115