OpenCloud with Authentik-MFA: direct at home, via Tailscale on the go or publicly via Cloudflare – without your own public IP

[LHBL2003]

Use the full LAN speed at home with your family, securely access OpenCloud and your home network via Tailscale-VPN on the go, and share files with friends and acquaintances – without any VPN. No static public IP, additional protection through Authentik with MFA/2FA, and almost no ongoing cloud service costs. All you need is your own domain address.

The vision

Family photos should be accessible on the go – but not with a stolen password alone. This guide adds Authentik and an email code to the OpenCloud login without recreating existing user accounts, files, or Spaces. Further MFA authentication options should then be easy to implement.

At home, access goes directly to the NAS. Family members mainly use Tailscale on the go; on someone else's computer, a browser accessing through Cloudflare Tunnel is enough. This requires neither your own public IP nor a rented server, also called a VPS. If a NAS, internet connection, and email sending are available, ideally only the domain costs should be added.

The aim was to make OpenCloud and Immich shares and Home Assistent accessible from outside via MFA, but in a way that OpenCloud WebDav and the Home Assistant Alexa Skill continue to work without being blocked by MFA. Here we set up the OpenCloud integration. Immich and Home Assistant need their own configuration, but this establishes the foundation.

What works afterwards:

• Login in the web browser and in the iPhone and Windows apps via Authentik.
• Access to the existing OpenCloud accounts through consistent usernames.
• WebDAV for scanners and WebDAV clients with an OpenCloud app token.
• Direct file access on the home network and through Tailscale, without the Cloudflare upload limit.
• Browser access without Tailscale through Cloudflare: 100 MB per upload request applies there, not as a size limit for downloads. Larger videos can generally be downloaded, just not uploaded.

Note: MFA protects account login, not automatically public share links or every API request. Shares require their own permissions, and where appropriate a password and expiration date. The Alexa integration also works with account linking and tokens; an interactive login page placed in front of it can interrupt this connection.

🌐 I hope the translation from German into English is correct :)
✍️ I’ve documented it retrospectively and hope that nothing is missing. If anything is, please feel free to post the relevant section with a correction. Ideally, include ‘before’ and ‘after’ versions. I’ll then be happy to update it accordingly.

Contents

• 1. Starting point and example values
• 2. How the connections work
• 3. Map existing users
• 4. Create OpenCloud clients in Authentik
• 5. Set up DNS and Nginx Proxy Manager
• 6. Set up email code and login flow
• 7. Activate Authentik in the OpenCloud stack
• 8. Connection tests for apps and WebDAV
• 9. Access through Tailscale on the go
• 10. Set up public access through Cloudflare
• 11. Narrow down errors systematically
• 12. Return to the previous login
• Appendix A: Automatically lowercase profile details
• Appendix B: Set up TOTP with KeePassXC as an additional MFA method

1. Starting point and example values

OpenCloud is already running: users can log in and access their files. Authentik, Nginx Proxy Manager (NPM), and AdGuard Home are also installed and administrable. This guide connects these services; it does not start with Docker or NAS installation.

The setup described uses Docker Compose on a UGREEN NAS 4800 Pro. Komodo manages the stacks. The same Compose files can be used without Komodo.

For the public route, we need an internet domain such as example.com with DNS management at Cloudflare. The domain may have been purchased from another provider. A website is not part of this. Authentik also needs SMTP access to send the login codes.

Replace these values

Purpose	Example
Your own domain	example.com
OpenCloud address	https://opencloud.example.com
Authentik address	https://authentik.example.com/
NAS and NPM	192.168.10.20
AdGuard Home	192.168.10.20
Home network	192.168.10.0/24
Username in OpenCloud and Authentik	alex
User's email	alex@example.com

AdGuard and NPM may run on other devices; in that case, enter their respective IP addresses. All paths and domains in this guide are examples. opencloud.example.com represents your own OpenCloud address; anyone using cloud.meinedomain.de, for example, substitutes it everywhere.

Setup versions

Component	Version
OpenCloud	7.5.0 Rolling
Authentik	2026.8.1
Nginx Proxy Manager	2.15.1
Komodo	1.19.5
Tailscale on the NAS	1.102.3
cloudflared	2026.8.2

The browser, iPhone app, Windows client, and WebDAV were used. The Android entries are included as a supplement but have not been tested in practice.

2. How the connections work

At home

PC / Smartphone
  ├── DNS query --> AdGuard Home
  │                    opencloud.example.com -> 192.168.10.20
  │                    authentik.example.com -> 192.168.10.20
  │
  └── HTTPS --> NAS:443 / Nginx Proxy Manager
                  ├── opencloud.example.com --> HTTP NAS:9200 / OpenCloud
                  └── authentik.example.com --> HTTP NAS:9700 / Authentik

AdGuard supplies the IP address; files then pass through NPM to OpenCloud. Authentik handles login, not file transfers. 9700 is the published NAS port for Authentik here, not its internal container port.

On the go with Tailscale

Your own device with Tailscale
  ├── DNS via Tailscale --> AdGuard on the home network --> NAS-IP
  └── HTTPS via Tailscale --> NAS as subnet router --> NPM:443
                                                         ├── OpenCloud
                                                         └── Authentik

Split-DNS provides the internal NAS IP; the subnet route makes it reachable. Simply enabling Tailscale is not enough: if DNS still returns the public address, access may still go through Cloudflare.

Without Tailscale, for example on someone else's computer

Browser on the internet
  └── HTTPS --> Cloudflare
                  └── Tunnel --> cloudflared on the NAS
                                   └── HTTPS --> NPM:443
                                                   ├── OpenCloud
                                                   └── Authentik

cloudflared establishes the outbound connection. This route therefore requires neither a public NAS IP nor inbound router port forwarding. An ordinary Cloudflare DNS entry alone does not replace the tunnel. With public access, the browser's TLS connection initially terminates at Cloudflare; LAN and Tailscale lead directly to NPM.

What happens during login

Browser/App --> OpenCloud
           --> Authentik: username, password, email code
           <-- Redirect with authorization code
           --> Authentik: exchange authorization code for tokens
           --> OpenCloud: access with token

OpenCloud reads preferred_username = alex
           --> finds the existing account username = alex
           --> uses its role and Space permissions

The login protocol is called OpenID Connect (OIDC). Authentik issues the tokens and is the Issuer. preferred_username is a user detail transmitted in them, a Claim. The desktop client additionally protects the code exchange with PKCE.

The OpenCloud container must also be able to reach Authentik through DNS and HTTPS. A visible login page only proves that the browser can get there. The NAS and clients also need a correctly synchronized clock for token validation.

3. Map existing users

Step 1: Align usernames

Explanation

We link accounts through the username: alex in Authentik belongs to alex in OpenCloud. The existing OpenCloud account is adjusted for this; no new one is created.

All usernames are consistently lowercase. The reason for this is Home Assistant, which uses lowercase usernames. This means we do not need an additional conversion rule. Separate names such as Alex and alex must not later map to the same target account through lowercasing. A case-insensitive login lookup does not replace this consistent storage. In Authentik, you can create the users Alex and alex; these are two different users, which is why capitalization matters.

