Skip to content

Latest commit

 

History

History
441 lines (339 loc) · 18 KB

OIDC_Implementation.md

File metadata and controls

441 lines (339 loc) · 18 KB

🔐 OpenID Connect (OIDC) Authentication Guide

← Back to Documentation Index

📋 Overview

This guide provides comprehensive instructions for setting up OpenID Connect (OIDC) authentication in the Mail Archiver application, with specific examples for Microsoft Entra ID (Azure AD) integration. OIDC enables secure single sign-on (SSO) authentication using external identity providers.

📚 Table of Contents

  1. Overview
  2. Prerequisites
  3. OIDC Configuration
  4. Microsoft Entra ID Setup
  5. Authelia Setup
  6. Testing and Validation
  7. User Management with OIDC
  8. Auto-Approve OIDC Users
  9. Passwordless Login Configuration

🌐 Overview

The Mail Archiver application supports OpenID Connect (OIDC) authentication, allowing users to authenticate using external identity providers such as Microsoft Entra ID and other OIDC-compliant providers. This feature enhances security by leveraging enterprise identity management systems and enables single sign-on (SSO) capabilities.

🛠️ Prerequisites

  • Administrative access to your chosen OIDC identity provider (e.g., Microsoft Entra ID)
  • Mail Archiver application already deployed and accessible via HTTPS
  • DNS name configured for your Mail Archiver instance (required for callback URLs)
  • Administrative access to the Mail Archiver application and host system for configuration
  • If using a reverse proxy, proper reverse proxy configuration for HTTPS header handling

🔧 Reverse Proxy Configuration for OIDC

When deploying Mail Archiver behind a reverse proxy with OIDC authentication, additional configuration may be required to ensure proper handling of authentication flows and token exchanges. OIDC authentication involves larger HTTP headers and response bodies that may exceed default buffer sizes in some reverse proxy configurations.

Nginx Proxy Manager Configuration

If you're using Nginx Proxy Manager as your reverse proxy, you may need to add the following configuration to handle OIDC authentication properly:

proxy_busy_buffers_size 512k;
proxy_buffers 4 512k;
proxy_buffer_size 256k;

These settings increase the buffer sizes to accommodate larger OIDC tokens and authentication responses. Without these settings, you may encounter issues with authentication flows, particularly with providers that return large ID tokens or when using additional scopes.

General Reverse Proxy Considerations

  • Ensure your reverse proxy preserves HTTPS headers (X-Forwarded-Proto, X-Forwarded-Host)
  • Configure appropriate timeout settings for authentication flows
  • Verify that large header sizes are supported
  • Test the authentication flow thoroughly after configuration changes

For detailed reverse proxy configuration guidance, refer to the Reverse Proxy Configuration Guide.

⚙️ OIDC Configuration

Enable OIDC in Configuration

To enable OIDC authentication, you need to configure the OAuth section in your appsettings.json file or environment variables for the docker deployment (see Installation and Setup).

Example Configuration (appsettings.json)

{
  "OAuth": {
    "Enabled": true,
    "Authority": "https://sts.windows.net/{TENANT-ID}/",
    "ClientId": "YOUR-CLIENT-ID",
    "ClientSecret": "YOUR-CLIENT-SECRET",
    "ClientScopes": [
      "openid",
      "profile",
      "email"
    ],
    "DisablePasswordLogin": false
  }
}

Environment Variables

When using Docker Compose or environment variables, configure the following variables in your docker-compose.yml file under the mailarchive-app service environment section:

environment:
  # OIDC Configuration
  - OAuth__Enabled=true
  - OAuth__Authority=https://sts.windows.net/{TENANT-ID}/
  - OAuth__ClientId=YOUR-CLIENT-ID
  - OAuth__ClientSecret=YOUR-CLIENT-SECRET
  - OAuth__ClientScopes__0=openid
  - OAuth__ClientScopes__1=profile
  - OAuth__ClientScopes__2=email
  - OAuth__DisablePasswordLogin=false

