Skip to content

Latest commit

 

History

History
293 lines (209 loc) · 11.7 KB

05-Authentication.md

File metadata and controls

293 lines (209 loc) · 11.7 KB
Raw

Authentication

You can authenticate against Active Directory, LDAP, a MariaDB, MySQL or 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

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

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

The following example will show you how to enable external authentication in Apache using basic authentication.

Create Basic Auth User

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

Add the following configuration to the <Directory> 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

If you want to authenticate against Active Directory or LDAP, you have to define an LDAP resource. This is referenced as data source for the Active Directory or LDAP configuration method.

LDAP

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.
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.

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

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.
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

If you want to authenticate against a MariaDB, MySQL or PostgreSQL database, you have to define a database resource 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.

Example:

# vim /etc/icingaweb2/authentication.ini

[auth_db]
backend  = db
resource = icingaweb-mysql

Please read this chapter in order to manually create users directly inside the database.

Groups

Navigate into **Configuration > Application > Authentication **.

Group configuration is stored in the /etc/icingaweb2/groups.ini file.

LDAP Groups

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.
domain Optional. The domain the LDAP server is responsible for. See Domain-aware Authentication.
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

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.

Example:

# vim /etc/icingaweb2/groups.ini

[icingaweb2]
backend = "db"
resource = "icingaweb_db"

Domain-aware Authentication

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

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

Active Directory

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

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 MariaDB or 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".