Basic-Auth Plugin

The Basic-Auth plugin provides HTTP Basic Authentication for Rusty Beam, authenticating users against credentials stored in an HTML configuration file. It supports both plaintext and bcrypt-encrypted passwords.

Overview

The basic-auth plugin is typically the first authentication layer in your plugin pipeline. It validates user credentials from HTTP Basic Authentication headers and sets user metadata for downstream plugins like the authorization plugin.

Key Features

HTTP Basic Authentication: Standard RFC 7617 compliant authentication
Multiple password formats: Supports plaintext and bcrypt encryption
User roles: Associates users with multiple roles for authorization
Configurable realm: Customizable authentication realm
Anonymous access: Can optionally allow unauthenticated requests to pass through
Standard HTTP responses: Returns proper 401 Unauthorized with WWW-Authenticate headers

Configuration

The basic-auth plugin is configured as part of the plugin pipeline in your host configuration:

<li itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/Plugin">
    <span itemprop="library">file://./plugins/basic-auth.so</span>
    <meta itemprop="realm" content="My Protected Site">
    <meta itemprop="authfile" content="file://./auth/users.html">
</li>

Configuration Parameters

Parameter	Type	Required	Default	Description
`authfile`	String (URL)	Yes	-	Path to the HTML file containing user credentials. Supports `file://` URLs.
`realm`	String	No	"Restricted Area"	Authentication realm displayed in browser authentication dialogs.

Credential Configuration

Credentials are defined in an HTML file using the Credential schema. Each credential entry includes:

username: The user's login name
password: The user's password (plaintext or bcrypt hash)
role (optional): User roles for authorization
encryption (optional): Password format ("plaintext" or "bcrypt")

Credential Configuration Example

<!DOCTYPE html>
<html>
<head>
    <title>Authentication Credentials</title>
</head>
<body>
    <table>
        <thead>
            <tr>
                <th>Username</th>
                <th>Password</th>
                <th>Roles</th>
                <th>Encryption</th>
            </tr>
        </thead>
        <tbody>
            <!-- Plaintext password example -->
            <tr itemscope itemtype="https://rustybeam.net/schema/Credential">
                <td itemprop="username">alice</td>
                <td itemprop="password">secret123</td>
                <td>
                    <ul>
                        <li itemprop="role">users</li>
                        <li itemprop="role">editors</li>
                    </ul>
                </td>
                <td itemprop="encryption">plaintext</td>
            </tr>
            
            <!-- Bcrypt password example -->
            <tr itemscope itemtype="https://rustybeam.net/schema/Credential">
                <td itemprop="username">bob</td>
                <td itemprop="password">$2b$10$x5BXBKwhjo.VCl8A/ieIJuqJxASQzArnVaQFcqwJrh5yrJbfHtwTC</td>
                <td>
                    <ul>
                        <li itemprop="role">administrators</li>
                        <li itemprop="role">users</li>
                    </ul>
                </td>
                <td itemprop="encryption">bcrypt</td>
            </tr>
        </tbody>
    </table>
</body>
</html>

Authentication Flow

Client sends request with Authorization: Basic <credentials> header
Plugin decodes Base64-encoded credentials
Looks up username in the configured user file
Validates password based on encryption type
If successful, sets authenticated_user metadata
If failed, returns 401 Unauthorized with WWW-Authenticate header

Metadata Set by Plugin

When authentication succeeds, the plugin sets the following metadata for use by downstream plugins:

Key	Value	Description
`authenticated_user`	Username	The authenticated user's username
`user_roles`	Comma-separated roles	User's assigned roles (e.g., "users,editors")

Plugin Pipeline Placement

Important: The basic-auth plugin should typically be placed:

At or near the beginning of the plugin pipeline
Before any authorization plugins that depend on user authentication
Before content-serving plugins (file-handler, selector-handler)

Typical pipeline order:

1. basic-auth.so      → Authenticates user
2. authorization.so   → Checks permissions
3. selector-handler.so → Processes requests
4. file-handler.so    → Serves files
5. access-log.so      → Logs requests

Anonymous Access

By default, the basic-auth plugin requires authentication for all requests. To allow anonymous access to certain resources:

Configure the authorization plugin to handle anonymous users (username "*")
Use the directory plugin to create separate pipelines for public/private areas
Or modify the plugin configuration to allow passthrough for unauthenticated requests

Password Encryption

Plaintext Passwords

Simple but insecure. Only use for development or testing:

<td itemprop="password">mypassword</td>
<td itemprop="encryption">plaintext</td>

Bcrypt Passwords

Recommended for production. Generate bcrypt hashes using:

# Using Python
python -c "import bcrypt; print(bcrypt.hashpw(b'mypassword', bcrypt.gensalt()).decode())"

# Using htpasswd (Apache tools)
htpasswd -bnBC 10 "" mypassword | tr -d ':\n'

# Using online tools (for testing only!)
# Various bcrypt generators are available online

Then use in configuration:

<td itemprop="password">$2b$10$x5BXBKwhjo.VCl8A/ieIJuqJxASQzArnVaQFcqwJrh5yrJbfHtwTC</td>
<td itemprop="encryption">bcrypt</td>

Security Considerations

HTTPS Required: Basic Authentication sends credentials in Base64 (not encrypted). Always use HTTPS in production.
Password Storage: Use bcrypt for production passwords. Never store plaintext passwords in production.
File Permissions: Ensure auth files are readable only by the server process.
Realm Names: Don't include sensitive information in realm names as they're visible to users.
Brute Force: Consider implementing rate limiting to prevent brute force attacks.

Browser Behavior

Authentication Prompt

When accessing a protected resource, browsers display a dialog:

Title: "Authentication Required"
Message: "The server [hostname] requires a username and password. The server says: [realm]"
Input fields for username and password

Credential Caching

Browsers cache Basic Authentication credentials for the session. Users typically need to close all browser windows to "log out".

Troubleshooting

Common Issues

Issue	Cause	Solution
Always getting 401	Incorrect credentials or auth file path	Check auth file path and user credentials
Can't load auth file	File path or permissions issue	Verify file:// URL and file permissions
Bcrypt validation fails	Incorrect hash or format	Regenerate hash and ensure proper format
No authentication prompt	Plugin not in pipeline or wrong order	Check plugin configuration and order
Authorization not working	Metadata not being set	Ensure basic-auth comes before authorization

Debug Logging

Run the server with -v flag to see authentication details:

./rusty-beam -v config.html

This will show:

Authentication attempts and results
User lookups and role assignments
Metadata being set for downstream plugins

Examples

cURL with Basic Auth

# Using -u flag
curl -u alice:secret123 http://localhost:3000/protected/

# Using Authorization header
curl -H "Authorization: Basic YWxpY2U6c2VjcmV0MTIz" http://localhost:3000/protected/

# Encoding credentials
echo -n "alice:secret123" | base64
# Output: YWxpY2U6c2VjcmV0MTIz

JavaScript Fetch API

// Using headers
fetch('http://localhost:3000/protected/', {
    headers: {
        'Authorization': 'Basic ' + btoa('alice:secret123')
    }
})

// Using credentials in URL (not recommended)
fetch('http://alice:secret123@localhost:3000/protected/')

Integration with Other Plugins

Authorization Plugin

The authorization plugin depends on the authenticated_user metadata set by basic-auth. Always place basic-auth before authorization in the pipeline.

Access-Log Plugin

The access-log plugin can log authenticated usernames. It reads the authenticated_user metadata set by basic-auth.

Directory Plugin

Use the directory plugin to create different authentication requirements for different paths. For example, public areas without basic-auth and private areas with it.