docs
cairnobs.org Demo Source
Esc

Install · 5 of 8

Signing in

Your identity provider over OpenID Connect, with roles from its groups or verified emails; Cairn OBS's own accounts with passkeys; and the emergency door for when single sign-on is down.

3 min read

Everyone who signs in has one of three roles: viewer, operator or admin (Who can do what). The ways in are listed under signin.providers in obs-beacond.yaml, in the order the sign-in page shows them:

type What it is
oidc Any OpenID Connect provider: Okta, Microsoft Entra ID, Google Workspace, Keycloak, Authentik, Auth0 and the like
local Accounts Cairn OBS keeps itself, signed in with passkeys, or a password and an authenticator code
inbuxa An inbuxa mail server's accounts, with roles from its permissions

With no signin at all, obs-beacond uses its own accounts, and logs the one-time link for the first admin (The server, from packages).

Your identity provider

Register Cairn OBS with the provider as a confidential web client whose only redirect address is https://<Cairn OBS>/auth/<id>/callback, then:

signin:
  providers:
    - id: sso
      type: oidc
      label: Sign in with Okta
      issuer: "https://example.okta.com"
      client_id: cairn-obs
      client_secret_file: /etc/obs-beacon/sso-client-secret
      redirect_url: "https://obs.example.org/auth/sso/callback"
      admin_groups: [obs-admins]
      operator_groups: [obs-operators]
      viewer_groups: [obs-viewers]
Key What it's for
issuer The provider's issuer, exactly as its /.well-known/openid-configuration names it. HTTPS (plain HTTP only on loopback)
client_id, client_secret_file The client. The secret is in a file, never in the config (leave it out for a public client)
redirect_url https://<Cairn OBS>/auth/<id>/callback
admin_groups, operator_groups, viewer_groups Group names. A member of an admin group is an admin, else of an operator group an operator, else of a viewer group a viewer
admin_emails, operator_emails, viewer_emails Addresses (ada@example.org) or whole domains (@example.org). They count only when the provider marks the address verified
groups_claim Where the groups are. Default groups; roles for Entra ID app roles; a dotted path such as realm_access.roles reads nested claims
scopes Default openid email profile; offline_access is added when the provider offers it
auth_params Extra authorization parameters, such as access_type: offline and prompt: consent for Google, or hd: example.org
recheck How often the role is decided again with the refresh token. Default 15 minutes
grace How long sessions last while the provider can't be reached. Default 24 hours

At least one of the six lists is required. There is no "anyone the provider knows" setting: someone who matches none of them is refused, and nothing about them is kept.

The ID token's signature is checked against the provider's published keys (RS, PS and ES algorithms and EdDSA; never none or a shared secret), with its issuer, audience, expiry and nonce. Every recheck, Cairn OBS asks the provider again, so taking someone out of a group, or disabling them, demotes or signs them out within that time.

Provider notes:

  • Microsoft Entra ID: use app roles (groups_claim: roles) rather than groups, which Entra leaves out of the token for people in many groups.
  • Google Workspace puts no groups in its tokens: use the _emails lists. Add auth_params: {access_type: offline, prompt: consent}, or sessions end when the access token does, usually within an hour.
  • Keycloak: realm roles are at groups_claim: realm_access.roles.

Cairn OBS's own accounts

signin:
  providers:
    - id: local
      type: local
      origin: "https://obs.example.org"   # passkeys are bound to this address
      passwords: true                     # optional

Admins add people under Configure › Users as admin, operator or viewer, and send each the one-time setup link it makes (good for 24 hours; the secret part of the link never reaches a server log). Disabling or removing an account ends its sessions on their next request.

People sign in with a passkey. With passwords: true, an account can instead use a password and a code from an authenticator app, never the password alone. Five failures in 15 minutes, from one address or for one account, block it for the rest of that time.

local can sit beside oidc on the sign-in page: your team through single sign-on, and an account or two of Cairn OBS's own.

The emergency door

When single sign-on is down, the people who need Cairn OBS most can't get in. The emergency door is the whole interface again, on a listener only reachable through an SSH tunnel to the server:

emergency_listen: "127.0.0.1:8152"    # loopback only
ssh -L 8152:127.0.0.1:8152 obs-server     # then open http://localhost:8152

An emergency account is an admin made under Configure › Users with Emergency account ticked. Its setup link is opened at the door, and its passkey is bound to localhost:8152, so it works there and nowhere else. Ordinary accounts can't sign in at the door. Every emergency sign-in is announced on every alert channel, whatever its minimum, and a red banner shows for as long as the session lasts.