Nextcloud Core Security

nextcloud-core-security

Quick Reference

Controller Security Defaults

Every controller method enforces ALL of the following unless explicitly overridden with attributes:

ALWAYS start from the default secure posture and relax only what is needed. The default is the most restrictive configuration possible.

Security Attributes (NC 27+)

Legacy annotations (pre-NC 27): @NoAdminRequired, @NoCSRFRequired, @PublicPage. ALWAYS use PHP 8 attributes for NC 28+ apps.

Critical Warnings

NEVER assume a controller method without attributes is public -- the default is admin-only, authenticated, 2FA-required, CSRF-validated. Forgetting #[NoAdminRequired] means regular users get HTTP 403.

NEVER combine #[PublicPage] + #[NoCSRFRequired] on state-changing endpoints without additional authentication (bearer token, API key, or OCS-APIRequest: true header). This creates a CSRF vulnerability.

NEVER use #[NoCSRFRequired] on browser-facing form endpoints -- CSRF protection exists to prevent cross-site attacks on session-authenticated users.

NEVER call $response->throttle() on successful attempts -- only on failures. Throttling success slows legitimate users.

NEVER disable brute force protection on authentication endpoints.

NEVER forget to return the $response from afterController() middleware -- the response will be silently lost.

Middleware Chain Architecture

Middleware provides cross-cutting security concerns. The chain follows Django's pattern with four hooks executed in a specific order:

Hook Execution Order

Request arrives
    |
    v
[Middleware 1] beforeController()    (forward order: 1 -> 2 -> 3)
[Middleware 2] beforeController()
[Middleware 3] beforeController()
    |
    v
Controller method executes
    |
    v  (if exception thrown, skip to afterException)
[Middleware 3] afterController()     (reverse order: 3 -> 2 -> 1)
[Middleware 2] afterController()
[Middleware 1] afterController()
    |
    v
[Middleware 3] beforeOutput()        (reverse order: 3 -> 2 -> 1)
[Middleware 2] beforeOutput()
[Middleware 1] beforeOutput()
    |
    v
Response sent

Exception Handling Flow

Exception thrown during controller execution
    |
    v
[Middleware 3] afterException()      (reverse order: 3 -> 2 -> 1)
    |-- if handled (returns Response): continue to afterController chain
    |-- if not handled: propagate to next middleware
[Middleware 2] afterException()
[Middleware 1] afterException()

Hook Signatures

Middleware Registration

// App-level middleware (runs only for your app's controllers)
public function register(IRegistrationContext $context): void {
    $context->registerMiddleware(MySecurityMiddleware::class);
}

// Global middleware (NC 26+, runs across ALL apps)
$context->registerMiddleware(MonitoringMiddleware::class, true);

ALWAYS register middleware in Application::register(), not in boot(). Middleware must be available before any controller executes.

Content Security Policy

Per-Response CSP

use OCP\AppFramework\Http\ContentSecurityPolicy;

$response = new TemplateResponse('myapp', 'main');
$csp = new ContentSecurityPolicy();
$csp->addAllowedImageDomain('https://images.example.com');
$csp->addAllowedConnectDomain('https://api.example.com');
$response->setContentSecurityPolicy($csp);

Global CSP via Event Listener

Register a listener for AddContentSecurityPolicyEvent to modify CSP across all responses from your app.

CSP Method Overview

ALWAYS use the most restrictive CSP possible. Only add domains that your app actually needs.

NEVER use allowInlineScript(true) or allowEvalScript(true) unless absolutely required -- these weaken XSS protection significantly.

Security Events Catalog

Register listeners via IRegistrationContext::registerEventListener() in Application::register().

Authentication Mechanisms

ALWAYS use Login Flow v2 to obtain app passwords for external clients. NEVER store user passwords directly.

Decision Trees

Choosing Security Attributes

Is this endpoint admin-only?
  YES -> Use no attributes (default is admin-only)
  NO  -> Add #[NoAdminRequired]
         |
         Does it need to work without login?
           YES -> Add #[PublicPage]
           NO  -> Stop here
         |
         Is it called by an API client (not browser)?
           YES -> Add #[NoCSRFRequired]
           NO  -> Keep CSRF protection
         |
         Is it a 2FA setup page?
           YES -> Add #[NoTwoFactorRequired]
           NO  -> Keep 2FA requirement

Choosing Rate Limiting

Is the endpoint sensitive (auth, data modification)?
  NO  -> No rate limiting needed
  YES -> Is it accessible to anonymous users?
           YES -> Add #[AnonRateLimit(limit: N, period: S)]
           NO  -> (skip)
         Is it accessible to authenticated users?
           YES -> Add #[UserRateLimit(limit: N, period: S)]
           NO  -> (skip)
         Does it involve credentials/tokens?
           YES -> Add #[BruteForceProtection(action: 'name')]
                  Call $response->throttle() on FAILURE only
           NO  -> Rate limiting is sufficient

Reference Links

• references/methods.md -- Security attributes, middleware methods, CSP methods
• references/examples.md -- Security patterns, CSP configuration, middleware implementation
• references/anti-patterns.md -- Security mistakes and how to avoid them

Official Sources

• https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/middleware.html
• https://docs.nextcloud.com/server/latest/developer_manual/basics/controllers.html
• https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/security.html