Multisite Login Dialog

Introduction

The default mechanism of user authentication in Nagios environments is to use basic authentication which is checked against htpaswd files on the Nagios server. In some environment the credentials are checked against LDAP servers but the frontend to the user remains the same.

When using basic authentication the user is asked for credentials by the browser after requesting a website. The browser pops up a small window for entering the username and password to access the requested page. After this request the auth credentials are sent with each HTTP request to that webpage. The webserver validates the credentials.

The served webpages like Multisite, NagVis, PNP4Nagios, ... don't know anything about the real credentials of the user. They get the name of the authenticated user in the environment variable REMOTE_USER and trust this information. From the view of the webpages it is a very easy sort of authentication. The webpage does not need to care about the user authentication.

You might see the disadvantage of this authentication mechanism: The browser controls the way the credential query dialog is displayed. In some cases it is strongly required to have a login dialog which can easily be designed. It might also be nessecary to add further information, like links to documentations, to the login page. It is very easy to create such login dialogs using HTML. But using form based login dialogs the basic authentication is not easily possible anymore.

Without the basic authentication on webserver level all the webpages need to implement the credential checking on their own. To make this possible Multisite implements an optional cookie and shared secret based authentication which can be implemented in the different addons. This has been done for Multisite, NagVis and pnp4nagios.

Technical details

In general you can say that multisite implements a login portal solution wheren you login in a central login dialog once. After success you have access to all web based addons withing this authentication realm.

The login dialog

The login dialog is a simple HTML page which asks the user for a username and a password. The dialog is shown when opening multisite without having a valid auth cookie or when directly accessing the URL check_mk/login.py.

When the login dialog has been opened while accessing another page it automaticaly redirects the user to the requested page after successfull authentication.

When opening the login dialog directly it is possible to provide the URL parameter _origintarget. This page will be opened after successful authentication.

The auth secret

The base of this authentication mechanism is the shared secret used for creating and validating auth cookies. The secret must be available to all addons which want to validate and create auth cookies.

The auth secret is basically a string of random characters which is directly read from the auth.secret file. The file is stored in the directory where the htpasswd file is stored.

Auth cookie format

The cookie must support multiple multisite installations per host. Though the name of the cookie is dynamically set. It depends on the url_prefix of the configured in multisite. The name is built as follows auth_<url_prefix> while the slashes in the url_prefix are replaced with underscores.

The value of the cookie has the following layout:

<USERNAME>:<ISSUE_TIME>:<AUTH_HASH>

For example the value of the cookie auth_test of my OMD site test:

omdadmin:1323169300.47:d9741d4ad65735cbf035a529fe038efc

USERNAME	This is the clear text username of the authed user.
ISSUE_TIME	The unix timestamp of the cookie creation time.
AUTH_HASH	The auth hash is a md5 hash of the following concatenated strings: <USERNAME><ISSUE_TIME><PASSWORD_HASH><AUTH_SECRET>. When any of those information changes the cookie is invalidated and the user needs to reauthenticate.

Integration in addons

The first addon which can use the authentication cookie is NagVis. NagVis 1.6 is shipped with a logon module named LogonMultisite. This logon module checks the HTTP request for the auth cookie and verifies the cookie contents. When the cookie is valid it authenticates the user stated in the cookie. When the cookie is not present or invalid NagVis redirects the user to the multisite login page. After successful auth the login module redirects the user back to the requested NagVis page.

Logging out

It is possible to destroy the authentication cookie by visiting the url check_mk/logout.py. This page tells the browser to remove the auth cookie.

Configuration

When you are using OMD simply execute omd config as site user and set the option Web GUI / MULTISITE_COOKIE_AUTH to on. This omd hook disables the basic authentication in multisite, nagvis and pnp4nagios and enables the cookie based authentication for these addons.

When not using OMD you have to do this by hand:

To enable the login dialog and cookie checking in Multisite just disable the basic authentication part in the apache configuration.

To enable the cookie based authentication in NagVis you need to put the following into the nagvis main configuration:

[global]
logonmodule="LogonMultisite"
logon_multisite_secret="<path-to-multisite-secret>/auth.secret"
logon_multisite_htpasswd="<path-to-htpasswd>/htpasswd"

You also need to disable the basic authentication in the apache configuration for NagVis.

Docs for pnp4nagios are missing. Sorry.