Configuration

1. In OpenCloud → Administration → People, open the existing account using the pencil or ⋮ → Edit.
2. Set Login name to the desired lowercase name, for example alex, and save.
3. In Authentik → Directory → Users, set the same name for the corresponding user.

Note: First name, last name, and email do not determine this mapping. Authentik may allow login by email; the username is still passed to OpenCloud.

Step 2: Prevent users from changing their own usernames

Explanation

If alex changes his name to alex-neu in his Authentik profile, OpenCloud can no longer find the associated account. Users must therefore not be allowed to change their login name themselves.

Configuration

In Authentik 2026.8.1, changing one's own username is already disabled by default. Only if this feature was previously enabled: Under Authentik → System → Settings, disable Allow users to change username and save. Authentik default value

Anyone who also wants to lowercase profile details when saving can find the optional policy in the appendix. It is not required for account mapping.

4. Create OpenCloud clients in Authentik

Step 3: Create applications with OIDC providers

Explanation

The web browser, desktop, and iPhone use different client IDs and redirect addresses. Each client therefore receives its own provider. They all use the same issuer and signing key.

Configuration

In Authentik → Applications → Applications, create the following applications, each with an OAuth2/OpenID Connect Provider. If the interface offers the two separately, first create the provider under Applications → Providers and then assign it to the application.

Application	Application-Slug	Client ID
OpenCloud Web	opencloud-web	web
OpenCloud Desktop	opencloud-desktop	OpenCloudDesktop
OpenCloud iOS	opencloud-ios	OpenCloudIOS
OpenCloud Android, optional	opencloud-android	OpenCloudAndroid

For each new provider, set or add these details. Fields not listed remain at their preset values:

Field	Setting
Client Type	Public
Authorization Flow	default-provider-authorization-implicit-consent
Signing Key	the same for all, here authentik Self-signed Certificate
Scopes	For desktop, iOS, and Android if applicable, additionally select the default mapping offline_access
Issuer mode	Same identifier is used for all providers

Add the redirect addresses from step 4 to the respective provider and save. openid, profile, and email are already selected when creating a new provider; no additional scope is needed for the web provider. Authentik 2026.8.1: Scope presets

Note: implicit-consent in the "Authorization-Flow" name does not mean that the Implicit grant needs to be enabled. The signing key is also not the HTTPS certificate from NPM. The web client below requests only openid profile email; native clients additionally need offline_access for renewable sessions.

Step 4: Enter redirect addresses

Configuration

In Authentik → Applications → Providers → edit the respective provider → Redirect URIs/Origins, enter the appropriate addresses.

OpenCloud Web: Mode Strict, type Authorization, one line each:

https://opencloud.example.com/oidc-callback.html
https://opencloud.example.com/oidc-silent-redirect.html
https://opencloud.example.com/

OpenCloud Desktop: Mode Regex, type Authorization, one line each:

^http://127\.0\.0\.1(:[0-9]+)?/?$
^http://localhost(:[0-9]+)?/?$

This returns the browser to the OpenCloud client on the PC. Its port changes; a fixed NAS address would be wrong here. These two entries replace earlier, broader regex patterns.

OpenCloud iOS: Mode Strict, type Authorization:

oc://ios.opencloud.eu

OpenCloud Android, optional: Mode Strict, type Authorization:

oc://android.opencloud.eu

Note: The app addresses remain unchanged, even with your own domain. Do not enter a blanket permission with .*. If another client version uses a different callback, specifically add its address.

Step 5: Assign applications and providers

Configuration

In Authentik → Applications → Applications, open each OpenCloud application:

If the application was created together with its provider in step 3, the assignment is already complete. Only for applications and providers created separately, select the appropriate provider and save.

Optionally, an icon can be added under UI settings.

Note: Without application bindings, Authentik generally allows all its users access to the application. In this setup, OpenCloud still requires an existing account with a matching username; file and Space permissions continue to apply there. An additional restriction to specific Authentik groups is optional and is not set up here. The MFA stage bindings in chapter 6 are unaffected by this. Authentik: Application access

5. Set up DNS and Nginx Proxy Manager

Step 6: Resolve to the NAS IP on the home network

Explanation

AdGuard should answer both domains with the internal NAS IP. This keeps logins and file transfers at home from going through Cloudflare.

Configuration

In AdGuard Home → Filters → DNS rewrites or Filters → DNS rewrites, create these rules:

Domain	Answer
opencloud.example.com	192.168.10.20
authentik.example.com	192.168.10.20

Then query your own domains in Windows PowerShell:

Resolve-DnsName opencloud.example.com
Resolve-DnsName authentik.example.com

The NAS IP must appear under IPAddress. This checks the desired name resolution, but does not by itself prove which DNS server answered.

Note: AdGuard should be set as the DNS server in the router's DHCP distribution. And a public provider for „Secure DNS“ in Chrome or differing IPv6 answers can bypass the local route.

Step 7: Set up the domain and HTTPS certificate

1. Buy a domain from Cloudflare

Explanation

For this setup, we buy a new domain directly from Cloudflare. It serves as the common base for addresses such as opencloud.example.com and authentik.example.com. The subdomains are set up later and do not need to be purchased individually.

Choose an available name with an inexpensive extension, for example meine-domain.uk, provided that name is still available. It does not have to be your country's extension: for the functions described here, .de, for example, offers no technical advantage over .uk or .com. Prices and registration conditions differ depending on the extension. Therefore, compare not only the purchase price but also the annual renewal costs. .uk is an example, not a guarantee of the lowest price at any given time.

Configuration

1. Create an account or log in to the Cloudflare dashboard.
2. Open Domains → Overview on the left and click Buy domain at the top right.
3. Search for the desired domain name – without https:// and without opencloud. in front of it. Compare available names and extensions.
4. Select Purchase for the desired domain. Enter the required contact and payment details, check the term and renewal, and complete the purchase.
5. If Cloudflare requests email address verification, open the verification link sent to you.
6. Under Domains → Overview, check whether the new domain appears with status Active. Then continue with 2. Create an HTTPS certificate in NPM.

Cloudflare also sets up DNS management for the domain purchased there; no manual nameserver change is needed. The domain costs the displayed registration or renewal fee. A paid website plan is not necessary for this setup. Cloudflare: Buy a domain

Note: An existing domain can also be connected to Cloudflare without necessarily transferring it to Cloudflare as the domain provider. This alternative route is not described here. If the domain is already active at Cloudflare, the purchase can be skipped. Cloudflare: Add an existing domain In the following examples, example.com is a placeholder for your own domain.

2. Create an HTTPS certificate in NPM

Explanation

The NAS does not use its own publicly reachable IP or an inbound internet port 80, so a DNS-Challenge is needed. This still allows Let's Encrypt to confirm the domain through a DNS entry. This DNS-Challenge therefore works without public access to the NAS.

Configuration

If a suitable certificate does not yet exist:

