Portal Tenant And User Administration

Purpose

This functional area manages the organizational structure of the platform and the people who can operate within it.

It defines who belongs to the platform, which tenant they work in, and what administrative scope they have.

Main Capabilities

• tenant creation and maintenance
• tenant activation and deactivation
• platform user creation and maintenance
• multi-tenant assignment for users
• role and administrative scope management using area-based roles
• per-user authentication mode control
• administrator-set password reset with optional forced change at next logon
• sign-in lockout clearance for accounts locked out by repeated failed authentication attempts

Tenant Management

Tenants are the core functional isolation boundary of the platform.

Administrators can:

• create tenants
• define tenant identity information
• activate or deactivate tenants
• inspect tenant records

Tenant-aware behavior across the platform depends on this configuration.

User Management

The Portal provides administrative user management for platform accounts.

Supported functions include:

• create users
• edit users
• inspect user records
• delete users when appropriate
• control authentication mode per user
• assign platform roles and scopes to users
• set a local password for a user and optionally require a password change at the next sign-in
• clear sign-in lockouts caused by repeated failed authentication attempts

This area is responsible for the lifecycle of users who can sign into the Portal.

Sign-In Lockout Management

When a user account is locked out due to repeated failed sign-in attempts, administrators can clear the lockout from the Users page without needing to reset the user's password.

The unlock action is available as an action button in the user list. Clicking the button opens a confirmation dialog that identifies the target user by username and requires explicit confirmation before the lockout is cleared. This prevents accidental execution from a misclick in a dense table.

Once confirmed, the lockout is removed immediately. The user can attempt sign-in again straight away.

Only users with MEMBERSHIP_MANAGE (or the global equivalent) can clear lockouts.

Authentication Mode

Each user account has an authentication mode that determines which sign-in methods are permitted for that account.

The supported values are:

• Local only — the user can only sign in with a local username and password. All external identity provider sign-in attempts are blocked.
• External only — the user can only sign in through a connected external identity provider such as Microsoft Entra ID or Keycloak. Local username and password sign-in is blocked.
• Local + External — the user can sign in using either a local password or an external identity provider.

The default for newly created accounts is Local only.

This setting is independent of whether external identity providers are configured. Setting a user to External only without an active provider link for that account will prevent them from signing in until a link is established.

Typical usage:

• Use Local only for service or bootstrap accounts that must never authenticate through an external directory.
• Use External only for corporate user accounts that are fully managed by an organizational IdP, eliminating the local-password bypass path.
• Use Local + External during IdP migration periods or for accounts that legitimately need both options.

User-To-Tenant Assignment

The Portal supports assigning users to one or more tenants so that access can be scoped correctly.

Functionally, this determines:

• which tenant context a user can administer
• whether a user operates globally or within specific tenant boundaries
• how tenant-aware access control behaves in the Portal

Each tenant assignment carries its own role set. This allows one user to have different responsibilities in different tenants, such as MEMBERSHIP_MANAGE in one tenant and GOVERNANCE_READ in another.

Role Model

A role is a named bundle of permissions, and a permission is written area:level. There are three levels — lookup, read, write — and eight areas: API Definitions, Membership, Security, AI Settings, Apps & Tools, Governance, ESRA & Data, and Tenants.

Three rules describe the whole model:

1. A session's authority is the union of the bundles it was granted. Two roles simply add together. Nothing overrides anything, and there is no order in which roles are applied — which is what makes "what may this session do" answerable by reading its token.
2. Levels form a ladder inside one area, and only there. security:write carries security:read carries security:lookup. Across areas they carry nothing: administering ESRA does not grant a Security read.
3. Scope lives on the grant, not in the role's name. Granting a role against a tenant applies it in that tenant; granting the same role against no tenant applies it in every tenant.

