cjw/Oxicloud
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

doc: add OXICLOUD_SMTP_* variables + external variables user options

Browse Source
This commit is contained in:
Edouard Vanbelle
2026-06-02 00:10:08 +02:00
parent df438b8269
commit 8a05ee00cb
2 changed files with 88 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/config/env.md
+23
View File
@@ -172,6 +172,29 @@ Enables the Nextcloud-compatible API layer (`/remote.php/`, `/ocs/`, `/status.ph
| `OXICLOUD_NEXTCLOUD_INSTANCE_ID` | `ocnca` | Instance ID suffix used in `oc:id` formatting |
| `OXICLOUD_NEXTCLOUD_VERSION` | `28.0.4` | Emulated Nextcloud version reported to clients (format: `major.minor.patch`) |
## Outbound Email (SMTP)
Used by the magic-link invitation flow and the login-via-email flow. When `OXICLOUD_SMTP_HOST` is empty (the default), the feature is disabled and any endpoint that needs email returns 503.
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_SMTP_HOST` | — | SMTP server hostname or IP. Empty disables the feature. |
| `OXICLOUD_SMTP_PORT` | `587` | Submission port (587 STARTTLS, 465 implicit TLS, 25 plain) |
| `OXICLOUD_SMTP_USER` | — | SASL username. Leave empty for anonymous relay. |
| `OXICLOUD_SMTP_PASS` | — | SASL password |
| `OXICLOUD_SMTP_FROM` | — | `From:` mailbox; bare address or RFC 5322 name-address (`OxiCloud <noreply@example.com>`) |
| `OXICLOUD_SMTP_TLS` | `starttls` | Transport encryption: `starttls`, `tls`, or `none` (emits startup WARN) |
## Magic-Link Authentication
Configures the invite-by-email and login-via-email flows. Both require SMTP to be configured above.
| Variable | Default | Description |
|---|---|---|
| `OXICLOUD_MAGIC_LINK_TTL_HOURS` | `24` | Lifetime of a freshly-minted magic-link token, in hours |
| `OXICLOUD_ALLOW_EXTERNAL_USERS` | `true` | Kill switch for the whole flow. `false` makes `POST /api/grants` reject `subject.type = "email"` for unknown addresses and `POST /api/auth/magic-link/send` return its uniform stub without issuing a token. |
| `OXICLOUD_EXTERNAL_EMAIL_DOMAINS` | — | Comma-separated allowlist of email domains accepted when minting a new external user (case-insensitive, exact match on the post-`@` part). Empty = any domain is allowed, subject to `OXICLOUD_ALLOW_EXTERNAL_USERS`. Subdomains must be listed explicitly: `partner.com` does NOT match `eng.partner.com`. Example: `partner-a.com,partner-b.io`. |
## Trusted Proxy
| Variable | Default | Description |
example.env
+65
View File
@@ -311,6 +311,71 @@ OXICLOUD_WOPI_ENABLED=false
# Clients use this to decide which protocol features to enable.
#OXICLOUD_NEXTCLOUD_VERSION=28.0.4
# -----------------------------------------------------------------------------
# OUTBOUND EMAIL (SMTP)
# -----------------------------------------------------------------------------
#
# Used by the magic-link invitation flow (sharing with someone by email) and
# the login-via-email flow. When HOST is empty (the default), the feature is
# disabled and any endpoint that needs email returns 503.
# SMTP server hostname or IP. Empty = feature disabled.
#OXICLOUD_SMTP_HOST=smtp.example.com
# Submission port. Common values:
# 587 = STARTTLS submission (default)
# 465 = implicit TLS submission
# 25 = plain relay (development only)
#OXICLOUD_SMTP_PORT=587
# SASL username for SMTP AUTH. Leave empty for anonymous relay.
#OXICLOUD_SMTP_USER=oxicloud@example.com
# SASL password. Logged as `<set>` / `<anon>` in startup banner (never echoed
# in plaintext).
#OXICLOUD_SMTP_PASS=
# `From:` mailbox. Either a bare address or RFC 5322 name-address form.
#OXICLOUD_SMTP_FROM=OxiCloud <noreply@example.com>
# Transport encryption mode:
# starttls = port 587 with STARTTLS upgrade (default — recommended)
# tls = implicit TLS from the first byte (port 465)
# none = no encryption; emits a startup WARN, development only
#OXICLOUD_SMTP_TLS=starttls
# -----------------------------------------------------------------------------
# MAGIC-LINK AUTHENTICATION
# -----------------------------------------------------------------------------
#
# Knobs for the invite-by-email / login-via-email flows. Both rely on SMTP
# being configured above.
# Lifetime of a freshly-minted magic-link token, in hours. After this, the
# background sweeper marks the token expired. Must be > 0.
#OXICLOUD_MAGIC_LINK_TTL_HOURS=24
# Kill switch for the whole magic-link flow.
# true = POST /api/grants accepts `subject.type = "email"`; new external
# users are created lazily and invitation mails are sent.
# false = the same call returns 403; POST /api/auth/magic-link/send
# returns the uniform stub response without issuing a token.
# This is the coarse "turn it all off" switch; the per-domain allowlist
# below is the fine-grained version.
#OXICLOUD_ALLOW_EXTERNAL_USERS=true
# Allowlist of email domains accepted when minting a new external user.
# Comma-separated, case-insensitive, exact-match on the post-`@` part of the
# address. Empty (the default) = any domain is allowed, subject to
# OXICLOUD_ALLOW_EXTERNAL_USERS above.
#
# Wildcards / subdomain semantics are intentionally NOT supported:
# `partner.com` does not match `eng.partner.com`. List every subdomain
# explicitly when needed.
#
# Example (only addresses on these two domains can be invited):
#OXICLOUD_EXTERNAL_EMAIL_DOMAINS=partner-a.com,partner-b.io
# -----------------------------------------------------------------------------
# PROXY
# -----------------------------------------------------------------------------