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 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.
You configure the authentication modules for the drivers in the OP5 Monitor user interface. OP5 Monitor stores the configuration for the authentication system in
For more information about configuring authentication modules, see Add or update authentication modules in Manage users, contacts, and permissions.
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
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
realname: "Monitor Admin"
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:
This is a small helper for adding/changing/deleting users in op5 Monitor.
/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
/usr/bin/op5-manage-users --remove --username=<username>
Here is a syntax example for creating a new OP5 Monitor user called
/usr/bin/op5-manage-users --update --username=gord --realname="Wheat King" --modules=Default --password=100thMeridian --group=admins
Here is the resulting content in
realname: "Wheat King"
op5-manage-usersdoes 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"
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"
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.
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-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
--- 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 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.