ldap-rest 0.1.4 → 0.1.6

package/docs/usage/plugins/auth/hmac.md

@@ -0,0 +1,293 @@
+# HMAC Authentication
+
+HMAC-SHA256 request signing authentication for backend services (Registration Service, admin panel backend, cloudery, etc.).
+
+## Configuration
+
+### Basic Configuration
+
+```bash
+--plugin core/auth/hmac \
+--auth-hmac "registration-service:secret-key-minimum-32-chars:Registration Service" \
+--auth-hmac "cloudery:another-secret-key-long-enough:Cloudery Backend"
+```
+
+**Environment Variable:**
+
+```bash
+DM_AUTH_HMAC="registration-service:secret-key-minimum-32-chars:Registration Service,cloudery:another-secret-key-long-enough:Cloudery Backend"
+```
+
+**Syntax:** `service-id:secret:name`
+
+- **service-id**: Service identifier (e.g., `registration-service`, `cloudery`)
+- **secret**: Shared secret for HMAC (minimum 32 characters recommended)
+- **name**: Descriptive service name (can contain colons)
+
+### Advanced Configuration
+
+```bash
+--auth-hmac-window 120000  # Time window in milliseconds (default: 120000 = 2 minutes)
+```
+
+**Environment Variable:**
+
+```bash
+DM_AUTH_HMAC_WINDOW=120000  # Default: 120000ms (2 minutes)
+```
+
+- **window**: Maximum time difference (in milliseconds) between server and client timestamp
+- Prevents replay attacks by rejecting requests with timestamps outside the window
+
+## How It Works
+
+### Request Signing Process
+
+1. **Client calculates signature:**
+
+   ```
+   signature = HMAC-SHA256(
+     secret,
+     "METHOD|PATH|timestamp|body-hash"
+   )
+   ```
+
+   Where:
+   - `METHOD`: HTTP method (GET, POST, PATCH, DELETE, PUT, etc.)
+   - `PATH`: Request path with query string (e.g., `/api/v1/ldap/users?filter=active`)
+   - `timestamp`: Unix timestamp in milliseconds (e.g., `1698765432000`)
+   - `body-hash`: SHA256(request_body) for POST/PATCH/PUT, empty string for GET/DELETE/HEAD
+
+2. **Client sends Authorization header:**
+
+   ```
+   Authorization: HMAC-SHA256 service-id:timestamp:signature
+   ```
+
+3. **Server validates:**
+   - Extracts `service-id`, `timestamp`, and `signature` from header
+   - Verifies timestamp is within configured window (prevents replay attacks)
+   - Retrieves service secret using `service-id`
+   - Recalculates signature using same method
+   - Compares signatures using constant-time comparison (prevents timing attacks)
+   - Rejects if mismatch or timestamp expired
+
+4. **On success:**
+   - Sets `req.user` to service name
+   - Allows request to proceed
+
+## Usage
+
+### Manual Request Example
+
+```bash
+# Example: GET request
+SERVICE_ID="registration-service"
+SECRET="secret-key-minimum-32-chars"
+METHOD="GET"
+PATH="/api/v1/ldap/users"
+TIMESTAMP=$(date +%s000)  # Unix timestamp in milliseconds
+
+# Calculate body hash (empty for GET)
+BODY_HASH=""
+
+# Create signing string
+SIGNING_STRING="${METHOD}|${PATH}|${TIMESTAMP}|${BODY_HASH}"
+
+# Calculate HMAC-SHA256 signature
+SIGNATURE=$(echo -n "$SIGNING_STRING" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)
+
+# Make request
+curl -H "Authorization: HMAC-SHA256 ${SERVICE_ID}:${TIMESTAMP}:${SIGNATURE}" \
+  http://localhost:8081${PATH}
+```
+
+### POST Request with Body
+
+```bash
+SERVICE_ID="registration-service"
+SECRET="secret-key-minimum-32-chars"
+METHOD="POST"
+PATH="/api/v1/ldap/users"
+TIMESTAMP=$(date +%s000)
+BODY='{"uid":"user1","mail":"user1@example.com"}'
+
+# Calculate body hash
+BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 | cut -d' ' -f2)
+
+# Create signing string
+SIGNING_STRING="${METHOD}|${PATH}|${TIMESTAMP}|${BODY_HASH}"
+
+# Calculate signature
+SIGNATURE=$(echo -n "$SIGNING_STRING" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)
+
+# Make request
+curl -X POST \
+  -H "Authorization: HMAC-SHA256 ${SERVICE_ID}:${TIMESTAMP}:${SIGNATURE}" \
+  -H "Content-Type: application/json" \
+  -d "$BODY" \
+  http://localhost:8081${PATH}
+```
+
+### Browser Client
+
+The HMAC client library is available as an npm module export:
+
+```bash
+npm install ldap-rest
+```
+
+```typescript
+import { HmacAuthClient } from 'ldap-rest/browser-shared-utils-hmac';
+
+const client = new HmacAuthClient({
+  serviceId: 'registration-service',
+  secret: 'secret-key-minimum-32-chars',
+});
+
+// Automatic authentication with HMAC signature
+const response = await client.get('/api/v1/ldap/users');
+const users = await response.json();
+
+// POST with automatic body hashing and signing
+await client.post('/api/v1/ldap/users', {
+  uid: 'user1',
+  mail: 'user1@example.com',
+});
+
+// Other methods: put, patch, delete
+await client.put('/api/v1/ldap/users/user1', { mail: 'new@example.com' });
+await client.delete('/api/v1/ldap/users/user1');
+```
+
+**Manual signature generation:**
+
+```typescript
+import { generateHmacSignature } from 'ldap-rest/browser-shared-utils-hmac';
+
+const signature = await generateHmacSignature(
+  'secret-key-minimum-32-chars',
+  'GET',
+  '/api/v1/ldap/users',
+  Date.now(),
+  undefined // no body for GET
+);
+
+const authHeader = `HMAC-SHA256 registration-service:${Date.now()}:${signature}`;
+```
+
+## Use Cases
+
+- **Backend Services**: Service-to-service authentication (Registration Service, admin panels, etc.)
+- **Microservices**: Secure inter-service communication
+- **Webhooks**: Verify request authenticity and integrity
+- **API Gateways**: Backend service authentication
+- **Cloudery Integration**: Secure communication with cloudery backend
+- **Automated Services**: CI/CD, monitoring, backup services
+
+## Security Considerations
+
+- **Secret Strength**: Use secrets of at least 32 characters (64+ recommended)
+- **Secret Storage**: Store secrets securely (encrypted configuration, environment variables, secret managers)
+- **HTTPS Required**: Always use HTTPS to protect signatures in transit
+- **Time Synchronization**: Ensure server and client clocks are synchronized (NTP recommended)
+- **Replay Protection**: Time window prevents replay attacks (adjust `auth-hmac-window` as needed)
+- **Constant-Time Comparison**: Signature validation uses `timingSafeEqual` to prevent timing attacks
+- **Secret Rotation**: Rotate secrets periodically for enhanced security
+- **Body Integrity**: Body hash ensures request payload hasn't been tampered with
+- **Path Integrity**: Full path (including query parameters) is signed
+
+## Security Features
+
+1. **Replay Attack Prevention**: Timestamp validation with configurable window
+2. **Timing Attack Protection**: Constant-time signature comparison
+3. **Request Integrity**: Body hash ensures payload integrity
+4. **Path Integrity**: Query parameters included in signature
+5. **Multi-Service Support**: Isolated secrets per service
+6. **Clock Drift Tolerance**: Configurable time window (default 2 minutes)
+
+## Advantages Over Other Methods
+
+| Feature                   | HMAC             | Token       | TOTP             |
+| ------------------------- | ---------------- | ----------- | ---------------- |
+| **Request Integrity**     | Yes (body hash)  | No          | No               |
+| **Replay Protection**     | Yes (timestamp)  | No          | Yes (time-based) |
+| **Signature Per Request** | Yes              | No (static) | Yes (30s codes)  |
+| **Body Tampering Detect** | Yes              | No          | No               |
+| **Path/Query Protection** | Yes              | No          | No               |
+| **Setup Complexity**      | Medium           | Simple      | Simple           |
+| **Best For**              | Backend services | Simple APIs | MFA, user auth   |
+
+## Comparison with Standards
+
+This implementation is similar to:
+
+- **AWS Signature V4**: Similar approach but simpler (AWS is more complex with canonicalization)
+- **HTTP Message Signatures (RFC 9421)**: IETF standard for HTTP signatures
+- **HMAC-Based Authentication**: Industry-standard pattern for service authentication
+
+Our approach provides a good balance between security and simplicity:
+
+- Simpler than AWS Signature V4 (easier to implement)
+- More secure than static tokens (request-specific signatures)
+- Better integrity than TOTP (includes body and path hashing)
+- Standard cryptography (HMAC-SHA256)
+
+## Troubleshooting
+
+**Problem:** 401 Unauthorized despite correct signature
+
+**Solutions:**
+
+1. Verify service-id matches exactly (case-sensitive)
+2. Verify secret is correctly configured (minimum 32 characters)
+3. Check system clock synchronization (use NTP: `ntpdate -q pool.ntp.org`)
+4. Increase `--auth-hmac-window` if experiencing timing issues
+5. Verify Authorization header format: `HMAC-SHA256 service-id:timestamp:signature`
+6. Check server logs for specific error messages
+7. Ensure timestamp is in milliseconds, not seconds
+8. Verify body hash calculation (must match exactly)
+
+**Problem:** Timestamp outside allowed window
+
+**Solutions:**
+
+1. Synchronize clocks using NTP
+2. Increase `--auth-hmac-window` (default: 120000ms = 2 minutes)
+3. Check if timestamp is in milliseconds (not seconds)
+4. Verify both server and client are using same timezone reference (UTC)
+
+**Problem:** Signature mismatch
+
+**Solutions:**
+
+1. Verify signing string format: `METHOD|PATH|timestamp|body-hash`
+2. Ensure METHOD is uppercase (GET, POST, etc.)
+3. Include full path with query parameters
+4. For POST/PATCH/PUT: verify body hash is SHA256(JSON.stringify(body))
+5. For GET/DELETE/HEAD: body-hash must be empty string
+6. Ensure secret is exactly the same on client and server
+7. Use hex encoding for signature (lowercase)
+8. Check for trailing whitespace in secret
+
+**Problem:** Warning about short secrets
+
+**Solutions:**
+
+1. Use secrets of at least 32 characters
+2. Recommended: 64+ characters for enhanced security
+3. Generate secure random secrets:
+   ```bash
+   openssl rand -hex 32  # 64-character hex string
+   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+   ```
+
+**Debug Example:**
+
+```bash
+# Enable debug logging
+DM_LOG_LEVEL=debug npm start
+
+# Check signing string in logs
+# Expected format: "GET|/api/v1/ldap/users|1698765432000|"
+```

