tyler.durden
/
icingaweb2
mirror of https://github.com/Icinga/icingaweb2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update documentation covering external authentication 

refs #8274
This commit is contained in:
Johannes Meyer 2015-01-28 17:52:17 +01:00
parent 78f5bf4f3d
commit 8383320f31
1 changed files with 59 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
doc/external_authentication.md
View File

@ -1,90 +1,83 @@
# Externel Authentication # External Authentication
It is possible to use the authentication mechanism of the webserver, It is possible to utilize the authentication mechanism of the webserver instead
instead of using the internal authentication-manager to of the internal authentication of Icinga Web 2 to authenticate users. This might
authenticate users. This might be useful if you only have very few users, and be useful if you only have very few users and user management over **.htaccess**
user management over *.htaccess* is sufficient, or if you must use some other is not sufficient or if you are required to use some other authentication
authentication mechanism that is only available through your webserver. mechanism that is only available by utilizing the webserver.
When external authentication is used, Icingaweb will entrust the Icinga Web 2 will entrust the complete authentication process to the
complete authentication process to the external authentication provider (the webserver): authentication provider of the webserver, if external authentication is used.
The provider should take care of authenticating the user and declining So it is very important that the webserver's authentication is configured
all requests with invalid or missing credentials. When the authentication correctly as wrong configuration might lead to unauthorized access or a
was succesful, it should provide the authenticated users name to its php-module malfunction in the login-process.
and Icingaweb will assume that the user is authorized to access the page.
Because of this it is very important that the webservers authentication is
configured correctly, as wrong configuration could lead to unauthorized
access to the site, or a broken login-process.
## Using External Authentication
## Use External Authentication External authentication in Icinga Web 2 requires the following preparations:
Using external authentication in Icingaweb requires two steps to work: 1. The external authentication must be set up properly to correctly
authenticate users
2. Icinga Web 2 must be configured to use external authentication
1. The external authentication must be set up correctly to always ### Preparing the External Authentication Provider
authenticate the users.
2. Icingaweb must be configured to use the external authentication.
This step depends heavily on the used webserver and authentication mechanism you
want to use. It is not possible to cover all possibillities and you should
probably read the documentation for your webserver to get detailed instructions
on how to set up authentication properly.
### Prepare the External Authentication Provider In general you need to make sure that:
This step depends heavily on the used webserver and authentication
mechanism you want to use. It is not possible to cover all possibillities
and you should probably read the documentation for your webserver for
detailed instructions on how to set up authentication properly.
In general, you need to make sure that:
- All routes require authentication
- Only permitted users are allowed to authenticate
- All routes require authentication
- Only permitted users are allowed to authenticate
#### Example Configuration for Apache and HTTPDigestAuthentication #### Example Configuration for Apache and HTTPDigestAuthentication
The following example will show how to enable external authentication in Apache using The following example will show how to enable external authentication in Apache
*HTTP Digest Authentication*. using *HTTP Digest Authentication*.
##### Create users ##### Creating users
To create users for a digest authentication we can use the tool *htdigest*. To create users for digest authentication you can use the tool *htdigest*. In
We choose *.icingawebdigest* as a name for the created file, containing this example **.icingawebdigest** is the name of the file containing the user
the user credentials. credentials.
This command will create a new file with the user *jdoe*. *htdigest* This command creates a new file with the user *jdoe*. *htdigest* will prompt
will prompt you for your password, after it has been executed. If you you for a password. If you want to add more users to the file you need to omit
want to add more users to the file you need to ommit the *-c* parameter the *-c* parameter in all following commands to not to overwrite the file.
in all further commands to avoInid the file to be overwritten.
````
sudo htdigest -c /etc/icingaweb2/.icingawebdigest "Icinga Web 2" jdoe
````
sudo htdigest -c /etc/httpd/conf.d/.icingawebdigest "Icingaweb 2" jdoe ##### Configuring the Webserver
The webserver should require authentication for all public Icinga Web 2 files.
##### Set up authentication ````
<Directory "/usr/share/icingaweb2/public">
AuthType digest
AuthName "Icinga Web 2"
AuthDigestProvider file
AuthUserFile /etc/icingaweb2/.icingawebdigest
Require valid-user
</Directory>
````
The webserver should require authentication for all public icingaweb files. ### Preparing Icinga Web 2
Once external authentication is set up correctly you need to configure Icinga
Web 2. In case you already completed the setup wizard it is likely that you are
now finished.
<Directory "/var/www/html/icingaweb"> To get Icinga Web 2 to use external authentication the file
AuthType digest **config/authentication.ini** is required. Just add the following section
AuthName "Icingaweb 2" called "autologin", or any name of your choice, and save your changes:
AuthDigestProvider file
AuthUserFile /etc/httpd/conf.d/.icingawebdigest
Require valid-user
</Directory>
````
### Prepare Icingaweb [autologin]
backend = external
````
When the external authentication is set up correctly, we need Congratulations! You are now logged in when visiting Icinga Web 2.
to configure IcingaWeb to use it as an authentication source. The
configuration key *authenticationMode* in the section *global* defines
if the authentication should be handled internally or externally. Since
we want to delegate the authentication to the Webserver we choose
"external" as the new value:
[global]
; ...
authenticationMode = "external"
; ...