ugr.rst 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475
  1. .. _security_webadmin_ugr:
  2. Users, Groups, Roles
  3. ====================
  4. This section provides the configuration options for :ref:`security_rolesystem_usergroupservices` and :ref:`security_rolesystem_roleservices`. In addition, users, groups, and roles themselves and can be added, edited, or removed. A great deal of configuration can be accomplished in this section and related pages.
  5. .. _security_webadmin_usergroupservices:
  6. User Group Services
  7. -------------------
  8. In this menu, user/group services can be added, removed, or edited. By default, there is one user/group service in GeoServer, which is :ref:`XML-based <security_rolesystem_usergroupxml>`. It is encrypted with :ref:`Weak PBE <security_passwd_encryption>` and uses the default :ref:`password policy <security_passwd_policy>`. It is also possible to have a user/group service based on :ref:`JDBC <security_rolesystem_usergroupjdbc>`, with or without JNDI.
  9. .. figure:: images/ugr_usergroup.png
  10. :align: center
  11. *User/group services*
  12. Clicking an existing user/group service will enable editing, while clicking the :guilabel:`Add new` link will configure a new user/group service.
  13. There are three tabs for configuration: Settings, Users, and Groups.
  14. .. note:: When creating a new user/group service, the form filled out initially can be found under the Settings tab.
  15. Add new XML user/group service
  16. ------------------------------
  17. To add a new XML user/group service, click the :guilabel:`Add new` link. XML is the default option. The following figure shows the configuration options for an XML user/group service.
  18. .. figure:: images/ugr_ugxmlsettings.png
  19. :align: center
  20. *Adding an XML user/group service*
  21. .. list-table::
  22. :widths: 40 60
  23. :header-rows: 1
  24. * - Option
  25. - Description
  26. * - Name
  27. - The name of the user/group service
  28. * - Password encryption
  29. - Sets the type of :ref:`security_passwd_encryption`. Options are :guilabel:`Plain text`, :guilabel:`Weak PBE`, :guilabel:`Strong PBE`, and :guilabel:`Digest`.
  30. * - Password policy
  31. - Sets the :ref:`password policy <security_passwd_policy>`. Options are any active password policies as set in the :ref:`security_webadmin_passwd` section.
  32. * - XML filename
  33. - Name of the file that will contain the user and group information. Default is :file:`users.xml` in the ``security/usergroup/<name_of_usergroupservice>`` directory.
  34. * - Enable schema validation
  35. - If selected, forces schema validation to occur every time the XML file is read. This option is useful when editing the XML file by hand.
  36. * - File reload interval
  37. - Defines the frequency (in milliseconds) in which GeoServer will check for changes to the XML file. If the file is found to have been modified, GeoServer will recreate the user/group database based on the current state of the file. This value is meant to be set in cases where the XML file contents might change "out of process" and not directly through the web admin interface. The value is specified in milliseconds. A value of 0 disables any checking of the file.
  38. Add new JDBC user/group service
  39. -------------------------------
  40. To add a new JDBC user/group service, click the :guilabel:`Add new` link, and then the :guilabel:`JDBC` option at the top of the following form. The following figure shows the configuration options for a JDBC user/group service.
  41. .. figure:: images/ugr_ugjdbcsettings.png
  42. :align: center
  43. *Adding a user/group service via JDBC*
  44. .. list-table::
  45. :widths: 40 60
  46. :header-rows: 1
  47. * - Option
  48. - Description
  49. * - Name
  50. - Name of the JDBC user/group service in GeoServer
  51. * - Password encryption
  52. - The method to used to :ref:`encrypt user passwords <security_passwd_encryption>`
  53. * - Password policy
  54. - The :ref:`policy <security_passwd_policy>` to use to enforce constraints on user passwords
  55. * - JNDI
  56. - When unchecked, specifies a direct connection to the database. When checked, specifies an existing connection located through :ref:`data_jndi`.
  57. * - Driver class name
  58. - JDBC driver to use for the database connection
  59. * - Connection URL
  60. - Specifies the JDBC URL to use when creating the database connection
  61. * - Username
  62. - Username to use when connecting to the database
  63. * - Password
  64. - Password to use when connecting to the database
  65. * - Create database tables
  66. - Specifies whether to create all the necessary tables in the underlying database
  67. * - Data Definition Language (DDL) file
  68. - Specifies a custom DDL file to use for creating tables in the underlying database, for cases where the default DDL statements fail on the given database. If left blank, internal defaults are used.
  69. * - Data Manipulation Language (DML) file
  70. - Specifies a custom DML file to use for accessing tables in the underlying database, for cases where the default DML statements fail on the given database. If left blank, internal defaults are used.
  71. In addition to the parameters listed above, the following additional parameter will apply when the :ref:`data_jndi` flag is set.
  72. .. figure:: images/ugr_ugjdbcjndisettings.png
  73. :align: center
  74. *Adding a user/group service via JDBC with JNDI*
  75. .. list-table::
  76. :widths: 40 60
  77. :header-rows: 1
  78. * - Option
  79. - Description
  80. * - JNDI resource name
  81. - JNDI name used to locate the database connection.
  82. Add new LDAP user/group service
  83. -------------------------------
  84. To add a new LDAP user/group service, click the :guilabel:`Add new` link, and then the :guilabel:`LDAP` option at the top of the following form. The following figure shows the configuration options for a LDAP user/group service.
  85. .. figure:: images/ldap_group_service.png
  86. :align: center
  87. *Adding a user/group service via LDAP*
  88. .. list-table::
  89. :widths: 40 60
  90. :header-rows: 1
  91. * - Option
  92. - Description
  93. * - Name
  94. - Name of the LDAP role service in GeoServer
  95. * - Password encryption
  96. - The method to used to :ref:`encrypt user passwords <security_passwd_encryption>`
  97. * - Password policy
  98. - The :ref:`policy <security_passwd_policy>` to use to enforce constraints on user passwords
  99. * - Server URL
  100. - URL for the LDAP server connection. It must include the protocol, host, and port, as well as the “distinguished name” (DN) for the root of the LDAP tree.
  101. * - TLS
  102. - Enables a STARTTLS connection. (See the section on :ref:`security_auth_provider_ldap_secure`.)
  103. * - Group search base
  104. - Relative name of the node in the tree to use as the base for LDAP groups. Example: ``ou=groups``. The root DN specified as port of the *Server URL* is automatically appended.
  105. * - Filter to search all groups
  106. - Sets the LDAP filter for search all groups available. Leave blank to derive from attribute.
  107. * - Filter to search group by name
  108. - Sets the LDAP filter for search a group by its name. Leave blank to derive from attribute.
  109. * - Attribute which contains the name of the group
  110. - Sets attribute containing the group name. Leave blank to derive from name filter.
  111. * - Query format to retrieve the user/group mapping
  112. - Query format used for mapping user/group memberships. Leave blank to derive from attribute. This may contain some placeholder values:
  113. ``{0}``, the ``username`` of the user, for example ``bob``.
  114. ``{1}``, the full DN of the user, for example ``uid=bob,ou=users``.
  115. * - Attribute name to retrieve the user/group mapping
  116. - Attribute name used for mapping user/group memberships. Leave blank to derive from filter.
  117. * - User search base
  118. - LDAP search base for users.
  119. * - Filter to search all users
  120. - Sets the filter for search all available users. Leave blank to derive from attribute.
  121. * - Filter to search user by name
  122. - Sets the filter format for search a user by its name. Leave blank to derive from attribute.
  123. * - Attribute which contains the name of the user
  124. - Sets the attribute containing the name for users. Leave blank to derive from name filter.
  125. * - List of attributes to populate
  126. - Sets a comma separated list of attributes to populate on users.
  127. * - Authenticated onto the LDAP before querying
  128. - When checked all LDAP searches will be done in authenticated mode, using the credentials given with the *Username* and *Password* options
  129. * - Username
  130. - Username to use when connecting to the LDAP server. Only applicable when the *Authenticated onto the LDAP before querying* parameter is **checked**.
  131. * - Password
  132. - Password to use when connecting to the LDAP server. Only applicable when the *Authenticated onto the LDAP before querying* parameter is **checked**.
  133. * - Enable Hierarchical groups search
  134. - When checked all LDAP group searches will use hierarchical mode, retrieving LDAP parent groups too.
  135. * - Max depth for hierarchical groups search
  136. - Max depth number for hierarchical LDAP groups search, use -1 for infinite depth. Only applicable when the *Enable Hierarchical groups search* parameter is **checked**.
  137. * - Nested group search filter
  138. - LDAP search pattern for searching parent groups. Only applicable when the *Enable Hierarchical groups search* parameter is **checked**.
  139. Edit user/group service
  140. -----------------------
  141. Once the new user/group service is added (either XML or JDBC), clicking on it in the list of user/group services will allow additional options to be specified, such as the users and groups associated with the service.
  142. There are three tabs in the resulting menu: :guilabel:`Settings`, :guilabel:`Users`, and :guilabel:`Groups`. The Settings tab is identical to that found when creating the user/group service, while the others are described below.
  143. The Users tab provides options to configure users in the user/group service.
  144. .. figure:: images/ugr_ugusers.png
  145. :align: center
  146. *Users tab*
  147. Clicking a username will allow its parameters to be changed, while clicking the :guilabel:`Add new` link will create a new user.
  148. .. _security_webadmin_users:
  149. Add user
  150. ~~~~~~~~
  151. .. figure:: images/ugr_newuser.png
  152. :align: center
  153. *Creating or editing a user*
  154. .. list-table::
  155. :widths: 40 60
  156. :header-rows: 1
  157. * - Option
  158. - Description
  159. * - User name
  160. - The name of the user
  161. * - Enabled
  162. - When selected, will enable the user to authenticate
  163. * - Password
  164. - The password for this user. Existing passwords will be obscured when viewed.
  165. * - Confirm password
  166. - To set or change the password enter the password twice.
  167. * - User properties
  168. - Key/value pairs associated with the user. Used for associating additional information with the user.
  169. * - Group list
  170. - Full list of groups, including list of groups to which the user is a member. Membership can be toggled here via the arrow buttons.
  171. * - Add a new group
  172. - Shortcut to adding a new group. Also available in the Groups tab.
  173. * - Role list
  174. - Full list of roles, including a list of roles to which the user is associated. Association can be toggled here via the arrow buttons.
  175. * - Add a new role
  176. - Shortcut to adding a new role
  177. * - List of current roles for the user
  178. - List of current roles associated with the user. Click a role to enable editing.
  179. The Groups tab provides configuration options for groups in this user/group service. There are options to add and remove a group, with an additional option to remove a group and the roles associated with that group.
  180. .. figure:: images/ugr_uggroups.png
  181. :align: center
  182. *Groups tab*
  183. .. _security_webadmin_groups:
  184. Remove User
  185. ~~~~~~~~~~~
  186. There are two related buttons that are responsible for removing users: :guilabel:`Remove Selected`, and :guilabel:`Remove Selected and remove role associations`.
  187. * :guilabel:`Remove Selected` removes user from `users.xml <https://github.com/geoserver/geoserver/blob/main/data/release/security/usergroup/default/users.xml>`_ and leave untouched `roles.xml <https://github.com/geoserver/geoserver/blob/main/data/release/security/role/default/roles.xml>`_.
  188. * :guilabel:`Remove Selected and remove role associations` removes user from `users.xml <https://github.com/geoserver/geoserver/blob/main/data/release/security/usergroup/default/users.xml>`_ and also removes user and associated role to user from `roles.xml <https://github.com/geoserver/geoserver/blob/main/data/release/security/role/default/roles.xml>`_.
  189. .. figure:: images/ugr_ugusers.png
  190. :align: center
  191. *Users tab*
  192. Add group
  193. ~~~~~~~~~
  194. .. figure:: images/ugr_newgroup.png
  195. :align: center
  196. *Creating or editing a group*
  197. .. list-table::
  198. :widths: 40 60
  199. :header-rows: 1
  200. * - Option
  201. - Description
  202. * - Group name
  203. - The name of the group
  204. * - Enabled
  205. - When selected the group will be active
  206. * - Role list
  207. - Full list of roles, including a list of roles to which the group is associated. Association can be toggled here via the arrow buttons.
  208. * - Add a new role
  209. - Shortcut to adding a new role
  210. In this menu, user/group services can be added, removed, or edited. By default, there is one user/group service in GeoServer, which is :ref:`XML-based <security_rolesystem_usergroupxml>`. It is encrypted with :ref:`Weak PBE <security_passwd_encryption>` and uses the default :ref:`password policy <security_passwd_policy>`. It is also possible to have a user/group service based on :ref:`JDBC <security_rolesystem_usergroupjdbc>` with or without JNDI.
  211. .. _security_webadmin_roleservices:
  212. Role services
  213. -------------
  214. In this menu, role services can be added, removed, or edited. By default, the active role service in GeoServer is :ref:`XML-based <security_rolesystem_rolexml>`, but it is also possible to have a role service based on :ref:`JDBC <security_rolesystem_rolejdbc>`, with or without JNDI.
  215. The Administrator role is called ``ROLE_ADMINISTRATOR``.
  216. .. figure:: images/ugr_roleservices.png
  217. :align: center
  218. *Role services*
  219. Clicking an existing role service will open it for editing, while clicking the :guilabel:`Add new` link will configure a new role service.
  220. There are two pages for configuration: Settings and Roles.
  221. .. note:: When creating a new role service, the form filled out initially can be found under the Settings tab.
  222. Add new XML role service
  223. ------------------------
  224. To add a new XML role service, click the :guilabel:`Add new` link. XML is the default option. The following figure shows the configuration options for an XML role service.
  225. .. figure:: images/ugr_rolexmlsettings.png
  226. :align: center
  227. *Adding an XML role service*
  228. .. list-table::
  229. :widths: 40 60
  230. :header-rows: 1
  231. * - Option
  232. - Description
  233. * - Name
  234. - The name of the role service
  235. * - Administrator role
  236. - The name of the role that performs the administrator functions
  237. * - XML filename
  238. - Name of the file that will contain the role information. Default is :file:`roles.xml` in the ``security/role/<name_of_roleservice>`` directory.
  239. * - File reload interval
  240. - Defines the frequency (in milliseconds) in which GeoServer will check for changes to the XML file. If the file is found to have been modified, GeoServer will recreate the user/group database based on the current state of the file. This value is meant to be set in cases where the XML file contents might change "out of process" and not directly through the web admin interface. The value is specified in milliseconds. A value of 0 disables any checking of the file.
  241. Add new JDBC role service
  242. -------------------------
  243. To add a new XML role service, click the :guilabel:`Add new` link, and then the :guilabel:`JDBC` option at the top of the following form. The following figure shows the configuration options for a JDBC role service.
  244. .. figure:: images/ugr_rolejdbcsettings.png
  245. :align: center
  246. *Adding a role service via JDBC*
  247. .. list-table::
  248. :widths: 40 60
  249. :header-rows: 1
  250. * - Option
  251. - Description
  252. * - Name
  253. - Name of the JDBC role service in GeoServer
  254. * - Administrator role
  255. - The name of the role that performs the administrator function
  256. * - JNDI
  257. - When unchecked, specifies a direct connection to the database. When checked, specifies an existing connection located through :ref:`data_jndi`.
  258. * - Driver class name
  259. - JDBC driver to use for the database connection
  260. * - Connection URL
  261. - Specifies the JDBC URL to use when creating the database connection
  262. * - Username
  263. - Username to use when connecting to the database
  264. * - Password
  265. - Password to use when connecting to the database
  266. * - Create database tables
  267. - Specifies whether to create all the necessary tables in the underlying database
  268. * - Data Definition Language (DDL) file
  269. - Specifies a custom DDL file to use for creating tables in the underlying database, for cases where the default DDL statements fail on the given database. If left blank, internal defaults are used.
  270. * - Data Manipulation Language (DML) file
  271. - Specifies a custom DML file to use for accessing tables in the underlying database, for cases where the default DML statements fail on the given database. If left blank, internal defaults are used.
  272. In addition to the parameters listed above, the following additional parameter will apply when the :ref:`data_jndi` flag is set.
  273. .. figure:: images/ugr_rolejdbcjndisettings.png
  274. :align: center
  275. *Adding a role service via JDBC with JNDI*
  276. .. list-table::
  277. :widths: 40 60
  278. :header-rows: 1
  279. * - Option
  280. - Description
  281. * - JNDI resource name
  282. - JNDI name used to locate the database connection.
  283. Add new LDAP role service
  284. -------------------------
  285. To add a new LDAP role service, click the :guilabel:`Add new` link, and then the :guilabel:`LDAP` option at the top of the following form. The following figure shows the configuration options for a LDAP role service.
  286. .. figure:: images/ldap_role_empty.png
  287. :align: center
  288. *Adding a role service via LDAP*
  289. .. list-table::
  290. :widths: 40 60
  291. :header-rows: 1
  292. * - Option
  293. - Description
  294. * - Name
  295. - Name of the LDAP role service in GeoServer
  296. * - Administrator role
  297. - The name of the role that performs the administrator function
  298. * - Group administrator role
  299. - The name of the role that performs the group administrator function
  300. * - Server URL
  301. - URL for the LDAP server connection. It must include the protocol, host, and port, as well as the “distinguished name” (DN) for the root of the LDAP tree.
  302. * - TLS
  303. - Enables a STARTTLS connection. (See the section on :ref:`security_auth_provider_ldap_secure`.)
  304. * - Group search base
  305. - Relative name of the node in the tree to use as the base for LDAP groups. Example: ``ou=groups``. The root DN specified as port of the *Server URL* is automatically appended.
  306. * - Group user membership search filter
  307. - Search pattern for extracting users of a LDAP group a user belongs to. This may contain some placeholder values:
  308. ``{0}``, the ``username`` of the user, for example ``bob``.
  309. ``{1}``, the full DN of the user, for example ``uid=bob,ou=users``. To use this placeholder, the *Filter used to lookup user* needs to be defined, so that the dn of a user can be extracted from its username.
  310. * - All groups search filter
  311. - Search pattern for locating the LDAP groups to be mapped to GeoServer roles inside the *Group search base* root node
  312. * - Filter used to lookup user.
  313. - optional filter used to extract a user dn, to be used together with *Group user membership search filter* when the {1} placeholder is specified. This may contain a placeholder value:
  314. ``{0}``, the ``username`` of the user, for example ``bob``.
  315. * - Role prefix
  316. - Prefix appended in front of role names extracted from the LDAP. If left blank, no prefix will be inserted.
  317. * - Convert Role To Upper Case
  318. - If selected all role names extracted from the LDAP will be converted to upper case.
  319. * - Authenticate to extract roles
  320. - When checked all LDAP searches will be done in authenticated mode, using the credentials given with the *Username* and *Password* options
  321. * - Username
  322. - Username to use when connecting to the LDAP server. Only applicable when the *Authenticate to extract roles* parameter is **checked**.
  323. * - Password
  324. - Password to use when connecting to the LDAP server. Only applicable when the *Authenticate to extract roles* parameter is **checked**.
  325. * - Enable Hierarchical groups search
  326. - When checked all LDAP group searches will use hierarchical mode, retrieving LDAP parent groups too.
  327. * - Max depth for hierarchical groups search
  328. - Max depth number for hierarchical LDAP groups search, use -1 for infinite depth. Only applicable when the *Enable Hierarchical groups search* parameter is **checked**.
  329. * - Nested group search filter
  330. - LDAP search pattern for searching parent groups. Only applicable when the *Enable Hierarchical groups search* parameter is **checked**.
  331. Edit role service
  332. -----------------
  333. Once the new role service is added (either XML or JDBC), clicking it in the list of role services will allow the additional options to be specified, such as the roles associated with the service.
  334. There are two tabs in the resulting menu: :guilabel:`Settings` and :guilabel:`Roles`. The Settings tab is identical to that found when creating the role service, while the Roles tab is described below.
  335. .. figure:: images/ugr_roleroles.png
  336. :align: center
  337. *Roles tab*
  338. Clicking a role will allow its parameters to be changed, while clicking the :guilabel:`Add new` link will create a new role.
  339. .. _security_webadmin_roles:
  340. Add role
  341. ~~~~~~~~
  342. .. figure:: images/ugr_newrole.png
  343. :align: center
  344. *Creating or editing a role*
  345. .. list-table::
  346. :widths: 40 60
  347. :header-rows: 1
  348. * - Option
  349. - Description
  350. * - Role name
  351. - The name of role. Convention is uppercase, but is not required.
  352. * - Parent roles
  353. - The role that this role inherits. See the section on :ref:`security_rolesystem_roles` for more information on inheritance.
  354. * - Role parameters
  355. - Key/value pairs associated with the role. Used for associating additional information with the role.