1. In Cloudflare → click the user icon at the top right → Profile → API Tokens → Create Token → Edit zone DNS → Use template → Permissions: Zone → DNS → Edit → Zone Resources: Include → Specific zone → example.com → Continue to summary → Create Token → copy token
2. In NPM → Certificates → Add Certificate → Let's Encrypt via DNS
3. Domain Names: enter example.com and *.example.com (type and click "Create example.com" below to apply).
4. Use DNS-Challenge: select DNS Provider Cloudflare and enter the token in the credentials field.
5. Request the certificate.
6. The status only becomes In Use when the certificate is used in **Proxy Hosts".

This can also secure immich.example.com and ha.example.com. *.example.com does not cover deeper names such as app.intern.example.com.

Note: Further details are available from NPM and the Cloudflare DNS plugin. The token stays private. A Cloudflare Origin certificate alone is not sufficient for trusted HTTPS during direct LAN access such as MyNas.local.

Step 8: Create the two proxy hosts

Explanation

The client reaches NPM through NAS-IP:443. NPM then communicates through the NAS IP with the published port of OpenCloud or Authentik – not with 127.0.0.1 inside its own container.

Configuration

1. On the NAS, make ports 80 and 443 available for NPM. If a NAS service occupies these ports, change its port assignment or disable it; keep NAS administration reachable through its separate administration port. This does not mean router port forwarding. On Ugreen, you can disable use of the ports under Control Panel → Device Connection → Port Settings --> Port 80 / 443 to make them available for NPM. The NAS remains reachable through ports 9999 and 9443.
2. In NPM → Hosts → Proxy Hosts → Add Proxy Host, create both hosts.
3. Set the following settings. The option switches are initially off when creating a new host; explicitly enable those marked on. Enter your own NAS IP and published ports.

Setting	OpenCloud	Authentik
Domain Names	opencloud.example.com	authentik.example.com
Scheme	http	http
Forward Hostname / IP	192.168.10.20	192.168.10.20
Forward Port	9200	9700
Access List	Publicly Accessible	Publicly Accessible
Cache Assets	off	off
Block Common Exploits	off	off, see below
Websockets Support	on	on
SSL certificate	example.com, *.example.com	the same certificate
Force SSL	on	on
HSTS Enabled	on	on
HTTP/2 Support	off	on

Note on the switches:

• Block Common Exploits on the Authentik host can reject the desktop callback redirect_uri=http://127.0.0.1:PORT. This results in 403 Forbidden – openresty, before Authentik even processes the login. Therefore, turn it off there; redirect validation in Authentik remains in place.
• Leave Cache Assets turned off. Access List = Publicly Accessible prevents an additional NPM login in front of OpenCloud and Authentik that could interfere with apps or WebDAV. OpenCloud continues to handle account login through Authentik.
• Only enable HSTS once HTTPS is working and the certificate is valid: the browser then remembers that HTTPS is mandatory.
• HTTP/2 Support off for OpenCloud and Block Common Exploits off for OpenCloud correspond to this setup. It has not been established that both settings are generally necessary. In particular, HTTP/2 has not been proven to be the cause of the transfer errors described later.

The OpenCloud port 9200 is made available in chapter 7 through its Compose file list. Until then, the new OpenCloud proxy host may not yet be reachable.

Step 9: Provide a shared discovery address

Explanation

OpenCloud and the apps need the login information at https://authentik.example.com/.well-known/openid-configuration. NPM forwards exactly this address to the web provider already created.

Configuration

1. In NPM, reopen the proxy host authentik.example.com for editing.
2. Click the gear icon.
3. Under Custom Nginx Configuration, enter the following block and save. Adjust the IP and Authentik port; opencloud-web is the Application-Slug from chapter 4.