Changed in 1.2.5. Scope used to be spelled into the role's name: GLOBAL_SECURITY_MANAGE was a separate role that had to be declared, made assignable, added to every policy and kept in step with its tenant-scoped twin. All fifteen GLOBAL_* roles are gone, and so is GLOBAL_READONLY — it was TENANT_READONLY with the scope welded into the name, and granting TENANT_READONLY against no tenant reconstitutes exactly what it was: an auditor who sees every tenant and changes nothing.

Existing grants are migrated automatically as part of database-migrator apply. Nothing has to be re-granted by hand, and no user's effective authority changes.

Area Roles

Fifteen roles, each granted at either scope.

ESRA is the one area with two writes, and neither implies the other. ESRA_DATA_MANAGE defines what exists and what is searchable; ESRA_EXPOSURE_MANAGE decides who is allowed to see it. Publishing enterprise data to an AI client therefore needs sign-off from two distinct role holders in sequence.

Whole-Tenant Roles

These are shown as themselves in the Users screen rather than expanded into the area roles they contain: a holder of TENANT_ADMIN holds one grant, not seven, and a form that showed seven would rewrite the grant as seven the next time it was saved.

The Lookup Tier

Every admin screen has to name things another area owns. A toolset is built from a mapping's endpoints, bound to a target system and an authentication profile; an ESRA capability picks a model profile; an audit target's credential names a secret. Before the lookup tier existed, each of those pickers cost the caller the owning area's full read policy — an ESRA exposure manager needed Apps & Tools to name a client application and Security to name an issuer — or, where a screen did not know to hide the control, returned 403 inside it.

api/v1/admin/lookups/* returns identity only: an id and a name, never configuration. A secret lookup carries a name, a store and a descriptor id — no value, and not the backend name, which is the address of the thing rather than a label for it.

Lookup permissions are never granted directly. They arrive as part of an area role's bundle: every area role carries its own area's lookup, plus the specific cross-area lookups its screens need. That is what makes a single area role usable on its own.

Two areas deliberately have no lookup: nothing names a Governance row, and a Membership lookup would be a user directory, which is the separation of duty Membership exists to keep.

The Security Restriction

The Security area is intentionally narrower than every other. TENANT_READONLY does not admit it — its rows are the platform's credentials and trust anchors, and "can look at the Portal" is not sufficient reason to enumerate them. Reading Security requires SECURITY_READ, SECURITY_MANAGE, TENANT_ADMIN or SUPER_ADMIN.

Security is also deliberately separate from Membership. Folding the two together would let every secret administrator create users and grant roles, which is the sharpest separation of duty on the platform.

Who May Grant What

You can only hand out what you already hold. A caller may assign a role when their own permissions already cover every permission that role carries — nothing more.

So a user administrator who holds only Membership delegates Membership. To let them grant Security's roles as well, grant them Security — which is the honest version of the same decision, and one that shows up in their own role list rather than only in what they can do to other people's.

Assigning yourself a role you already hold is permitted and changes nothing; assigning yourself one you do not is what the rule refuses, to yourself and to anyone else alike.

Editing a user who holds roles you cannot grant still works. Those grants pass through untouched, and you may remove them — taking authority away is not acquiring it. What you cannot do is add one.

The Portal greys out the roles you may not grant and says why. Granting a role at global scope requires SUPER_ADMIN.

Administrative Scope

Role assignment controls which combination of areas a user can access and at what level:

• Global scope — any role granted with no tenant. The holder acts across every tenant, within the areas their roles cover. A global session is never narrowed to one tenant by the Portal; which rows it may ask for is still the area's own decision.
• Tenant scope — the same roles granted against a tenant. The holder sees and administers that tenant only.

Reading across tenants and writing across tenants are separate decisions. A global grant reads its area everywhere; whether it may write there is decided per area, so a global ESRA administrator cannot write another area's rows in any tenant.

Granting at global scope requires SUPER_ADMIN.

Operational Importance

Tenant and user administration provides the human governance foundation of the platform.

Without it, the platform could not:

• separate customer or organizational boundaries
• control who can configure mappings and tools
• restrict administrative capabilities to the correct audience
• enable fine-grained operational delegation through area-specific roles