Multitenancy and Security in Openkoda Tutorial

What Does Multitenancy Mean in Insurance Software?

Three different questions get filed under “security” in a policy administration system, and they have three different answers. Keeping them apart is most of the subject:

Tenancy - whose data is this? One installation can carry several businesses: a managing general agent and the carriers it runs, a group and its subsidiaries, a platform and its clients. Each is a tenant organization with its own people, its own products, its own currency.
Authorization - what may this person do? Inside a tenant, access is composed from individual privileges into roles. Not three fixed levels, but a catalogue you assemble.
Accountability - what actually happened? Every change recorded by the system as it occurs, with who, when and from where.

The useful distinction across all three is between what is enforced and what is configured. Tenant separation is enforced: it is in the data layer, not in a filter somebody remembered to add to a query. Privileges are enforced: the navigation a user sees is derived from them. What you configure is which tenants exist, which privileges make up which role, and who holds it.

This walkthrough goes through all three, and it changes something at each stop. It builds a role, gives it to a colleague, and then finds its own footprints in the audit log.

The whole thing is on video as well, if you would rather watch someone do it than read the steps. It covers the same nine steps in one pass; the written version below is the one to keep open in another window while you work through your own installation.

How Tenant Separation, Roles and Audit Work

Before you start, you will need: an account with administration rights in at least one organization, and a colleague’s account to give a role to.

Step 1 - See the Businesses on One Installation

Settings → Organizations lists the tenants. Each has its own members, its own product catalogue, its own currency, and one of them is the one you are currently working inside.

The Organizations table listing five tenant organizations with their member counts, product counts, currency and creation date, one marked as current — Five organizations on one installation, each with its own people and its own currency - and one of them marked as the one you are currently inside.

Currency per organization is the detail worth noticing. A tenant is not a folder or a label on shared records; it is far enough down that two organizations on the same installation can trade in different money. Setting them up is its own walkthrough: managing multiple insurance organizations in one platform.

Step 2 - Switch, and Watch the Data Change

Switch into another organization and open the same screen you were just on. It is not the same data filtered; it is a different tenant’s catalogue.

The product catalogue after switching to Demo MGA North, showing a single life product, with the organization name in the top bar — The same screen, one organization later: one product, where the business we just left had sixteen. Not a filtered view - a different tenant.

Two things to check when you do this on your own installation. First, the top bar: it names the organization you are inside, and it is the only thing on screen that tells you. Second, trust the screen over the summary: the Organizations table’s product count is a rolled-up figure and can lag what the catalogue actually holds, so if the two disagree, the catalogue is the one to believe.

What you cannot do from here is reach the other tenant’s data by editing the address bar or guessing an identifier. That separation is in the foundations of the platform rather than in each screen’s query, which is the difference between a system that is multi-tenant and one that merely filters.

Step 3 - Start From the Ready-Made Roles

Back in your own organization, Settings → Roles is who can do what. Seven roles ship with the system - administrator, billing, claims handler, product manager, read-only viewer, sales, underwriter - and each one reports how many privileges it contains and how many people hold it.

The roles table listing administrator, billing, claims handler, product manager, read-only viewer, sales and underwriter roles with their privilege and user counts — Seven roles come with the system, each carrying a count of the privileges inside it - from 65 for an administrator down to 12 for a claims handler.

Read the privileges column before you adopt any of them. A claims handler carrying twelve privileges and an administrator carrying sixty-five is the whole design in two numbers: these are not levels on a ladder, they are different-sized bags of the same currency.

Step 4 - Read the Privilege Catalogue

Open a new role and you see what roles are made of: 79 privileges, grouped by the area they act on - product configuration, transactions, documents, insights, data access, administration, and a pair per dashboard.

Privileges grouped by area - documents and communications, insights and operations, data access and administration - each a card with a description and a code — The catalogue behind those roles: 79 privileges grouped by area, each one a view or a manage, each with the code the system checks.

The pattern to notice is view versus manage. Almost every capability appears twice - view documents and manage documents, view dashboards and manage dashboards - which is what lets you build a role that can see everything about renewals and change none of it.

And note what is in the administration group: impersonate users is itself a privilege. The ability to see the application as somebody else is not an ambient superpower; it is a box that someone has to have ticked, which is the right way round for a capability that powerful.

Step 5 - Build a Role by Ticking What a Job Needs

Name the role, describe it, and tick the privileges the job actually requires.