location = /.well-known/openid-configuration {
    proxy_pass http://192.168.10.20:9700/application/o/opencloud-web/.well-known/openid-configuration;

    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Do not add an additional server block or a second location /. The change belongs in NPM, not in its automatically generated files.

Check

Open https://authentik.example.com/.well-known/openid-configuration in the browser. The response must contain JSON, with issuer exactly https://authentik.example.com/ and publicly usable HTTPS endpoints. If you get a login page, 404, or an internal container address, check the proxy rule, Application-Slug, and issuer setting. All providers must use the same signing key because the shared discovery points to the web provider. Authentik/OpenCloud integration

6. Set up email code and login flow

Step 10: Prepare email sending and the email stage

Explanation

OpenCloud's mail configuration does not apply to Authentik. Authentik needs its own SMTP settings and a stage that sets up the email authenticator.

Configuration

Enter the credentials in the Authentik stack's .env:

EMAIL_USERNAME=mail@gmail.com
EMAIL_PASSWORD=TheGmailAppPassword
EMAIL_FROM=mail@gmail.com

These short variable names only work if the Compose file passes them to Authentik under environment for server and worker:

# Email
  server:
    image: ghcr.io/goauthentik/server:2026.8
    container_name: Authentik-SERVER
    environment:
      AUTHENTIK_EMAIL__HOST: smtp.gmail.com
      AUTHENTIK_EMAIL__USE_TLS: true
      AUTHENTIK_EMAIL__USE_SSL: false
      AUTHENTIK_EMAIL__PORT: 587
      AUTHENTIK_EMAIL__USERNAME: ${EMAIL_USERNAME}
      AUTHENTIK_EMAIL__PASSWORD: ${EMAIL_PASSWORD}
      AUTHENTIK_EMAIL__FROM: ${EMAIL_FROM}
      ...

Do not enable both encryption options (TLS/SSL). Then redeploy the Authentik stack. SMTP settings

Then, in Authentik → Flows and Stages → Stages:

1. Create an Email Authenticator Setup Stage named mfa-email-setup.
2. Optionally set Authenticator type name to E-Mail-Code; this is only the displayed name of the factor.
3. Save. The Use global connection settings option, already enabled when creating a new stage in the web interface, uses the SMTP values entered above. Authentik 2026.8.1: Email stage form

Note: Do not select the general Email Stage for verification or recovery. For the second factor, we need the Email Authenticator Setup Stage. The user must have a reachable mailbox recorded.

Step 11: Combine the password prompt and make MFA mandatory

Explanation

Username and password should be requested on the same login page. Authentik then requires a second factor. Without a configured factor, the MFA check must not be skipped as it is by default; instead, email setup is started.

Configuration

In Authentik → Flows and Stages → Flows, click the blue name default-authentication-flow in the Identifier column – not the pencil icon. Open the Stage Bindings tab.

1. Under default-authentication-identification → Edit Stage, select the existing default-authentication-password in the Password stage field and save.
2. Remove the separate row Order 20 → default-authentication-password, type Password Stage, from Stage Bindings. Password stage itself: is now used by the Identification stage.
3. Under default-authentication-mfa-validation → Edit Stage, change only these two settings and save:

Field	Change
Not configured action	Change from Skip to Force the user to configure an authenticator
Configuration stages	Select mfa-email-setup created in step 10; use only this setup stage

The sequence then looks like this:

10   default-authentication-identification
       └── Password stage: default-authentication-password
30   default-authentication-mfa-validation
100  default-authentication-login

Note: Users with an allowed second factor already configured can continue to use it. Selecting mfa-email-setup determines setup for users without a suitable factor; it does not enforce email exclusively for all users.

Step 12: Check the login

The default brand already uses default-authentication-flow; reassignment is not necessary. Other applications using this flow also receive the MFA rules. Authentik 2026.8.1: Default brand

Only if the flow assignment was previously changed: In Authentik → Applications → Providers → OpenCloud provider → Advanced flow settings → Authentication Flow, select the default-authentication-flow edited here. This is not an additional step for an unchanged default installation.

Check

Open Authentik in a new private browser window and log in with a regular user. The email must arrive; an incorrect code must not complete the login.

Note: Existing Authentik sessions can avoid another password/MFA prompt. seconds=0 on the Validation stage does not invalidate an existing SSO session. Password and MFA recovery are separate processes and are not automatically protected by this login flow.

7. Activate Authentik in the OpenCloud stack

Step 13: Explain and place the files

Explanation

Two files are needed for the integration: authentik-idp.yml configures the OpenCloud container, and csp.yaml adds browser permissions. Both belong to the OpenCloud setup, not in the Authentik stack. In this step, you place them; they are activated in step 15.

authentik-idp.yml – Login and account mapping

The additional Compose file switches login to Authentik. It maps Authentik users to existing OpenCloud accounts through the username and prevents new accounts from being created automatically. It also mounts the CSP file read-only in the container.

These settings are already included in the template:

Setting	Effect
PROXY_USER_OIDC_CLAIM: preferred_username	read the username from Authentik
PROXY_USER_CS3_CLAIM: username	find the existing OpenCloud account through this name
PROXY_AUTOPROVISION_ACCOUNTS: false	do not create new accounts through login
PROXY_ROLE_ASSIGNMENT_DRIVER: default	do not take roles from an OIDC role claim
GRAPH_ASSIGN_DEFAULT_USER_ROLE: true	assign the default role if none exists yet
OC_EXCLUDE_RUN_SERVICES: idp	disable the built-in login service while using Authentik

An Authentik account alone is not enough: alex must also exist in OpenCloud. Roles and Space permissions remain in OpenCloud. This reuses existing accounts instead of creating separate accounts for Authentik. The way back to the previous login is described in section 13. OpenCloud: External IdP

Configuration

1. Open the custom folder in the existing OpenCloud stack directory.
2. Create authentik-idp.yml there, paste the contents of the following collapsible box, and save.

🔵 authentik-idp.yml – show full file contents (open collapsible box here)

---
# External login service; keep the existing user directory.
# Example: IDP_DOMAIN=authentik.example.com
services:
  opencloud:
    environment:
      OC_EXCLUDE_RUN_SERVICES: "idp"
      OC_OIDC_ISSUER: "${IDP_ISSUER_URL:?IDP_ISSUER_URL setzen}"
      IDP_DOMAIN: "${IDP_DOMAIN:?IDP_DOMAIN setzen}"
      PROXY_OIDC_REWRITE_WELLKNOWN: "true"
      PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD: "jwt"
      OC_OIDC_CLIENT_ID: "${OC_OIDC_CLIENT_ID:-web}"
      OC_OIDC_CLIENT_SCOPES: "${OC_OIDC_CLIENT_SCOPES:-openid profile email}"
      WEB_OIDC_CLIENT_ID: "${OC_OIDC_CLIENT_ID:-web}"
      WEB_OIDC_SCOPE: "${OC_OIDC_CLIENT_SCOPES:-openid profile email}"
      WEBFINGER_WEB_OIDC_CLIENT_ID: "${WEBFINGER_WEB_OIDC_CLIENT_ID:-web}"
      WEBFINGER_WEB_OIDC_CLIENT_SCOPES: "${WEBFINGER_WEB_OIDC_CLIENT_SCOPES:-openid profile email}"
      WEBFINGER_DESKTOP_OIDC_CLIENT_ID: "${WEBFINGER_DESKTOP_OIDC_CLIENT_ID:-OpenCloudDesktop}"
      WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPES: "${WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPES:-openid profile email offline_access}"
      WEBFINGER_IOS_OIDC_CLIENT_ID: "${WEBFINGER_IOS_OIDC_CLIENT_ID:-OpenCloudIOS}"
      WEBFINGER_IOS_OIDC_CLIENT_SCOPES: "${WEBFINGER_IOS_OIDC_CLIENT_SCOPES:-openid profile email offline_access}"
      WEBFINGER_ANDROID_OIDC_CLIENT_ID: "${WEBFINGER_ANDROID_OIDC_CLIENT_ID:-OpenCloudAndroid}"
      WEBFINGER_ANDROID_OIDC_CLIENT_SCOPES: "${WEBFINGER_ANDROID_OIDC_CLIENT_SCOPES:-openid profile email offline_access}"
      PROXY_USER_OIDC_CLAIM: "preferred_username"
      PROXY_USER_CS3_CLAIM: "username"
      PROXY_AUTOPROVISION_ACCOUNTS: "false"
      PROXY_ROLE_ASSIGNMENT_DRIVER: "default"
      GRAPH_ASSIGN_DEFAULT_USER_ROLE: "true"
      PROXY_CSP_CONFIG_FILE_LOCATION: "/etc/opencloud/csp.yaml"
    volumes:
      - "${OC_CONFIG_DIR:?OC_CONFIG_DIR setzen}/csp.yaml:/etc/opencloud/csp.yaml:ro"

Note – only for custom changes: OC_EXCLUDE_RUN_SERVICES determines which OpenCloud services do not start. Our authentik-idp.yml enters idp there, disabling the previous login service. If you have already disabled other services through this parameter, their names must remain in this line, with idp added. Otherwise, they could start again. Without such custom entries, nothing needs to be changed.

csp.yaml – Browser permissions

The csp.yaml specifies which additional sources the browser may load for OpenCloud. It supplements the rules OpenCloud already includes. The template therefore contains only the additions for this setup; for example, diagrams.net is already allowed by default.

For Euro Office, permission under frame-src is required. The document editor is displayed within the OpenCloud website but comes from a different address. The Compose file tells OpenCloud this address; only the CSP allows the browser to embed the editor.

Without this entry, both creating Office documents and Open with Euro Office for existing DOCX files failed when reproducing the setup. The editor is blocked in the browser; this does not indicate whether a file has already been created on the server side. Therefore, keep the Euro Office entry. Explanation of frame-src

The other entries allow:

• connect-src: Requests from the OpenCloud web interface to Authentik for login.
• frame-src for Authentik: Embedded login windows, if the web client uses them. A normal redirect does not need this permission.
• media-src: Audio and video through blob: addresses generated in the browser.
• worker-src: Background scripts from OpenCloud itself ('self') and through blob: addresses. These scripts may be needed depending on the web application.

The template uses PROXY_CSP_CONFIG_FILE_LOCATION to supplement the defaults of OpenCloud 7.5.0. Do not switch to PROXY_CSP_CONFIG_FILE_OVERRIDE_LOCATION: that would replace the defaults, for which this short file alone is not sufficient.

Configuration

1. On the NAS, go to the existing OpenCloud configuration folder that OC_CONFIG_DIR points to, for example /volume1/docker-ssd/komodo/docker/opencloud/config.
2. Create csp.yaml there, paste the contents of the following collapsible box, and save. The placeholders remain unchanged; their values come from the stack environment in step 14.

🔵 csp.yaml – show full file contents (open collapsible box here)

---
# Adds to OpenCloud's browser permissions for Authentik,
# Euro Office, media, and background scripts.
directives:
  # Requests to Authentik for login.
  connect-src:
    - "https://${IDP_DOMAIN|authentik.opencloud.test}/"
  # Embedded web pages (iframes).
  frame-src:
    # Required to create and open documents in Euro Office.
    - "https://${EURO_OFFICE_DOMAIN|euro-office.opencloud.test}/"
    # For login flows that load Authentik in an iframe.
    - "https://${IDP_DOMAIN|authentik.opencloud.test}/"
  # Audio and video through media addresses generated by the browser.
  media-src:
    - "blob:"
  # Background scripts from OpenCloud and browser sources.
  worker-src:
    - "'self'"
    - "blob:"

Note on placement: The csp.yaml is stored permanently in the configuration folder on the NAS – not under custom and not directly in the container. The authentik-idp.yml makes it available read-only to OpenCloud at /etc/opencloud/csp.yaml. This preserves it when the container is recreated. User files do not belong in this configuration folder. The file extensions differ: authentik-idp.yml and csp.yaml.

/volume1/docker-ssd/komodo/
├── stacks/opencloud/
│   ├── docker-compose.yml        existing base
│   ├── .env                      OpenCloud stack environment
│   └── custom/
│       └── authentik-idp.yml     additional Compose file
└── docker/opencloud/
    └── config/
        └── csp.yaml              browser connection rules

Step 14: Add to the OpenCloud environment

Explanation

The files from step 13 use variables for the addresses. You therefore enter the Authentik address in the OpenCloud stack environment instead of replacing it in the YAML files.

Configuration

1. Open the OpenCloud stack .env or Komodo → Stacks → opencloud → Config → Environment.
2. Add the two values using your own Authentik domain:

IDP_DOMAIN=authentik.example.com
IDP_ISSUER_URL=https://authentik.example.com/

IDP_DOMAIN contains only the hostname; IDP_ISSUER_URL includes https:// and the trailing slash.

3. Keep the existing values for OC_DOMAIN, OC_CONFIG_DIR, and OC_DATA_DIR. If OC_CONFIG_DIR is currently missing, enter the existing configuration folder from step 13.
4. Save the changes.

Note: The authentik-idp.yml passes IDP_DOMAIN to OpenCloud. For Euro Office, the existing weboffice/euro-office.yml already handles EURO_OFFICE_DOMAIN. OpenCloud inserts these addresses when reading the CSP. The *.opencloud.test addresses there are only fallback values for missing variables, not additional domains to set up.

Client IDs and scopes are specified in the authentik-idp.yml and do not also need to go in the .env. Only adjust already existing, differing OC_OIDC_CLIENT_* or WEBFINGER_* values to the IDs from step 3, or remove the relevant overrides.

Step 15: Add to the Compose file list

Explanation

Placing the authentik-idp.yml alone does not activate it yet. The OpenCloud stack must use it in addition to its existing Compose files. It goes at the end of the file list so that its login settings override the previous defaults.

Configuration

1. In Komodo → Stacks → opencloud → Config → File Paths, open the existing Compose file list.
2. For NPM access through the NAS port, add external-proxy/opencloud-exposed.yml if this entry is still missing. Replace an existing external-proxy/opencloud.yml with it; do not include both.
3. Add custom/authentik-idp.yml as the last file. Do not activate a conflicting Keycloak/IdP overlay at the same time.
4. Save the file list. Redeploying the stack follows in step 16.

With the existing Office and search services, the list in this setup looks like this:

docker-compose.yml
weboffice/euro-office.yml
external-proxy/euro-office-exposed.yml
search/tika.yml
search/opensearch.yml
external-proxy/opencloud-exposed.yml
custom/authentik-idp.yml

Keep existing Office and search services. They do not need to be set up again for the MFA integration.

Note on NPM access: external-proxy/opencloud-exposed.yml sets PROXY_HTTP_ADDR: "0.0.0.0:9200" and publishes 0.0.0.0:9200:9200. This allows NPM to reach OpenCloud through NAS-IP:9200. The alternative external-proxy/opencloud.yml binds only to loopback and does not suit this access route. Allow backend ports only for the necessary internal access, not through the router to the internet.

Note on the file list:

• Do not include the csp.yaml here. It is already included through authentik-idp.yml.
• Bear in mind support for Multi-Compose-Files. In Dockhand, this feature is currently still being implemented through the following feature request: Dockhand: Support multiple composes in one repo (as of: 24.07.2026). This example therefore uses Komodo as the Docker management system. Implementation is also possible directly with Docker in principle, but less convenient.

Step 16: Redeploy OpenCloud and log in

Configuration

Redeploy in the stack manager. A simple restart does not apply new environment values and mounts.

When managing Compose manually on the NAS, first check with your own complete file list; for the list above, the command is:

cd /volume1/docker-ssd/komodo/stacks/opencloud
docker compose \
  -f docker-compose.yml \
  -f weboffice/euro-office.yml \
  -f external-proxy/euro-office-exposed.yml \
  -f search/tika.yml \
  -f search/opensearch.yml \
  -f external-proxy/opencloud-exposed.yml \
  -f custom/authentik-idp.yml \
  config --quiet

Then, with the same list, replace config --quiet with up -d. Keep the previous Compose project name so that the existing containers and volumes remain associated. Do not remove data volumes. The filenames come from opencloud-compose and must match your own version.

Check

On the home network, open a new private browser window:

1. Open https://opencloud.example.com.
2. Log in with a regular user through Authentik and enter the email code.
3. Open the existing files and Spaces and upload a small file to a writable Space.
4. Also log in with the existing administrator and check their administration access.

The OpenCloud integration is now set up. If login fails, first use chapter 11 before changing further settings.

Note on INSECURE: With INSECURE=true, services that use this value can also accept invalid HTTPS certificates. Therefore, do not set the value to true just to bypass a login error. If it is already true, do not change it without checking: depending on the existing configuration, Euro Office, for example, might no longer work afterwards.

8. Connection tests for apps and WebDAV

iPhone and Windows

1. In the OpenCloud app, add an account with server address https://opencloud.example.com.
2. In the browser that opens, log in with the corresponding Authentik user and complete MFA.
3. Allow the redirect back to the app.
4. Open or synchronize the desired Space and transfer a small file.

The server address remains the same on the go. Do not enter the Authentik address or NAS IP as the OpenCloud server.

Note: In this guide, accounts are mapped through the username. This keeps the mapping the same even if the email address changes. Apps on Windows, Mac, or iPhone may still have the previous mapping stored. If login fails because of this, remove the account only from the affected app and then add it again. This is not necessary if login works. Back up unsynchronized files and offline data beforehand. Do not delete the OpenCloud user, Spaces, or local folders.

Alternatively, mapping through the email address can be configured in the authentik-idp.yml: PROXY_USER_OIDC_CLAIM: "email" and PROXY_USER_CS3_CLAIM: "mail". PROXY_AUTOPROVISION_ACCOUNTS: "false" remains in place. Authentik must transmit the email address in the token; it must match the email field of the existing OpenCloud account and be unique. Changes to these addresses must be controlled so that no one can use another account's address for mapping. This is independent of whether a username or email is entered in the Authentik login window. For the setup described here, mapping through the username remains configured.

WebDAV: Scanners and other clients

This section is only relevant if you use WebDAV – for example, with a WebDAV-capable scanner that stores documents directly in OpenCloud, or a client for file access. Otherwise, you can skip it.

Set up the connection

In OpenCloud → personal settings → App Tokens, generate a separate token for the scanner or client. Enter the following in its WebDAV settings:

Field	Value
URL	actual WebDAV address of the Space or folder
Username	alex, not their email address
Password	the generated OpenCloud app token

A Space address looks like this, for example:

https://opencloud.example.com/dav/spaces/<storage-id>$<space-id>/

Use the actual IDs; do not derive them from the Space name. Do not include credentials in published configurations.

Test the connection

Use the scanner to save a test scan in the target folder, or upload a small file with the WebDAV client. Then check in OpenCloud whether the file has arrived in the intended folder. For read-only access, download an existing file instead.

Note: App tokens allow access without an interactive MFA dialog. They must be kept secret and are revoked in OpenCloud; blocking an account in Authentik alone does not guarantee that existing app tokens are blocked. Do not indiscriminately enable PROXY_ENABLE_BASIC_AUTH=true for this. OpenCloud app tokens

If a scanner should only access Scans, use an account with the appropriate permissions in OpenCloud. A separate token alone does not restrict access to this folder.

9. Access through Tailscale on the go

Step 17: Set up the NAS, subnet route, and DNS

Explanation

Through Tailscale, your phone or notebook reaches OpenCloud through the internal NAS address – without the detour through Cloudflare. This requires two things: a route into the home network (subnet route) and internal resolution of your domain through AdGuard (Split-DNS).

For private use, the free Personal plan offers up to 6 users, unlimited personal devices, and 50 tagged devices („Tagged Resources“), for example servers, NAS devices, or subnet routers. A NAS does not count as a Tagged Resource simply because of its function, but only once the corresponding tag is assigned. As of: September 2026. Tailscale plans

That is enough, for example, for two parents and four children, each with their own account. Each person can connect several of their own devices, such as a phone, tablet, and notebook. Separate accounts make it possible to assign access rights per person and revoke them individually if needed. You can also accommodate more than 6 family members if, for example, two share an account (mother and father, siblings, and the maternal and paternal grandparents.) This also allows larger families to be brought together through the Tailscale tunnel.

The examples use the home network 192.168.10.0/24, the NAS with AdGuard at 192.168.10.20, and the domain example.com. Replace these three values with your own.

1. Tailscale container on the NAS

Configuration

Place the Compose configuration in the Tailscale stack on the NAS, not in the OpenCloud stack. For an existing container, keep its data path.

🔵 Tailscale – Compose example for the NAS setup (open collapsible box here)

services:
  tailscale:
    image: tailscale/tailscale:latest
    container_name: tailscale
    network_mode: host
    privileged: true
    environment:
      # Single-use authentication key from Tailscale administration.
      - TS_AUTHKEY=${TS_AUTHKEY:?TS_AUTHKEY setzen}
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_USERSPACE=false
      # The home network to be made reachable through the NAS.
      - TS_ROUTES=192.168.10.0/24
    volumes:
      - /volume1/docker-ssd/tailscale:/var/lib/tailscale
    devices:
      - /dev/net/tun:/dev/net/tun
    restart: unless-stopped

1. On the Tailscale website, in Tailscale administration → Settings → Keys, generate an Auth Key with Reusable = off and Ephemeral = off.
2. Store the key in the Tailscale stack environment as TS_AUTHKEY. Do not write it in the published Compose file.
3. Set TS_ROUTES to your own home network. This means the network, for example 192.168.10.0/24, not the individual NAS IP.
4. Deploy the Tailscale stack. The NAS should then appear on the Tailscale website under Network → Machines.

The mounted data folder stores the device login; a normal restart does not require a new Auth Key. If the device is deleted in Tailscale and logged in again, use a new single-use key. Tailscale Docker parameters

Note:

• privileged: true corresponds to this NAS setup and gives the container extensive host permissions; it is not a general minimum requirement for Tailscale. No Exit Node is set up here: only the route into the home network should go through the NAS, not all internet traffic.
• Using Tailscale within the family has the advantage that, for example, the currently existing certificate message in the iOS app when switching between the home network and external access through Cloudflare ([BUG] app does not persist trusted certificates across network changes) does not appear. Within the family, the NPM certificate is always used for access.

2. Approve the subnet in Tailscale

To operate as a subnet router, IP forwarding must also be enabled on the NAS. If Tailscale reports missing forwarding, set it up on the NAS according to the subnet router guide. TS_ROUTES advertises the network but does not by itself enable host forwarding.

Configuration

1. In Tailscale administration → Network → Machines, open the three-dot menu → Edit subnet routes for the NAS.
2. Enable the advertised route 192.168.10.0/24 and save.
3. Also use the three dots for the NAS to select Disable key expiry if expiry is still enabled. This keeps the NAS logged in without requiring regular reauthentication. This setting concerns the device key, not the single-use Auth Key used earlier. The device remains authorized until revoked or removed. Tailscale subnet routers

Note: A newly set up Tailscale network initially allows communication between all devices in your own Tailscale network. As long as this default rule remains unchanged, no additional Tailscale access rules are needed for this. The subnet route must still be approved as described above.
With restricted access rules, authorized users must be allowed to reach NPM at 192.168.10.20:443 (TCP) and AdGuard at 192.168.10.20:53 (UDP and TCP). An active NAS firewall must also allow these connections. No additional firewall settings were needed for this in the UGREEN setup described here.

3. Resolve your own domain through AdGuard

Configuration

In Tailscale administration → Network → DNS → Nameservers, add a custom nameserver:

Setting	Value
Nameserver	192.168.10.20 – NAS address of AdGuard
Restrict to domain / Split DNS	enabled
Domain	example.com
Use with exit node	disabled

Save. Then click Enable under Network → DNS → MagicDNS if MagicDNS is not yet enabled.

Requests for opencloud.example.com and authentik.example.com then go to AdGuard. Its DNS rewrites already configured return the internal NAS IP. This Split-DNS rule does not apply to other domains. MagicDNS alone does not replace this rule: It provides names for devices on the Tailscale network. Tailscale DNS · MagicDNS

DNS requests for other internet domains continue to use the DNS servers otherwise configured on the device, for example those of the mobile provider. This Split-DNS rule does not forward them to AdGuard on the home network. Anyone who also wants AdGuard to resolve these requests while Tailscale is connected can adjust the global DNS settings in Tailscale for this. This redirects only DNS requests, not automatically all internet traffic.

Note: No Exit Node is used in this setup: only access to the home network goes through Tailscale, while other internet traffic continues to use the device's normal connection. The DNS option Use with exit node therefore remains disabled. It does not activate an Exit Node, but merely determines whether AdGuard should also be used as the DNS server with an Exit Node selected later.

4. Test access on the go

Configuration and check

1. Install Tailscale on the phone or notebook, log in to your own Tailscale network, and connect.
2. Allow the use of Tailscale DNS settings. Windows, macOS, and iOS automatically accept approved subnet routes; on Linux, enable this with tailscale set --accept-routes=true if necessary.
3. Turn off Wi-Fi on the phone and use mobile data; alternatively, connect the notebook to a phone hotspot.
4. Open https://opencloud.example.com, log in through Authentik, and transfer a file.

On the Windows notebook, you can additionally check in PowerShell whether the internal address is returned:

Resolve-DnsName opencloud.example.com
Resolve-DnsName authentik.example.com

192.168.10.20 is expected here. The familiar domain names remain in the browser; NPM continues to supply the HTTPS certificate. No additional Tailscale certificate is needed for this route.

Note: If the home network and another Wi-Fi network have the same subnet, routing conflicts can occur. Mobile data is therefore suitable for an unambiguous first test.

10. Set up public access through Cloudflare

Step 18: Forward the tunnel to NPM

Explanation

This route is intended for devices without Tailscale. The tunnel also goes through NPM so that the discovery rule from step 9 applies. The domain was already set up at Cloudflare in step 7. Public access to the prepared services is now enabled.

Configuration

1. Create a tunnel

There are numerous easy-to-understand video guides showing how to set up a Cloudflare tunnel with Docker on a NAS or Linux system.

1. Open Cloudflare dashboard → Networking → Tunnels.
2. Select Create a tunnel.
3. Assign a name, for example nas-tunnel, and confirm with Create Tunnel. The name is only for recognition and does not have to match a domain.
4. In the following installation step, open the Docker instructions for the cloudflared connector. Use the tunnel token displayed there for the NAS container.
5. Start the connector on the NAS and wait until Cloudflare shows the connection. Then select Continue.

The connector establishes the connection from the NAS to Cloudflare. No inbound router port forwarding is needed for this. Treat the token like a password and do not publish it.

2. Publish OpenCloud and Authentik

In Cloudflare → Networking → Tunnels → nas-tunnel → the Routes tab at the top → Add route → Published application, create one entry each for OpenCloud and Authentik. Enter the subdomain (opencloud or authentik) and select your own domain. Leave the path field empty:

Field	OpenCloud	Authentik
Published hostname	opencloud.example.com	authentik.example.com
Service URL	https://192.168.10.20:443	https://192.168.10.20:443
HTTP Host Header	opencloud.example.com	authentik.example.com
Origin Server Name	opencloud.example.com	authentik.example.com

Enter Host-Header and Origin Server Name without https:// or a path. They ensure that the correct NPM host and its certificate are used despite the internal target IP.

• Do not enable cache rules for authentication responses and private API/file responses. Additional browser challenges can block native apps and WebDAV.
• If Euro Office is also used on the go, also make its own domain and NPM host available through the tunnel.

Check

Outside the home network, turn off Tailscale. Open OpenCloud in a new private browser window, log in, and upload and download a small file. This actually tests the public route.

Note: Do not publish NAS, NPM, or database administration through this tunnel. TLS verification to NPM remains enabled for the two application addresses.

Understanding the upload limit correctly

Cloudflare Free limits an upload request to 100 MB. This is not an equivalent download limit and, with clients using suitable chunking, is not necessarily the maximum file size either.

A single 150 MB upload can fail with HTTP 413; this also happens with large videos in Immich. This Cloudflare limit does not apply over LAN or Tailscale; a higher NPM setting alone does not remove it on the public route. Cloudflare: HTTP 413

11. Narrow down errors systematically

„Not logged in“ appears after MFA

In the case described, the administrator worked, but the regular user did not. Their OpenCloud login name was still the email address; Authentik was already supplying the username.

In OpenCloud → Administration → People, compare the login name with Authentik → Directory → Users → Username and align it on the existing account. Also, for 401 on /graph/v1.0/me after the token exchange, check user mapping and roles first. The error alone does not prove a browser or proxy defect.

The desktop shows „403 Forbidden – openresty“

In NPM → edit Authentik proxy host, first check Block Common Exploits. The local desktop callback can trigger this protection rule.

If the error remains, compare NPM and Authentik logs for the same request. openresty alone does not prove the cause. Do not set blanket redirect permissions, and do not disable PKCE.

WebDAV reports „PermissionDenied“ or „Authentication error“

In the OCR case, the token was correct, but the email address was entered as the user in the client. Access worked with the OpenCloud username. Then, if necessary, check the token, actual Space URL, and write permissions.

An app still expects the old email identity

Disconnect the client account and reconnect it, as described in chapter 8. Keep the existing user in OpenCloud.

„Remote host signaled shutdown“ or „excessive load detected“

Transfer the affected file again and look at the OpenCloud and NPM logs for the same time: was the container restarted, the connection closed, or a limit reached? HTTP/2 is a possible lead to investigate, but not a proven cause in this setup.

File changes are not applied

In Komodo, Info → Show once contained different content from the file edited through SMB. Therefore, correct the source actually used there and redeploy the stack.

For Failed to write contents, check the path, read-only mounts, and NAS ACLs. root in the container does not guarantee write permissions to every mounted file; indiscriminate chmod 777 is not a solution.

View the active OpenCloud configuration

In the NAS terminal, first determine the actual container name:

docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Ports}}'

