ldap-rest 0.1.3 → 0.1.5

package/docs/usage/plugins/README.md

@@ -0,0 +1,87 @@
+# Plugins
+
+LDAP-Rest is extensible through a plugin system. This section documents all available plugins.
+
+## LDAP Plugins
+
+LDAP entity management:
+
+| Plugin                                   | Description                                             |
+| ---------------------------------------- | ------------------------------------------------------- |
+| [flat-generic](ldap/flat-generic.md)     | Generic LDAP entity management (users, positions, etc.) |
+| [groups](ldap/groups.md)                 | LDAP group management with member validation            |
+| [organizations](ldap/organizations.md)   | Hierarchical organization management                    |
+| [bulk-import](ldap/bulk-import.md)       | Bulk import from CSV                                    |
+| [trash](ldap/trash.md)                   | Trash system (soft delete)                              |
+| [external-users](ldap/external-users.md) | Automatic external contact creation                     |
+| [on-change](ldap/on-change.md)           | LDAP change detection                                   |
+
+## Authentication Plugins
+
+Secure API access:
+
+| Plugin                 | Description                              |
+| ---------------------- | ---------------------------------------- |
+| [token](auth/token.md) | Bearer token authentication              |
+| [totp](auth/totp.md)   | TOTP authentication (time-based codes)   |
+| [hmac](auth/hmac.md)   | HMAC-SHA256 signing for backend services |
+| [llng](auth/llng.md)   | LemonLDAP::NG SSO integration            |
+| [oidc](auth/oidc.md)   | OpenID Connect / OAuth 2.0               |
+
+## Authorization Plugins
+
+Access control:
+
+| Plugin                                       | Description                     |
+| -------------------------------------------- | ------------------------------- |
+| [authz-per-branch](auth/authz-per-branch.md) | Branch-level LDAP authorization |
+| [authz-linid1](auth/authz-linid1.md)         | LinID 1.x integration           |
+
+## Security Plugins
+
+Protection and rate limiting:
+
+| Plugin                                 | Description                       |
+| -------------------------------------- | --------------------------------- |
+| [trusted-proxy](auth/trusted-proxy.md) | X-Forwarded-For header validation |
+| [rate-limit](auth/rate-limit.md)       | Request rate limiting             |
+| [crowdsec](auth/crowdsec.md)           | IP blocking via CrowdSec          |
+
+## Integration Plugins
+
+Connect to external systems:
+
+| Plugin                                                   | Description                  |
+| -------------------------------------------------------- | ---------------------------- |
+| [james-mail](integrations/james-mail.md)                 | Apache James synchronization |
+| [james-mailboxes](integrations/james-mailboxes.md)       | Apache James team mailboxes  |
+| [calendar-resources](integrations/calendar-resources.md) | Twake calendar resources     |
+| [app-accounts](integrations/app-accounts.md)             | Applicative accounts API     |
+
+## Utility Plugins
+
+| Plugin                          | Description        |
+| ------------------------------- | ------------------ |
+| [static](utilities/static.md)   | Static file server |
+| [weblogs](utilities/weblogs.md) | HTTP logging       |
+
+## Plugin Dependencies
+
+Some plugins require other plugins:
+
+```
+core/twake/james
+  └─ requires: core/ldap/onChange
+
+core/ldap/externalUsersInGroups
+  └─ requires: core/ldap/groups
+
+core/auth/authzPerBranch
+  └─ requires: An authentication plugin
+```
+
+See [the complete dependencies matrix](../../plugin-development/dependencies.md).
+
+## Load Order
+
+Authentication plugins are loaded first to secure API endpoints. The order is defined in `src/plugins/priority.json`.

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

