gitea-admin/gh-christianlouis-docuelevate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add authentication configuration and validation

Browse Source 
- Introduced new authentication settings in config.py including `auth_enabled`, `admin_username`, `admin_password`, and `session_secret`.
- Added validation for `session_secret` to ensure it meets security requirements when authentication is enabled.
- Updated main.py to conditionally mount static files and log warnings if the directory is not found.
- Removed unused email template files and added new authentication and notification setup documentation.
- Implemented authentication configuration validation in validators.py and updated settings display.
- Enhanced the user interface with a new login template and SVG assets for branding.
- Added comprehensive guides for setting up authentication and notifications in the documentation.
This commit is contained in:
Christian Krakau-Louis
2025-04-11 03:44:08 +02:00
parent 05ede35059
commit d79652b494
21 changed files with 785 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/AuthenticationSetup.md
+189
View File
@@ -0,0 +1,189 @@
# Setting up Authentication
This guide explains how to configure authentication for DocuElevate to secure your installation.
## Required Configuration Parameters
| **Variable** | **Description** |
|----------------------------|----------------------------------------------------------|
| `AUTH_ENABLED` | Enable or disable authentication (`True`/`False`) |
| `SESSION_SECRET` | Secret key for session encryption (min 32 characters) |
| `ADMIN_USERNAME` | Username for basic authentication |
| `ADMIN_PASSWORD` | Password for basic authentication |
| `AUTHENTIK_CLIENT_ID` | Client ID for OpenID Connect authentication |
| `AUTHENTIK_CLIENT_SECRET` | Client secret for OpenID Connect authentication |
| `AUTHENTIK_CONFIG_URL` | OpenID Connect discovery URL |
| `OAUTH_PROVIDER_NAME` | Display name for the OAuth provider button |
For a complete list of configuration options, see the [Configuration Guide](ConfigurationGuide.md).
## Authentication Methods
DocuElevate supports two primary authentication methods:
1. **Simple Authentication** - Basic username/password authentication managed by DocuElevate
2. **OpenID Connect** - Integration with identity providers like Authentik, Keycloak, or Auth0
## Session Security
DocuElevate uses FastAPI's session management to maintain user sessions. The session data is stored in cookies that are encrypted and signed using your application's secret key. This prevents tampering with session data while ensuring users remain authenticated between requests.
The `SESSION_SECRET` is automatically used by the web framework to:
1. Encrypt and sign session cookies
2. Protect against cross-site request forgery (CSRF) attacks
3. Secure other session-related functionality
Always use a strong, randomly generated secret key of at least 32 characters for production environments.
### Generating a Secure Session Secret
You can generate a secure random string using Python:
```python
import secrets
print(secrets.token_hex(32)) # Outputs a 64-character hex string (32 bytes)
```
Or using OpenSSL:
```bash
openssl rand -hex 32
```
Make sure to keep this secret value confidential and don't reuse it across different applications.
## Setting up Simple Authentication
For smaller deployments or testing, simple authentication is easy to set up:
1. In your `.env` file, set:
```
AUTH_ENABLED=True
SESSION_SECRET=your-secure-random-string-at-least-32-chars
ADMIN_USERNAME=your_admin_username
ADMIN_PASSWORD=your_secure_password
```
2. Restart DocuElevate to apply the changes
3. When you navigate to the application, you'll be prompted to log in with the credentials you set
## Setting up OpenID Connect with Authentik
For larger deployments or when you need more advanced authentication features, OpenID Connect (OIDC) is recommended:
### 1. Create an Application in Authentik
1. Log in to your Authentik admin interface
2. Navigate to "Applications" > "Applications"
3. Click "Create"
4. Fill in the following details:
- **Name**: DocuElevate
- **Slug**: docuelevate
- **Provider**: Create a new OAuth2/OIDC Provider
- **Launch URL**: The URL of your DocuElevate instance (e.g., https://docuelevate.example.com)
5. For the OAuth2/OIDC Provider settings:
- **Client Type**: Confidential
- **Redirect URIs**: https://docuelevate.example.com/auth (adjust for your domain)
- **Signing Key**: Select an appropriate signing key
- **Scopes**: Select "openid", "email", and "profile" at minimum
6. Save the provider and then the application
7. Note down the **Client ID** and **Client Secret** from the provider details
### 2. Configure DocuElevate
1. In your `.env` file, set:
```
AUTH_ENABLED=True
SESSION_SECRET=your-secure-random-string-at-least-32-chars
AUTHENTIK_CLIENT_ID=your_client_id_from_authentik
AUTHENTIK_CLIENT_SECRET=your_client_secret_from_authentik
AUTHENTIK_CONFIG_URL=https://auth.example.com/application/o/docuelevate/.well-known/openid-configuration
OAUTH_PROVIDER_NAME=Authentik SSO
```
2. Adjust the `AUTHENTIK_CONFIG_URL` to match your Authentik instance and application slug
3. Restart DocuElevate to apply the changes
### 3. Test the Authentication
1. Navigate to your DocuElevate instance
2. You should be redirected to the Authentik login page
3. After successful authentication, you'll be redirected back to DocuElevate
## Using Other OpenID Connect Providers
DocuElevate can work with any OpenID Connect-compliant provider, not just Authentik:
### Keycloak Setup
1. Create a client in Keycloak with:
- **Client ID**: your preferred client ID
- **Access Type**: confidential
- **Valid Redirect URIs**: https://docuelevate.example.com/auth
2. Get the client secret from the "Credentials" tab
3. Configure DocuElevate with:
```
AUTHENTIK_CLIENT_ID=your_keycloak_client_id
AUTHENTIK_CLIENT_SECRET=your_keycloak_client_secret
AUTHENTIK_CONFIG_URL=https://keycloak.example.com/auth/realms/your-realm/.well-known/openid-configuration
OAUTH_PROVIDER_NAME=Keycloak SSO
```
### Auth0 Setup
1. Create a new application in Auth0
2. Get your client ID and secret
3. Set the callback URL to https://docuelevate.example.com/auth
4. Configure DocuElevate with:
```
AUTHENTIK_CLIENT_ID=your_auth0_client_id
AUTHENTIK_CLIENT_SECRET=your_auth0_client_secret
AUTHENTIK_CONFIG_URL=https://your-tenant.auth0.com/.well-known/openid-configuration
OAUTH_PROVIDER_NAME=Auth0
```
## Security Considerations
1. **Always use HTTPS** in production to protect authentication tokens and passwords
2. Generate a strong, random `SESSION_SECRET` (at least 32 characters)
3. Use strong passwords for simple authentication
4. Consider using a password manager to generate and store your admin credentials
5. Restrict the scopes requested from your OIDC provider to only what's needed
6. Consider setting up user groups and permissions in your identity provider
7. If using simple authentication in production, consider implementing rate limiting for login attempts
## Troubleshooting Authentication Issues
If you encounter issues with authentication:
1. **Login failures with simple authentication**:
- Verify that the username and password exactly match the values in your `.env` file
- Check if there are leading or trailing spaces in your credentials
- Ensure your `.env` file is properly loaded by the application
2. **Session issues**:
- Check that your `SESSION_SECRET` is set correctly
- Clear browser cookies and cache if experiencing persistent login issues
3. **OIDC issues**:
- **Redirect URI mismatch**: Ensure the redirect URI in your provider configuration exactly matches your DocuElevate URL + "/auth"
- **SSL-related errors**: Make sure your certificates are valid and trusted
- **Provider connectivity**: Ensure DocuElevate can reach your identity provider
4. **Token validation errors**:
- Check that the clocks are synchronized between DocuElevate and the identity provider
- Verify that the signing keys are correctly configured
5. **Debug OpenID information**:
- For most providers, you can visit the `/.well-known/openid-configuration` endpoint to verify their settings
For more general configuration issues, see the [Configuration Troubleshooting Guide](ConfigurationTroubleshooting.md).
docs/ConfigurationGuide.md
+30 -2
View File
@@ -35,9 +35,13 @@ DocuElevate can monitor multiple IMAP mailboxes for document attachments. Each m
| **Variable** | **Description** |
|-------------------------|---------------------------------------------------------------|
| `AUTH_ENABLED` | Enable or disable authentication (`true`/`false`). |
| `AUTHENTIK_CLIENT_ID` | Client ID for Authentik OAuth2. |
| `AUTHENTIK_CLIENT_SECRET` | Client secret for Authentik OAuth2. |
| `SESSION_SECRET` | Secret key used to encrypt sessions and cookies (at least 32 chars). |
| `ADMIN_USERNAME` | Username for basic authentication (when not using OIDC). |
| `ADMIN_PASSWORD` | Password for basic authentication (when not using OIDC). |
| `AUTHENTIK_CLIENT_ID` | Client ID for Authentik OAuth2/OIDC authentication. |
| `AUTHENTIK_CLIENT_SECRET` | Client secret for Authentik OAuth2/OIDC authentication. |
| `AUTHENTIK_CONFIG_URL` | Configuration URL for Authentik OpenID Connect. |
| `OAUTH_PROVIDER_NAME` | Display name for the OAuth provider button. |
### OpenAI & Azure Document Intelligence
@@ -162,6 +166,18 @@ For detailed setup instructions, see the [OneDrive Setup Guide](OneDriveSetup.md
For detailed setup instructions, see the [Amazon S3 Setup Guide](AmazonS3Setup.md).
### Notification System
| **Variable** | **Description** |
|----------------------------|----------------------------------------------------------|
| `NOTIFICATION_URLS` | Comma-separated list of Apprise notification URLs |
| `NOTIFY_ON_TASK_FAILURE` | Send notifications on task failures (`True`/`False`) |
| `NOTIFY_ON_CREDENTIAL_FAILURE` | Send notifications on credential failures (`True`/`False`) |
| `NOTIFY_ON_STARTUP` | Send notification when system starts (`True`/`False`) |
| `NOTIFY_ON_SHUTDOWN` | Send notification when system shuts down (`True`/`False`)|
For detailed setup instructions, see the [Notifications Setup Guide](NotificationsSetup.md).
### Uptime Kuma
| **Variable** | **Description** |
@@ -209,9 +225,13 @@ AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT=https://...
# Authentication
AUTH_ENABLED=true
SESSION_SECRET=a-very-long-and-secure-random-secret-key-string-for-session-encryption
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_secure_password
AUTHENTIK_CLIENT_ID=...
AUTHENTIK_CLIENT_SECRET=...
AUTHENTIK_CONFIG_URL=https://auth.example.com/.well-known/openid-configuration
OAUTH_PROVIDER_NAME=Authentik SSO
# Storage services
PAPERLESS_NGX_API_TOKEN=...
@@ -270,6 +290,14 @@ EMAIL_USE_TLS=True
EMAIL_SENDER=DocuElevate System <docuelevate@example.com>
EMAIL_DEFAULT_RECIPIENT=recipient@example.com
# Notification Settings
# Configure notification services using Apprise URL format
NOTIFICATION_URLS=discord://webhook_id/webhook_token,mailto://user:pass@gmail.com,tgram://bot_token/chat_id
NOTIFY_ON_TASK_FAILURE=True
NOTIFY_ON_CREDENTIAL_FAILURE=True
NOTIFY_ON_STARTUP=True
NOTIFY_ON_SHUTDOWN=False
# OneDrive (Personal Account)
ONEDRIVE_CLIENT_ID=12345678-1234-1234-1234-123456789012
ONEDRIVE_CLIENT_SECRET=your_client_secret
docs/ConfigurationMaster.md
+2
View File
@@ -13,6 +13,8 @@ DocuElevate is designed to be highly configurable through environment variables,
- [Dropbox Setup](DropboxSetup.md) - How to set up Dropbox integration
- [OneDrive Setup](OneDriveSetup.md) - How to set up Microsoft OneDrive/Graph integration
- [Amazon S3 Setup](AmazonS3Setup.md) - How to set up Amazon S3 integration
- [Authentication Setup](AuthenticationSetup.md) - How to set up user authentication
- [Notifications Setup](NotificationsSetup.md) - How to set up system notifications
## Configuration File Location
docs/DeploymentGuide.md
+1
View File
@@ -13,6 +13,7 @@ This guide provides instructions for deploying DocuElevate in various environmen
- Paperless NGX instance
- SMTP server (for email notifications)
- IMAP server(s) (for email attachment processing)
- Notification services (Discord, Telegram, etc. for system alerts)
## Docker Deployment
docs/NotificationsSetup.md
+219
View File
@@ -0,0 +1,219 @@
# Setting up System Notifications
This guide explains how to set up the notification system for DocuElevate, which allows you to receive alerts about important system events.
## Required Configuration Parameters
| **Variable** | **Description** |
|----------------------------|----------------------------------------------------------|
| `NOTIFICATION_URLS` | Comma-separated list of Apprise notification URLs |
| `NOTIFY_ON_TASK_FAILURE` | Send notifications on task failures (`True`/`False`) |
| `NOTIFY_ON_CREDENTIAL_FAILURE` | Send notifications on credential failures (`True`/`False`) |
| `NOTIFY_ON_STARTUP` | Send notification when system starts (`True`/`False`) |
| `NOTIFY_ON_SHUTDOWN` | Send notification when system shuts down (`True`/`False`)|
For a complete list of configuration options, see the [Configuration Guide](ConfigurationGuide.md).
## Overview
DocuElevate uses the Apprise library to provide a flexible notification system that supports over 70 different notification services, including:
- Email
- SMS
- Messaging apps (Telegram, Discord, Slack, Matrix, etc.)
- Push notification services (Pushover, Pushbullet, etc.)
- Web hooks
- And many more
## Setting up Notifications
### 1. Choose Your Notification Services
First, decide which notification services you want to use. The Apprise library supports a wide range of services, each with its own URL format. Here are some common examples:
- **Discord**: `discord://webhook_id/webhook_token`
- **Telegram**: `tgram://bot_token/chat_id`
- **Email**: `mailto://user:pass@example.com`
- **Pushover**: `pover://user_key/app_token`
- **Slack**: `slack://tokenA/tokenB/tokenC`
- **Matrix**: `matrix://username:password@domain/#room`
- **Microsoft Teams**: `msteams://token_a/token_b/token_c`
- **Gotify**: `gotify://hostname/token`
For a complete list of supported services and their URL formats, see the [Apprise Wiki](https://github.com/caronc/apprise/wiki).
### 2. Configure Your Notification URLs
Set the `NOTIFICATION_URLS` environment variable with a comma-separated list of your notification service URLs:
```dotenv
NOTIFICATION_URLS=discord://webhook_id/webhook_token,mailto://user:pass@gmail.com,tgram://bot_token/chat_id
```
You can specify as many notification services as you need.
### 3. Configure Notification Triggers
DocuElevate can send notifications for various system events. Configure which events should trigger notifications:
```dotenv
NOTIFY_ON_TASK_FAILURE=True # Notify when background tasks fail
NOTIFY_ON_CREDENTIAL_FAILURE=True # Notify when service credentials fail (e.g. API token expired)
NOTIFY_ON_STARTUP=True # Notify when the system starts
NOTIFY_ON_SHUTDOWN=False # Notify when the system shuts down
```
## Automated Credential Checking
DocuElevate includes a powerful credential monitoring system that regularly checks the validity of your configured service credentials. This helps you proactively address authentication issues before they affect your document processing workflows.
### How Credential Checking Works
1. **Regular Monitoring**: The system automatically checks all configured service credentials at regular intervals (every 5 minutes) and at startup.
2. **Smart Notifications**: When credential failures are detected, the system sends notifications through your configured notification channels.
3. **Notification Rate Limiting**: To prevent notification spam, alerts follow a progressive notification strategy:
- First 3 failures: Notification sent for each failure
- Subsequent failures: Notifications suppressed until credential is restored
- Recovery: Notification sent when credentials are working again
4. **Services Monitored**:
- OpenAI API
- Azure Document Intelligence
- Dropbox
- Google Drive
- OneDrive/Microsoft Graph
- Other configured storage providers
### Notification Content
When a credential failure is detected, the notification includes:
- The affected service name
- The specific error message
- A reminder to check and update credentials
Example notification:
```
Subject: Credential Failure: Dropbox
The credentials for Dropbox have failed:
Invalid refresh token: Token has been revoked or expired.
Please check and update the credentials in the system settings.
```
### Configuration Options
To control credential check notifications:
```dotenv
# Enable/disable credential failure notifications
NOTIFY_ON_CREDENTIAL_FAILURE=True
```
When set to `False`, the system will still perform the checks but won't send notifications about failures.
### Troubleshooting Credential Issues
If you receive credential failure notifications:
1. **Check token expiration**: For OAuth-based services (Google Drive, OneDrive, Dropbox), refresh tokens may have expired.
2. **Verify API keys**: Ensure your API keys for services like OpenAI and Azure Document Intelligence are still valid.
3. **Check service status**: The service itself might be experiencing downtime.
4. **Review quota limits**: Some services have usage quotas that might have been exceeded.
5. **Regenerate credentials**: Use the built-in auth wizards to generate new tokens:
- Go to Settings > [Service Name] Setup
- Click "Refresh Token" or "Start Authentication Flow"
- Complete the authentication process to generate new credentials
### Viewing Credential Status
You can view the current status of your service credentials in the system dashboard:
1. Navigate to the Status page in the DocuElevate interface
2. Check the Service Status section
3. Each service will show its current status (Valid, Invalid, or Not Configured)
## Service-Specific Setup Instructions
### Discord Notifications
1. Go to your Discord server
2. Select a channel or create a new one for notifications
3. Go to Server Settings > Integrations > Webhooks
4. Click "New Webhook" and set up a webhook for your channel
5. Copy the webhook URL (it will look like `https://discord.com/api/webhooks/123456789/abcdefg`)
6. Extract the webhook ID and token (the parts after `webhooks/`)
7. Format your Apprise URL as: `discord://123456789/abcdefg`
### Telegram Notifications
1. Start a chat with [@BotFather](https://t.me/botfather) on Telegram
2. Create a new bot using the `/newbot` command
3. Note the bot token provided by BotFather
4. Start a chat with your new bot or add it to a group
5. Get the chat ID:
- For direct messages: send a message to the bot, then visit `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
- For group chats: add the bot to the group, send a message mentioning the bot, then check the same URL
6. Format your Apprise URL as: `tgram://bot_token/chat_id`
### Email Notifications
To send notifications via email, configure the Apprise URL with your SMTP server details:
```
# Gmail example
mailto://your-email@gmail.com:password@smtp.gmail.com?smtp=587
```
For Gmail, you'll need to use an app password if you have 2FA enabled.
## Task Failure Notifications
In addition to credential monitoring, DocuElevate can notify you about background task failures. When enabled, the system will send notifications whenever a background processing task encounters an error.
To configure task failure notifications:
```dotenv
# Enable/disable task failure notifications
NOTIFY_ON_TASK_FAILURE=True
```
Task failure notifications include:
- Task name and ID
- Error type and message
- Task arguments (for debugging)
## Testing Your Notification Setup
To test your notification setup once configured:
1. Start the DocuElevate application
2. If `NOTIFY_ON_STARTUP=True`, you should receive a notification when the system starts
3. Check the application logs for any errors related to notifications
## Security Considerations
When setting up notifications:
1. **Protect your credentials**: Keep your notification URLs secure, as they often contain access tokens or passwords.
2. **Use environment variables**: Store notification URLs in environment variables rather than hard-coding them.
3. **Limit notification content**: Be mindful of sending sensitive information in notifications.
4. **Consider encryption**: For highly sensitive environments, consider using encrypted notification channels.
## Troubleshooting
If you're not receiving notifications:
1. **Check service connectivity**: Ensure the DocuElevate server can access the notification services.
2. **Verify URL format**: Double-check the format of your notification URLs.
3. **Check application logs**: Look for errors related to the notification system in logs.
4. **Test services individually**: Try configuring one notification service at a time to isolate issues.
5. **Check service-specific limits**: Some services have rate limits on notifications.
For more general configuration issues, see the [Configuration Troubleshooting Guide](ConfigurationTroubleshooting.md).
docs/README.md
+2
View File
@@ -13,6 +13,8 @@ Welcome to the DocuElevate documentation. This directory contains comprehensive
- [Dropbox Setup](DropboxSetup.md) - How to set up Dropbox integration
- [OneDrive Setup](OneDriveSetup.md) - How to set up Microsoft OneDrive/Graph integration
- [Amazon S3 Setup](AmazonS3Setup.md) - How to set up Amazon S3 integration
- [Authentication Setup](AuthenticationSetup.md) - How to set up user authentication
- [Notifications Setup](NotificationsSetup.md) - How to set up system notifications
- [Configuration Troubleshooting](ConfigurationTroubleshooting.md) - Solutions to common configuration issues
- [Troubleshooting](Troubleshooting.md) - General troubleshooting and solutions to common issues
docs/UserGuide.md
+22
View File
@@ -11,6 +11,28 @@ DocuElevate offers an intuitive web interface for uploading, managing, and proce
1. Navigate to your DocuElevate instance (typically at `http://your-server-address:8000`)
2. If authentication is enabled, you'll be prompted to log in using your credentials
### Authentication
DocuElevate supports two main authentication methods:
#### Basic Authentication
If basic authentication is configured:
1. You'll see a simple login form
2. Enter your username and password as configured in the system
3. Click "Log In" to access DocuElevate
#### OpenID Connect (OIDC)
If OpenID Connect authentication is configured:
1. You'll see a login button
2. Clicking this will redirect you to your identity provider (e.g., Authentik, Keycloak, Auth0)
3. Log in with your existing credentials on that platform
4. You'll be redirected back to DocuElevate after successful authentication
#### User Sessions
- Once authenticated, your session will remain active until you log out or it expires
- Click the "Logout" button in the top navigation bar to end your session
- For security, sessions automatically expire after a period of inactivity
### Main Interface
DocuElevate features a simple navigation system with the following main sections: