231 lines
7.6 KiB
Markdown
231 lines
7.6 KiB
Markdown
# Sensitive Variables - UI User Guide
|
|
|
|
## Overview
|
|
|
|
Roster now supports marking variables as **sensitive** to store their values securely in GNOME Keyring instead of plain text. This guide explains how to use this feature in the UI.
|
|
|
|
## Features
|
|
|
|
### 🔒 Lock Icon Toggle
|
|
|
|
Each variable in the Environments dialog has a lock icon button:
|
|
- **Unlocked** (🔓 `channel-insecure-symbolic`) - Variable is stored in plain JSON
|
|
- **Locked** (🔒 `channel-secure-symbolic`) - Variable is stored encrypted in GNOME Keyring
|
|
|
|
### Visual Indicators
|
|
|
|
1. **Lock Icon Color/State**
|
|
- Inactive (gray): Non-sensitive variable
|
|
- Active (accent color): Sensitive variable
|
|
|
|
2. **Variable Name Styling**
|
|
- Regular variables: Normal text
|
|
- Sensitive variables: Colored with accent color and bold weight
|
|
|
|
3. **Value Entry Fields**
|
|
- Regular variables: Show plain text
|
|
- Sensitive variables: Show bullets (••••••) instead of text
|
|
|
|
## How to Use
|
|
|
|
### Step 1: Open Environments Dialog
|
|
|
|
1. Select a project from the sidebar
|
|
2. Click the "Environments" button in the header bar
|
|
3. The dialog shows a table with:
|
|
- Rows: Variable names
|
|
- Columns: Environment values
|
|
|
|
### Step 2: Create Variables
|
|
|
|
If you haven't already:
|
|
1. Click the **"Add Variable"** button (bottom-left)
|
|
2. Enter a variable name (e.g., `api_key`)
|
|
3. Click "Add"
|
|
|
|
### Step 3: Mark Variable as Sensitive
|
|
|
|
**Option A: Before Entering Values (Recommended)**
|
|
1. Find the variable row in the table
|
|
2. Click the **lock icon** next to the variable name
|
|
3. Icon changes from 🔓 to 🔒
|
|
4. Now enter your secret values - they go directly to keyring
|
|
|
|
**Option B: After Entering Values (Migration)**
|
|
1. If you already entered sensitive values in plain text
|
|
2. Click the lock icon to mark as sensitive
|
|
3. Values are automatically moved from JSON to GNOME Keyring
|
|
4. JSON file now shows empty placeholders
|
|
|
|
### Step 4: Enter Sensitive Values
|
|
|
|
1. Click in the value entry field for any environment
|
|
2. Type your secret value
|
|
3. You'll see bullets (••••••) instead of text
|
|
4. Value is automatically saved to GNOME Keyring
|
|
|
|
### Step 5: Use in Requests
|
|
|
|
Sensitive variables work exactly like regular variables:
|
|
```
|
|
URL: {{base_url}}/users
|
|
Headers:
|
|
Authorization: Bearer {{api_key}}
|
|
```
|
|
|
|
When you send the request, values are automatically retrieved from the keyring and substituted.
|
|
|
|
## UI Walkthrough
|
|
|
|
### Example: Storing a GitHub Token
|
|
|
|
**Before (Insecure - in plain JSON):**
|
|
```
|
|
Variables Table:
|
|
┌─────────────┬──────────────────┬──────────────────┐
|
|
│ Variable │ Production │ Development │
|
|
├─────────────┼──────────────────┼──────────────────┤
|
|
│ base_url 🔓 │ api.github.com │ api.dev.local │
|
|
│ token 🔓 │ ghp_abc123... │ ghp_dev456... │ ← VISIBLE!
|
|
└─────────────┴──────────────────┴──────────────────┘
|
|
```
|
|
|
|
**After (Secure - in GNOME Keyring):**
|
|
```
|
|
Variables Table:
|
|
┌─────────────┬──────────────────┬──────────────────┐
|
|
│ Variable │ Production │ Development │
|
|
├─────────────┼──────────────────┼──────────────────┤
|
|
│ base_url 🔓 │ api.github.com │ api.dev.local │
|
|
│ token 🔒 │ •••••••••••• │ •••••••••••• │ ← HIDDEN!
|
|
└─────────────┴──────────────────┴──────────────────┘
|
|
```
|
|
|
|
## Tooltips
|
|
|
|
Hover over the lock icon to see:
|
|
- **Unlocked**: "Not sensitive (stored in JSON) - Click to mark as sensitive"
|
|
- **Locked**: "Sensitive (stored in keyring) - Click to make non-sensitive"
|
|
|
|
## Making a Variable Non-Sensitive Again
|
|
|
|
If you accidentally marked a variable as sensitive:
|
|
1. Click the lock icon again (🔒 → 🔓)
|
|
2. Values are moved from keyring back to JSON
|
|
3. You can now see the values in plain text
|
|
|
|
**Warning**: Only do this if the variable truly doesn't contain secrets!
|
|
|
|
## Viewing Secrets in GNOME Keyring
|
|
|
|
Want to verify your secrets are stored?
|
|
1. Open **"Passwords and Keys"** application (Seahorse)
|
|
2. Look under **"Login"** keyring
|
|
3. Find entries labeled: `Roster: ProjectName/EnvironmentName/VariableName`
|
|
|
|
Example:
|
|
```
|
|
Login Keyring
|
|
└─ Roster: My API Project/Production/api_key
|
|
└─ Roster: My API Project/Development/api_key
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### ✅ DO Mark as Sensitive:
|
|
- `api_key` - API keys
|
|
- `secret_key` - Secret keys
|
|
- `password` - Passwords
|
|
- `token` - Bearer tokens, OAuth tokens
|
|
- `client_secret` - OAuth client secrets
|
|
- `private_key` - Private keys
|
|
- Any variable containing credentials
|
|
|
|
### ❌ DON'T Mark as Sensitive:
|
|
- `base_url` - API endpoints
|
|
- `env` - Environment names
|
|
- `region` - Cloud regions
|
|
- `timeout` - Timeout values
|
|
- `version` - API versions
|
|
- Any non-secret configuration
|
|
|
|
### Workflow Tips
|
|
|
|
1. **Create variables first, then mark as sensitive**
|
|
- Add variable
|
|
- Click lock icon
|
|
- Enter values (they go directly to keyring)
|
|
|
|
2. **Use descriptive names**
|
|
- ✅ `stripe_secret_key`
|
|
- ❌ `key1`
|
|
|
|
3. **Group related variables**
|
|
```
|
|
base_url 🔓
|
|
api_key 🔒
|
|
api_secret 🔒
|
|
timeout 🔓
|
|
```
|
|
|
|
4. **Audit regularly**
|
|
- Check which variables are marked as sensitive
|
|
- Ensure all secrets are locked (🔒)
|
|
|
|
## Troubleshooting
|
|
|
|
### Q: I clicked the lock but it didn't work
|
|
**A:** Check the application logs. The keyring might be locked. Unlock it with your login password.
|
|
|
|
### Q: Can I see my secret values after marking as sensitive?
|
|
**A:** The UI shows bullets (••••••) for security. To view:
|
|
- Temporarily unlock (click 🔒 → 🔓)
|
|
- Or use "Passwords and Keys" app to view in keyring
|
|
|
|
### Q: What happens if I delete a sensitive variable?
|
|
**A:** Both the JSON entry AND the keyring secret are deleted automatically.
|
|
|
|
### Q: What happens if I rename a sensitive variable?
|
|
**A:** The keyring secret is automatically renamed. No data is lost.
|
|
|
|
### Q: What happens if I delete an environment?
|
|
**A:** All keyring secrets for that environment are deleted automatically.
|
|
|
|
### Q: What happens if I delete a project?
|
|
**A:** ALL keyring secrets for that project are deleted automatically.
|
|
|
|
## Security Notes
|
|
|
|
- ✅ Secrets are encrypted with your login password
|
|
- ✅ Automatically unlocked when you log in
|
|
- ✅ Protected by OS-level security
|
|
- ✅ Same security as browser passwords, WiFi passwords, SSH keys
|
|
- ⚠️ Non-sensitive variables are still in plain JSON
|
|
- ⚠️ Mark variables as sensitive BEFORE entering secret values
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
- **Tab**: Move between value fields
|
|
- **Enter**: Confirm value (auto-saved)
|
|
- **Escape**: Close dialog
|
|
|
|
## Visual Design
|
|
|
|
The UI uses the following visual cues:
|
|
|
|
1. **Lock Icon State**
|
|
- Gray/inactive = Plain JSON storage
|
|
- Colored/active = Encrypted keyring storage
|
|
|
|
2. **Variable Name Color**
|
|
- Sensitive variables have accent color and bold font
|
|
|
|
3. **Password Entry**
|
|
- Sensitive variable values show as bullets
|
|
- Same UX as password fields throughout GNOME
|
|
|
|
4. **Consistent with GNOME HIG**
|
|
- Follows GNOME Human Interface Guidelines
|
|
- Familiar patterns (lock icon = security)
|
|
- Accessible and keyboard-navigable
|