In the following commands, replace OPENCloud_CONTAINER with this name:

docker exec OPENCloud_CONTAINER printenv OC_OIDC_ISSUER
docker exec OPENCloud_CONTAINER printenv PROXY_USER_OIDC_CLAIM
docker exec OPENCloud_CONTAINER printenv PROXY_USER_CS3_CLAIM
docker exec OPENCloud_CONTAINER printenv PROXY_AUTOPROVISION_ACCOUNTS
docker exec OPENCloud_CONTAINER printenv IDP_DOMAIN
docker inspect --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}' OPENCloud_CONTAINER

The expected values, in order, are https://authentik.example.com/, preferred_username, username, false, and authentik.example.com. The mount list must show the NAS file config/csp.yaml mapped to /etc/opencloud/csp.yaml.

Read the appropriate logs

On the NAS, substitute the actual container names:

docker logs --since 10m --timestamps OPENCloud_CONTAINER
docker logs --since 10m --timestamps AUTHENTIK_SERVER_CONTAINER
docker logs --since 10m --timestamps AUTHENTIK_WORKER_CONTAINER

For NPM, also read the logs of the affected proxy host. In the NPM data directory, they are usually named logs/proxy-host-<id>_access.log and logs/proxy-host-<id>_error.log. Container startup messages are not enough for a failed HTTP request.

