User Management

User Management

RedAmon includes a built-in authentication system with two roles: Admin and Standard. Users log in with email and password, and the admin controls who can access the platform.

---

First-Time Setup: Creating the Admin

When you run ./redamon.sh install (or ./redamon.sh up / ./redamon.sh update for the first time), the script automatically detects that no admin account exists and prompts you in the terminal:

[WARN] No admin user found. Let's create one.

  Admin name: Your Name
  Admin email: admin@example.com
  Admin password: ********
  Confirm password: ********

Field	What it is
Admin name	Display name shown in the UI header and user list. Can be anything (e.g. Admin, your real name).
Admin email	The email you use to sign in at http://localhost:3000/login. Must be unique.
Admin password	Minimum 4 characters. Stored as a bcrypt hash in the PostgreSQL database.

After this step, open http://localhost:3000 and you will see the login page.

---

Logging In

Navigate to http://localhost:3000. If you are not logged in, you are redirected to the login page.

Enter the email and password you configured during setup and click Sign In. After a successful login, you land on the Red Zone (/graph) page. The welcome/disclaimer modal still appears on first login, as before.

Sessions last 7 days. After expiry, you are redirected back to the login page.

---

Roles

RedAmon has two user roles:

Admin

Admins have full control over the platform:

• Switch users -- use the user dropdown in the header to switch between any user, including users without a password. This works the same way as the pre-auth user selector.
• Create users -- from the Users page (/settings/users), create new accounts with a name, email, optional password, and role.
• Set or change passwords -- set or reset any user's password without knowing their current one.
• Delete users -- remove any user except themselves. Deleting a user also deletes all their projects, conversations, and settings.
• Change roles -- promote a standard user to admin or demote an admin to standard.
• Access the Users page -- the "Users" link in the header navigation is visible only to admins.

Standard

Standard users have limited permissions:

• Log in -- only if the admin has set a password for them.
• Use the app -- create projects, run scans, interact with the AI agent, and view reports within their own scope.
• Change their own password -- via the user dropdown > "Change Password". Requires entering the current password.
• Cannot switch users -- the user dropdown shows only their own name and a logout button.
• Cannot access user management -- the Users page is not visible or accessible.

Passwordless Users (Backward Compatibility)

Users that existed before the auth system was added (or users created by an admin without setting a password) cannot log in directly. They are "managed" users that only an admin can switch to via the user dropdown. This preserves full backward compatibility with existing databases.

---

Managing Users (Admin)

Admins manage users from the Users page, accessible via the "Users" link in the header navigation or at /settings/users.

Creating a User

1. Click Create User
2. Fill in the form:
   • Name (required) -- display name
   • Email (required) -- must be unique, used for login
   • Password (optional) -- if left empty, the user is passwordless (admin-switchable only, cannot log in)
   • Role -- standard (default) or admin
3. Click Create User

Setting or Changing a Password

1. In the user table, click Set Password next to any user
2. Enter the new password and confirm it
3. Click Set Password

This works for both users who already have a password (replaces it) and passwordless users (enables them to log in).

Deleting a User

1. Click the Delete button next to a user
2. Confirm the deletion

Warning: Deleting a user permanently removes all their projects, reconnaissance data, graph nodes, AI agent conversations, settings, and reports. This cannot be undone.

You cannot delete your own account.

---

Changing Your Own Password

All users (admin and standard) can change their own password:

1. Click your name/avatar in the top-right corner of the header
2. Select Change Password from the dropdown
3. Enter your current password, then the new password (twice)
4. Click Change Password

---

Resetting a Forgotten Password

If an admin forgets their password and cannot log in, reset it from the terminal:

./redamon.sh reset-password

You will be prompted for the user's email and a new password. This works for any user, not just admins.

---

How Authentication Works

• JWT tokens -- login creates a signed JWT stored in an httpOnly cookie (not accessible to JavaScript). Sessions expire after 7 days.
• Password hashing -- passwords are hashed with bcrypt (cost factor 12) before storage. The hash is never exposed through the API.
• Service-to-service auth -- internal Docker services (agent, recon, scanners) use a shared INTERNAL_API_KEY header to call the webapp API without user authentication. This key is auto-generated during install.
• Secrets -- AUTH_SECRET (JWT signing key) and INTERNAL_API_KEY are auto-generated into .env on first install. Do not share or commit this file.

---

Next Steps

Once you have an account and are logged in, you are ready to create your first project.