icingaweb2/doc/security.md

# <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/* **