@@ -0,0 +1,65 @@
+# Authentication Plugins
+
+LDAP-Rest provides multiple authentication plugins to secure API access. These plugins can be used individually or combined depending on your infrastructure requirements.
+
+## Available Authentication Methods
+
+| Method                    | Plugin                    | Description                                      |
+| ------------------------- | ------------------------- | ------------------------------------------------ |
+| [Token](token.md)         | `core/auth/token`         | Simple bearer token authentication               |
+| [TOTP](totp.md)           | `core/auth/totp`          | Time-based One-Time Password authentication      |
+| [HMAC](hmac.md)           | `core/auth/hmac`          | HMAC-SHA256 request signing for backend services |
+| [LemonLDAP::NG](llng.md)  | `core/auth/llng`          | Integration with LemonLDAP::NG SSO               |
+| [OpenID Connect](oidc.md) | `core/auth/openidconnect` | OAuth 2.0 / OpenID Connect authentication        |
+
+## Authorization Plugins
+
+| Method                                          | Plugin                     | Description                 |
+| ----------------------------------------------- | -------------------------- | --------------------------- |
+| [Authorization Per Branch](authz-per-branch.md) | `core/auth/authzPerBranch` | Branch-level access control |
+| [Authorization LinID 1.x](authz-linid1.md)      | `core/auth/authzLinid1`    | LinID 1.x integration       |
+
+## Security Plugins
+
+| Method                            | Plugin                   | Description                                           |
+| --------------------------------- | ------------------------ | ----------------------------------------------------- |
+| [Trusted Proxy](trusted-proxy.md) | `core/auth/trustedProxy` | Validate X-Forwarded-For headers from reverse proxies |
+| [Rate Limiting](rate-limit.md)    | `core/auth/rateLimit`    | Prevent brute force attacks                           |
+| [CrowdSec](crowdsec.md)           | `core/auth/crowdsec`     | IP reputation and blocking                            |
+
+## Choosing an Authentication Method
+
+| Feature                | Token         | TOTP              | HMAC                   | LemonLDAP::NG         | OpenID Connect                   |
+| ---------------------- | ------------- | ----------------- | ---------------------- | --------------------- | -------------------------------- |
+| **Setup Complexity**   | Simple        | Simple            | Medium                 | Medium                | Medium                           |
+| **User Management**    | None          | Manual            | Manual (service-based) | External (LLNG)       | External (Provider)              |
+| **SSO Support**        | No            | No                | No                     | Yes                   | Yes                              |
+| **MFA Support**        | No            | Yes (TOTP itself) | N/A                    | Yes (via LLNG)        | Yes (via Provider)               |
+| **Session Management** | Stateless     | Stateless         | Stateless              | LLNG Sessions         | OIDC Sessions                    |
+| **Code Expiration**    | Never         | 30-60 seconds     | Per-request            | Session-based         | Session-based                    |
+| **Request Integrity**  | No            | No                | Yes (body + path hash) | No                    | No                               |
+| **Replay Protection**  | No            | Yes (time-based)  | Yes (timestamp)        | Session-based         | Session-based                    |
+| **Best For**           | APIs, Scripts | APIs, Enhanced    | Backend Services       | Enterprises with LLNG | Cloud/SaaS, Enterprises with SSO |
+| **Dependencies**       | None          | None              | None                   | lemonldap-ng-handler  | express-openid-connect           |
+
+## Combining with Authorization
+
+All authentication plugins set `req.user` to the authenticated identity. You can use hooks to implement custom authorization:
+
+```javascript
+hooks: {
+  afterAuth: async ([req, res]) => {
+    // Check if user can access this endpoint
+    if (req.path.startsWith('/api/v1/ldap/users') && !isAdmin(req.user)) {
+      throw new Error('Forbidden: Admin access required');
+    }
+    return [req, res];
+  };
+}
+```
+
+## See Also
+
+- [LemonLDAP::NG Documentation](https://lemonldap-ng.org/documentation)
+- [OpenID Connect Specification](https://openid.net/connect/)
+- [express-openid-connect](https://github.com/auth0/express-openid-connect)

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

@@ -0,0 +1,95 @@
+# CrowdSec Integration
+
+IP reputation and blocking using [CrowdSec](https://crowdsec.net/).
+
+## Configuration
+
+```bash
+--plugin core/auth/crowdsec \
+--crowdsec-url "http://localhost:8080" \
+--crowdsec-api-key "your-api-key"
+```
+
+**Environment Variables:**
+
+```bash
+DM_CROWDSEC_URL="http://localhost:8080"
+DM_CROWDSEC_API_KEY="your-api-key"
+```
+
+## Prerequisites
+
+1. **CrowdSec Installation**: Running CrowdSec instance
+2. **API Key**: Bouncer API key from CrowdSec
+
+## How It Works
+
+1. Extracts client IP from request (respects trusted proxy)
+2. Queries CrowdSec API for IP reputation
+3. Blocks requests from banned IPs with `403 Forbidden`
+4. Allows legitimate requests to proceed
+
+## Use Cases
+
+- **IP Reputation**: Block known malicious IPs
+- **Threat Intelligence**: Leverage community-shared threat data
+- **Dynamic Blocking**: Automatic response to attacks
+- **Compliance**: Security monitoring and logging
+
+## CrowdSec Setup
+
+### Install CrowdSec
+
+```bash
+# Debian/Ubuntu
+curl -s https://packagecloud.io/install/repositories/crowdsec/crowdsec/script.deb.sh | sudo bash
+sudo apt install crowdsec
+
+# Generate bouncer API key
+sudo cscli bouncers add ldap-rest-bouncer
+```
+
+### Configure LDAP-Rest
+
+```bash
+npx ldap-rest \
+  --plugin core/auth/crowdsec \
+  --crowdsec-url "http://localhost:8080" \
+  --crowdsec-api-key "generated-api-key" \
+  ...
+```
+
+## Combining with Other Security Plugins
+
+Recommended security stack:
+
+```bash
+--plugin core/auth/trustedProxy \
+--trusted-proxy "127.0.0.1" \
+--plugin core/auth/crowdsec \
+--crowdsec-url "http://localhost:8080" \
+--crowdsec-api-key "your-api-key" \
+--plugin core/auth/rateLimit \
+--rate-limit-max 100 \
+--plugin core/auth/token \
+--auth-token "your-token"
+```
+
+Order matters:
+
+1. `trustedProxy` - Sanitize IP headers first
+2. `crowdsec` - Block known bad IPs
+3. `rateLimit` - Limit request frequency
+4. Authentication plugins
+
+## Security Considerations
+
+- Keep CrowdSec updated for latest threat intelligence
+- Monitor CrowdSec logs for blocked requests
+- Consider local decisions for sensitive applications
+- Use HTTPS between LDAP-Rest and CrowdSec API
+
+## See Also
+
+- [CrowdSec Documentation](https://docs.crowdsec.net/)
+- [CrowdSec Hub](https://hub.crowdsec.net/)

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)