be62c8701a
- Add `show-arguments` recipe documenting all version update commands - Add `complete-update-interactive` recipe for manual confirmations - Maintain `complete-update` as automatic mode (no prompts) - Update `update-help` to reference new recipes and modes - Document 7-step workflow and step-by-step differences Changes: - complete-update: Automatic mode (recommended for CI/CD) - complete-update-interactive: Interactive mode (with confirmations) - show-arguments: Complete documentation of all commands and modes - Both modes share same 7-step workflow with different behavior in Step 4
264 lines
4.9 KiB
Markdown
264 lines
4.9 KiB
Markdown
# nu_plugin_auth Quick Reference
|
|
|
|
**Version**: 0.1.0
|
|
**Status**: Login/Logout Commands Implemented
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
```nushell
|
|
# Build plugin
|
|
cargo build --release -p nu_plugin_auth
|
|
|
|
# Register with Nushell
|
|
plugin add target/release/nu_plugin_auth
|
|
plugin use nu_plugin_auth
|
|
```
|
|
|
|
---
|
|
|
|
## Login Command
|
|
|
|
### Basic Usage
|
|
```nushell
|
|
# Interactive login (password prompt)
|
|
auth login admin
|
|
|
|
# Login with password
|
|
auth login admin mypassword
|
|
|
|
# Login and save to keyring
|
|
auth login admin --save
|
|
|
|
# Custom Control Center URL
|
|
auth login admin --url http://control.example.com:8081
|
|
```
|
|
|
|
### Flags
|
|
| Flag | Short | Type | Description | Default |
|
|
|------|-------|------|-------------|---------|
|
|
| `--url` | - | String | Control Center URL | `http://localhost:8081` |
|
|
| `--save` | - | Switch | Save tokens to keyring | `false` |
|
|
|
|
### Output
|
|
```nushell
|
|
{
|
|
success: true,
|
|
user: {
|
|
id: "user-123",
|
|
username: "admin",
|
|
email: "admin@example.com",
|
|
roles: ["admin", "developer"]
|
|
},
|
|
expires_in: 900,
|
|
token_saved: true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Logout Command
|
|
|
|
### Basic Usage
|
|
```nushell
|
|
# Logout current user
|
|
auth logout
|
|
|
|
# Logout specific user
|
|
auth logout --user admin
|
|
|
|
# Logout all sessions
|
|
auth logout --all
|
|
```
|
|
|
|
### Flags
|
|
| Flag | Short | Type | Description | Default |
|
|
|------|-------|------|-------------|---------|
|
|
| `--user` | `-u` | String | Username | Current system user |
|
|
| `--url` | - | String | Control Center URL | `http://localhost:8081` |
|
|
| `--all` | `-a` | Switch | Logout all sessions | `false` |
|
|
|
|
### Output
|
|
```nushell
|
|
{
|
|
success: true,
|
|
message: "Logged out successfully",
|
|
user: "admin"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## MFA Commands (Bonus)
|
|
|
|
### TOTP Enrollment
|
|
```nushell
|
|
# Enroll in TOTP
|
|
auth mfa enroll totp
|
|
|
|
# Enroll for specific user
|
|
auth mfa enroll totp --user alice
|
|
```
|
|
|
|
**Output**: QR code in terminal + secret + backup codes
|
|
|
|
### TOTP Verification
|
|
```nushell
|
|
# Verify TOTP code
|
|
auth mfa verify --code 123456
|
|
|
|
# Verify for specific user
|
|
auth mfa verify --code 123456 --user alice
|
|
```
|
|
|
|
### WebAuthn Enrollment
|
|
```nushell
|
|
# Enroll WebAuthn (YubiKey, Touch ID)
|
|
auth mfa enroll webauthn
|
|
```
|
|
|
|
---
|
|
|
|
## Security Features
|
|
|
|
- ✅ **OS Keyring**: Secure credential storage (Keychain, libsecret, Credential Manager)
|
|
- ✅ **No Echo**: Password input not visible in terminal
|
|
- ✅ **HTTPS**: TLS with rustls (no OpenSSL)
|
|
- ✅ **JWT Tokens**: RS256-signed access + refresh tokens
|
|
- ✅ **Token Revocation**: Server-side blacklist on logout
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
```nushell
|
|
# No active session
|
|
auth logout
|
|
# Error: No active session: No token found
|
|
|
|
# Invalid credentials
|
|
auth login baduser wrongpass
|
|
# Error: Login failed: HTTP 401 - Invalid credentials
|
|
|
|
# Network error
|
|
auth login admin --url http://invalid:8081
|
|
# Error: HTTP request failed: connection refused
|
|
```
|
|
|
|
---
|
|
|
|
## Platform Support
|
|
|
|
| Platform | Credential Storage |
|
|
|----------|-------------------|
|
|
| macOS | Keychain |
|
|
| Linux | Secret Service (libsecret/gnome-keyring) |
|
|
| Windows | Credential Manager |
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
| Endpoint | Method | Description |
|
|
|----------|--------|-------------|
|
|
| `/auth/login` | POST | Authenticate and get tokens |
|
|
| `/auth/logout` | POST | Revoke access token |
|
|
| `/auth/verify` | GET | Verify token validity |
|
|
| `/auth/sessions` | GET | List active sessions |
|
|
| `/mfa/enroll/{type}` | POST | Enroll in MFA |
|
|
| `/mfa/verify` | POST | Verify MFA code |
|
|
|
|
---
|
|
|
|
## Workflow Examples
|
|
|
|
### Standard Login/Logout
|
|
```nushell
|
|
# Login
|
|
auth login admin --save
|
|
|
|
# Do work...
|
|
|
|
# Logout
|
|
auth logout
|
|
```
|
|
|
|
### Multiple Users
|
|
```nushell
|
|
# Login as different users
|
|
auth login alice --save
|
|
auth login bob --save
|
|
|
|
# Logout specific user
|
|
auth logout --user alice
|
|
```
|
|
|
|
### CI/CD Integration
|
|
```nushell
|
|
# Non-interactive login
|
|
let token = auth login $env.CI_USER $env.CI_PASS | get user.id
|
|
|
|
# Use token for operations...
|
|
|
|
# Cleanup
|
|
auth logout --user $env.CI_USER
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "No token found" error
|
|
**Cause**: No active session or keyring not accessible
|
|
**Fix**: Login again with `--save` flag
|
|
|
|
### "HTTP request failed"
|
|
**Cause**: Control Center not running or wrong URL
|
|
**Fix**: Check Control Center status and `--url` flag
|
|
|
|
### "Login failed: HTTP 401"
|
|
**Cause**: Invalid credentials
|
|
**Fix**: Verify username and password
|
|
|
|
### Keyring access denied
|
|
**Cause**: OS permission issue
|
|
**Fix**: Grant keychain/keyring access to plugin binary
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
### Build Commands
|
|
```bash
|
|
# Check code
|
|
cargo check -p nu_plugin_auth
|
|
|
|
# Build debug
|
|
cargo build -p nu_plugin_auth
|
|
|
|
# Build release
|
|
cargo build --release -p nu_plugin_auth
|
|
|
|
# Run tests
|
|
cargo test -p nu_plugin_auth
|
|
```
|
|
|
|
### Plugin Location
|
|
- Source: `provisioning/core/plugins/nushell-plugins/nu_plugin_auth/`
|
|
- Binary: `target/release/nu_plugin_auth`
|
|
|
|
---
|
|
|
|
## Related Commands (Future)
|
|
|
|
- `auth verify` - Verify current token
|
|
- `auth sessions` - List all sessions
|
|
- `auth whoami` - Show current user
|
|
- `auth refresh` - Refresh expired token
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-10-09
|
|
**Documentation**: See `LOGIN_LOGOUT_IMPLEMENTATION.md` for complete details
|