feat: Add authentication configuration and validation
- 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
@@ -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).
|
||||
Reference in New Issue
Block a user