Doc for administration interface

app/translations/messages.en.yml

@@ -272,7 +272,7 @@ Message:
   Flash:
     deleteSuccesFull: "Successful deletion"
     domainCreatd: "The domain has been successfully created"
-    domainUpdated: "The field has been successfully updated"
+    domainUpdated: "The domain has been successfully updated"
     missingRuleForDomain: "A rule must first be created for this domain"
     ruleExistForDomain: "A similar rule already exists in this area"
     domainRuleCreated: "The domain rule was created with success"
@@ -488,26 +488,26 @@ Entities:
       imapFlag: "IMAP security"
       active: "Active domain"
       transport: Transport
-      policy: "Policy for the field"
+      policy: "Policy for the domain"
       level: "Spam threshold"
-      mailAuthenticationSender: "Email address that sends authentication request"
+      mailAuthenticationSender: "Email address that sends authentication requests"
       imapNoValidateCert: Do not validate certificates
       defaultLang: "Default language"
       quota: Rate Limit
       quota_emails: Number of email during the period
       quota_seconds: Period duration
       addQuota: "Add a rate limit"
-      sendUserAlerts: "Send alerts to users dashboard in AgentJ"
+      sendUserAlerts: "Send alerts to users on the dashboard in AgentJ"
       sendUserMailAlerts: "Send alerts to users by email"
     labels:
       infos: "Informations"
       agentJConfig: "AgentJ configuration"
       connectors: "Connectors"
       rules: Rules
-      domainrules: "Rules of the field"
+      domainrules: "Rules of the domain"
       domaineSender: "sending domain"
-      domainMessages: "Messages from the field"
-      ipAddresses: "IP Address"
+      domainMessages: "Messages from the domain"
+      ipAddresses: "IP Address of the sending server"
       dns: "DNS"
       domain: DOMAIN
       auth: AUTH, USERS & ALIAS

docs/README.md

@@ -7,6 +7,7 @@
 - [Login with OAuth2](/docs/administrators/oauth2.md)
 - [Versioning policy](/docs/versioning.md)
 - [Changelog of AgentJ](/CHANGELOG.md)
+- [Administration via the web interface](/docs/administrators/webinterface.md)
 
 ## The Developers' Guides
 

docs/administrators/webinterface.md

