> For the complete documentation index, see [llms.txt](https://docs.flopsar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flopsar.com/security/authentication-authorization-and-identity.md).

# 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

Flopsar authenticates two kinds of operator:

* **Local accounts** — created and managed inside Flopsar and stored in the local database. The password is a salted scrypt hash (see Cryptography & Key Management). Each record carries `is_local = true`.
* **LDAP users** — authenticated against an external directory on every sign-in. Flopsar does **not** persist a user row for them. Identity, role, and permissions exist only for the lifetime of the JWT session and are recomputed from directory groups at the next login.

A first **Owner** account (display name "Administrator") is created when the database is initialized; use it to perform initial configuration and to create further local 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 is the source of truth for both authentication and authorization of directory users.** After a successful bind, Flopsar reads the user's group memberships and maps them to a Flopsar role (each role may have an LDAP group DN). If several groups match, the role with the most permissions wins; if none match, the session uses **Guest** (no permissions). Identities are not stored locally, so a change of directory groups takes effect at the next login. Changing the role mappings in Flopsar ends the open sessions of LDAP users, so it applies at once. Configure this on [LDAP](https://docs.flopsar.com/administrator-guide/ldap.md) and [Managing Roles](https://docs.flopsar.com/administrator-guide/managing-roles.md). Local accounts always take precedence: if the username matches a local user, LDAP is not consulted.

### Account locking

A local account can be **administratively locked**. A locked account is rejected at sign-in even if its credentials are valid, and locking ends every session the user has open (see Session control and revocation). LDAP users have no local account to lock: disable them in the directory, then end their open sessions on the **Sessions** page.

*Changed in Flopsar 7.2:* locking ends the user's open sessions at once. In earlier versions it only stopped new sign-ins, and a token the user already had stayed valid until it expired or the server restarted.

{% 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 %}

### Multi-factor authentication and single sign-on

Flopsar has no built-in multi-factor authentication and does not support single sign-on protocols such as OpenID Connect or SAML. Every sign-in is a username and a password, checked against a local account or over LDAP, and LDAP does not add a second factor even when the directory itself requires one for other systems. Where a second factor is required, put it in front of the management interface, for example a VPN or an access gateway that requires it before port 9443 can be reached.

## 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. New local users start here until you assign a role. LDAP users whose groups do not map to any role also receive Guest for that session.

Beyond these, administrators can **create custom roles** with any combination of the permissions below, optionally map a directory group DN, and assign them to local 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 local user accounts; viewing roles.
* **LDAP configuration** — viewing and editing the directory integration.
* **Agents and applications** — viewing agents, querying them, switching agent features, managing agent tokens, assigning applications, and deleting application data.
* **Profiles** — viewing, editing, deploying, and changing the activation status of monitoring profiles.
* **Data and analysis** — viewing captured parameters, stored data, live view, and using the AI assistant.
* **Plugins** — managing plugins, viewing plugins, and viewing plugin source.
* **Filtering and data masking** — editing dashboards, charts, and matching rules (**Edit filters**) and editing data masks (the latter being directly relevant to the privacy controls described in Privacy & Data Handling).
* **Archiving** — viewing and deleting archive files.
* **Server** — viewing server information and running server-level queries.
* **License** — viewing the license, updating it, and editing license mapping.
* **AI settings** — viewing and editing the assistant provider, keys, tool policy, proxy, and TLS. Using the chat is a separate permission (**Use AI assistant**). What the model may receive is on [AI Assistant](https://docs.flopsar.com/security/ai-assistant.md).

The full checklist with Workstation titles is on [Managing Roles](https://docs.flopsar.com/administrator-guide/managing-roles.md).

Role permissions are resolved **at login** and embedded in the session token, so changing a role's permissions ends the open sessions in that role and its users sign in again with the new access (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, the banned-applications list, and a random session identifier.

* **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 <token>` 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, checks that its session is still open, and then checks the route's required permission against the token's claims, returning `401 Unauthorized` for a missing, invalid, or ended session and `403 Forbidden` for insufficient permissions.

### Session control and revocation

Each sign-in opens a **session** that the server keeps in memory, and every request is checked against it. A session ends when its token expires, when the user signs out, or when the server ends it. The server ends sessions in these cases:

* **Signing out** ends that session only. Sessions of the same user in other browsers stay open.
* **Locking or deleting a local account** ends all sessions of that user.
* **Assigning a user a different role** ends all sessions of that user.
* **Changing your own password** ends your other sessions; the one you changed it from stays open. **Resetting the password** of another user ends all of that user's sessions.
* **Changing the permissions or the banned applications of a role, or deleting a role,** ends the sessions of everyone in that role, so they sign in again with the new access.
* **Changing the LDAP settings,** or the LDAP group of a role, ends the sessions of all LDAP users, because their role is resolved from the directory at sign-in.
* **An administrator** with **Edit users** ends one session, or all sessions of a user, on the **Sessions** page.
* **Restarting the server** ends every session. Sessions and the HS512 signing secret are held only in memory, so all users have to sign in again.

When a session ends, the Workstation closes its live connection (WebSocket close code `4001`) and returns to the sign-in page, which tells the user that the session has ended. API clients get `401 Unauthorized`. Every session ended by the server, except at restart, is recorded in the audit trail as `session_revoke`, and every sign-out as `logout`.

Changes made in the LDAP directory itself, such as disabling a user or changing their groups, do not end an open session; they take effect at the next sign-in. To cut off such a user at once, end their sessions on the **Sessions** page. There is no sign-out after a period of inactivity: a session stays open until one of the events above or the end of its 12-hour lifetime.

*Changed in Flopsar 7.2:* the server keeps track of sessions and ends them on the events above. In earlier versions tokens were stateless: signing out only removed the token from the browser, locking an account or changing a role did not affect a token already issued, and the only way to end a session before it expired was to restart the server.

## 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.
