Authentication

obserae lets people sign in three ways, side by side:

• Local accounts — created on the Users page, with a password stored (hashed) by obserae. Additional accounts are included with Business, Business+ and Enterprise; Community keeps the built-in admin available.
• Active Directory (LDAP) — your team signs in with their existing company credentials. Optional, and set up on Identity & Access → Authentication.
• Single sign-on (OIDC / SSO) — your team signs in through your identity provider (Keycloak, Authentik, Microsoft Entra ID, Google…) with one click. Optional, and set up on Identity & Access → OIDC / SSO.

Business, Business+, and Enterprise licenses include LDAP, OIDC / SSO, groups, and additional user accounts. In Community, only the built-in local admin can authenticate. Other users, group mappings, provider settings and tokens remain stored while unavailable, and return unchanged after renewal. Nothing is deleted when the 30-day post-expiry grace period ends.

Turning on Active Directory or SSO does not remove your local accounts. The built-in admin always stays a local account you can use to get back in — even if your provider is unreachable. Think of it as your break-glass key.

Before you start

Ask whoever manages your Active Directory for:

• The directory URL, ideally secure: ldaps://dc.corp.example:636.
• A service account (a dedicated read-only user) — its full DN and password. obserae uses it to look people up; it never needs to be an administrator.
• Where users live (the user base DN, e.g. OU=Users,DC=corp,DC=example).
• The names (or full DNs) of the AD groups you want to map to obserae roles.

Set it up

The local section index keeps the long configuration form easy to scan. It stays beside the form on desktop and becomes a horizontal index on narrow screens.

1. Open Identity & Access → Authentication.
2. Tick Enable LDAP / Active Directory sign-in.
3. Fill in the Directory URL. Prefer ldaps:// (secure). If your server uses plain ldap:// with StartTLS, tick Use STARTTLS. Paste your Root CA if the certificate is issued by an internal authority.
4. Under Service account, enter the Bind DN and Bind password. The password is stored encrypted and never shown again.
5. Under User search, set the User base DN and, usually, keep the default User filter (sAMAccountName=%s) — that is the standard Active Directory login attribute.
6. Add one or more Group mappings: on the left, an AD group (its name or full DN); on the right, the obserae role it should grant (admin, analyst, auditor, or any group you created).
7. Click Test connection. A green message means obserae reached the directory and the service account signed in. Fix any error before continuing.
8. Click Save changes.

Now an Active Directory user can sign in on the normal login page with their company username and password.

How roles are decided

When someone signs in, obserae looks at the AD groups they belong to and grants the obserae roles you mapped. This is refreshed every time they log in, so moving someone between AD groups updates their obserae access on their next sign-in — no action needed in obserae.

A user who matches no mapping can still sign in, but sees nothing they are allowed to act on until you add a mapping for one of their groups. You will see them appear on the Users page (marked as an LDAP account) so you can adjust the mapping.

Good to know

• The admin is your safety net. If the directory ever becomes unreachable, sign in as the local admin. An operator can reset its password on the host with obserae-cli user reset-admin-password.
• Passwords are never stored by obserae for AD users. obserae checks them against the directory each time; it only keeps a lightweight profile (name and group membership) so the rest of the product works.
• LDAP accounts are managed in Active Directory, not here. Their roles come from the group mapping, so the Users page does not let you edit an LDAP user’s groups directly.

Tokens for machines

A script, a supervision probe, a firewall and an automation platform each need a different slice of obserae, and none of them needs a person’s account. Create a group holding exactly what that machine calls, put a user in it, and mint the token for that user (Identity & Access → Users → + New token).

Three profiles cover almost every case:

Add rules:read to the SOAR group if its playbooks ask whether a flow was allowed, and cartography:read if they read assets by name. None of these permits any change to the map, the rules or the configuration.

