4.8. Administration Users

4.8.1. About Admin Users

Unlike Gateways Users, Admin Users have full or limited access to system and partition settings. The special role of the super administrator allows the management of very central system functions and the creation of so-called partitions.

Admin users can have one of the following roles:

  • Super-Admin

  • Partition Admin

  • Partition Read-Only

4.8.2. Two-Factor Authentication

In addition to password authentication, suSSHi Chef allows you to use a one-time password (OTP) authentication. An OTP is an automatically generated numeric or alphanumeric string used to authenticate a user for a single transaction or login session, typically in addition to a static password. OTP is more secure than a static password, especially a user-created password, which can be weak and/or reused across multiple accounts. The security improvement of OTP is based on the fact that the codes are constantly changing and can only be used once.

Time-based (RFC 6238, TOTP) and HMAC-based (RFC 4226, HOTP) are the two main open OTP algorithms, which both generate a numeric code with usually 6 or 8 digits.

In suSSHi Chef, TOTP is used to enable two-factor authentication (2FA). It requires an application that calculates the correct OTP for each time that changes every 30 seconds. There are a number of apps available for your smartphone operating system. One of the most famous is the very simple and limited Google Authenticator. We recommend to use an OTP app that is capable of locking the store with another password or PIN.

Each user receives his own individual and random secret key, which is synchronized with a suitable OTP application on the smartphone. Synchronization takes place by presenting a QR code image to the user and allowing him to scan the QR code with an OTP app installed on his smartphone.

4.8.2.1. Preparation

In order to start using the two-factor authentication with suSSHi Chef, an encryption key must be generated and provided to the suSSHi Chef container to securely store the personal OTP secrets in the database.

Warning

If you use multiple suSSHi Chef instances, the same encryption key must be configured for all of them. Please note that you must not change the encryption key if you have already stored encrypted OTP secrets in the database, as you will not be able to decrypt them afterwards.

For example, OpenSSL can be used to create such a key, although the syntax may vary depending on your operating system:

$ openssl rand -hex 32
6cbe51e3917575717bf22e9e1ba342b7988e2d2ef78460ac8708aa2f6f4f21fb

Please add the newly created encryption key to the .env file:

SECRET_KEY_OTP=6cbe51e3917575717bf22e9e1ba342b7988e2d2ef78460ac8708aa2f6f4f21fb

Next, add the newly created variable to the environment variables in the suSSHi Chef service section of your docker-compose.yml to pass it to the containers environment variables.

environment:
  ...
  - SECRET_KEY_OTP=${SECRET_KEY_OTP}

After restarting/recreating the container, you can start using OTP authentication.

$ docker-compose up -d susshi-chef

4.8.2.2. Activation

In order to enable OTP authentication, navigate to System / Preferences and select OATH-TOTP as authentication method.

Tip

Authentication Realm is used as label, which allows to distinguish between OTP profiles with this label as unique identifier.

../../_images/authentication_settings_otp.png

After updating the preferences, you will be prompted to scan your personal OTP secret, which will be displayed as QR code.

Warning

If you proceed without scanning the QR code, you can no longer log in to suSSHi Chef.

../../_images/authentication_settings_otp_activated.png

Afterwards, the personal OTP activation codes must be sent to all other administrators. By clicking Inform User (column OTP), your default mail client opens with a notification message including the personal activation code for this administrator.

../../_images/otp_pending_users.png

The next time administrators log in, they will be prompted to enter the activation code they received earlier.

../../_images/otp_activation_code.png

Finally, the personal OTP secret will be created that can be scanned with the preferred authenticator app.

../../_images/otp_activation_qr_code.png

4.8.3. Admin User Reset

During the initialization of your installation, an administrative user named admin was created. If you forgot his password and got locked out, or if you did not save his personal OTP secret, you can reset the admin password and create a new OTP activation token if two-factor authentication is enabled. To do this, you must access the Docker host with a running suSSHi Chef container.

Enter the running container on the Docker host:

$ docker-compose exec susshi-chef bash

Run the following command to reset or recreate the admin user if the default admin user has been deleted in the meanwhile:

$ bundle exec rake chef:reset_admin_user

In case the command completes successfully, the default password has been restored and a new OTP activation token has been created:

Admin User Reset
================
- Password for administrative user 'admin' has been set back to default password 'ChangeMe&1234' - please change password immediately.
- Role has been set back to 'Super-Admin'.
- Your system is configured for OTP, so OTP secret for 'admin' has been reset, too.
-> Please activate OTP with new OTP activation token: 71ddfa4049921accd2e10f1bbf0af519bb52529879e3d2102f1d26d0e17949af

You can now access suSSHi Chef with the default administrative user admin.