keywarden/docs/user-guide.md

User Guide

This guide covers everyday usage of Keywarden for all authenticated users. For administrative tasks (server management, access assignments, etc.), see the Admin Guide.

Logging In

Navigate to your Keywarden instance in a web browser and enter your username and password.

• If MFA is enabled on your account, you will be prompted for a TOTP code after entering your password.
• If your account is locked due to too many failed login attempts, wait for the lockout period to expire or ask an administrator to unlock it.
• If you were invited via email, use the invitation link to set your password before logging in.

Dashboard

The dashboard provides an overview of your environment:

• Key Count — Number of SSH keys you own
• Server Count — Servers you have access to (admins/owners see all servers)
• Group Count — Server groups (admins/owners see all groups)
• Assignment Count — Access assignments related to you
• Recent Keys — Latest SSH keys
• Recent Audit Log — Your recent activity (admins see global activity)
• Recent Deployments — Latest key deployment results

SSH Key Management

Generating Keys

1. Navigate to Keys → Generate Key
2. Fill in the form:
   • Name: A descriptive name for the key (e.g., "Production Deploy Key")
   • Key Type: Choose between:
     • Ed25519 (recommended) — Fast, secure, compact. 256-bit.
     • RSA 2048 — Widely compatible
     • RSA 4096 — Maximum RSA security
     • Ed448 — 224-bit security level (experimental)
   • Comment: Optional comment embedded in the public key
3. Click Generate

The private key is encrypted with AES-256-GCM and stored in the database. It never touches the filesystem in plaintext.

Importing Keys

1. Navigate to Keys → Import Key
2. Enter a name for the key
3. Paste the private key (PEM format) into the text area
4. Click Import

Keywarden automatically detects the key type (RSA, Ed25519, Ed448) and extracts the public key and fingerprint.

Viewing Keys

The Keys page lists all your SSH keys with:

• Name, type, key size
• SHA-256 fingerprint
• Creation date

Admins and owners see all keys in the system, grouped by owner.

Downloading Keys

From the key list, you can download:

• Public Key — For deployment to servers
• Private Key — Decrypted and downloaded (use with caution)

Deleting Keys

Click the delete button next to a key. This permanently removes both the public and encrypted private key from the database.

Note: Deleting a key from Keywarden does not remove it from servers where it was previously deployed.

My Access

Navigate to My Access to see all access assignments that grant you access to servers:

• Target — Server or server group
• System User — The Linux user account on the target server
• SSH Key — Which of your keys is deployed
• Sudo — Whether sudo privileges are granted
• Status — Current sync status (pending, synced, failed)
• Initial Password — If a system user was created for you, the initial password is shown here

This is a read-only view. Only administrators can create, modify, or delete access assignments.

User Settings

Navigate to Settings to manage your account:

Theme

Choose between:

• Auto — Follows your system/browser preference
• Light — Always light mode
• Dark — Always dark mode

Password Change

Change your password. The new password must comply with the configured password policy (displayed on the form).

Two-Factor Authentication (MFA)

Enabling MFA

1. Go to Settings → Two-Factor Authentication
2. Click Enable MFA
3. Scan the QR code with an authenticator app (Google Authenticator, Authy, etc.)
4. Enter the 6-digit code from your app to confirm
5. MFA is now active for your account

Disabling MFA

Click Disable MFA in settings. This is only available if the administrator has not enforced MFA system-wide.

If MFA is enforced by the administrator, you must set it up before you can access any other page.

Email Notifications

If email is configured, you can enable Login Notifications. Every time someone logs into your account, you'll receive an email with:

• IP address
• Timestamp
• User agent (browser)

Profile Picture

Upload a profile picture (avatar) that is displayed next to your name in the navigation. Supported formats: JPEG, PNG, GIF, WebP. Maximum size is limited by the server's request size limit.

Audit Log

Navigate to Audit to view the activity log:

• Regular users see their own activity
• Admins see activity from all non-owner users
• Owners see all activity

The audit log records every significant action including logins, key operations, deployments, settings changes, and administrative actions.

Forced Password Change

If an administrator flags your account for a mandatory password change, you will be redirected to the password change page on every request until you set a new password. This typically happens:

• After your initial account creation
• If an admin resets your password
• If there's a security concern

Invitation Flow

If you receive an invitation email:

1. Click the invitation link
2. You'll see a registration page with your pre-assigned username
3. Choose a password that meets the password policy
4. Confirm the password
5. Click Set Password
6. You can now log in with your username and new password