Introduction

This project sets up Authelia, an open-source authentication and authorization server, with ProtonMail Bridge for SMTP. Authelia fulfills the role of identity and access management (IAM), providing multi-factor authentication (2FA) and single sign-on (SSO) via a web portal. It integrates seamlessly with reverse proxies to enhance the security of your applications.

What is Authelia?

Authelia is an authentication server that:

• Provides multi-factor authentication.
• Enables secure single sign-on for web applications.
• Acts as a companion for reverse proxies.

What is ProtonMail Bridge?

ProtonMail Bridge allows ProtonMail accounts to work with email clients that support SMTP and IMAP. It creates a secure connection and forwards traffic, acting as a middleman. This setup enables Authelia to send password reset emails, 2FA codes, and account verification messages using a ProtonMail account.

---

Repository Structure

authbridge/
├── README.md                      # Project documentation
├── docker-compose.yml             # Main Docker Compose file
├── .env.example                   # Template for environment variables
├── config/                        # Authelia configuration
│   ├── configuration.yml          # Main Authelia configuration
│   └── users_database.yml         # User definitions
├── protonmail/                    # ProtonMail Bridge setup files
│   ├── Dockerfile                 # Container definition for ProtonMail Bridge
│   └── supervisord.conf           # Supervisor configuration for the Bridge

---

Network Architecture

graph TD
    subgraph Docker Host
        subgraph Authelia Network [authelia network - 172.xx.0.0/16]
            A[Authelia - 172.xx.0.2] --> |PostgreSQL| D[Database - 172.xx.0.3]
            A --> |Redis| R[Redis - 172.xx.0.4]

            subgraph ProtonMail Container [172.xx.0.5]
                PMB[ProtonMail Bridge - listening on 127.0.0.1:1025]
                S[Socat Proxy - listening on 0.0.0.0:2525]
                S --> |forward| PMB
            end

            A -->|SMTP on port 2525| S
        end

        subgraph Reverse Proxy Network [172.yy.0.0/16]
            A <--> |HTTP/HTTPS| RP[Reverse Proxy - 172.yy.0.2]
        end

        subgraph Volume Mounts
            PMB -.- PD[protonmail-data]
            A -.- AD[authelia config]
            R -.- RD[redis data]
            D -.- DD[postgres data]
        end
    end

    U[User] --> |HTTPS| RP

classDef note text-align:left;

Loading

Flow Explanation

1. Users interact with Authelia through the reverse proxy over HTTPS.
2. Authelia communicates with Redis and PostgreSQL for session management and data storage.
3. Authelia sends emails via the ProtonMail Bridge container.
4. ProtonMail Bridge uses Socat to forward SMTP traffic from 0.0.0.0:2525 to 127.0.0.1:1025.

---

Setup Instructions

1. Clone the Repository

git clone https://github.com/MinjaeKimmm/authbridge
cd authbridge

2. Generate .env File

Create the .env file with the required secrets:

echo "JWT_SECRET=$(tr -cd '[:alnum:]' < /dev/urandom | fold -w 64 | head -n 1)
SESSION_SECRET=$(tr -cd '[:alnum:]' < /dev/urandom | fold -w 64 | head -n 1)
STORAGE_PASSWORD=$(tr -cd '[:alnum:]' < /dev/urandom | fold -w 64 | head -n 1)
STORAGE_ENCRYPTION_KEY=$(tr -cd '[:alnum:]' < /dev/urandom | fold -w 64 | head -n 1)
REDIS_PASSWORD=$(tr -cd '[:alnum:]' < /dev/urandom | fold -w 64 | head -n 1)
SMTP_PASSWORD=your_protonmail_password" > .env && chmod 600 .env

After creating the .env file, edit SMTP_PASSWORD manually to include the password obtained from ProtonMail Bridge.

3. Update Configuration Files

Edit config/configuration.yml and config/users_database.yml to match your domain and user requirements.

Example for configuration.yml:

notifier:
  smtp:
    address: 'smtp://protonmail:2525'
    username: [email protected]
    sender: [email protected]
    tls:
      skip_verify: true

4. Set Up ProtonMail Bridge

4.1 Start ProtonMail Container

docker run -it --privileged -v $(pwd)/protonmail-data:/root protonmail-test /bin/bash

4.2 Inside the Container

1. Generate a GPG key:

   gpg --generate-key
   

   • Name: bridge-key
   • Email: Leave blank.
   • Passphrase: Leave blank.

2. Initialize pass:

   KEY_ID=$(gpg --list-secret-keys --keyid-format LONG | grep sec | awk '{print $2}' | cut -d'/' -f2)
   
   pass init "$KEY_ID"
   

3. Start the Bridge CLI:

   protonmail-bridge --cli
   

4. Once in CLI, login with your ProtonMail credentials.

5. Wait until protonmail fully syncs

6. Once syncing is finished, save the SMTP password.

7. Exit the container.

5. Edit the .env File

Edit the .env file with the SMTP password:

vi .env

6. Generate Password Hash for Users

docker run --rm -it authelia/authelia:latest authelia crypto hash generate argon2

Copy the hash to config/users_database.yml.

7. Start Services

docker compose up -d

8. Verify Setup

Check logs to ensure all services are running correctly:

docker logs authelia
docker logs protonmail-bridge

---

Debugging and Troubleshooting

Network Connectivity

# Check listening ports
docker exec [container] netstat -tulpn

# Test SMTP connection
docker exec [container] socat - TCP:127.0.0.1:1025

# Check container DNS
docker exec [container] ping [service-name]

Container Logs

# General logs
docker logs [container]

# Specific ProtonMail logs
docker exec protonmail-bridge cat /var/log/protonmail-bridge.err.log

Common Issues

• Connection Refused: Verify services are running and ports are accessible.
• TLS Errors: Ensure tls.skip_verify is set to true if using self-signed certificates.
• Service Dependencies: Check service startup order and healthchecks.