# Device Password Configuration Guide

## Overview

The sync agent supports device passwords for authentication. This allows secure connection to devices that require passwords.

## Configuration Formats

### Format 1: Simple IP (No Password)
```json
{
  "devices": [
    "192.168.1.100",
    "192.168.1.101"
  ]
}
```

### Format 2: Device Object with Password
```json
{
  "devices": [
    {
      "ip": "192.168.1.100",
      "password": "your_device_password"
    }
  ]
}
```

### Format 3: Mixed (Some with password, some without)
```json
{
  "devices": [
    "192.168.1.100",
    {
      "ip": "192.168.1.101",
      "password": "password_for_101"
    },
    "192.168.1.102",
    {
      "ip": "192.168.1.103",
      "password": "password_for_103"
    }
  ]
}
```

## How It Works

### Password Transmission

When the sync agent syncs users to a device, it sends:

```json
POST http://192.168.1.100:4370/iclock/user
{
  "password": "device_password",
  "users": [
    {
      "id": 1,
      "name": "John Doe",
      "user_id": "E001",
      "email": "john@example.com"
    }
  ]
}
```

The device receives the password and can use it to authenticate or validate the request.

## Configuration Steps

### Step 1: Get Device Password
Find the password for each device. This is typically:
- Set in device management interface
- Default password from device documentation
- Custom password you configured

### Step 2: Edit Configuration
Edit `sync_agent_config.json`:

```bash
nano sync_agent_config.json
```

### Step 3: Add Device with Password
Use object format:

```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "devices": [
    {
      "ip": "192.168.1.100",
      "password": "your_device_password"
    }
  ],
  "auto_discover": false
}
```

### Step 4: Save and Test

```bash
python3 sync_agent.py --device 192.168.1.100
```

Expected output:
```
✅ Success: Successfully synced 50 users
```

## Example Configurations

### Example 1: Single Device with Password
```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 10,
  "devices": [
    {
      "ip": "192.168.1.100",
      "password": "SecurePass123"
    }
  ],
  "auto_discover": false
}
```

### Example 2: Multiple Devices with Different Passwords
```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 10,
  "devices": [
    {
      "ip": "192.168.1.100",
      "password": "Office-Password-001"
    },
    {
      "ip": "192.168.1.101",
      "password": "Office-Password-002"
    },
    {
      "ip": "192.168.1.102",
      "password": "Office-Password-003"
    }
  ],
  "auto_discover": false
}
```

### Example 3: Multiple Locations with Different Passwords
```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 10,
  "devices": [
    {
      "ip": "192.168.1.100",
      "password": "Location-A-Pass"
    },
    {
      "ip": "192.168.1.101",
      "password": "Location-A-Pass"
    },
    {
      "ip": "10.0.0.50",
      "password": "Location-B-Pass"
    },
    {
      "ip": "10.0.0.51",
      "password": "Location-B-Pass"
    }
  ],
  "auto_discover": false
}
```

### Example 4: Auto-Discovery + Manual with Password
```json
{
  "cloud_url": "https://your-adms.cloud.com",
  "sync_interval_minutes": 10,
  "devices": [
    {
      "ip": "192.168.1.50",
      "password": "special_device_password"
    }
  ],
  "auto_discover": true,
  "network_prefix": "192.168.1"
}
```

In this config:
- Device `192.168.1.50` will use the specified password
- Other discovered devices will sync without password

## Security Considerations

### Best Practices

1. **Use Strong Passwords**
   - Use complex passwords for production devices
   - Mix uppercase, lowercase, numbers, symbols

2. **Protect Configuration File**
   - Do not commit `sync_agent_config.json` to git
   - Use `.gitignore` to exclude it
   - Restrict file permissions: `chmod 600 sync_agent_config.json`

3. **Use Environment Variables** (Optional)
   - For extra security, store passwords in environment variables:
   ```bash
   export DEVICE_PASSWORD_100="your_password"
   ```

4. **Change Default Passwords**
   - Don't use default device passwords
   - Change on all new devices immediately

5. **Regular Audits**
   - Review device passwords periodically
   - Update if someone with access leaves

### File Permissions

```bash
# Make config file only readable by owner
chmod 600 sync_agent_config.json

# On Linux/Mac
# Restrict to current user only
chown $USER:$USER sync_agent_config.json
```

## Troubleshooting

### Password Not Working

**Symptom:** "HTTP 401" or "Authentication failed"

**Solutions:**
1. Verify password is correct
2. Check device password requirements
3. Ensure password doesn't have special URL characters (or URL-encode it)

**Test:**
```bash
# Test device connection with password
python3 sync_agent.py --device 192.168.1.100
```

### Device Not Accepting Users

**Symptom:** Device syncs but users don't appear

**Check:**
1. Verify device password is correct
2. Check device logs for sync errors
3. Test device directly via web UI

### Mixed Sync Results

**Symptom:** Some devices sync, others fail

**Check:**
1. Verify each device's password separately
2. Check network connectivity for failing devices
3. Review logs for error messages

## Device Password Policies

Different devices may have different password requirements:

### ZKTeco Devices
- Typically 6-16 characters
- Alphanumeric + some special characters
- Set in device management interface

### Standard HTTP Devices
- Can be any length
- Check device documentation

### Custom Devices
- Verify password format with device admin
- Test before deploying widely

## Migration

### From No Passwords to Passwords

1. Update all device configurations
2. Edit `sync_agent_config.json`
3. Change devices from strings to objects:

```json
// Before
"devices": ["192.168.1.100", "192.168.1.101"]

// After
"devices": [
  {
    "ip": "192.168.1.100",
    "password": "password_100"
  },
  {
    "ip": "192.168.1.101",
    "password": "password_101"
  }
]
```

4. Test each device
5. Restart sync agent

## Monitoring

### Check Sync Logs

```bash
# View recent logs
tail -f logs/sync_agent_*.log

# Search for password-related errors
grep -i password logs/sync_agent_*.log

# Search for authentication errors
grep -i "401\|auth\|failed" logs/sync_agent_*.log
```

### Expected Success Log

```
Syncing to 192.168.1.100...
✅ Successfully synced 50 users
📤 Reported sync status to cloud
```

## Advanced Usage

### Dynamic Passwords

For rotating passwords, create wrapper script:

```bash
#!/bin/bash
# get_password.sh

case $1 in
  192.168.1.100) echo "password_100" ;;
  192.168.1.101) echo "password_101" ;;
  *) echo "" ;;
esac
```

Then modify sync_agent.py to call this script (advanced).

### Encrypted Passwords

For production, consider:
1. Using OS keystore (system secrets)
2. Encrypted configuration file
3. External secrets management

## Support

For device password issues:
1. Verify device password in device UI
2. Test directly: `curl -X POST http://192.168.1.100:4370/iclock/user -d '{"password":"...","users":[]}'`
3. Check device documentation
4. Review sync agent logs

---

**Need help?** See README.md or QUICK_START.md