d9ef2f0d5b
Some checks failed
Build and Test / Validate Setup (push) Has been cancelled
Build and Test / Build (darwin-amd64) (push) Has been cancelled
Build and Test / Build (darwin-arm64) (push) Has been cancelled
Build and Test / Build (linux-amd64) (push) Has been cancelled
Build and Test / Build (windows-amd64) (push) Has been cancelled
Build and Test / Build (linux-arm64) (push) Has been cancelled
Build and Test / Security Audit (push) Has been cancelled
Build and Test / Package Results (push) Has been cancelled
Build and Test / Quality Gate (push) Has been cancelled
Nightly Build / Check for Changes (push) Has been cancelled
Nightly Build / Validate Setup (push) Has been cancelled
Nightly Build / Nightly Build (darwin-amd64) (push) Has been cancelled
Nightly Build / Nightly Build (darwin-arm64) (push) Has been cancelled
Nightly Build / Nightly Build (linux-amd64) (push) Has been cancelled
Nightly Build / Nightly Build (windows-amd64) (push) Has been cancelled
Nightly Build / Nightly Build (linux-arm64) (push) Has been cancelled
Nightly Build / Create Nightly Pre-release (push) Has been cancelled
Nightly Build / Notify Build Status (push) Has been cancelled
Nightly Build / Nightly Maintenance (push) Has been cancelled
- Bump all 18 plugins from 0.110.0 to 0.111.0
- Update rust-toolchain.toml channel to 1.93.1 (nu 0.111.0 requires ≥1.91.1)
Fixes:
- interprocess pin =2.2.x → ^2.3.1 in nu_plugin_mcp, nu_plugin_nats, nu_plugin_typedialog
(required by nu-plugin-core 0.111.0)
- nu_plugin_typedialog: BackendType::Web initializer — add open_browser: false field
- nu_plugin_auth: implement missing user_info_to_value helper referenced in tests
Scripts:
- update_all_plugins.nu: fix [package].version update on minor bumps; add [dev-dependencies]
pass; add nu-plugin-test-support to managed crates
- download_nushell.nu: rustup override unset before rm -rf on nushell dir replace;
fix unclosed ) in string interpolation
211 lines
5.0 KiB
Markdown
211 lines
5.0 KiB
Markdown
# nu_plugin_auth
|
|
|
|
Nushell plugin for provisioning platform authentication.
|
|
|
|
## Overview
|
|
|
|
This plugin provides native Nushell commands for authenticating with the provisioning platform's control center. It integrates with the JWT authentication system and supports MFA workflows.
|
|
|
|
## Features
|
|
|
|
- **JWT Authentication** - Login with username/password, receive access and refresh tokens
|
|
- **MFA Support** - TOTP and WebAuthn second-factor authentication
|
|
- **Session Management** - List and manage active authentication sessions
|
|
- **Secure Token Storage** - Store credentials in system keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
|
|
- **Token Verification** - Verify token validity and decode claims
|
|
|
|
## Commands
|
|
|
|
### `auth login`
|
|
|
|
Login to provisioning platform with JWT authentication.
|
|
|
|
**Syntax:**
|
|
|
|
```nushell
|
|
nushell
|
|
auth login <username> [password] [--url <control-center-url>] [--save]
|
|
```
|
|
|
|
**Examples:**
|
|
|
|
```nushell
|
|
nushell
|
|
# Login with password prompt (secure)
|
|
auth login admin
|
|
|
|
# Login with password in command (less secure)
|
|
auth login admin mypassword
|
|
|
|
# Login to custom control center URL
|
|
auth login admin --url http://control.example.com:8081
|
|
|
|
# Login and save credentials to keyring
|
|
auth login admin --save
|
|
```
|
|
|
|
### `auth logout`
|
|
|
|
Logout from provisioning platform (revoke tokens).
|
|
|
|
**Syntax:**
|
|
|
|
```nushell
|
|
nushell
|
|
auth logout [--all]
|
|
```
|
|
|
|
**Examples:**
|
|
|
|
```nushell
|
|
nushell
|
|
# Logout from current session
|
|
auth logout
|
|
|
|
# Logout from all active sessions
|
|
auth logout --all
|
|
```
|
|
|
|
### `auth verify`
|
|
|
|
Verify current authentication token.
|
|
|
|
**Syntax:**
|
|
|
|
```nushell
|
|
nushell
|
|
auth verify [--token <jwt-token>]
|
|
```
|
|
|
|
**Examples:**
|
|
|
|
```nushell
|
|
nushell
|
|
# Verify stored authentication token
|
|
auth verify
|
|
|
|
# Verify specific token
|
|
auth verify --token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
```
|
|
|
|
### `auth sessions`
|
|
|
|
List active authentication sessions.
|
|
|
|
**Syntax:**
|
|
|
|
```nushell
|
|
nushell
|
|
auth sessions [--active]
|
|
```
|
|
|
|
**Examples:**
|
|
|
|
```nushell
|
|
nushell
|
|
# List all sessions
|
|
auth sessions
|
|
|
|
# List only active sessions
|
|
auth sessions --active
|
|
```
|
|
|
|
## Installation
|
|
|
|
### Build from source
|
|
|
|
```nushell
|
|
bash
|
|
cd provisioning/core/plugins/nushell-plugins/nu_plugin_auth
|
|
cargo build --release
|
|
```
|
|
|
|
### Register with Nushell
|
|
|
|
```nushell
|
|
nushell
|
|
plugin add target/release/nu_plugin_auth
|
|
plugin use auth
|
|
```
|
|
|
|
### Using justfile (recommended)
|
|
|
|
```nushell
|
|
bash
|
|
# From nushell-plugins directory
|
|
just install-plugin nu_plugin_auth
|
|
|
|
# Or using shortcut
|
|
just i nu_plugin_auth
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The plugin uses the following defaults:
|
|
|
|
- **Control Center URL**: `http://localhost:8081`
|
|
- **Keyring Service**: `provisioning-platform`
|
|
- **Token Storage**: System keyring (platform-dependent)
|
|
|
|
Override defaults using command flags:
|
|
|
|
```nushell
|
|
nushell
|
|
# Use custom control center URL
|
|
auth login admin --url https://control.production.example.com
|
|
```
|
|
|
|
## Authentication Flow
|
|
|
|
1. **Login**: User provides credentials → Plugin sends request to control center → Receives JWT tokens
|
|
2. **Token Storage**: Access and refresh tokens stored in system keyring (if `--save` flag used)
|
|
3. **Authenticated Requests**: Plugin retrieves tokens from keyring → Includes in API requests
|
|
4. **Token Refresh**: Automatic refresh using refresh token when access token expires
|
|
5. **Logout**: Revoke tokens at control center → Remove from keyring
|
|
|
|
## Security Considerations
|
|
|
|
- **Keyring Storage**: Tokens stored in OS-provided secure storage (Keychain, Credential Manager, Secret Service)
|
|
- **Password Prompts**: Interactive password prompts avoid exposing passwords in shell history
|
|
- **Token Expiration**: Access tokens expire after 15 minutes (configurable at control center)
|
|
- **Refresh Tokens**: Valid for 7 days (configurable at control center)
|
|
- **MFA Support**: Plugin supports TOTP and WebAuthn second-factor authentication
|
|
|
|
## Integration with Control Center
|
|
|
|
This plugin communicates with the provisioning platform's control center REST API:
|
|
|
|
- **POST /api/auth/login** - Login with credentials
|
|
- **POST /api/auth/logout** - Revoke tokens
|
|
- **POST /api/auth/verify** - Verify token validity
|
|
- **GET /api/auth/sessions** - List active sessions
|
|
|
|
See control center API documentation for details: `provisioning/platform/control-center/README.md`
|
|
|
|
## Development Status
|
|
|
|
**Version**: 0.1.0 (Initial structure)
|
|
|
|
**Implementation Progress**:
|
|
|
|
- ✅ Plugin structure created (Agente 1)
|
|
- ⏳ Login command implementation (Agente 2)
|
|
- ⏳ Logout command implementation (Agente 3)
|
|
- ⏳ Verify command implementation (Agente 4)
|
|
- ⏳ Sessions command implementation (Agente 5)
|
|
- ⏳ Test suite implementation (Agente 6)
|
|
|
|
## License
|
|
|
|
MIT License - See LICENSE file for details
|
|
|
|
## Contributing
|
|
|
|
This plugin is part of the provisioning platform project. See main project documentation for contribution guidelines.
|
|
|
|
## Related Documentation
|
|
|
|
- **Control Center API**: `provisioning/platform/control-center/README.md`
|
|
- **JWT Authentication**: `docs/architecture/JWT_AUTH_IMPLEMENTATION.md`
|
|
- **MFA Implementation**: `docs/architecture/MFA_IMPLEMENTATION_SUMMARY.md`
|
|
- **Security System**: `docs/architecture/ADR-009-security-system-complete.md` |