User Management

Overview

User Management in NetStacks Controller provides centralized control over who can access the platform and what they can do once authenticated. Every person who logs into the Controller — whether through local credentials, LDAP, or OIDC — is represented as a user object with a unique username, optional email, display name, and one or more assigned roles.

Users are the foundation of NetStacks role-based access control (RBAC). Each user is assigned roles that grant specific permissions such as managing devices, deploying stacks, accessing the credential vault, or administering the platform itself. The user model supports multiple authentication sources so that you can mix local accounts for service integrations with SSO accounts for your engineering team.

Key capabilities of user management include:

• Creating local users with hashed passwords or linking to external auth sources (LDAP/OIDC)
• Assigning one or more roles to control feature access through granular permissions
• Disabling or enabling accounts without deleting user history
• Resetting passwords and revoking active sessions for immediate access control
• Automatic SSH credential creation for new users to simplify device access onboarding
• Full audit trail of all user management actions

How It Works

User data is stored in PostgreSQL with the following key fields: id (UUID),org_id (organization scope), username (unique within the org),email, display_name, auth_source (local, ldap, or oidc),password_hash (for local users), is_active, created_at, and last_login.

Password Handling

Local user passwords are hashed using bcrypt before storage. Passwords are never stored in plaintext or transmitted in API responses. When a password is changed via the admin API, the new hash replaces the old one, and the admin can optionally propagate the password change to the user's personal SSH device credentials in the vault.

Session and Token Management

When a user logs in, the Controller issues a JWT access token (short-lived) and a refresh token (longer-lived, stored in the database). Active sessions are tracked against the organization's license seat count. Admins can revoke all active sessions for a specific user, which invalidates all their refresh tokens and forces re-authentication on every connected client.

Role Assignment

Users are linked to roles through a many-to-many relationship. A user can hold multiple roles simultaneously, and the effective permission set is the union of all permissions from all assigned roles. Role assignments can be managed individually (add/remove one role) or in bulk (set all roles at once, replacing any previous assignments).

Auto-Created Credentials

When a new local user is created, the Controller automatically generates a personal SSH password credential in the encrypted vault. This credential uses the same username and password as the user account, giving the new user immediate access to devices that accept password-based SSH authentication. The credential is stored encrypted (AES-256-GCM) and the user is granted view access to their own credential.

Step-by-Step Guide

Creating a New User

1. Navigate to Admin → Users in the Controller web interface.
2. Click Add User in the top-right corner.
3. Enter a unique username (e.g., jsmith).
4. Optionally enter an email (e.g., jsmith@dc1.example.net) and display name (e.g., John Smith).
5. Select the authentication source: Local (enter a password), LDAP (user authenticates against directory), or OIDC (user authenticates via SSO).
6. For local users, enter a strong password that meets your organization's policy.
7. Assign one or more roles (e.g., Operator, Viewer). See Roles & Permissions for details.
8. Click Create. The user can now log in, and a personal SSH credential is auto-created in the vault.

Editing a User

1. Navigate to Admin → Users and find the user in the list. Use the search bar to filter by username, email, or display name.
2. Click the user row to open their profile.
3. Update email, display name, or role assignments as needed.
4. Click Save to apply changes.

Disabling and Enabling Users

1. Open the user's profile from Admin → Users.
2. Toggle the Active status to disabled.
3. The user is immediately prevented from logging in. Existing sessions remain valid until they expire or are explicitly revoked.
4. To re-enable, toggle the status back to active. The user can log in again with their existing credentials.

Resetting a User's Password

1. Open the user's profile and enter a new password in the password field.
2. Optionally check Update device credential to also change the password on the user's personal SSH credential in the vault.
3. Click Save. The password hash is updated immediately.

Revoking Active Sessions

1. Open the user's profile from Admin → Users.
2. Click Revoke Sessions to invalidate all active refresh tokens.
3. The user is forced to re-authenticate on their next token refresh. Access tokens already in flight remain valid until they expire (typically minutes).

Deleting a User

1. Open the user's profile and click Delete User.
2. Confirm the deletion. This permanently removes the user account.
3. Audit log entries referencing this user are retained for compliance.

Code Examples

All user management endpoints are under /api/admin/users and require a valid JWT bearer token with the appropriate permission (users.view for read operations, users.* for write operations).

Create a New User

curl -X POST https://netstacks.dc1.example.net/api/admin/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jsmith",
    "email": "jsmith@dc1.example.net",
    "display_name": "John Smith",
    "password": "S3cur3P@ssw0rd!"
  }'

List Users with Search

