Setup SMTP

How to Set Up SMTP Notifications for Authelia

Authelia supports sending email notifications via an SMTP server, which is essential for account management and security events like password recovery and login alerts. This guide will walk you through configuring SMTP notifications for Authelia.

Prerequisites

• An SMTP server (e.g., Gmail, custom domain SMTP server)
• Access to your configuration.yml file
• Basic knowledge of YAML and email server parameters

Configuration File Example

Below is a basic example of the notifier section in the configuration.yml file:

notifier:
  disable_startup_check: false
  smtp:
    address: 'smtp://127.0.0.1:25'
    timeout: '5s'
    username: 'test'
    password: 'password'
    sender: "Authelia "
    identifier: 'localhost'
    subject: "[Authelia] {title}"
    startup_check_address: '[email protected]'
    disable_require_tls: false
    disable_starttls: false
    disable_html_emails: false
    tls:
      server_name: 'smtp.aeoneros.com'
      skip_verify: false
      minimum_version: 'TLS1.2'
      maximum_version: 'TLS1.3'
      certificate_chain: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----        
      private_key: |
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----

Key Configuration Options

• address: The SMTP server's address. Must include the protocol (smtp, submission, or submissions).
• username: The username for SMTP authentication. Pair it with a password.
• password: The password for SMTP authentication. It is strongly recommended to use a secret for containerized environments.
• sender: The email address used for the "From" field. Must follow RFC5322 format.
• identifier: The identifier sent with HELO/EHLO commands. Avoid using localhost for external SMTP services.
• subject: The subject template for emails, supporting the {title} placeholder.
• tls: Optional TLS settings, including minimum/maximum versions and custom certificate chains.

Using Gmail

If you are using Gmail as your SMTP server, you must generate an App Password. Configure the notifier section as follows:

notifier:
  smtp:
    address: 'submission://smtp.gmail.com:587'
    username: '[email protected]'
    password: 'your-app-password'
    sender: "Admin "

Follow Google's documentation to generate an app password: Generate App Password.

Testing the Configuration

To test your configuration, restart Authelia and check the logs:

docker logs authelia

Ensure no errors related to the SMTP connection appear. Use the startup_check_address to validate the SMTP setup without sending actual emails.

Troubleshooting

• Ensure the SMTP server address and port are correct.
• Verify credentials are correct and have sufficient permissions.
• Check the logs for specific error messages.
• Review Authelia's official documentation for advanced troubleshooting tips.

With the correct configuration, SMTP notifications enhance user experience and provide critical security alerts seamlessly.