Initial Commit
This commit is contained in:
@@ -0,0 +1,233 @@
|
||||
# How to Use Long-Lived Tokens
|
||||
|
||||
## Why Use Long-Lived Tokens?
|
||||
|
||||
✅ **More Secure** - Password is never stored on device
|
||||
✅ **Convenient** - No repeated logins (token valid for months/years)
|
||||
✅ **Revocable** - Can be invalidated from server without changing password
|
||||
✅ **Best Practice** - Official Music Assistant apps use this method
|
||||
|
||||
## Creating a Long-Lived Token
|
||||
|
||||
### Method 1: Via Web Interface (Recommended)
|
||||
|
||||
1. **Open Music Assistant in your browser:**
|
||||
```
|
||||
https://musicassistant-app.hanold.online
|
||||
```
|
||||
|
||||
2. **Login with your username and password**
|
||||
|
||||
3. **Go to Settings:**
|
||||
- Click the gear icon (⚙️) in the top right
|
||||
- Select "Users" or "User Management"
|
||||
|
||||
4. **Create a Token:**
|
||||
- Find your user account
|
||||
- Click "Create Token" or "Generate Long-Lived Access Token"
|
||||
- Give it a name (e.g., "iPhone App")
|
||||
- Set expiration (optional - can be "Never")
|
||||
|
||||
5. **Copy the Token:**
|
||||
- Token will be displayed ONCE
|
||||
- Copy it immediately!
|
||||
- **Important:** You can't see it again after closing the dialog
|
||||
|
||||
6. **Use in App:**
|
||||
- Open the iOS app
|
||||
- Select "Long-Lived Token" as login method
|
||||
- Paste the token
|
||||
- Enter server URL
|
||||
- Click "Connect"
|
||||
|
||||
### Method 2: Via API (Advanced)
|
||||
|
||||
If you need to automate token creation:
|
||||
|
||||
```bash
|
||||
# Step 1: Login to get short-lived token
|
||||
curl -X POST https://musicassistant-app.hanold.online/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'
|
||||
|
||||
# Response: {"access_token": "eyJ..."}
|
||||
|
||||
# Step 2: Create long-lived token (requires WebSocket connection)
|
||||
# This is complex - use the web interface instead!
|
||||
```
|
||||
|
||||
## Using the Token in the App
|
||||
|
||||
### Option A: Long-Lived Token (Recommended)
|
||||
|
||||
1. **In LoginView, select "Long-Lived Token"**
|
||||
2. **Enter server URL:**
|
||||
```
|
||||
https://musicassistant-app.hanold.online
|
||||
```
|
||||
(No port number needed if using reverse proxy on 443!)
|
||||
|
||||
3. **Paste your token:**
|
||||
- Token looks like: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
|
||||
- Very long string (100+ characters)
|
||||
- Contains dots (.)
|
||||
|
||||
4. **Click "Connect"**
|
||||
|
||||
### Option B: Username & Password
|
||||
|
||||
1. **In LoginView, select "Username & Password"**
|
||||
2. **Enter credentials**
|
||||
3. **App will create a long-lived token automatically**
|
||||
4. **Token is saved in Keychain for future use**
|
||||
|
||||
## Token Security
|
||||
|
||||
### Stored Securely
|
||||
- Token is saved in iOS Keychain
|
||||
- Encrypted by the system
|
||||
- Not accessible to other apps
|
||||
- Survives app reinstalls
|
||||
|
||||
### Token Protection
|
||||
- Never share your token
|
||||
- Treat it like a password
|
||||
- Revoke if compromised
|
||||
- Create device-specific tokens
|
||||
|
||||
### Revoking a Token
|
||||
|
||||
If your token is compromised:
|
||||
|
||||
1. **Go to Music Assistant Settings → Users**
|
||||
2. **Find the token in the list**
|
||||
3. **Click "Revoke" or "Delete"**
|
||||
4. **Create a new token**
|
||||
5. **Update the app with new token**
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Invalid Token" Error
|
||||
|
||||
**Causes:**
|
||||
- Token was revoked on server
|
||||
- Token expired
|
||||
- Token not copied completely
|
||||
- Server URL mismatch
|
||||
|
||||
**Solution:**
|
||||
- Generate a new token
|
||||
- Copy entire token (check for truncation)
|
||||
- Verify server URL matches
|
||||
|
||||
### "Connection Failed" Error
|
||||
|
||||
**Causes:**
|
||||
- Server URL incorrect
|
||||
- Server offline
|
||||
- Network issues
|
||||
- Reverse proxy misconfiguration
|
||||
|
||||
**Solution:**
|
||||
- Test server URL in browser
|
||||
- Check server is running
|
||||
- Verify network connectivity
|
||||
- Check reverse proxy logs
|
||||
|
||||
### Token Not Working After Server Upgrade
|
||||
|
||||
**Cause:**
|
||||
- Tokens may be invalidated during MA upgrades
|
||||
|
||||
**Solution:**
|
||||
- Generate a new token
|
||||
- Update in app
|
||||
|
||||
## Comparison: Token vs Credentials
|
||||
|
||||
| Aspect | Long-Lived Token | Username & Password |
|
||||
|--------|-----------------|---------------------|
|
||||
| Security | ✅ Better | ⚠️ Password stored temporarily |
|
||||
| Convenience | ✅ No repeated logins | ❌ Manual login needed |
|
||||
| Revocability | ✅ Easy to revoke | ⚠️ Must change password |
|
||||
| Setup | ⚠️ Initial setup required | ✅ Simple |
|
||||
| Recommended | ✅ Yes | ⚠️ For first setup only |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use Long-Lived Tokens** for production
|
||||
2. **Create device-specific tokens** (one per iPhone/iPad)
|
||||
3. **Name tokens clearly** (e.g., "iPhone 15 Pro")
|
||||
4. **Set reasonable expiration** (e.g., 1 year)
|
||||
5. **Rotate tokens periodically** (every 6-12 months)
|
||||
6. **Revoke unused tokens** to reduce security risk
|
||||
|
||||
## Token Format
|
||||
|
||||
A Music Assistant token looks like:
|
||||
```
|
||||
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMTIzIiwiaWF0IjoxNjc4ODg1MjAwLCJleHAiOjE5OTQyNDUyMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
|
||||
```
|
||||
|
||||
**Structure:**
|
||||
- Three parts separated by dots (.)
|
||||
- Base64-encoded JSON
|
||||
- Signed by server
|
||||
- Contains user ID and expiration
|
||||
|
||||
**Do NOT:**
|
||||
- Manually edit the token
|
||||
- Share it publicly
|
||||
- Commit to git repositories
|
||||
- Include in screenshots
|
||||
|
||||
## Integration with App
|
||||
|
||||
The app handles tokens automatically:
|
||||
|
||||
```swift
|
||||
// Token is saved securely
|
||||
service.authManager.saveToken(serverURL: url, token: token)
|
||||
|
||||
// Token is used for all API calls
|
||||
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
|
||||
|
||||
// Token persists across app restarts
|
||||
// Loaded automatically from Keychain
|
||||
```
|
||||
|
||||
## Advantages Over Password
|
||||
|
||||
1. **Granular Control**
|
||||
- Different tokens for different devices
|
||||
- Revoke one without affecting others
|
||||
|
||||
2. **Audit Trail**
|
||||
- See which tokens are active
|
||||
- Track last used time
|
||||
- Monitor token usage
|
||||
|
||||
3. **No Password Exposure**
|
||||
- Password never leaves browser
|
||||
- Token can't be used to change password
|
||||
- Limited scope of damage if compromised
|
||||
|
||||
4. **Performance**
|
||||
- No password hashing on each request
|
||||
- Direct token validation
|
||||
- Faster authentication
|
||||
|
||||
## Summary
|
||||
|
||||
**For Regular Use:**
|
||||
→ Use **Long-Lived Token** method
|
||||
→ Create token via web interface
|
||||
→ Copy/paste into app
|
||||
→ Store in Keychain
|
||||
→ Enjoy seamless authentication!
|
||||
|
||||
**For Initial Setup:**
|
||||
→ Use **Username & Password** once
|
||||
→ App creates token automatically
|
||||
→ Switch to token method for security
|
||||
→ Revoke password-created tokens if needed
|
||||
Reference in New Issue
Block a user