Add documentation for security configuration
Add a doc page to explain configuring user and group permissions and general user and group handling. refs #9377
This commit is contained in:
Matthias Jentsch
parent
4cea9f15e9
commit
10592bb7c8
|
|
@ -0,0 +1,211 @@
|
|||
# <a id="security"></a> Security
|
||||
|
||||
In certain situations it is useful to allow someone access to IW2, but
|
||||
to prevent him from doing certain actions or from seeing specific objects.
|
||||
For example, it might be a good idea, to allow the configuration of IW2 to
|
||||
a certain group of administrators to prevent misconfiguration or security-breaches.
|
||||
Another important use case is the creation groups of users that can only see the
|
||||
fraction of hosts and services of the monitoring environment they are in charge of.
|
||||
|
||||
The following chapter will describe how to do the security configuration of IW2
|
||||
and how apply permissions and restrictions to users or groups of users.
|
||||
|
||||
## Basics
|
||||
|
||||
IW2 has powerful tools to configure those restrictions for each **user** or **group**.
|
||||
There are two general kinds of objects whose access can be managed in IW2:
|
||||
**actions** and **objects**.
|
||||
|
||||
### Actions
|
||||
|
||||
Actions are all the things an IW2 user can do, like changing a certain configuration,
|
||||
changing permissions or sending a command to the Icinga2-Core through the (Command Pipe)[http://docs.icinga.org/icinga2/latest/doc/module/icinga2/toc#!/icinga2/latest/doc/module/icinga2/chapter/getting-started#setting-up-external-command-pipe]. in the monitoring module. All actions must be be **allowed explicitly** using permissions.
|
||||
|
||||
### Objects
|
||||
|
||||
There are all kinds of different objects in IW2, like Hosts, Services, Notifications and many more. **By default, a user can see all objects that are available in IW2**, but it is possible to define filters to restrict what each user can see.
|
||||
|
||||
|
||||
### Users
|
||||
|
||||
Anyone that can **log into IW2** is considered a user and can be referenced to by the
|
||||
**login name**, independently of which mechanism was used to authenticate that user.
|
||||
For example, there might be user called **jdoe**, which is authenticated
|
||||
using Active Directory, and one user **icingaadmin**, that is authenticated using a MySQL-Database as backend, both users can be referenced to using their the login **icingaadmin** or **jdoe** in configuration.
|
||||
|
||||
IW2 users and groups are not configured by an IW2 configuration file, but provided by
|
||||
an authentication backend. This means that how creating and deleting users works depends entirely on the backend. For extended information on setting up authentication backends, please read the chapter [authentication](authentication.md#authentication).
|
||||
|
||||
**ATTENTION !**
|
||||
|
||||
It is important to distinct between the "contacts" defined in the Icinga2-Core
|
||||
configuration and the "users" that can access IW2. In this guide and for
|
||||
handling security in IW2 in general only the latter ones are of importance.
|
||||
|
||||
|
||||
### Groups
|
||||
|
||||
If there is a big amounts of users to manage, it would be tedious to specify each user
|
||||
separately when referring to a bigger group of users at once. For this reasons, it
|
||||
is possible to group users in groups.
|
||||
|
||||
Like with users, groups are identified solely by their unique group name, and provided
|
||||
by different kind of backend called "group backends". This means, that how groups are defined depends entirely on the used group backend. For extended information on setting up group backends, please read the chapter [authentication](authentication.md#authentication).
|
||||
|
||||
|
||||
TODO: example
|
||||
|
||||
## Roles
|
||||
|
||||
A role defines a set of **permissions** and **restrictions** in IW2, and assigns
|
||||
those to users and user groups. For example, a role **admins** could define that certain
|
||||
users have access to all configuration options, or another role **support**
|
||||
could define that a list of users or groups is restricted to see only hosts and services
|
||||
that match a specific query.
|
||||
|
||||
Roles can be assigned to groups and users. In the end, the actual permission of a certain user
|
||||
will be determined by the sum of all roles that are assigned to the user, or to
|
||||
groups the user is part of.
|
||||
|
||||
|
||||
### Configuration
|
||||
|
||||
Roles can be changed either through the icingaweb2 interface, by navigation
|
||||
to the page **Configuration > Authentication > Roles**, or through editing
|
||||
configuration file:
|
||||
|
||||
|
||||
/etc/icingaweb2/roles.ini
|
||||
|
||||
|
||||
### Example
|
||||
|
||||
[winadmin]
|
||||
users = "johndoe, janedoe"
|
||||
groups = "admin"
|
||||
permissions = "config/application/*, monitoring/commands/schedule-check"
|
||||
monitoring/hosts/filter = "host=*win*"
|
||||
monitoring/services/filter = "host=*win*"
|
||||
|
||||
|
||||
|
||||
### Syntax
|
||||
|
||||
Each role is defined as a section, with the name of the role as section name. The following
|
||||
attributes can be defined for each role:
|
||||
|
||||
|
||||
| Key | Value |
|
||||
|----------- |------------------------------------------------------------------|
|
||||
| users | A comma-separated list of user **login names** that are affected by this role |
|
||||
| groups | A comma-separated list of **groups names** that are affected by this role |
|
||||
| permissions | A comma-separated list of permissions granted by this role |
|
||||
| module/monitoring/host | A filter expression applied to all hosts |
|
||||
| module/monitoring/serivce | A fuilter expression applied to all services |
|
||||
|
||||
|
||||
### Permissions
|
||||
|
||||
Permissions can be used to allow users or groups certain **actions**. By default,
|
||||
all actions are **prohibited** and must be allowed explicitly by a role for any user.
|
||||
|
||||
Each action in IW2 is denoted by a **namespaced key**, which is used to order and
|
||||
group those actions. All actions that affect the configuration of IW2, are in a
|
||||
namespace called **config**, while all configurations that affect authentication
|
||||
are in the namespace **config/authentication**
|
||||
|
||||
**Wildcards** can be used to grant permission for all actions in a certain namespace.
|
||||
The permission **config/* ** would grant permission to all configuration actions,
|
||||
while just specifying a wildcard ** * ** would give permission for all actions.
|
||||
|
||||
When multiple roles assign permissions to the same user, either directly or indirectly
|
||||
through a group, all permissions will be combined to get the users actual permission set.
|
||||
|
||||
###### Global permissions
|
||||
|
||||
| Keys | Permits |
|
||||
|------|---------|
|
||||
| * | Everything, including module-specific permissions |
|
||||
| config/* | All configuration actions |
|
||||
| config/application/* | Configuring IcingaWeb2 |
|
||||
| config/application/general | General settings, like logging or preferences |
|
||||
| config/application/resources | Change resources for retrieving data |
|
||||
| config/application/userbackend | Change backends for retrieving available users |
|
||||
| config/application/usergroupbackend | Change backends for retrieving available groups |
|
||||
| config/authentication/* | Configure IcingaWeb2 authentication mechanisms |
|
||||
| config/authentication/users/* | All user actions |
|
||||
| config/authentication/users/show | Display avilable users |
|
||||
| config/authentication/users/add | Add a new user to the backend |
|
||||
| config/authentication/users/edit | Edit existing user in the backend |
|
||||
| config/authentication/users/remove | Remove existing user from the backend |
|
||||
| config/authentication/groups/* | All group actions |
|
||||
| config/authentication/groups/show | Display available groups |
|
||||
| config/authentication/groups/add | Add a new group to the backend |
|
||||
| config/authentication/groups/edit | Edit existing group in a backend |
|
||||
| config/authentication/groups/remove | Remove existing group from the backend |
|
||||
| config/authentication/roles/* | All role actions |
|
||||
| config/authentication/roles/add | Add a new role |
|
||||
| config/authentication/roles/show | Display available roles |
|
||||
| config/authentication/roles/edit | Change an existing role |
|
||||
| config/authentication/roles/remove | Remove an existing row |
|
||||
| config/modules | Enable or disable modules and module settings |
|
||||
|
||||
|
||||
###### Monitoring module permissions
|
||||
|
||||
| Keys | Permits |
|
||||
|------|---------|
|
||||
| monitoring/command/* | Allow all commands |
|
||||
| monitoring/command/schedule-check | Allow scheduling host and service checks' |
|
||||
| monitoring/command/acknowledge-problem | Allow acknowledging host and service problems |
|
||||
| monitoring/command/remove-acknowledgement | Allow removing problem acknowledgements |
|
||||
| monitoring/command/comment/* | Allow adding and deleting host and service comments |
|
||||
| monitoring/command/comment/add | Allow commenting on hosts and services |
|
||||
| monitoring/command/downtime/delete | Allow deleting host and service downtimes' |
|
||||
| monitoring/command/process-check-result | Allow processing host and service check results |
|
||||
| monitoring/command/feature/instance | Allow processing commands for toggling features on an instance-wide basis |
|
||||
| monitoring/command/feature/object | Allow processing commands for toggling features on host and service objects |
|
||||
| monitoring/command/send-custom-notification | Allow sending custom notifications for hosts and services |
|
||||
|
||||
### Restrictions
|
||||
|
||||
Restrictions can be used to define what a user or group can see, by specifying
|
||||
a filter expression. This filter expression will be **implicitly** added as an AND-Clause
|
||||
to the used filter expression.
|
||||
|
||||
Any URL filter **?foo=bar&baz=bar** in IW2, would therefore implicitly
|
||||
become ** ?(foo=bar&baz=bar)&( $RESTRICTION_FILTER )**, depending on the users current restrictions.
|
||||
|
||||
##### Filter Expressions
|
||||
|
||||
Any filter expression that is allowed in
|
||||
|
||||
|
||||
###### Monitoring module filters
|
||||
|
||||
Restrictions can apply to services, hosts or custom keys defined by any module.
|
||||
The monitoring module provides the following restrictions:
|
||||
|
||||
| Keys | Filters |
|
||||
|------|---------|
|
||||
| monitoring/hosts/filter | Restrict hosts view to the hosts that match the filter |
|
||||
| monitoring/services/filter | Restrict services view to the services that match the filter |
|
||||
|
||||
Restrictions on hosts or services will automatically apply to all notifications, events
|
||||
or downtimes that belong to those objects.
|
||||
|
||||
** ATTENTION ! **
|
||||
|
||||
Specifying a host filter will **not** automatically apply to all services on that host. If this behavior is desired, it is always necessary to filter the host for those services too.
|
||||
|
||||
## Modules
|
||||
|
||||
When creating IW2 modules, it might be necessary to define new actions that can be granted or revoked to certain users. One example for this, is the monitoring module, that is the heart of the monitoring functionality of IW2.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Q: I cannot see the menu for changing roles in Icinga Web 2
|
||||
|
||||
A: Your user lacks the permission to change the authentication configuration,
|
||||
add a new role in roles.ini that gives your current user
|
||||
the permission to access **config/authentication/* **
|
||||
Loading…
Reference in New Issue