package/docs/usage/plugins/auth/llng.md

@@ -0,0 +1,99 @@
+# LemonLDAP::NG Authentication
+
+Integration with [LemonLDAP::NG](https://lemonldap-ng.org/) (LLNG) Web SSO solution.
+
+## Configuration
+
+```bash
+--plugin core/auth/llng \
+--llng-ini /etc/lemonldap-ng/lemonldap-ng.ini
+```
+
+**Environment Variable:**
+
+```bash
+DM_LLNG_INI="/etc/lemonldap-ng/lemonldap-ng.ini"
+```
+
+## Prerequisites
+
+1. **LemonLDAP::NG Handler**: The `lemonldap-ng-handler` npm package (optional dependency)
+2. **LLNG Configuration**: Valid `lemonldap-ng.ini` file
+3. **Virtual Host Configuration**: LDAP-Rest must be configured as a protected application in LLNG
+
+## How It Works
+
+1. Uses the LemonLDAP::NG Handler to validate requests
+2. Extracts user identity from `Lm-Remote-User` header
+3. Sets `req.user` to authenticated username
+4. Inherits all LLNG authorization rules and features
+
+## Installation
+
+Install the optional dependency:
+
+```bash
+npm install lemonldap-ng-handler
+```
+
+## LLNG Configuration
+
+Configure LDAP-Rest as a protected virtual host in LemonLDAP::NG:
+
+```apache
+# In LLNG Manager: Virtual Hosts > api.example.com
+<VirtualHost *:443>
+  ServerName api.example.com
+
+  # LemonLDAP::NG Handler
+  PerlHeaderParserHandler Lemonldap::NG::Handler::ApacheMP2
+
+  # Proxy to LDAP-Rest
+  ProxyPass / http://localhost:8081/
+  ProxyPassReverse / http://localhost:8081/
+</VirtualHost>
+```
+
+## Use Cases
+
+- **Enterprise SSO**: Centralized authentication for multiple applications
+- **Advanced Authorization**: Fine-grained access control using LLNG rules
+- **Session Management**: Centralized session handling
+- **Multi-Factor Authentication**: MFA support through LLNG
+
+## Example: LLNG Authorization Rules
+
+Configure access rules in LLNG Manager:
+
+```perl
+# Allow only HR group to access users endpoint
+$groups =~ /\bhr\b/ and $uri =~ m#^/api/v1/ldap/users#
+
+# Allow admins full access
+$groups =~ /\badmins\b/
+
+# Allow specific users to manage groups
+$uid eq "groupmanager" and $uri =~ m#^/api/v1/ldap/groups#
+```
+
+## Troubleshooting
+
+**Problem:** Handler not found
+
+**Solution:** Install optional dependency:
+
+```bash
+npm install lemonldap-ng-handler
+```
+
+**Problem:** Authentication refused
+
+**Solutions:**
+
+1. Verify LLNG handler is configured correctly
+2. Check virtual host configuration
+3. Review LLNG access logs
+
+## See Also
+
+- [LemonLDAP::NG Documentation](https://lemonldap-ng.org/documentation)

package/docs/usage/plugins/auth/oidc.md

@@ -0,0 +1,167 @@
+# OpenID Connect Authentication
+
+OAuth 2.0 / OpenID Connect authentication for modern identity providers.
+
+## Configuration
+
+```bash
+--plugin core/auth/openidconnect \
+--oidc-server "https://auth.example.com" \
+--oidc-client-id "ldap-rest-client" \
+--oidc-client-secret "client-secret-here" \
+--base-url "https://api.example.com"
+```
+
+**Environment Variables:**
+
+```bash
+DM_OIDC_SERVER="https://auth.example.com"
+DM_OIDC_CLIENT_ID="ldap-rest-client"
+DM_OIDC_CLIENT_SECRET="client-secret-here"
+DM_BASE_URL="https://api.example.com"
+```
+
+## Prerequisites
+
+1. **OpenID Provider**: [Lemonldap-NG](https://lemonldap-ng.org), Keycloak, Auth0, Okta, Azure AD, etc.
+2. **Client Registration**: LDAP-Rest registered as OAuth2/OIDC client
+3. **Optional Dependency**: The `express-openid-connect` npm package
+
+## Installation
+
+Install the optional dependency:
+
+```bash
+npm install express-openid-connect
+```
+
+## How It Works
+
+1. Uses `express-openid-connect` for OAuth2/OIDC flow
+2. Handles authorization code flow automatically
+3. Extracts user identity from `sub` claim
+4. Sets `req.user` to user's subject identifier
+5. Provides `beforeAuth` and `afterAuth` hooks for customization
+
+## Provider Configuration
+
+### Keycloak
+
+```bash
+--oidc-server "https://keycloak.example.com/realms/master" \
+--oidc-client-id "ldap-rest" \
+--oidc-client-secret "abc123..." \
+--base-url "https://api.example.com"
+```
+
+**Client Settings:**
+
+- Access Type: `confidential`
+- Valid Redirect URIs: `https://api.example.com/callback`
+- Standard Flow Enabled: `ON`
+
+### Auth0
+
+```bash
+--oidc-server "https://tenant.auth0.com" \
+--oidc-client-id "your-client-id" \
+--oidc-client-secret "your-client-secret" \
+--base-url "https://api.example.com"
+```
+
+### Azure AD
+
+```bash
+--oidc-server "https://login.microsoftonline.com/{tenant-id}/v2.0" \
+--oidc-client-id "application-id" \
+--oidc-client-secret "client-secret" \
+--base-url "https://api.example.com"
+```
+
+## Scopes
+
+Default scopes requested:
+
+- `openid` - Basic OpenID Connect
+- `profile` - User profile information
+- `email` - User email address
+
+## Hooks
+
+The OpenID Connect plugin supports custom hooks:
+
+### beforeAuth Hook
+
+Called before authentication processing:
+
+```javascript
+hooks: {
+  beforeAuth: async ([req, res]) => {
+    // Custom pre-authentication logic
+    console.log('Authentication attempt from:', req.ip);
+    return [req, res];
+  };
+}
+```
+
+### afterAuth Hook
+
+Called after successful authentication:
+
+```javascript
+hooks: {
+  afterAuth: async ([req, res]) => {
+    // Access OIDC user data
+    const user = req.oidc.user;
+    console.log('User authenticated:', user.email);
+
+    // Add custom user properties
+    req.customData = {
+      email: user.email,
+      name: user.name,
+    };
+
+    return [req, res];
+  };
+}
+```
+
+## Use Cases
+
+- **Modern Identity Providers**: Integration with cloud identity services
+- **Social Login**: Google, Microsoft, GitHub authentication
+- **Multi-Tenant Applications**: Different OIDC providers per tenant
+- **Standards-Based**: Portable across OIDC-compliant providers
+
+## Troubleshooting
+
+**Problem:** express-openid-connect not found
+
+**Solution:** Install optional dependency:
+
+```bash
+npm install express-openid-connect
+```
+
+**Problem:** Missing config parameter
+
+**Solution:** Ensure all required parameters are set:
+
+- `--oidc-server`
+- `--oidc-client-id`
+- `--oidc-client-secret`
+- `--base-url`
+
+**Problem:** Redirect loop
+
+**Solutions:**
+
+1. Set a long secret, shorts are refused by `openid-client`
+2. Verify `--base-url` matches actual public URL
+3. Check redirect URI in provider matches `{base-url}/callback`
+4. Ensure HTTPS in production (many providers require it)
+
+## See Also
+
+- [OpenID Connect Specification](https://openid.net/connect/)
+- [express-openid-connect](https://github.com/auth0/express-openid-connect)

package/docs/usage/plugins/auth/rate-limit.md

@@ -0,0 +1,62 @@
+# Rate Limiting
+
+Prevent brute force attacks by limiting the number of requests per IP address.
+
+## Configuration
+
+```bash
+--plugin core/auth/rateLimit \
+--rate-limit-window 60000 \
+--rate-limit-max 100
+```
+
+**Environment Variables:**
+
+```bash
+DM_RATE_LIMIT_WINDOW=60000   # Time window in milliseconds (default: 60000 = 1 minute)
+DM_RATE_LIMIT_MAX=100        # Maximum requests per window (default: 100)
+```
+
+## How It Works
+
+1. Tracks request count per IP address
+2. Uses sliding window algorithm
+3. Returns `429 Too Many Requests` when limit exceeded
+4. Automatically respects `X-Forwarded-For` when behind trusted proxy
+
+## Use Cases
+
+- **Brute Force Prevention**: Limit authentication attempts
+- **API Protection**: Prevent abuse of API endpoints
+- **DDoS Mitigation**: Basic protection against flood attacks
+- **Fair Usage**: Ensure equitable API access
+
+## Headers
+
+When rate limiting is active, responses include:
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1698765492
+```
+
+## Combining with Trusted Proxy
+
+For correct IP detection behind reverse proxies:
+
+```bash
+--plugin core/auth/trustedProxy \
+--trusted-proxy "127.0.0.1" \
+--plugin core/auth/rateLimit \
+--rate-limit-max 100
+```
+
+The rate limiter will use the real client IP from `X-Forwarded-For` when the request comes from a trusted proxy.
+
+## Security Considerations
+
+- Always use with `trustedProxy` plugin behind reverse proxies
+- Consider different limits for different endpoints
+- Monitor for legitimate users hitting limits
+- Combine with CrowdSec for IP reputation