Adding upstream version 2.12.1.upstream/2.12.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 293 insertions, 0 deletions

diff --git a/doc/05-Authentication.md b/doc/05-Authentication.md
new file mode 100644
index 0000000..5923a8c
--- /dev/null
+++ b/doc/05-Authentication.md
@@ -0,0 +1,293 @@
+# Authentication <a id="authentication"></a>
+
+You can authenticate against Active Directory, LDAP, a MySQL or a PostgreSQL database or delegate
+authentication to the web server.
+
+Authentication methods can be chained to set up fallback authentication methods
+or if users are spread over multiple places.
+
+## Configuration <a id="authentication-configuration"></a>
+
+Navigate into **Configuration > Application > Authentication **.
+
+Authentication methods are configured in the `/etc/icingaweb2/authentication.ini` file.
+
+Each section in the authentication configuration represents a single authentication method.
+
+The order of entries in the authentication configuration determines the order of the authentication methods.
+If the current authentication method errors or if the current authentication method does not know the account being
+authenticated, the next authentication method will be used.
+
+## External Authentication <a id="authentication-configuration-external-authentication"></a>
+
+Authentication to the web server can be delegated with the `autologin` section
+which specifies an external backend.
+
+Option                   | Description
+-------------------------|-----------------------------------------------
+backend                  | **Required.** Specifies the backend type. Must be set to `external`.
+strip\_username\_regexp  | **Optional.** Regular expression to strip off specific user name parts.
+
+Example:
+
+```
+# vim /etc/icingaweb2/authentication.ini
+
+[autologin]
+backend = external
+```
+
+If your web server is not configured for authentication though, the `autologin` section has no effect.
+
+### Example Configuration for Apache and Basic Authentication <a id="authentication-configuration-external-authentication-example"></a>
+
+The following example will show you how to enable external authentication in Apache
+using basic authentication.
+
+#### Create Basic Auth User <a id="authentication-configuration-external-authentication-example-user"></a>
+
+You can use the tool `htpasswd` to generate basic authentication credentials. This example writes the
+user credentials into the `.http-users` file.
+
+The following command creates a new file which adds the user `icingaadmin`.
+`htpasswd` will prompt you for a password.
+If you want to add more users to the file you have to omit the `-c` switch to not overwrite the file.
+
+```
+sudo htpasswd -c /etc/icingaweb2/.http-users icingaadmin
+```
+
+#### Apache Configuration <a id="authentication-configuration-external-authentication-example-apache"></a>
+
+Add the following configuration to the `&lt;Directory&gt;` directive in the `icingaweb2.conf` web server
+configuration file.
+
+```
+AuthType Basic
+AuthName "Icinga Web 2"
+AuthUserFile /etc/icingaweb2/.http-users
+Require valid-user
+```
+
+Restart your web server to apply the changes.
+
+Example on CentOS 7:
+
+```
+systemctl restart httpd
+```
+
+## Active Directory or LDAP Authentication <a id="authentication-configuration-ad-or-ldap-authentication"></a>
+
+If you want to authenticate against Active Directory or LDAP, you have to define an
+[LDAP resource](04-Resources.md#resources-configuration-ldap).
+This is referenced as data source for the Active Directory or LDAP configuration method.
+
+### LDAP <a id="authentication-configuration-ldap-authentication"></a>
+
+Option                   | Description
+-------------------------|-----------------------------------------------
+backend                  | **Required.** Specifies the backend type. Must be set to `ldap`.
+resource                 | **Required.** The name of the LDAP resource defined in [resources.ini](04-Resources.md#resources).
+user\_class              | **Optional.** LDAP user class. Defaults to `inetOrgPerson`.
+user\_name\_attribute    | **Optional.** LDAP attribute which contains the username. Defaults to `uid`.
+filter                   | **Optional.** LDAP search filter. Requires `user_class` and `user_name_attribute`.
+
+> **Note for SELinux**
+>
+> If you run into problems connecting with LDAP and have SELinux enabled, take a look [here](90-SELinux.md#selinux-optional-booleans).
+
+Example:
+
+```
+# vim /etc/icingaweb2/authentication.ini
+
+[auth_ldap]
+backend             = ldap
+resource            = my_ldap
+user_class          = inetOrgPerson
+user_name_attribute = uid
+filter              = "memberOf=cn=icinga_users,cn=groups,cn=accounts,dc=icinga,dc=org"
+```
+
+If `user_name_attribute` specifies multiple values all of them must be unique.
+Please keep in mind that a user will be logged in with the exact user id used to authenticate
+with Icinga Web 2 (e.g. an alias) ignoring the actual primary user id.
+
+### Active Directory <a id="authentication-configuration-ad-authentication"></a>
+
+Option                   | Description
+-------------------------|-----------------------------------------------
+backend                  | **Required.** Specifies the backend type. Must be set to `msldap`.
+resource                 | **Required.** The name of the LDAP resource defined in [resources.ini](04-Resources.md#resources).
+user\_class              | **Optional.** LDAP user class. Defaults to `user`.
+user\_name\_attribute    | **Optional.** LDAP attribute which contains the username. Defaults to `sAMAccountName`.
+filter                   | **Optional.** LDAP search filter. Requires `user_class` and `user_name_attribute`.
+
+Example:
+
+```
+# vim /etc/icingaweb2/authentication.ini
+
+[auth_ad]
+backend  = msldap
+resource = my_ad
+```
+
+## Database Authentication <a id="authentication-configuration-db-authentication"></a>
+
+If you want to authenticate against a MySQL or a PostgreSQL database, you have to define a
+[database resource](04-Resources.md#resources-configuration-database) which will be referenced as data source for the database
+authentication method.
+
+Option                   | Description
+-------------------------|-----------------------------------------------
+backend                  | **Required.** Specifies the backend type. Must be set to `db`.
+resource                 | **Required.** The name of the database resource defined in [resources.ini](04-Resources.md#resources). |
+
+Example:
+
+```
+# vim /etc/icingaweb2/authentication.ini
+
+[auth_db]
+backend  = db
+resource = icingaweb-mysql
+```
+
+Please read [this chapter](20-Advanced-Topics.md#advanced-topics-authentication-tips-manual-user-database-auth)
+in order to manually create users directly inside the database.
+
+
+## Groups <a id="authentication-configuration-groups"></a>
+
+Navigate into **Configuration > Application > Authentication **.
+
+Group configuration is stored in the `/etc/icingaweb2/groups.ini` file.
+
+### LDAP Groups <a id="authentication-configuration-groups-ldap"></a>
+
+Option                   | Description
+-------------------------|-----------------------------------------------
+backend                  | **Required.** Specifies the backend type. Can be set to `ldap`, `msldap`.
+resource                 | **Required.** The name of the LDAP resource defined in [resources.ini](04-Resources.md#resources).
+domain                   | **Optional.** The domain the LDAP server is responsible for. See [Domain-aware Authentication](05-Authentication.md#domain-aware-auth).
+user\_class              | **Optional.** LDAP user class. Defaults to `inetOrgPerson` with `msldap` and `user` with `ldap`.
+user\_name\_attribute    | **Optional.** LDAP attribute which contains the username. Defaults to `sAMAccountName` with `msldap` and `uid` with `ldap`.
+user\_base\_dn           | **Optional.** The path where users can be found on the LDAP server.
+base_dn                  | **Optional.** LDAP base dn for groups. Leave empty to select all groups available using the specified resource.
+group\_class             | **Optional.** LDAP group class. Defaults to `group`.
+group\_member\_attribute | **Optional.** LDAP attribute where a group's members are stored. Defaults to `member`.
+group\_name\_attribute   | **Optional.** LDAP attribute which contains the groupname. Defaults to `sAMAccountName` with `msldap` and `gid` with `ldap`.
+group\_filter            | **Optional.** LDAP group search filter. Requires `group_class` and `group_name_attribute`.
+nested\_group\_search    | **Optional.** Enable nested group search in Active Directory based on the user. Defaults to `0`. Only available with `backend` type `msldap`.
+
+Example for Active Directory groups:
+
+```
+# vim /etc/icingaweb2/groups.ini
+
+[active directory]
+backend = "msldap"
+resource = "auth_ad"
+group_class = "group"
+user_class = "user"
+user_name_attribute = "userPrincipalName"
+```
+
+Example for Active Directory using the group backend resource `ad_company`.
+It also references the defined user backend resource `ad_users_company`.
+
+```
+# vim /etc/icingaweb2/groups.ini
+
+[ad_groups_company]
+backend = "msldap"
+resource = "ad_company"
+user_backend = "ad_users_company"
+nested_group_search = "1"
+base_dn = "ou=Icinga,ou=Groups,dc=company,dc=com"
+```
+
+### Database Groups <a id="authentication-configuration-groups-database"></a>
+
+Option                   | Description
+-------------------------|-----------------------------------------------
+backend                  | **Required.** Specifies the backend type. Must be set to `db`.
+resource                 | **Required.** The name of the database resource defined in [resources.ini](04-Resources.md#resources).
+
+Example:
+
+```
+# vim /etc/icingaweb2/groups.ini
+
+[icingaweb2]
+backend = "db"
+resource = "icingaweb_db"
+```
+
+
+## Domain-aware Authentication <a id="domain-aware-auth"></a>
+
+If there are multiple LDAP/AD authentication backends with distinct domains, you should make Icinga Web 2 aware of the
+domains. This is possible since version 2.5 and can be done by configuring each LDAP/AD backend's domain. You can also
+use the GUI for this purpose. This enables you to automatically discover a suitable value based on your LDAP server's
+configuration. (AD: NetBIOS name, other LDAP: domain in DNS-notation)
+
+**Example:**
+
+```
+# vim /etc/icingaweb2/authentication.ini
+
+[auth_icinga]
+backend             = ldap
+resource            = icinga_ldap
+user_class          = inetOrgPerson
+user_name_attribute = uid
+filter              = "memberOf=cn=icinga_users,cn=groups,cn=accounts,dc=icinga,dc=com"
+domain              = "icinga.com"
+
+[auth_example]
+backend  = msldap
+resource = example_ad
+domain   = EXAMPLE
+```
+
+If you configure the domains like above, the icinga.com user "jdoe" will have to log in as "jdoe@icinga.com" and the
+EXAMPLE employee "rroe" will have to log in as "rroe@EXAMPLE". They could also log in as "EXAMPLE\\rroe", but this gets
+converted to "rroe@EXAMPLE" as soon as the user logs in.
+
+> **Caution!**
+>
+> Enabling domain-awareness or changing domains in existing setups requires migration of the usernames in the Icinga Web 2
+> configuration. Consult `icingacli --help migrate config users` for details.
+
+### Default Domain <a id="default-auth-domain"></a>
+
+For the sake of simplicity a default domain can be configured (in `config.ini`).
+
+**Example:**
+
+```
+# vim /etc/icingaweb2/config.ini
+
+[authentication]
+default_domain = "icinga.com"
+```
+
+If you configure the default domain like above, the user "jdoe@icinga.com" will be able to just type "jdoe" as username
+while logging in.
+
+### How it works <a id="domain-aware-auth-process"></a>
+
+### Active Directory <a id="domain-aware-auth-ad"></a>
+
+When the user "jdoe@ICINGA" logs in, Icinga Web 2 walks through all configured authentication backends until it finds
+one which is responsible for that user -- e.g. an Active Directory backend with the domain "ICINGA". Then Icinga Web 2
+asks that backend to authenticate the user with the sAMAccountName "jdoe".
+
+### SQL Database <a id="domain-aware-auth-sqldb"></a>
+
+When the user "jdoe@icinga.com" logs in, Icinga Web 2 walks through all configured authentication backends until it
+finds one which is responsible for that user -- e.g. a MySQL backend (SQL database backends aren't domain-aware). Then
+Icinga Web 2 asks that backend to authenticate the user with the username "jdoe@icinga.com".