@@ -0,0 +1,199 @@
+# Administration via the web interface
+
+When you are logged in to the web interface as an administrator, you have the ability to:
+
+- Configure AgentJ
+- Manage blocked emails, senders, etc. for each user
+
+The later part won't be covered on this documentation page, as the process is the same as for a regular user.
+
+## Managing a domain
+
+In order to manage a domain, you have to go to the `Domains` section in the sidebar. You have the ability to create a new domain or edit an existing one.
+
+The form is the same in both case:
+
+- Active domain: Tick the checkbox in order to enable the domain in AgentJ.
+- Domain name: The domain name you want to protect with AgentJ.
+- SMTP server: The domain name or IP address of your mail server.
+- SMTP port: The network port used by your mail server to receive emails (usually 25/TCP).
+
+> [!IMPORTANT]
+> You have to configure your existing mail server to unconditionally accept emails from AgentJ. Refer to your mail server's documentation.
+
+- Logo: The logo you want to use to replace the AgentJ logo in the web interface.
+- Default language: The default language for the web interface.
+- IP Address of the sending server: The IP address used by your mail server to send emails. Useful only if you also want outgoing mail to pass through AgentJ.
+
+In the DNS section there is the DKIM DNS record, which you have to put in the DNS zone of your domain. Every email generated by AgentJ or every outgoing mail passing through AgentJ will be signed with DKIM. The DNS section is only visible once the domain has been created. If this is a domain creation, hit `Save` to see the DNS record for DKIM.
+
+### Adding an auth connector
+
+Once your domain is created, you have to connect AgentJ to an authentication server. Outside of administrators, AgentJ doesn't store user passwords or password hashes. The authentication of users is done by the authentication server.
+
+For now, the following authentication servers are supported by AgentJ:
+
+- IMAP
+- LDAP
+- Office 365
+
+Depending on the connector, AgentJ will be able to import users into its database. If it is not possible, you will have to create users manually.
+
+You also have the ability to connect AgentJ to your SSO to streamline the connection process. This is done in the `.env` file. See the [Login with OAuth2](/docs/administrators/oauth2.md) page for more information.
+
+In order to add a connector, go to the `AUTH, USERS & ALIAS` in your domain configuration and click on `Add connector`.
+
+#### IMAP
+
+- Connector name: The display name you want to use for the connector.
+- Host: The domain name or IP address of your IMAP server.
+- Port: The port of your IMAP server (usually 993/TCP).
+- Encryption: The encryption type used for the connection.
+- Do not validate certificates: Tick to skip the validation of the certificate. Not recommended!
+
+> [!IMPORTANT]
+> Users connecting with this connector won't be imported automatically as your email server won't leak the entire list of the user. Even if you use this connector for authentication, you will have to create the users manually in AgentJ. See the dedicated section.
+
+#### LDAP
+
+- Connector name: The display name you want to use for the connector.
+- Host: The domain name or IP address of your LDAP server.
+- Port: The port of your LDAP server (389/TCP with no encryption, 636/tcp with encryption).
+- Encryption: The encryption protocol used to reach your LDAP server. Choose between None, SSL and TLS. None by default.
+- LDAP version: The version of your LDAP protocol. Choose between 2 and 3. 3 by default.
+
+Connection information
+
+- Anonymous connection: Tick if your LDAP server allows anonymous connection. Otherwise, fill in the following fields.
+- Bind DN: DN used to bind to the LDAP server.
+- Password: Password used to bind to the LDAP server with the previous bind DN.
+- Base DN: The base DN of your LDAP tree.
+
+Users information
+
+- Filter for users: LDAP filter used to get email accounts.
+- LDAP field for username: LDAP field in an entry corresponding to the username.
+- LDAP field for email: LDAP field in an entry corresponding to the email address.
+- LDAP field for alias (if different from email): LDAP field in an entry corresponding to the email alias(es).
+
+Advanced options
+
+- Assign user(s) to group(s): Assign users retrieved to this already existing group.
+- LDAP field for shared mailboxes: LDAP field in an entry corresponding to shared mailboxes.
+- Also synchronize groups: Synchronizes LDAP groups in AgentJ (same as internal groups, but synchronized with LDAP). Tick to enable and fill in the following fields.
+- Filter for groups: LDAP filter used to get groups.
+- LDAP field for group name: LDAP field in an entry corresponding to the group name.
+- LDAP field for group members: LDAP field in an entry corresponding to listing group members.
+
+Users will be automatically imported into the AgentJ database.
+
+#### Office 365
+
+Refer to the documentation of Office 365 to create a new connector in your Office 365 subscription.
+
+- Connector name: The display name you want to use for the connector.
+- Also synchronize groups: Synchronizes Office 365 groups in AgentJ (same as internal groups, but synchronized with Office 365). Tick to enable.
+- Tenant ID: The Office 365 connector tenant ID.
+- Client ID: The Office 365 connector client ID.
+- Client Secret: The Office 365 connector client secret.
+
+Users will be automatically imported into AgentJ database.
+
+### Adding rate limits
+
+You can configure rate limits in AgentJ. They can be used to limit the number of emails sent during a time span. Each rate limit is defined by:
+
+- A number of emails
+- A time span
+
+If a user tries to send more emails in the defined time span, the following emails will be blocked.
+
+For a user to be subject to rate limits, there are multiple ways:
+
+- At the domain level: Applies to each user of the domain individually.
+- At the group level: Applies to each user of the group individually.
+- At the user level: Applies to the user.
+
+There is a concept of precedence: a quota on a user overrides a quota on a group and a quota on a group overrides a quota on a domain.
+
+### Configuring filter levels
+
+> [!CAUTION]
+> Don't modify these settings unless you known exactly what you are doing!
+
+AgentJ allows you to customize the way it filters emails. You can choose to disable some filtering or make AgentJ less strict.
+
+On the `Filters & Rates` tab of a domain, you have the following parameters:
+
+- Filter threshold:
+    - Block all emails: Enable human authentication on incoming emails.
+    - Allow all emails: Disable human authentication on incoming emails.
+- Policy for the domain: Choose one policy created in the `Policy` tab. See the dedicated section.
+- Spam threshold: Each received email is rated with a score. The higher the score, the higher the chance that an email is spam. AgentJ marks an email as spam if its score is higher than this threshold. Depending on the context, you can choose to adjust this score in order to balance the number of false positives/false negatives.
+- Email address that sends authentication requests: The noreply email address used to send authentication requests and reports.
+- Rate limit: Refer to the previous section.
+
+### Alerts
+
+On the `Alerts` tab of a domain, you can tick two checkboxes:
+
+- Send alerts to users on the dashboard in AgentJ: Display alerts on the dashboard for admin users.
+- Send alerts to users by email: Send emails to administrators on alerts.
+
+Alerts can be generated if a user exceeds its rate limits or if a user sends a virus.
+
+## Users
+
+Users are managed under the `Users` tab.
+
+### Administrator
+
+On the `Administrator` tab you can manage privileged users. When editing or creating an admin, there are the following fields:
+
+- Name: The display name of the user.
+- Login: The username of the user.
+- Role:
+    - Local admin: This user has access to one or more domains.
+    - Super admin: This user has access to every domain.
+- Email: The email address of the user. Used for alerts.
+- Password: The password of the user.
+- Domain: The domain(s) the user has access to. This field is only displayed if the user is a Local admin.
+
+### Email accounts
+
+This tab is here to configure email accounts managed by AgentJ.
+
+> [!IMPORTANT]
+> If an email account is missing, emails sent to him will be rejected by AgentJ.
+
+As seen in the section dedicated to the authentication of users, some connectors are able to automatically import users. When using a connector not able to do that (or when using no connector), you have to create users manually in AgentJ.
+
+There are two ways for that.
+
+- Import a list of users from a text file. The format of the text file is defined in the pop-up opened after clicking on `Import from file`.
+- Create a user one by one. Click on `New user` for that.
+
+When you create or edit an user, there is the following fields:
+
+- Name: The display name of the user.
+- Email: The email address of the user.
+- Group: The group(s) the user belongs to. Not mandatory. Groups must be created before.
+- Shared with: If another user should be able to manage this user (Manage blocked mails, authorize senders, etc.). Not mandatory. An user can be shared with multiple users. The other user(s) must be created before.
+- Rate limit: See the dedicated section on the subject.
+- Send report: Tick the box if the user should receive daily reports by email about blocked emails.
+
+### Alias
+
+On the `Alias` tab, you can assign aliases to user. An alias is an email address which always point to one and only one other email address managed by AgentJ. For example mp@example.com could be an alias for martin.dupond@example.com.
+
+Each email sent to an alias is managed exactly as it was received directly by the user. It appears in the user reports, with every other email.
+
+> [!NOTE]
+> Even if the alias is created correctly in AgentJ, it has to be created accordingly on your email server. Refer to its documentation for that.
+
+### Policies
+
+> [!CAUTION]
+> Don't modify these settings unless you known exactly what you are doing!
+
+This section allows you to fine tune AgentJ behavior by altering Amavis configuration.