Manage authentication

Overview

This page explains how to perform some advanced authentication tasks on your OP5 Monitor system. It is intended for users with access to the command line and advanced knowledge of authentication. For basic user permission configuration, see Manage users, contacts, and permissions.

Authentication drivers

Authentication drivers handle OP5 Monitor user authentication. Each driver both authenticates the user and resolves group memberships for the user. The groups are then mapped to permissions by the authorisation layer.

There are three types of authentication driver:

Default driver — local user management.
Apache driver — Apache authentication.
LDAP driver — external user management.

When you create local users with the default driver in OP5 Monitor, it stores the users locally on the OP5 Monitor server. For more information about creating local users, see Manage users in Manage users, contacts, and permissions.

Authentication modules

You configure the authentication modules for the drivers in the OP5 Monitor user interface. OP5 Monitor stores the configuration for the authentication system in /etc/op5/auth.yml.

For more information about configuring authentication modules, see Add or update authentication modules in Manage users, contacts, and permissions.

Default driver

We highly recommend that you always keep the default driver configured with an administrator account as a backup, even if your system is primarily using LDAP. If anything goes wrong, you can use /usr/bin/op5-manage-users to change the administrator password and access OP5 Monitor.

This driver stores local users in the configuration file /etc/op5/auth_users.yml.

Updating local users from the command line

All local user passwords are stored in /etc/op5/auth_users.yml, listed inside user blocks, such as the example below. The string beginning $1$VGn0 is a hash of the password monitor:

monitor:
 username: "monitor"
 realname: "Monitor Admin"
 password: "$1$VGn0CdSG$AMJjvHoF8M2nSy8SiPrW70"
 groups:
 - "admins"
 password_algo: "crypt"
 modules:
 - "Default"

You can change local users, including their passwords, with command /usr/bin/op5-manage-users. Running the command without any arguments prints its syntax help:

monitor:
This is a small helper for adding/changing/deleting users in op5 Monitor.

Create/edit user:
 /usr/bin/op5-manage-users --update --username=<username> (--password=<password>) \
 --module=<module1> [--module=<modulen>] [--realname=<realname> --group=<group1> [--group=<groupn>]]

--username User's username
 --password Password is only required if an authentication module that requires passwords is chosen
 --module Authentication module that should be used for this user
 --realname Full name of user
 --group User's group memberships

Delete user:
 /usr/bin/op5-manage-users --remove --username=<username>

Here is a syntax example for creating a new OP5 Monitor user called gord:

monitor:
/usr/bin/op5-manage-users --update --username=gord --realname="Wheat King" --modules=Default --password=100thMeridian --group=admins

Here is the resulting content in auth_users.yml:

monitor:
gord:
 username: "gord"
 realname: "Wheat King"
 password: "$1$s4gwhkvu$2ZB0.yHVSkcxWUtxtuLYX0"
 password_algo: "crypt"
 modules:
 - "Default"
 groups:
 - "admins"

Notes:

op5-manage-users does not append, it overwrites every entry for the user. For example, attempting to change only the group of the user created above updates the entire entry for the user:

monitor:
    op5-manage-users --update --username=gord --group=limited_edit

The password and all other entries are removed:

monitor:
gord:
  username: "gord"
  groups:
    - "limited_edit"

Changing the variable order in the command moves the user's real name to the bottom of the file entry. For example, this runs successfully:

monitor:
op5-manage-users --update --username=jfriday --realname="Sgt. Joe Friday" --group=admins --password=Badge714 --modules=Default

The resulting entry in auth_users.yml is less readable:

monitor:
jfriday:
  username: "jfriday"
  password: "$1$DTVh5ZeF$Tm1WeJDyH2AaY3FQ21Li4."
  password_algo: "crypt"
  modules:
    - "Default"
  groups:
    - "admins"
  realname: "Sgt. Joe Friday"

Apache driver

If you use an Apache driver for authentication, you need to take measures to protect the /monitor path access on the Apache web server, either with an .htaccess file or in the Apache configuration. You can use Apache modules for single sign-on authentication solutions, or other systems such as MySQL or Kerberos.

The driver retrieves the authenticated user name from Apache, and adds the group apache_auth_user to all logged-in users.

Users and permissions

The Apache driver uses a similar configuration to the default driver for group permissions. This means that you need to set up additional local users to resolve group memberships, since Apache does not have a way to resolve them.

You can specify one or more authentication modules per user in OP5 Monitor. This enables the user to log in using their specific authentication modules. As with ordinary local users, you can assign them to user groups to give them permissions for different parts of OP5 Monitor.

For guidance on configuring local users, user groups, and permissions in OP5 Monitor, see Manage users, contacts, and permissions.

Header authentication for single sign on (SSO)

Header authentication can be used to give SSO access to OP5 Monitor, by sending extra headers with the HTTP request. The headers must be sent on every page load, which means performing authentication every time you load a page.

You can only use this authentication method when all requests are made through an authenticating proxy that filters all request headers. Failing to do this enables any user to send extra headers that can grant admin privileges.

Configuration

You can enable HTTP header authentication by adding an authentication module using a header driver. To configure this module, you need to manually add the information below to /etc/op5/auth.yml. Note that X-Username, X-Realname, X-Email, and X-Groups need to be replaced with the corresponding headers, which are case-insensitive:

HeaderAuth:   
  driver: "Header"      
  header_username: X-Username
  header_realname: X-Realname
  header_email: X-Email
  header_groups: X-Groups
  group_list_delimiter: ","

Additionally, you must set the enable_auto_login option in the same file to true for header authentication to work.

Below is an example configuration of the authentication module in OP5 Monitor (from /etc/op5/auth.yml):

---
common:
  session_key: "auth_user"
  default_auth: "LDAP"
  enable_auto_login: true
  apc_enabled: false
  apc_ttl: ""
  apc_store_prefix: ""
  version: 3
HeaderAuth:
  driver: "Header"
  header_username: "Demo-Username"
  header_groups: "Demo-Groups"
  header_realname: "Demo-Realname"
  header_email: "Demo-Email"
  group_list_delimiter: ","
Default:
  driver: "Default"

Permissions

Permissions are handled by the groups that are sent in the group header, which you can configure using the OP5 Monitor Groups function. For more information, see Manage user groups in Manage users, contacts, and permissions.