If alex works on the LAN but not over mobile data without Tailscale, investigate the Cloudflare/proxy route. If only the administrator works on the same device, check user mapping first.

Note: The Authentik data folder does not have to contain a Compose file; look up its location in the stack manager. Before sharing logs or environment output, remove passwords, tokens, cookies, and private details.

12. Return to the previous login

The integration is deliberately set up as an additional Compose file. To go back, we change the login, not user management or data storage.

Configuration

1. In Komodo → Stacks → opencloud → Config → Files, remove custom/authentik-idp.yml from the active list. When managing Compose manually, omit the corresponding -f argument. The file does not have to be deleted.
2. Restore external OIDC, Web, and WebFinger values set outside this overlay to their previous values. idp must no longer be excluded through OC_EXCLUDE_RUN_SERVICES.
3. Redeploy the stack with the remaining files and the same project name. A simple restart is not enough.
4. In a new private browser window, log in with the previous OpenCloud username and OpenCloud password.
5. Reconnect apps if necessary.

Note: Authentik passwords are not transferred to OpenCloud. If all Authentik changes are in the overlay and the base provides the internal IdP, omitting it and redeploying is sufficient. Existing user management and data volumes remain in place.

Appendix A: Automatically lowercase profile details

Explanation

This optional rule converts, for example, Alex@Example.com to alex@example.com when saving your own details in the Authentik web interface. It also processes submitted usernames; changing them yourself remains blocked by step 2.

