gh-christianlouis-docuelevate/docs/AuthenticationSetup.md

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
ADMIN_GROUP_NAME	OIDC group name that grants admin access (default: admin)
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.

Authentication Methods

DocuElevate supports multiple authentication methods that can be used independently or together:

1. Simple Authentication - Basic username/password authentication managed by DocuElevate
2. OpenID Connect - Integration with identity providers like Authentik, Keycloak, or Auth0
3. Social Login - Sign in with Google, Microsoft, Apple, or Dropbox accounts (see Social Login Setup Guide)

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:

import secrets
print(secrets.token_hex(32))  # Outputs a 64-character hex string (32 bytes)

Or using OpenSSL:

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
   ADMIN_GROUP_NAME=admin
   

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.

Social Login

DocuElevate supports social login with Google, Microsoft, Apple, and Dropbox. Social login allows users to authenticate using their existing accounts with these providers, without needing a separate DocuElevate password.

Social login can be used alongside any other authentication method (simple auth, OIDC, local signup). Each social provider is independently configured.

For detailed setup instructions, prerequisites, and provider-specific configuration, see the Social Login Setup Guide.