Configuration Parameters Explained

  • OAuth__Enabled: Set to true to enable OIDC authentication
  • OAuth__Authority: The OpenID Connect authority URL of your identity provider
  • OAuth__ClientId: The client ID assigned by your identity provider
  • OAuth__ClientSecret: The client secret assigned by your identity provider
  • OAuth__ClientScopes: Array of scopes requested from the identity provider
  • OAuth__DisablePasswordLogin: Set to true to disable traditional username/password login and enforce OAuth-only authentication (see Passwordless Login Configuration for more details)
  • OAuth__AutoApproveUsers: Set to true to automatically approve new OIDC users without requiring admin approval (default: false). See Auto-Approve OIDC Users for details

⚠️ Important: The Client Secret should be kept secure. Use Docker secrets or environment variables in production environments.

☁️ Microsoft Entra ID Setup

This section provides step-by-step instructions for configuring Microsoft Entra ID (formerly Azure AD) as an OIDC identity provider for Mail Archiver.

🚀 Create App Registration

  1. Navigate to the Microsoft Entra Admin Center

  2. Sign in with your administrator account

  3. In the left navigation pane, select App registrations

  4. Click + New registration at the top of the App registrations page

  5. Fill in the following details:

    • Name: Enter a descriptive name (e.g., "Mail Archiver OIDC")
    • Supported account types: Select Accounts in this organizational directory only
    • Redirect URI: Select Web and enter your Mail Archiver callback URL: 
      https://your-mail-archiver-domain/oidc-signin-completed
      Replace your-mail-archiver-domain with your actual domain (e.g., mailarchiver.example.com)

  6. Click Register

🔐 Configure Authentication

  1. After registration, note down the following values from the Overview page:

    • Application (client) ID - You'll need this as OAuth__ClientId
    • Directory (tenant) ID - You'll need this in the Authority URL

  2. In the left menu, select Authentication

  3. Click Settings

  4. Under Implicit grant and hybrid flows, ensure ID tokens is checked

  5. Under Supported account types, verify your selection matches your requirements

  6. Under Redirect URIs, ensure your callback URL is listed correctly

🎯 Configure API Permissions

  1. In the left menu, select API permissions
  2. Click + Add a permission
  3. Select Microsoft Graph
  4. Choose Delegated permissions
  5. Add the following permissions (if needed for additional features):
    • openid - Sign users in
    • email - View users' email address
    • profile - View users' basic profile
  6. Click Add permissions
  7. Click Grant admin consent for [Your Organization] if you want to pre-authorize the application

🔑 Generate Client Secret

  1. Navigate to Certificates & secrets in the left menu
  2. Under Client secrets, click + New client secret
  3. Provide a description (e.g., "Mail Archiver Auth Secret")
  4. Select an expiration period
  5. Click Add
  6. Important: Copy the Value immediately and store it securely. This secret will not be shown again. It's needed as the OAuth__ClientSecret

🔐 Authelia Setup

This section provides configuration details for setting up Authelia as an OIDC identity provider for Mail Archiver. Authelia is an open-source authentication and authorization server that supports OIDC.

🛠️ Authelia Configuration

identity_providers:
  oidc:
    clients:
      - client_id: 'mailarchiver'
        client_name: 'mailarchiver'
        client_secret: '$xyzg'  # The digest of 'insecure_secret'.
        public: false
        redirect_uris:
          - 'https://your-mail-archiver-domain/oidc-signin-completed'
        scopes:
          - 'openid'
          - 'profile'
          - 'email'
        response_types:
          - 'code'
        grant_types:
          - 'authorization_code'
        token_endpoint_auth_method: 'client_secret_post'