Configuration

1. In Authentik → Customization → Policies → Create → Expression Policy, create the policy normalize-username-email-lowercase or open the existing one.
2. Use this expression:

prompt_data = request.context.get("prompt_data", {})

if prompt_data.get("username"):
    prompt_data["username"] = prompt_data["username"].lower()

if prompt_data.get("email"):
    prompt_data["email"] = prompt_data["email"].lower()

return True

3. In Authentik → Flows and Stages → Flows, click the blue name default-user-settings-flow in the Identifier column – not the pencil. Open the Stage Bindings tab.
4. Expand default-user-settings-write, type User Write Stage, using ›.
5. Under Create or bind… → Bind existing policy, assign the policy normalize-username-email-lowercase if it is not already bound.
6. Save the new policy binding. Do not change anything on the existing Write stage or its stage binding; their defaults already suit this process. Authentik 2026.8.1: User settings flow

Note: The policy only applies to changes to your own profile through this User-Settings-Flow. It does not retrospectively rewrite existing accounts and does not apply when creating or editing users under Authentik → Directory → Users. Create new usernames there in lowercase from the start. Changes in OpenCloud are not processed by this policy either.

Assign existing password rules

Anyone using custom password rules binds them in Authentik → Flows and Stages → Stages → relevant password Prompt stage → Validation Policies. A rule created under Customization → Policies alone does not take effect yet. This concerns profile or password changes, not the MFA check configured above. Prompt Stage

