diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/06-Security.md | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/doc/06-Security.md b/doc/06-Security.md new file mode 100644 index 0000000..b8d7cf2 --- /dev/null +++ b/doc/06-Security.md @@ -0,0 +1,242 @@ +# Security + +Access control is a vital part of configuring Icinga Web 2 securely. It is important that not every user that has +access to Icinga Web 2 can perform any action or see any host and service. Allow only a small group of administrators +to change the Icinga Web 2 configuration to prevent mis-configuration and security breaches. Define different rules +to users and groups of users which should only see a part of the monitoring environment they're in charge of. + +This chapter will describe how to configure such rules in Icinga Web 2 and how permissions, refusals, restrictions +and role inheritance work. + +## Basics + +Icinga Web 2 access control is done by defining **roles** that associate privileges with **users** and **groups**. +Privileges of a role consist of **permissions**, **refusals** and **restrictions**. A role can **inherit** privileges +from another role. + +### Role Memberships + +A role is tied to users or groups of users. Upon login, a user's roles are identified by the username or names of +groups the user is a member of. + +> **Note** +> +> Since Icinga Web 2, users in the Icinga configuration and the web authentication are separated, to allow use of +> external authentication providers. This means that users and groups defined in the Icinga configuration are not +> available to Icinga Web 2. It uses its own authentication backend to fetch users and groups from, +> [which must be configured separately](05-Authentication.md#authentication). + +### Privileges + +Permissions are used to grant access. Whether this means that a user can see a certain area or perform a distinct +action is fully up to the permission in question. Without granting a permission, the user will lack access and won't +see the area or perform the action. + +Refusals are used to deny access. So they're the exact opposite of permissions. Most permissions can be refused. +Refusing a permission will block the user's access no matter if another role grants the permission. Refusals +override permissions. + +Restrictions are expressions that limit access. What this exactly means is up to how the restriction is being utilized. +Without any restriction, a user is supposed to see *everything*. A user that occupies multiple roles, which all define +a restriction of the same type, will see *more*. + +## Roles + +A user can occupy multiple roles. Permissions and restrictions stack up in this case, thus will grant *more* access. +Refusals still override permissions however. A refusal of one role negates the granted permission of any other role. + +### Configuration + +Roles can be changed either through the UI, by navigating to the page **Configuration > Authentication > Roles**, +or by editing the configuration file `/etc/icingaweb2/roles.ini`. + +#### Example + +The following shows a role definition from the configuration file mentioned above: + +``` +[winadmin] +users = "jdoe, janedoe" +groups = "admin" +permissions = "config/*, module/monitoring, monitoring/commands/schedule-check" +refusals = "config/authentication" +monitoring/filter/objects = "host_name=*win*" +``` + +This describes a role with the name `winadmin`. The users `jdoe` and `janedoe` are members of it. Just like the +members of group `admin` are. Full configuration access is granted, except of the authentication configuration, +which is forbidden. It also grants access to the *monitoring* module which includes the ability to re-schedule +checks, but only on objects related to hosts whose name contain `win`. + +#### Syntax + +Each role is defined as a section, with the name of the role as section name. The following +options can be defined for each role in a default Icinga Web 2 installation: + +Name | Description +--------------------------|----------------------------------------------- +parent | The name of the role from which to inherit privileges. +users | Comma-separated list of **usernames** that should occupy this role. +groups | Comma-separated list of **group names** whose users should occupy this role. +permissions | Comma-separated list of **permissions** granted by this role. +refusals | Comma-separated list of **permissions** refused by this role. +unrestricted | If set to `1`, owners of this role are not restricted in any way (Default: `0`) +monitoring/filter/objects | **Filter expression** that restricts the access to monitoring objects. + +### Administrative Roles + +Roles that have the wildcard `*` as permission, have full access and don't need any further permissions. However, +they are still affected by refusals. + +Unrestricted roles are supposed to allow users to access data without being limited to a subset of it. Once a user +occupies an unrestricted role, restrictions of the same and any other role are ignored. + +### Inheritance + +A role can inherit privileges from another role. Privileges are then combined the same way as if a user occupies +all roles in the inheritance path. Or to rephrase that, each role shares its members with all of its parents. + +## Permissions + +Each permission in Icinga Web 2 is denoted by a **namespaced key**, which is used to group permissions. All permissions +that affect the configuration of Icinga Web 2, are in a namespace called **config**, while all configuration options +that affect modules are covered by the permission `config/modules`. + +**Wildcards** can be used to grant all permissions in a certain namespace. The permission `config/*` grants access to +all configuration options. Just specifying a wildcard `*` will grant all permissions. + +Access to modules is restricted to users who have the related module permission granted. Icinga Web 2 provides +a module permission in the format `module/<moduleName>` for each installed module. + +### General Permissions + +Name | Permits +-----------------------------|----------------------------------------------- +\* | allow everything, including module-specific permissions +application/announcements | allow to manage announcements +application/log | allow to view the application log +config/\* | allow full config access +config/access-control/\* | allow to fully manage access control +config/access-control/groups | allow to manage groups +config/access-control/roles | allow to manage roles +config/access-control/users | allow to manage user accounts +config/general | allow to adjust the general configuration +config/modules | allow to enable/disable and configure modules +config/navigation | allow to view and adjust shared navigation items +config/resources | allow to manage resources +user/\* | allow all account related functionalities +user/application/stacktraces | allow to adjust in the preferences whether to show stacktraces +user/password-change | allow password changes in the account preferences +user/share/navigation | allow to share navigation items +module/`<moduleName>` | allow access to module `<moduleName>` (e.g. `module/monitoring`) + +### Monitoring Module Permissions + +The built-in monitoring module defines an additional set of permissions, that +is described in detail in the monitoring module documentation. + +## Restrictions + +Restrictions can be used to define what a user can see by specifying an expression that applies to a defined set of +data. By default, when no restrictions are defined, a user will be able to see the entire data that is available. + +The syntax of the expression used to define a particular restriction varies. This can be a comma-separated list of +terms, or [a full-blown filter](06-Security.md#filter-expressions). For more details on particular restrictions, +check the table below or the module's documentation providing the restriction. + +### General Restrictions + +Name | Applies to +--------------------------|------------------------------------------------------------------------------------------ +application/share/users | which users a user can share navigation items with (comma-separated list of usernames) +application/share/groups | which groups a user can share navigation items with (comma-separated list of group names) + +### Username placeholder + +It is possible to reference the local username (without the domain part) of the user in restrictions. To accomplish +this, put the macro `$user.local_name$` in the restriction where you want it to appear. + +This can come in handy if you have e.g. an attribute on hosts or services defining which user is responsible for it: +`_host_deputy=$user.local_name$|_service_deputy=$user.local_name$` + +### Filter Expressions + +Filters operate on columns. A complete list of all available filter columns on hosts and services can be found in +the monitoring module documentation. + +Any filter expression that is allowed in the filtered view, is also an allowed filter expression. +This means, that it is possible to define negations, wildcards, and even nested +filter expressions containing AND and OR-Clauses. + +The filter expression will be **implicitly** added as an **AND-Clause** to each query on +the filtered data. The following shows the filter expression `host_name=*win*` being applied on `monitoring/filter/objects`. + + +Regular filter query: + + AND-- service_problem = 1 + | + +--- service_handled = 0 + + +With our restriction applied, any user affected by this restrictions will see the +results of this query instead: + + + AND-- host_name = *win* + | + +--AND-- service_problem = 1 + | + +--- service_handled = 0 + +#### Stacking Filters + +When multiple roles assign restrictions to the same user, either directly or indirectly +through a group, all filters will be combined using an **OR-Clause**, resulting in the final +expression: + + + AND-- OR-- $FILTER1 + | | + | +-- $FILTER2 + | | + | +-- $FILTER3 + | + +--AND-- service_problem = 1 + | + +--- service_handled = 0 + + +As a result, a user is be able to see hosts that are matched by **ANY** of +the filter expressions. The following examples will show the usefulness of this behavior: + +#### Example 1: Negation + +``` +[winadmin] +groups = "windows-admins" +monitoring/filter/objects = "host_name=*win*" +``` + +Will display only hosts and services whose host name contains **win**. + +``` +[webadmin] +groups = "web-admins" +monitoring/filter/objects = "host_name!=*win*" +``` + +Will only match hosts and services whose host name does **not** contain **win** + +Notice that because of the behavior of two stacking filters, a user that is member of **windows-admins** and **web-admins**, will now be able to see both, Windows and non-Windows hosts and services. + +#### Example 2: Hostgroups + +``` +[unix-server] +groups = "unix-admins" +monitoring/filter/objects = "(hostgroup_name=bsd-servers|hostgroup_name=linux-servers)" +``` + +This role allows all members of the group unix-admins to see hosts and services +that are part of the host-group linux-servers or the host-group bsd-servers. |