Set Up Basic Authentication

Overview

F5 NGINX Management Suite uses NGINX as a front-end proxy and for user access. By default, NGINX Management Suite uses basic authentication, which means you need to send your username and password with each request to confirm your identity. When logging in to NGINX Management Suite for the first time, use the default admin account and password. After that, you can create additional user accounts. Adding users and setting passwords are explained below.

Security Consideration
While convenient, basic authentication is less secure than other methods: credentials are sent as base64-encoded text, which is not secure encryption. If your data gets intercepted, the encoding is easily reversible. If you use NGINX Plus for your front-end proxy, consider switching to OpenID Connect (OIDC) for authentication. For production environments, we strongly recommend OIDC.

Default Admin User

When you install NGINX Management Suite, a default admin user is created with a randomly generated password that’s displayed in the installation output.

You can change the default admin password by running the script that’s provided or manually editing the /etc/nms/nginx/.htpasswd file. For instructions, see the Set User Passwords section below.

The admin user is associated with an admin role that grants full permissions for all modules and features. You can delete the admin user, but only after assigning the admin role to another user. The admin role cannot be deleted and must be assigned to at least one user.

Create New Users

Note:
Please note that the web interface does not support adding user passwords directly. Once you’ve created new users, refer to the following steps to set user passwords.

To add users, take the following steps:

  1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in.

  2. Select the Settings (gear) icon in the upper-right corner.

  3. On the left menu, select Users.

  4. Select Create.

  5. On the Create User form, enter the details for the user:

    • Username: A unique username to identify the user.
    • Email: The user’s email address.
    • First Name: The user’s first name.
    • Last Name: The user’s last name.
    • Description: An optional brief description of the user.

  6. In the Roles list, select one or more roles to assign to the user.

    Learn more about roles and how to create them in the Getting Started with RBAC topic.

  7. (Required for Basic Auth) Add each user’s username and password to the /etc/nms/nginx/.htpasswd file on the NGINX Management Suite server. You can choose to run a script or make the changes manually. Refer to the Set User Passwords topic for instructions.

See Also:
Refer to the “Provision Users and Groups with SCIM” topic for instructions on automating user and group creation using the SCIM API.

Set User Passwords

Before you begin:
Before you can set users’ passwords, you need to create users in NGINX Management Suite. Once you’ve created the users, select from the following options to set their passwords.

(Recommended) Use the Provided Script

You can use the basic_passwords.sh script to add a user’s encrypted password to the /etc/nms/nginx/.htpasswd file on the NGINX Management Suite server.

Note:
The basic_passwords.sh script requires the OpenSSL package. We strongly recommend OpenSSL v1.1.1 or later.

To change a user’s password with the basic_passwords.sh script:

  1. Open an SSH connection to your NGINX Management Suite host and log in.

  2. Run the basic_passwords.sh script, providing the username you want to update and the desired password. Make sure to enclose the password in single quotation marks.

    sudo bash /etc/nms/scripts/basic_passwords.sh <username> '<desired password>'

    For example:

    sudo bash /etc/nms/scripts/basic_passwords.sh johndoe 'jelly22fi$h'

Manually Set User Passwords

To manually set user passwords:

  1. Open the /etc/nms/nginx/.htpasswd file on the NGINX Management Suite host and add the username and password for each user.
  2. Save the changes to the file.
See Also:
Refer to the documentation Restricting Access with HTTP Basic Auth for detailed instructions on working with the password file.

Making API Requests with Basic Authentication

To use basic authentication for API requests, include your base64-encoded credentials as a “Basic” token in the “Authorization” header. To set up base64-encoded credentials, run the following command:

echo -n <username>:<password> | base64

Now you can include those credentials with your API request. Here’s how you can do it with curl:

curl -X GET "https://<NMS_FQDN>/api/platform/<API_VERSION>/systems" -H "Authorization: Basic <base64 encoded credentials>"

In this example, replace <NMS_FQDN> with your NGINX Management Suite’s fully qualified domain name and <API_VERSION> with the API version you want to use.


Security Consideration
You can use basic authentication for API requests, but you should be cautious: credentials are sent as base64-encoded text, which is not secure encryption. If your data gets intercepted, the encoding is easily reversible. In production environments where security is critical, we recommend switching to OpenID Connect (OIDC).

Ending Your Browser Session

With basic authentication, NGINX Management Suite doesn’t offer a “Log Out” button. To end your session, just close the web browser you’re using.

When you close the browser, it voids the authentication token or session cookie tied to your account. This step is crucial for securing your account and blocking unauthorized access to NGINX Management Suite.

Last modified August 22, 2024