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.
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
_emailslists. Addauth_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.