Listener Authentication

Overview

Listener authentication allows you to control who can access your streams. Whether you're running a subscription service, private broadcast, or pay-per-listen operation, Mcaster1DNAS v2.5.1-rc1 provides flexible authentication methods to secure your content.

Authentication Methods

Mcaster1DNAS v2.5.1-rc1 supports two primary authentication mechanisms:

HTPASSWD Authentication (YAML)

Configure file-based authentication for simple username/password protection.

# mcaster1.yaml
mount:
  - path: /premium
    stream_name: "Premium Stream"
    authentication:
      type: htpasswd
      filename: /etc/mcaster1/users.htpasswd
      allow_duplicate_users: false  # Prevent multiple connections per username

Configuration Options

• type: Set to "htpasswd"
• filename: Path to htpasswd file (relative to server basedir or absolute)
• allow_duplicate_users: Allow/prevent multiple simultaneous connections with same username (default: false)

Managing Users via Web Interface

Access the authentication management interface at:

http://yourserver:8000/admin/stats.xsl

Look for the lock icon next to authenticated mountpoints. Click to manage users:

• Add Users: Enter username and password, click "Add New User"
• Delete Users: Click delete link next to each user
• View Users: See all configured users for the mountpoint

Note: The htpasswd file will be created automatically when you add the first user.

Managing Users via Command Line

# Create htpasswd file and add user
htpasswd -c /etc/mcaster1/users.htpasswd username

# Add additional users (without -c to avoid overwriting)
htpasswd /etc/mcaster1/users.htpasswd another_user

# Remove user (edit file manually or use htpasswd -D)
htpasswd -D /etc/mcaster1/users.htpasswd username

URL Authentication (YAML)

Integrate with external web services for dynamic authentication.

# mcaster1.yaml
mount:
  - path: /subscription
    stream_name: "Subscription Stream"
    authentication:
      type: url
      auth_url: https://example.com/auth/verify
      timeout: 5  # Timeout in seconds

How URL Authentication Works

When a listener connects, Mcaster1DNAS sends an HTTP GET request to your auth_url with parameters:

https://example.com/auth/verify?mount=/subscription&user=username&pass=password&ip=192.168.1.100&agent=VLC%202.0

Your authentication script should return:

• HTTP 200: Authentication successful, allow connection
• HTTP 401/403: Authentication failed, deny connection
• Any other code: Treated as authentication failure

Example PHP Authentication Script

<?php
// verify.php - Simple authentication example
$mount = $_GET['mount'] ?? '';
$user = $_GET['user'] ?? '';
$pass = $_GET['pass'] ?? '';
$ip = $_GET['ip'] ?? '';

// Check against database, payment processor, etc.
$db = new PDO('mysql:host=localhost;dbname=radio', 'user', 'pass');
$stmt = $db->prepare('SELECT * FROM subscribers WHERE username=? AND password_hash=?');
$stmt->execute([$user, password_hash($pass, PASSWORD_DEFAULT)]);

if ($stmt->rowCount() > 0) {
    // Log access
    $logStmt = $db->prepare('INSERT INTO access_log VALUES (?, ?, ?)');
    $logStmt->execute([$user, $ip, date('Y-m-d H:i:s')]);

    http_response_code(200);
    echo "Authenticated";
} else {
    http_response_code(403);
    echo "Access denied";
}
?>

Use Cases

Subscription Service

Use URL authentication to verify subscribers against a payment processor or membership database. Only active subscribers can listen.

Corporate Internal Streaming

Use HTPASSWD with employee credentials. Distribute usernames/passwords to authorized staff only.

Pay-Per-Listen

URL authentication with payment gateway integration. Verify payment before allowing stream access.

Geographic Restrictions

URL authentication can check IP geolocation and deny access from specific countries or regions.

Time-Limited Access

URL authentication with expiring tokens. Grant temporary access that expires after a set time.

Monitoring Authenticated Streams

Track who's listening to authenticated streams:

http://yourserver:8000/admin/listclients?mount=/premium

Shows usernames of authenticated listeners along with connection times and IP addresses.

Security Best Practices

• Use HTTPS: Encrypt credentials in transit with SSL/TLS
• Strong Passwords: Enforce password complexity requirements
• Limit Duplicate Logins: Set allow_duplicate_users: false to prevent sharing
• Log Access: Monitor who connects and from where
• IP Whitelisting: Combine with firewall rules for additional security
• Regular Audits: Review user accounts and remove inactive users
• Secure Auth Scripts: Validate and sanitize all input in URL authentication handlers

Troubleshooting Authentication

Users Can't Connect

• Verify htpasswd file path is correct and readable
• Check usernames and passwords are correct (case-sensitive)
• Review error.log for authentication failures
• Test URL authentication endpoint manually with curl

Duplicate Login Prevention Not Working

• Ensure allow_duplicate_users: false is set
• Check that users aren't reconnecting with different sessions
• Review timeout settings that may disconnect idle users

URL Authentication Timing Out

• Increase timeout value in configuration
• Optimize authentication script performance
• Check network connectivity to auth server
• Review auth server logs for errors