Keep indicators:read on its own credential rather than folding it into the SOAR token: the feed is pulled by the enforcement device, and revoking the firewall’s access should not revoke the playbook’s.

Do not reach for the built-in analyst or auditor role for a machine. Both are person-shaped: they carry the sessions, the cartography and the alerts together, which is far more than any of the three profiles above needs.

Single sign-on (OIDC / SSO)

If your company runs an identity provider (Keycloak, Authentik, Microsoft Entra ID, Google Workspace…), let people sign in with one click.

1. In your provider, create an OAuth2 / OIDC application for obserae. Note its Issuer URL, Client ID and Client secret, and register the redirect URL https://<your-obserae>/auth/oidc/callback.
2. Open Identity & Access → OIDC / SSO, tick Enable, and paste those values. Use Test connection to confirm obserae can reach the provider.
3. Under Group mapping, map a provider group to an obserae role (for example soc-admins → admin). Membership refreshes on every sign-in.
4. Click Save changes. A “Sign in with …” button now appears on the login page.

Good to know:

• No role, no access. Someone whose provider groups match none of your mappings is refused — add a mapping (or a default role group) first.
• SSO users have no password here and no separate 2FA in obserae — both live at your provider. The built-in admin still signs in locally as your break-glass key.
• Behind a reverse proxy? Set the Redirect URL field to your public https://…/auth/oidc/callback so it matches what your provider expects.

Change your own password

Local accounts can change their own password from My account (the menu with your name, top-right). Under Password, enter your current password, then the new one twice, and click Change password.

For your security this signs you out everywhere — every device and browser — so you (and anyone who had your old password) must sign in again with the new one. LDAP / Active Directory users change their password in the directory, not here, so the Password section is hidden for them.

Two-factor authentication (2FA)

Local accounts can add a second factor — the 6-digit code from an authenticator app (Google Authenticator, Aegis, 1Password, …). It is the single best way to stop a stolen or guessed password from working on its own.

Turn it on for yourself. Open My account from the menu with your name (top-right). Click Enable two-factor authentication, scan the QR code with your app (or type the shown secret), then enter the current 6-digit code to confirm. obserae then shows you a list of recovery codes — save them somewhere safe. Each one lets you sign in once if you lose your phone, and they are shown only this one time.

From then on, signing in asks for your code after your password. Lost your phone? Use a recovery code. Lost those too? An admin can reset your 2FA (below) so you can set it up again.

Require it for your team (admins). On Identity & Access → Login security you can require 2FA for everyone or for specific groups. Anyone who is required but has not set it up yet is sent to their My account page to do so at their next sign-in. (Two-factor is for people signing in — API tokens are not affected.)

When 2FA is required for someone, the Disable button on their My account page is greyed out — they cannot turn off a factor their group mandates. Lift the requirement in Login security first if you need to let them disable it.

Reset someone’s 2FA (admins). On the Users tab, a user with 2FA on shows a Reset MFA button — use it when they have lost their device; they can then enroll again.

Configuration exports preserve this state with the local user: the TOTP secret is a master-key-derived enc:v1: envelope and unused recovery codes remain one-way hashes. Restore the matching master key with the bundle; otherwise an enabled factor is rejected during validation instead of becoming unusable.

Locking out attackers

Identity & Access → Login security also protects the login page:

• Rate limiting temporarily blocks further attempts after too many failures — both for a targeted username and from a single source address. You choose how many failures are allowed and how long the block lasts (e.g. 5 tries, then a 5-minute pause).
• Allowed networks let you say which IP ranges may sign in at all — for everyone, or per group (for example, “admins only from the office network”). Anyone outside the allowed ranges is refused. If you ever lock yourself out, an operator can clear the restriction from the host.

From the command line

An operator can do the same from the host:

obserae-cli ldap show     # review the current settings (password hidden)
obserae-cli ldap test     # check the directory is reachable
obserae-cli ldap set --enabled --url ldaps://dc.corp.example:636 ...