Set Up Basic Authentication
Learn how to manage user access in NGINX Management Suite using basic authentication with NGINX as a front-end proxy. This guide covers first-time login, creating additional users, and setting passwords.
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.
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.
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.
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.
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:
In a web browser, go to the FQDN for your NGINX Management Suite host and log in.
Select the Settings (gear) icon in the upper-right corner.
On the left menu, select Users.
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.
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.
(Required for Basic Auth) Add each user’s username and password to the
/etc/nms/nginx/.htpasswdfile 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.
Refer to the “Provision Users and Groups with SCIM” topic for instructions on automating user and group creation using the SCIM API.
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.
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.
basic_passwords.shscript requires the OpenSSL package. We strongly recommend OpenSSL v1.1.1 or later.
To change a user’s password with the
Open an SSH connection to your NGINX Management Suite host and log in.
basic_passwords.shscript, 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>'
sudo bash /etc/nms/scripts/basic_passwords.sh johndoe 'jelly22fi$h'
To manually set user passwords:
- Open the
/etc/nms/nginx/.htpasswdfile on the NGINX Management Suite host and add the username and password for each user.
- Save the changes to the file.
Refer to the documentation Restricting Access with HTTP Basic Auth for detailed instructions on working with the password file.
To use basic authentication for API requests, include your base64-encoded credentials as a “Basic” token in the “Authorization” header. Here’s how you can do it with cURL:
curl -X GET "https://<NMS_FQDN>/api/platform/<API_VERSION>/systems" -H "Authorization: Basic YWRtaW..."
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.
-H "Authorization: Basic YWRtaW..." sets the “Authorization” header with your base64-encoded username and password. Replace
YWRtaW... with your actual encoded credentials.
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).
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.