📝 Client Registration Details

  • client_id: mailarchiver - The unique identifier for the Mail Archiver application
  • client_name: mailarchiver - The display name shown to users during authentication
  • client_secret: The hashed secret used for client authentication (replace with your own secure secret in production)
  • redirect_uris: The callback URL where Authelia will redirect users after authentication. Replace [YOUR_MAILARCHIVER_URL] with your actual Mail Archiver domain
  • scopes: The permissions requested from Authelia:
    • openid: Required for OIDC authentication
    • profile: Access to basic profile information
    • email: Access to email address
  • response_types: code - Authorization code flow
  • grant_types: authorization_code - Authorization code grant type
  • token_endpoint_auth_method: client_secret_post - Client authentication method

⚠️ Security Note: The example uses a default secret for demonstration. In production, generate a secure secret and hash it using Authelia's tools. Never use the example secret in production environments.

🧪 Testing and Validation

Initial Setup Testing

  1. Restart your Mail Archiver application after configuring OIDC settings
  2. Navigate to your Mail Archiver login page
  3. You should see a new "Login with OAuth" button alongside the regular login form
  4. Click the "Login with OAuth" button to initiate the OIDC flow
  5. You should be redirected to your identity provider's login page
  6. After successful authentication, you should be redirected back to Mail Archiver

User Provisioning Validation

  • First-time OIDC users will be automatically created in the Mail Archiver database
  • Users will be created with the default "User" role and will need admin approval for access

👥 User Management with OIDC

User Roles and Permissions

OIDC users follow the same role-based access control as local users:

  • Admin: Full system access (requires manual assignment by existing admin, or automatic via AdminEmails configuration)
  • User: Standard user access to assigned mail accounts
  • Self-Manager: Can manage their own account and add new accounts

Auto-Provisioning Administrators

You can configure specific email addresses to be automatically provisioned as administrators when they first log in via OIDC:

{
  "OAuth": {
    "AdminEmails": [
      "admin@example.com",
      "it-manager@example.com"
    ]
  }
}

When a user with one of these email addresses logs in for the first time:

  • They are automatically created as an active administrator
  • No manual approval is required
  • They gain full administrative privileges immediately
  • Email matching is case-insensitive

Security Note: Only add trusted email addresses to this list, as these users will have full system access.

User Provisioning Flow

New Users (Not in AdminEmails)

  1. User authenticates via OAuth provider
  2. System checks if email exists in local database
  3. If new user:
    • Account is created with username format: {DisplayName}_{UniqueId}
    • User is marked as inactive and requires approval
    • Admin must manually activate the user in Users management
  4. User receives "Account pending approval" message

New Users (In AdminEmails)

  1. User authenticates via OAuth provider
  2. System recognizes email is in AdminEmails list
  3. Account is automatically created:
    • User is marked as active and admin
    • No approval required
    • User can immediately access the system
  4. User is logged in successfully

Password Management

OIDC users cannot have or change passwords within Mail Archiver since authentication is handled by the external identity provider:

  • The "Change Password" option will be disabled for OIDC users
  • Password reset must be handled through the OIDC provider
  • Local password fields will remain empty for OIDC users

✅ Auto-Approve OIDC Users

By default, new OIDC users must be manually approved by a local administrator before they can access the application. This provides a double-gating model where both the IdP and the local admin must grant access.

For OIDC-first deployments where the Identity Provider (IdP) is the single source of truth for access control, this manual approval step can be skipped by enabling the AutoApproveUsers option.

Enabling Auto-Approve

Set AutoApproveUsers to true in your configuration:

{
  "OAuth": {
    "Enabled": true,
    "AutoApproveUsers": true,
    "Authority": "https://your-provider.com",
    "ClientId": "your-client-id",
    "ClientSecret": "your-secret"
  }
}

Or via environment variable:

environment:
  - OAuth__AutoApproveUsers=true

Behavior

Setting New OIDC User Behavior
AutoApproveUsers: false (default) User is created as inactive and requires admin approval before access is granted
AutoApproveUsers: true User is created as active and can immediately access the application

