An Enterprise license
The server is the free edition until it is given an Enterprise license, the file OwnBase sends:
ownbase-server --data ./data --license ./acme.license
OWNBASE_LICENSE_FILE names the file from the environment, and OWNBASE_LICENSE
holds the license itself, for a secret store; give one of them. The server checks it
offline when it starts. A license that is not one, was changed, or cannot be read
stops the server with the reason. One that has ended keeps its features for 14 days,
and the owner and administrators see a line under the conversation's header saying
until when; then the features turn off. Within 30 days of the end, and when the
workspace has more members than the license covers, they are told too. Chat, sign-in
and joining never depend on a license. Diagnostics shows where the license stands,
and GET /api/admin/license answers the same for the owner and administrators.
The Enterprise code is in ee/, source-available under its own license; the rest of
the server is MIT. See ee/README.md.
Single sign-on#
A license with sso lets the owner sign people in through the company's OpenID
Connect provider, such as Okta, Microsoft Entra ID, Google Workspace or Keycloak. The
server needs its public address, since the provider sends people back to it:
ownbase-server --data ./data --license ./acme.license --public-url https://chat.acme.com
At the provider, register a web application with the sign-in redirect address
https://chat.acme.com/api/sso/callback. Then, in Workspace settings under Sign-in,
give its issuer, client ID and client secret; OwnBase reads the rest from the issuer's
/.well-known/openid-configuration and checks it before saving. For Entra ID, use the
tenant's own issuer (https://login.microsoftonline.com/<tenant id>/v2.0), not the
shared one.
The sign-in screen then has a "Sign in with" button. People who have an account link it once in Account settings, under Security. The owner can let the provider make accounts for people new to the workspace, only for verified addresses at the domains given when any are, and can require single sign-on, after which passwords sign in the owner alone. The desktop app signs in through the system's browser and comes back to itself.
Single sign-on with SAML#
The same sso license feature covers SAML 2.0, for providers set up that way, such
as Okta, Microsoft Entra ID, AD FS, Google Workspace or Keycloak. It needs the public
address too. At the provider, add a SAML application with:
- Entity ID (Okta: audience URI, Entra: identifier):
https://chat.acme.com/api/saml/metadata. That address also serves this workspace's metadata, for providers that read it, once the license is in. - Sign-in address (the assertion consumer service, Okta: single sign-on URL,
Entra: reply URL):
https://chat.acme.com/api/saml/acs. - Name ID: a value that stays the same for each person, such as their email address or a persistent ID. A transient one is refused, since nobody could be linked by it.
- Attributes:
emailanddisplayName, or the provider's usual names for them. Entra's own claims work as they come.
Then, in Workspace settings under Sign-in, fill in "Single sign-on with SAML" with what the provider gives: its sign-in address (Okta: identity provider single sign-on URL, Entra: login URL), its entity ID (Okta: identity provider issuer, Entra: Microsoft Entra identifier) and its signing certificate. Paste the certificate as it comes; while the provider changes certificates, put the new one after the old one, separated by a comma.
Sign-in begins in OwnBase. An answer the provider sends unasked, such as from its dashboard of apps, is refused, so point the dashboard tile at the workspace's address (Entra: sign-on URL). The answer must be signed with that certificate, on the assertion or on the response around it; come from that entity ID; be for this workspace; be in date, within a minute of this server's clock; and answer the sign-in it ends. It is used once. An email address in it counts as verified, since the provider is the company's directory, so give new accounts only to domains whose addresses the provider controls.
Linking, new accounts and requiring single sign-on work as for OpenID Connect. Both can be set up at once: the sign-in screen then has a button for each, and requiring either one turns passwords off for everyone but the owner.
SCIM provisioning#
A license with scim lets the company's identity provider, such as Okta or Microsoft
Entra ID, manage who is in the workspace over SCIM 2.0: it adds people, keeps their
names current, and deactivates them when they leave.
In Workspace settings under Sign-in, the owner presses Make a token in "Provisioning
with SCIM". The token is shown once; copy it into the provider's SCIM settings as the
bearer token (Okta: HTTP header, Entra: secret token). Give the provider the base
address https://chat.acme.com/scim/v2, the server's public address followed by
/scim/v2; people are at /scim/v2/Users. Making a new token stops the old one at
once, and Turn off stops the provider changing anything. People it added stay either way.
Someone the provider adds gets an account with no password and a username from the first part of their SCIM userName, usually their address, and joins the public channels as anyone joining does. They sign in with single sign-on: the first time the provider signs them in with a verified address it gave over SCIM, that account is theirs. The provider cannot change apps or guests, and never deactivates the owner.
Deactivating someone, or deleting them, which OwnBase treats the same way, ends their sessions at once and keeps their messages; nobody is deleted. Adding them again brings back the same account. Groups are not mapped to channels: a provider asking for groups gets an empty list, and making one is refused, so leave group push off. Assigning a group to the application still works, since the provider then sends its people one by one.
When the license ends, everyone the provider added stays, and it can still rename, deactivate and reactivate them, but it cannot add anyone new.
Turning OpenID Connect, SAML or provisioning on or off, changing their settings and making a new SCIM token all go in the administrative record, with who did it. The entry names the settings that changed, never a secret, certificate or token.
Compliance: legal hold, export and sending the record#
A license with compliance adds a Compliance tab to Workspace settings, for the
owner. It has three parts.
Legal hold. Name people by username and channels by name. From then on, messages written by the people held, and every message in the channels held, are kept whatever their age: the retention sweep skips them and the whole thread each is in, and nobody can delete them, not their author, an administrator, an app, or a report's removal. Deleting one is refused with "This message is kept for the workspace's records, so it cannot be deleted." Deleting the first message of a thread a held message is in is refused too, since that deletes the replies. Editing still works, and the words an edit replaces are kept for the export. The people held are not told, apart from that refusal. Direct conversations cannot be named; hold the people in them instead, which keeps what they wrote there.
Export. Choose a range of days (in UTC) and people, channels or both, save, then press Download the export. It downloads once, by a link that works for a minute, as a zip:
messages.jsonl, a line for each message written in the range by the people chosen, anywhere, every message in their direct conversations whoever wrote it, and every message in the channels chosen: thread replies and the server's notes about calls included, oldest first.conversations.jsonlandpeople.jsonl, for the ids those lines name.files/<id>/<name>for each file still attached.manifest.json: the range, the choice, who made it and when, and counts.
What "edits" and "deletions" can honestly hold follows from what the server keeps (see What deleting a message does). An edited message has its newest words and when it was last edited; earlier words are there only for messages that were held when they were edited. A deleted message has who wrote it, where, when it was sent and when it was deleted, and nothing of what it said: the words and files were erased at the time. Messages retention has already removed are not there at all.
Sending the record. Each entry of the administrative record goes, in order, to a webhook, to syslog, or both:
- A webhook gets
POST {"entries": [...]}as JSON, signed as OwnBase signs what it sends apps:x-ownbase-signatureisv0=and the HMAC-SHA256, with the signing secret you give, ofv0:<x-ownbase-request-timestamp>:<body>. It goes through the same guard as app webhooks, so a private address is refused unless the server runs with--allow-private-hooks. Any answer other than 2xx counts as a failure. - Syslog takes
udp://host:514,tcp://host:514(octet counted, RFC 6587) ortls://host:6514. Each entry is one RFC 5424 message, facility log audit, with the entry's action as the message id and the entry as JSON.
Each entry has its id, time, the username of who did it as actor, the action, its
target and details, and never what anyone wrote. A destination set up for the first time
gets the whole record first. A failure is shown in the panel and tried again every
minute, from the entry after the last one sent, so nothing is skipped, though an entry
can arrive twice; use its id to tell.
Holds, exports and changes to where the record goes are themselves in the record. When the license ends, holds stay in force and can be lifted but not added to, no new export can be made, and nothing more is sent until the license is renewed; then everything recorded meanwhile goes.