# Authentication, Authorization & Identity This page describes how the Flopsar Server establishes **who a user is** (authentication), **what they are allowed to do** (authorization), and how **API sessions** are issued and controlled. It covers local accounts, LDAP integration, the role-based permission model, and JSON Web Token (JWT) sessions. Access control and the authentication of users are essential requirements of the Cyber Resilience Act (Annex I, Part I, points (d) and (e)). This page is the operator-facing description of how Flopsar implements them. ## Identity types Every user record carries an `is_local` flag that determines how the user is authenticated: * **Local accounts** — created and managed inside Flopsar. The password is stored as a salted scrypt hash (see Cryptography & Key Management). * **LDAP-backed accounts** — authenticated against an external directory. Flopsar keeps a local user record for such users, but it holds no password for them. A first **Owner** account (display name "Administrator") is created when the database is initialized; use it to perform initial configuration and to create further users and roles. ## Authentication ### How the server chooses a method When a sign-in request arrives, the server first checks whether the username belongs to a **known local account**. If it does, the password is verified locally. If it does not and **LDAP authentication is enabled**, the credentials are verified against the directory. If LDAP is disabled, the server falls back to looking the user up directly. In all cases a failed or successful attempt is written to the audit log; see Logging, Monitoring & Audit Trail. ### Local accounts Local passwords are verified against a per-user salted scrypt hash; the plaintext is never stored. Password complexity for local accounts is governed by the `[pass_policy]` configuration (minimum length, required character classes, forbidden characters), which is **disabled by default** and should be enabled for production. See the `[pass_policy]` reference and the Hardening Checklist. ### LDAP / LDAPS When LDAP is enabled, authentication proceeds as follows: 1. The server connects to the directory (`ldap://` or, recommended, `ldaps://`) and **binds with a configured service account**. 2. It **searches** for the user beneath the configured base DN, using the configured UID attribute and optional filter. The supplied username is escaped before being placed into the search filter. 3. It then attempts to **bind as the located user** with the supplied password. A successful bind authenticates the user. LDAP settings are managed at runtime through the Identity & Access screens / IAM API, not in `settings.toml`. The relevant security flags — `use_ssl` (LDAPS) and `skip_verify` (disable certificate verification) — are discussed in Cryptography & Key Management and Network Surface & Port Reference. **Do not leave `skip_verify` enabled in production.** **LDAP provides authentication only, not authorization.** On a user's first successful LDAP login, Flopsar creates a local record for them with the **Guest** role, which carries **no permissions**. An administrator must then assign an appropriate role before the user can do anything. Flopsar does not map directory groups to roles; role assignment is always performed inside Flopsar. This keeps authorization decisions under the operator's direct control and consistent for local and LDAP users alike. ### Account locking An account can be **administratively locked**. A locked account is rejected at sign-in even if its credentials are valid. Locking is the primary way to immediately deny access to a specific user (see Session control and revocation for how this interacts with already-issued tokens). {% hint style="info" %} Flopsar does not implement automatic lockout or rate-limiting after repeated failed logins; failed attempts are recorded in the audit log. For brute-force resistance, place the management interface behind controls that provide rate-limiting (for example a reverse proxy or WAF) and monitor failed-login audit events. See the Hardening Checklist. {% endhint %} ## Authorization Flopsar uses **role-based access control (RBAC)**. Each user is assigned exactly one role, and each role carries a set of fine-grained permissions. ### Roles Two roles are built in and **cannot be modified or deleted**: * **Owner** — holds **all** permissions. This is the full-administrator role; the initial "Administrator" account has it. Grant it sparingly. * **Guest** — holds **no** permissions by default. It is the role newly created and newly provisioned LDAP users receive, so that a new identity has no access until a role is deliberately assigned. This enforces least-privilege by default. Beyond these, administrators can **create custom roles** with any combination of the permissions below and assign them to users. ### Permissions Permissions are fine-grained and are evaluated with **OR logic**: a protected operation declares the permission(s) it needs, and a user is allowed through if their role holds **any** of them. The Owner role implicitly satisfies every permission check. The permission set spans these areas: * **Users and roles** — viewing and editing user accounts; viewing roles. * **LDAP configuration** — viewing and editing the directory integration. * **Agents and applications** — viewing agents, querying them, managing agent features and agent tokens, assigning applications, and deleting applications. * **Profiles** — viewing, editing, deploying, and changing the activation status of monitoring profiles. * **Data and analysis** — viewing captured parameters, stored data, and the live view. * **Plugins and extensions** — managing extensions, viewing plugins, editing plugins, and viewing plugin source. * **Filtering and data masking** — editing filters and editing data masks (the latter being directly relevant to the privacy controls described in Privacy & Data Handling). * **Archiving** — viewing and editing archive/retention settings. * **Server** — viewing server information and running server-level queries. * **License** — viewing the license, updating it, and editing license mapping. Because role permissions are resolved **at login** and embedded in the session token, changing a role's permissions affects a user the next time a token is issued for them, not retroactively within an active session (see below). ### Application-level restrictions (banned applications) In addition to role permissions, an individual user can have a list of **banned applications** — applications whose data they may not see. This restriction travels in the session token and applies on top of the user's role. ## API sessions (JWT) ### Token issuance A successful sign-in returns a **JSON Web Token** signed with **HMAC-SHA-512 (HS512)**. The token's claims include the issuer (`FLOPSAR`), issue and expiry timestamps, the username and display name, the role, whether the user is local, the resolved permission bitmask, and the banned-applications list. * **Lifetime:** **12 hours** from issuance. After expiry the client must sign in again. * **Transport:** the token is presented on each request in the `Authorization: Bearer ` header (and as the authorization value on the WebSocket channel). Always send it over the TLS-protected interface. Every protected API route runs through middleware that decodes and verifies the token and then checks the route's required permission against the token's claims, returning `401 Unauthorized` for a missing/invalid token and `403 Forbidden` for insufficient permissions. ### Session control and revocation Flopsar uses **stateless tokens** — there is no server-side session store. This shapes how access is revoked: * **Locking an account** prevents that user from signing in again (and thus from obtaining new tokens). Combined with the 12-hour lifetime, this bounds how long an already-issued token for a now-locked user remains usable. * **Restarting the server invalidates every token at once.** The HS512 signing secret is generated at start-up and held only in memory, so a restart forces all users to re-authenticate. This is the immediate, global "revoke everything" lever. * **Role and permission changes take effect on the next token issuance** for the affected user (within at most the 12-hour lifetime), not instantly within an active session. {% hint style="info" %} If you need to immediately cut off a specific user, lock the account; if you need to immediately invalidate all sessions (for example during incident response), restart the server. Plan token lifetime expectations around these mechanics. {% endhint %} ## Recommended configuration * Enable the password policy (`[pass_policy]`) for local accounts and set a sensible minimum length and character requirements. * Reserve the **Owner** role for a small number of administrators; model day-to-day access with custom least-privilege roles. * Use **LDAPS with certificate verification** if you integrate a directory, and never enable `skip_verify` in production. * Keep the management interface on TLS and, where possible, behind a reverse proxy that adds rate-limiting and IP restrictions. * Monitor login-failure and account-lock audit events. These and other recommendations are consolidated in the Hardening Checklist. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.flopsar.com/7/security/authentication-authorization-and-identity.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.