curl "https://netstacks.dc1.example.net/api/admin/users?limit=25&offset=0&search=smith" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "users": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "org_id": "org-uuid-here",
      "username": "jsmith",
      "email": "jsmith@dc1.example.net",
      "display_name": "John Smith",
      "auth_source": "local",
      "created_at": "2025-03-15T10:30:00Z",
      "last_login": "2025-03-15T14:22:00Z"
    }
  ],
  "total": 1
}

Get User with Roles

curl https://netstacks.dc1.example.net/api/admin/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN"

Disable a User

curl -X PUT https://netstacks.dc1.example.net/api/admin/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Assign Roles to a User

# Set all roles at once (replaces existing assignments)
curl -X PUT https://netstacks.dc1.example.net/api/admin/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/roles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_ids": [
      "role-operator-uuid",
      "role-viewer-uuid"
    ]
  }'

Delete a User

curl -X DELETE https://netstacks.dc1.example.net/api/admin/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN"

Questions & Answers

How do I create a new user in NetStacks?

Navigate to Admin → Users, click Add User, fill in the username, email, and password (for local accounts), assign roles, and click Create. You can also create users programmatically via the REST API by POSTing to /api/admin/users with a valid admin token.

Can I import users from LDAP automatically?

Yes. When LDAP authentication is enabled with the auto_create_users setting set to true, users who authenticate successfully via LDAP are automatically created in NetStacks on their first login. Their profile information (username, email, display name) is populated from LDAP attributes based on the configured attribute mapping. See Authentication for LDAP setup details.

How do I revoke a user's active sessions?

Open the user's profile in Admin → Users and clickRevoke Sessions. This invalidates all stored refresh tokens for that user. Active access tokens remain valid until they expire (typically a few minutes), after which the user must re-authenticate. For immediate lockout, also disable the user account.

What happens when I disable a user?

A disabled user cannot log in or obtain new tokens. However, any access tokens already issued remain valid until they expire. To force an immediate disconnect, combine disabling the account with revoking their active sessions. The user's data, roles, and audit history are preserved. Re-enabling the account restores full access.

How do I reset a user's password?

Open the user's profile and enter a new password in the password field. Optionally check the Update device credential option to also update the password on the user's personal SSH credential in the vault. This ensures the user's device access stays in sync with their account password.

Can a user have multiple roles?

Yes. Users can be assigned multiple roles simultaneously. The effective permission set is the union of all permissions across all assigned roles. For example, a user with both the Operator and Viewer roles has all permissions from both. Use the PUT /api/admin/users/:id/roles endpoint to set all roles at once.

What is the auto-created SSH credential?

When you create a local user, NetStacks automatically generates a personal SSH password credential in the encrypted vault using the same username and password. This lets the user immediately connect to network devices that accept SSH password authentication without additional credential setup.

Troubleshooting

User Cannot Log In

• Check that the user's is_active status is true. Disabled accounts cannot authenticate.
• Verify the correct auth source. If the user was created as an LDAP user, local password login will not work.
• Check the LDAP/OIDC provider status if the user authenticates externally. Connection failures to the directory server prevent authentication.
• Review the audit log for failed login events (auth.login_failed) which include the reason for failure.

Password Reset Not Working

• Password resets only apply to local auth source users. LDAP and OIDC users manage their passwords through their identity provider.
• If using the Update device credential option, ensure the vault master key is properly configured. Credential encryption failures are logged but do not block the password change.

LDAP User Not Appearing

• LDAP users are created on first successful login, not on a sync schedule. The user must authenticate at least once before they appear in the user list.
• Verify that auto_create_users is enabled in the LDAP configuration under Authentication settings.
• Check the LDAP user filter and base DN to ensure the user's entry is within the search scope.

Session Expired Unexpectedly

• Access tokens have a short TTL (configurable, typically 15–30 minutes). If the client fails to refresh in time, the session expires.
• Check if an admin revoked sessions for the user, which invalidates all refresh tokens.
• Verify the license seat count. If the organization has exceeded its seat limit, new sessions may be rejected.

“Cannot update your own user profile” Error

• The API prevents admins from modifying their own account to avoid accidental self-lockout. Have another admin make changes to your profile.

Related Features

• Roles & Permissions — Define the permission sets assigned to users through roles.
• Authentication (LDAP/OIDC) — Configure external identity providers for SSO and directory-based authentication.
• Audit Logs — Review user management actions including account creation, role changes, and session revocations.
• Credential Vault — Manage the encrypted vault where auto-created user SSH credentials are stored.
• API Authentication — Understand how JWT tokens, refresh flows, and bearer authentication work for API access.