1# Security <a id="security"></a> 2 3Access control is a vital part of configuring Icinga Web 2 in a secure way. 4It is important that not every user that has access to Icinga Web 2 is able 5to do any action or to see any host and service. For example, it is useful to allow 6only a small group of administrators to change the Icinga Web 2 configuration, 7to prevent misconfiguration or security breaches. Another important use case is 8creating groups of users which can only see the fraction of the monitoring 9environment they are in charge of. 10 11This chapter will describe how to do the security configuration of Icinga Web 2 12and how to apply permissions and restrictions to users or groups of users. 13 14## Basics <a id="security-basics"></a> 15 16Icinga Web 2 access control is done by defining **roles** that associate permissions 17and restrictions with **users** and **groups**. There are two general kinds of 18things to which access can be managed: actions and objects. 19 20 21### <a id="security-basics-actions"></a>Actions 22 23Actions are all the things an Icinga Web 2 user can do, like changing a certain configuration, 24changing permissions or sending a command to an Icinga 2 instance. 25All actions must be be **allowed explicitly** using permissions. 26 27A permission is a simple list of identifiers of actions a user is 28allowed to do. Permissions are described in greater detail in the 29section [Permissions](06-Security.md#permissions). 30 31### Objects <a id="security-basics-objects"></a> 32 33There are all kinds of different objects in Icinga Web 2: Hosts, Services, Notifications, Downtimes and Events. 34 35By default, a user can **see everything**, but it is possible to **explicitly restrict** what each user can see using restrictions. 36 37Restrictions are complex filter queries that describe what objects should be displayed to a user. Restrictions are described 38in greater detail in the section [Restrictions](06-Security.md#restrictions). 39 40### <a id="security-basics-users"></a>Users 41 42Anyone who can **login** to Icinga Web 2 is considered a user and can be referenced to by the 43**user name** used during login. 44For example, there might be user called **jdoe** authenticated 45using Active Directory, and a user **icingaadmin** that is authenticated using a MySQL-Database as backend. 46In the configuration, both can be referenced to by using their user names **icingaadmin** or **jdoe**. 47 48Icinga Web 2 users and groups are not configured by a configuration file, but provided by 49an **authentication backend**. For extended information on setting up authentication backends and managing users, please read the chapter [Authentication](05-Authentication.md#authentication). 50 51 52> **Note** 53> 54> Since Icinga Web 2, users in the Icinga configuration and the web authentication are separated, to allow 55> use of external authentication providers. This means that users and groups defined in the Icinga configuration are not available to Icinga Web 2. Instead it uses its own authentication 56> backend to fetch users and groups from, which must be configured separately. 57 58#### <a id="security-basics-users-managing"></a>Managing Users 59 60When using a [Database 61as authentication backend](05-Authentication.md#authentication-configuration-db-authentication), it is possible to create, add and delete users directly in the frontend. This configuration 62can be found at **Configuration > Authentication > Users **. 63 64### <a id="security-basics-groups"></a>Groups 65 66If there is a big amount of users to manage, it would be tedious to specify each user 67separately when regularly referring to the same group of users. Because of that, it is possible to group users. 68A user can be member of multiple groups and will inherit all permissions and restrictions. 69 70Like users, groups are identified solely by their **name** that is provided by 71 a **group backend**. For extended information on setting up group backends, 72 please read the chapter [Authentication](05-Authentication.md#authentication). 73 74 75#### <a id="security-basics-groups-managing"></a>Managing Groups 76 77When using a [Database as an authentication backend](05-Authentication.md#authentication-configuration-db-authentication), 78it is possible to manage groups and group memberships directly in the frontend. This configuration 79can be found at **Configuration > Authentication > User Groups **. 80 81## <a id="security-roles"></a>Roles 82 83A role defines a set of **permissions** and **restrictions** and assigns 84those to **users** and **groups**. For example, a role **admins** could define that certain 85users have access to all configuration options, or another role **support** 86could define that a list of users or groups is restricted to see only hosts and services 87that match a specific query. 88 89The actual permission of a certain user will be determined by merging the permissions 90and restrictions of the user itself and all the groups the user is member of. Permissions can 91be simply added up, while restrictions follow a slighty more complex pattern, that is described 92in the section [Stacking Filters](06-Security.md#stacking-filters). 93 94### <a id="security-roles-configuration"></a>Configuration 95 96Roles can be changed either through the icingaweb2 interface, by navigation 97to the page **Configuration > Authentication > Roles**, or through editing the 98configuration file: 99 100``` 101vim /etc/icingaweb2/roles.ini 102``` 103 104#### <a id="security-roles-configuration-example"></a>Introducing Example 105 106To get you a quick start, here is an example of what a role definition could look like: 107 108``` 109[winadmin] 110users = "jdoe, janedoe" 111groups = "admin" 112permissions = "config/*, monitoring/commands/schedule-check" 113monitoring/filter/objects = "host_name=*win*" 114``` 115 116 117This example creates a role called **winadmin**, that grants all permissions in `config/*` and `monitoring/commands/schedule-check` and additionally only 118allows the hosts and services that match the filter `host_name=*win*` to be displayed. The users 119**jdoe** and **janedoe** and all members of the group **admin** will be affected 120by this role. 121 122 123#### Syntax <a id="syntax"></a> 124 125Each role is defined as a section, with the name of the role as section name. The following 126attributes can be defined for each role in a default Icinga Web 2 installation: 127 128 129Name | Description 130--------------------------|----------------------------------------------- 131users | Comma-separated list of user **user names** that are affected by this role. 132groups | Comma-separated list of **group names** that are affected by this role. 133permissions | Comma-separated list of **permissions** granted by this role. 134monitoring/filter/objects | **Filter expression** that restricts the access to services and hosts. 135 136 137 138## Permissions <a id="permissions"></a> 139 140Permissions can be used to allow users or groups certain **actions**. By default, 141all actions are **prohibited** and must be allowed explicitly by a role for any user. 142 143Each action in Icinga Web 2 is denoted by a **namespaced key**, which is used to order and 144group those actions. All actions that affect the configuration of Icinga Web 2, are in a 145namespace called **config**, while all configurations that affect modules 146are in the namespace `config/modules` 147 148**Wildcards** can be used to grant permission for all actions in a certain namespace. 149The permission `config/*` would grant permission to all configuration actions, 150while just specifying a wildcard `*` would give permission for all actions. 151 152Access to modules is restricted to users who have the related module permission granted. Icinga Web 2 provides 153a module permission in the format `module/<moduleName>` for each installed module. 154 155When multiple roles assign permissions to the same user (either directly or indirectly 156through a group) all permissions are added together to get the users actual permission set. 157 158### Global Permissions <a id="permissions-global"></a> 159 160Name | Permits 161--------------------------|----------------------------------------------- 162\* | allow everything, including module-specific permissions 163config/\* | allow all configuration actions 164config/modules | allow enabling or disabling modules 165module/<moduleName> | allow access to module <moduleName> 166 167 168### Monitoring Module Permissions <a id="permissions-module"></a> 169 170The built-in monitoring module defines an additional set of permissions, that 171is described in detail in the monitoring module documentation. 172 173 174## Restrictions <a id="restrictions"></a> 175 176Restrictions can be used to define what a user or group can see by specifying 177a filter expression that applies to a defined set of data. By default, when no 178restrictions are defined, a user will be able to see every information that is available. 179 180A restrictions is always specified for a certain **filter directive**, that defines what 181data the filter is applied to. The **filter directive** is a simple identifier, that was 182defined in an Icinga Web 2 module. The only filter directive that is available 183in a default installation, is the `monitoring/filter/objects` directive, defined by the monitoring module, 184that can be used to apply filter to hosts and services. This directive was previously 185mentioned in the section [Syntax](06-Security.md#syntax). 186 187### <a id="restrictions-filter"></a>Filter Expressions 188 189Filters operate on columns. A complete list of all available filter columns on hosts and services can be found in 190the monitoring module documentation. 191 192Any filter expression that is allowed in the filtered view, is also an allowed filter expression. 193This means, that it is possible to define negations, wildcards, and even nested 194filter expressions containing AND and OR-Clauses. 195 196The filter expression will be **implicitly** added as an **AND-Clause** to each query on 197the filtered data. The following shows the filter expression `host_name=*win*` being applied on `monitoring/filter/objects`. 198 199 200Regular filter query: 201 202 AND-- service_problem = 1 203 | 204 +--- service_handled = 0 205 206 207With our restriction applied, any user affected by this restrictions will see the 208results of this query instead: 209 210 211 AND-- host_name = *win* 212 | 213 +--AND-- service_problem = 1 214 | 215 +--- service_handled = 0 216 217#### Username placeholder <a id="username-placeholder"></a> 218 219The string `$user:local_name$` is replaced by the local username (without the domain part) of the logged on user while evaluating restrictions. 220This can come in handy if you have some kind of attribute on host or service level defining which user is responsible for a certain host or service. 221 222**Example** 223 224``` 225monitoring/filter/objects = (_responsible=$user:local_name$|_deputy=$user:local_name$) 226``` 227 228#### Stacking Filters <a id="stacking-filters"></a> 229 230When multiple roles assign restrictions to the same user, either directly or indirectly 231through a group, all filters will be combined using an **OR-Clause**, resulting in the final 232expression: 233 234 235 AND-- OR-- $FILTER1 236 | | 237 | +-- $FILTER2 238 | | 239 | +-- $FILTER3 240 | 241 +--AND-- service_problem = 1 242 | 243 +--- service_handled = 0 244 245 246As a result, a user is be able to see hosts that are matched by **ANY** of 247the filter expressions. The following examples will show the usefulness of this behavior: 248 249#### <a id="restrictions-filter-example1"></a>Example 1: Negation 250 251``` 252[winadmin] 253groups = "windows-admins" 254monitoring/filter/objects = "host_name=*win*" 255``` 256 257Will display only hosts and services whose host name contains **win**. 258 259``` 260[webadmin] 261groups = "web-admins" 262monitoring/filter/objects = "host_name!=*win*" 263``` 264 265Will only match hosts and services whose host name does **not** contain **win** 266 267Notice 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. 268 269#### <a id="restrictions-filter-example2"></a>Example 2: Hostgroups 270 271``` 272[unix-server] 273groups = "unix-admins" 274monitoring/filter/objects = "(hostgroup_name=bsd-servers|hostgroup_name=linux-servers)" 275``` 276 277This role allows all members of the group unix-admins to see hosts and services 278that are part of the host-group linux-servers or the host-group bsd-servers. 279