Appendix B: Set up TOTP with KeePassXC as an additional MFA method

Explanation

In addition to the email code, you can use a TOTP code from KeePassXC. After your username and password, either email or TOTP is then sufficient. KeePassXC generates the codes on your device, even without an internet connection or working email delivery. Authentik itself must still be reachable for login.

To do this, we allow TOTP in the existing MFA check and then connect your Authentik account to KeePassXC. Nothing changes in OpenCloud, the Compose files, or account mapping.

1. Allow TOTP in the existing MFA check

Configuration – Authentik administration

1. In Authentik → Flows and Stages → Flows, click the blue name default-authentication-flow in the Identifier column – not the pencil icon. Open the Stage Bindings tab.
2. Under default-authentication-mfa-validation → Edit Stage, additionally enable TOTP Authenticators under Device Classes if it is not already selected. Leave Email-based Authenticators enabled; do not remove other methods already allowed.
3. Save. Edit Binding is not required for this.

Not configured action remains set to Force the user to configure an authenticator, as in step 11. Configuration stages also remains set to mfa-email-setup: this selection only concerns initial setup when a user does not yet have a suitable factor. We will set up the additional TOTP device through the personal settings in the next section.

Note: Do not add a second Validation stage to the login flow. Both methods should be available for selection in the same stage, not required one after the other. Authentik: MFA validation and allowed methods

2. Use the existing TOTP setup

Explanation

Authentik 2026.8.1 already includes the flow and stage default-authenticator-totp-setup. They allow personal registration of a TOTP device; you do not need to create them again or add them to the login flow. Authentik: Default TOTP setup

Configuration – personal Authentik account

1. At https://authentik.example.com, log in as the user for whom you want to set up TOTP. Initially, use the email code as before.
2. Switch to the user interface using the gear icon at the top right. Open ⚙️ Settings → Credentials → MFA Devices.
3. Select Enroll → TOTP Device. If the display name has been changed, select the corresponding TOTP entry.
4. Leave the page with the QR code open. Click Copy Secret to copy the setup key for KeePassXC.

This setup only applies to the currently logged-in user. For your separate administrator account, repeat it using that account's own login and a separate KeePassXC entry. The menu labels correspond to Authentik 2026.8.1.

Note: If TOTP Device is missing under Enroll, check Authentik → Flows and Stages → Stages → default-authenticator-totp-setup → Edit: Configuration flow must point to the existing flow default-authenticator-totp-setup. In the unchanged default setup, this assignment is already in place.

3. Store the key in KeePassXC

Configuration – KeePassXC and Authentik

Note: If you use Google Authenticator or Microsoft Authenticator, scan the QR code with the app. Then enter the six-digit code displayed there in Authentik and confirm with Continue. You can then skip the KeePassXC setup.

1. In KeePassXC, open your database and select or create the entry for the relevant Authentik account, for example Authentik – alex.
2. Right-click the entry and select TOTP → Set up TOTP… or TOTP → Set up TOTP….
3. Paste the key copied with Copy Secret into the secret key field. For the unchanged Authentik TOTP stage, use the KeePassXC defaults: 6 digits, 30 seconds, SHA-1.
4. Confirm with OK and save the KeePassXC database.
5. Copy the current six-digit code using Right-click the entry → TOTP → Copy TOTP. On Windows, you can also use Ctrl+T. Or click the clock icon 🕒 at the beginning of the row.
6. Return to the open Authentik setup page, paste the code under TOTP Code, and confirm with Continue. Only then is the TOTP device also registered in Authentik.

• The email method remains in place. Do not confuse the setup key with the short-lived login code: the key is stored once in KeePassXC; for login, you use the code generated from it each time. KeePassXC: Set up TOTP

4. Try both login methods

Check

1. Leave the existing session open and open a new private browser window.
2. Open https://opencloud.example.com and enter your username and password in Authentik.
3. At the MFA prompt, select Traditional authenticator for TOTP. If Authentik initially sends an email code, you can switch to Traditional authenticator using "Select another authentication method". After a successful login, Authentik remembers the method used and preselects TOTP in the future. Email codes are then only sent again when you switch back to the email method.
4. Enter the current code from KeePassXC. You should then return to OpenCloud.
5. Close all private windows, open a new private window, and log in again – this time select Email and use the email code.

Authentik may automatically preselect the last-used method next time. The other remains available. Authentik: Selecting the MFA method

Note: If a TOTP code is rejected, first check the time on the KeePassXC device and the NAS and use a freshly generated code. The KeePassXC database must also be available without an OpenCloud login, for example as a local copy. If the password and TOTP key are in the same database, access to that database affects both factors; a separate database with different protection keeps them separate. KeePassXC: Security of TOTP keys