Two privileges ticked in the transactions group - view quotes and view policies - among many unticked ones — A role is what you tick. Here: view quotes, view policies and - further down - view documents. Three boxes out of seventy-nine.

Three ticks out of seventy-nine is worth dwelling on, because it is the argument against fixed levels. A renewals clerk who reads quotes, policies and documents and changes nothing is not “read-only viewer minus some things” and not “underwriter minus some things”. It is its own small shape, and it takes about a minute to express.

Write the description as a sentence about the job, not about the ticks. “Works the renewal queue. Reads, never configures.” is what the next administrator needs to know; a list of three privilege names is already on the screen.

The roles list now including the new Renewals Clerk role with three privileges — And it joins the list as an equal: three privileges, no sample tag, created today.

Step 6 - Give It to Somebody

Settings → Users is the other half. Note that the table has separate columns for membership and roles: membership is account-level access to the organization, roles decide what a person sees once they are in. An administrator has everything regardless of roles.

The team members table showing each person's membership level, join date, roles and the actions available, including impersonate — People and permissions are separate columns: membership is account-level access to the organization, roles decide what you see once you are in.

Assigning is ticking a box against a person, and it applies immediately. There is no publish step between the tick and the change in what they can reach, which is the same pattern as the wider tutorial on managing user roles and permissions.

The roles dialog for a teammate, listing every role as a checkbox including the newly created one — Assigning is ticking a box against a person - and the role built a minute ago is already in the list.

Step 7 - Check Your Work by Seeing the App as Them

A role is a claim about what somebody will experience. The only way to know it is true is to look, and impersonation lets you look without borrowing anyone’s password.

The application while impersonating a teammate: a banner naming who is being viewed as and who is really signed in, above a visibly shorter sidebar — Impersonation, with the banner that never lets you forget you are in it - and a sidebar four sections shorter than an administrator's.

Compare that sidebar with the ones in the screenshots above: billing, claims, the whole Configure group and the whole Admin group are simply not there. Privileges are not a set of error messages you hit after clicking. They decide what is rendered, so a user does not spend their day finding locked doors.

Two properties of impersonation are worth insisting on when you evaluate any system that offers it: the banner is always visible and names both parties, and, as the next step but one shows, the whole episode is written to the audit log while it is happening.

Step 8 - Choose How People Sign In

Authentication is a per-organization choice: ordinary credentials, or a passwordless magic link emailed to the person.

The authentication method setting for this organization, offering username and password or a passwordless magic link — Sign-in is a choice per organization, not per installation: credentials, or a passwordless link sent to the person's email.

Per-organization matters for exactly the reason multitenancy does: the subsidiary you onboarded last month may have a different security posture from the one you have run for a decade, and they are on the same installation.

Customers and brokers never use these at all. They arrive through their own portals, with their own accounts, scoped to their own records - a separate population from the staff users this screen governs.

Step 9 - Read the Audit Trail

Underneath everything, the log. Every record created, updated or deleted, with who did it, when, from which address, and how many fields changed.

The top of the audit trail showing the impersonation starting and stopping and the role being created, each with the user, the IP address and the time — The top three rows are this walkthrough: the role created, the impersonation started, the impersonation stopped - each with who, when and from which address.

The top of the log is the best possible demonstration, because it is this walkthrough looking back at itself: the role we created, the impersonation we started, the impersonation we ended. Nobody wrote those entries; the system wrote them as the actions happened, which is the only kind of record worth having when somebody asks months later who changed what.

Older audit rows showing submissions, quotes and coverages being updated, each recording how many fields changed — Further down, the ordinary traffic: every record created, updated or deleted, with a count of the fields that changed on it.

The changes column is the part auditors reach for: not just that a quote was updated, but that two fields on it were, and which. Combined with the entity id beside each row, that is a reconstruction of a record’s history rather than a list of times somebody touched it.

The three ideas in this walkthrough are usually sold as one feature and are really three: data that belongs to a tenant, access composed from privileges, and a log written by the system rather than by the person making the change. What they have in common is that they are enforced underneath the screens rather than applied by them, which is why you can check them the way this article does - by switching tenants and looking, by impersonating and looking, by reading the log and finding your own footprints in it.

And all three are configuration rather than code. New subsidiary, new job title, new person: an organization, a handful of ticks, a box against a name. None of it needs a release, which matters because org charts change far more often than software does.