Note: AdminEmails always takes precedence — users matching AdminEmails are always auto-approved as administrators regardless of this setting.

When to Use

This option is recommended for environments where:

  • The IdP controls application access (e.g., via app assignment or group membership in Authentik, Entra ID, Authelia, etc.)
  • You want to eliminate the double-gating model (IdP grant + local admin approval)
  • Access revocation is managed at the IdP level (removing app assignment automatically prevents login)

Complete OIDC-First Setup Example

{
  "OAuth": {
    "Enabled": true,
    "Authority": "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0",
    "ClientId": "your-client-id",
    "ClientSecret": "your-secret",
    "ClientScopes": ["openid", "profile", "email"],
    "DisablePasswordLogin": true,
    "AutoRedirect": true,
    "AutoApproveUsers": true,
    "AdminEmails": ["admin@company.com"]
  }
}

In this setup:

  • Users are automatically redirected to the OIDC provider
  • New users are automatically approved on first login
  • Admin emails are auto-provisioned as administrators
  • Access control is fully managed at the IdP level

Security Considerations

  • Trust: Enabling AutoApproveUsers means you trust the IdP to control who can access the application. Ensure your IdP is properly configured with appropriate app assignments or group-based access.
  • Role Assignment: Auto-approved users are created with standard user permissions (not admin). Admin access still requires either AdminEmails configuration or manual role assignment.
  • Revocation: When a user's access is removed in the IdP, they can no longer authenticate via OIDC. However, their local account remains active. To fully revoke access, also deactivate the user in the Mail Archiver admin panel.
  • Backward Compatibility: The default value is false, preserving the existing behavior for current deployments.

🔒 Passwordless Login Configuration

⚠️ Important: Even with passwordless login configuration, an initial admin user is still created during the first startup. You must set a secure password for this admin user in your appsettings.json or docker-compose.yml file to ensure system security.

For organizations that want to enforce OAuth-only authentication, the application supports disabling password login entirely.

Disabling Password Login

Set DisablePasswordLogin to true to hide username/password fields:

{
  "OAuth": {
    "Enabled": true,
    "DisablePasswordLogin": true,
    "Authority": "https://your-provider.com",
    "ClientId": "your-client-id",
    "ClientSecret": "your-secret"
  }
}

Result: Login page displays only the "Login with OAuth" button.

Auto-Redirect to OAuth Provider

Enable AutoRedirect to automatically redirect users to your OAuth provider:

{
  "OAuth": {
    "Enabled": true,
    "DisablePasswordLogin": true,
    "AutoRedirect": true,
    "Authority": "https://your-provider.com",
    "ClientId": "your-client-id",
    "ClientSecret": "your-secret"
  }
}

Requirements:

  • DisablePasswordLogin must be true
  • OAuth.Enabled must be true

Result: Users see a brief loading screen and are automatically redirected to the OAuth provider.

Complete Passwordless Setup Example

{
  "OAuth": {
    "Enabled": true,
    "Authority": "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0",
    "ClientId": "your-client-id",
    "ClientSecret": "your-secret",
    "ClientScopes": ["openid", "profile", "email"],
    "DisablePasswordLogin": true,
    "AutoRedirect": true,
    "AdminEmails": ["admin@company.com", "it@company.com"]
  }
}

Security Considerations

  • Admin Email Provisioning: The OAuth provider is trusted to verify email addresses. Only add trusted addresses to AdminEmails.
  • Emergency Access: Consider keeping one password-based admin account for emergency access before fully disabling password login.
  • Testing: Thoroughly test OAuth authentication before disabling password login in production.
  • SSO Environment: Auto-redirect is best suited for single sign-on environments where all users authenticate via the same provider.

Note: This guide is current as of 2025. Identity provider services regularly update their interfaces and features, so some UI elements may differ. Always refer to the latest documentation from your identity provider for the most up-to-date information.