Tenant First-Admin Bootstrap Service

Overview

The TenantAdminBootstrapService is an internal service responsible for orchestrating the creation of the first administrator for a new tenant in a multi-tenant deployment. This process, known as bootstrapping, is triggered upon the activation of a new SaaS license for a tenant.

The service's primary input is the first administrator's identity (an email address) and the corresponding tenant ID. This identity is provided by the platform within a cryptographically signed fleet-state document. The system guarantees that this identity is authentic and platform-signed before it reaches this service; any unsigned or forged identity documents are rejected by an upstream FleetStateClient.

The core function of this service is to bind the operation to the specific tenant, ensuring that all subsequent actions, particularly database writes, are strictly confined to that tenant's data scope using Row-Level Security (RLS). It then delegates the actual database transaction to the AuthModeRepository. The entire process is idempotent: if a tenant has already been bootstrapped, the service performs no action.

This service is a critical component of the tenant onboarding process, ensuring that each tenant is securely and correctly initialized with its own isolated administrator and authentication state.

How it Works

The TenantAdminBootstrapService is invoked by an internal FleetReconciler process after it successfully verifies a signed fleet-state document containing a new tenant's details. The service executes the bootstrap process through its bootstrapFirstAdmin method.

The operational flow is as follows:

sequenceDiagram
    participant Processor as Fleet State Processor
    participant Service as Tenant Admin Bootstrap Service
    participant Persistence as Auth Data Persistence
    participant Events as Event Bus

    Processor->>Service: bootstrapFirstAdmin(tenantId, adminEmail)
    Service->>Service: 1. Validate inputs (tenantId, adminEmail)
    alt Inputs are invalid
        Service-->>Processor: Returns `false`
    else Inputs are valid
        Service->>Service: 2. Set TenantContext for isolation
        Service->>Persistence: 3. bootstrapTenantAdmin(tenantId, adminEmail)
        Persistence-->>Service: 4. Returns result (e.g., `true` if seeded)
        alt Admin was seeded
            Service->>Events: 5. publishEvent(TenantAuthModeChangedEvent)
        end
        Service->>Service: 6. Restore original TenantContext
        Service-->>Processor: 7. Returns result
    end

1. Input Validation: The service first validates its inputs. It requires a non-null tenantId and a non-blank adminEmail that contains an @ character. If the inputs are invalid, it logs a debug message and returns false, halting the process.

2. Tenant Context Scoping: Before performing any actions, the service saves the current TenantContext and then sets it to the tenantId provided in the call. This step is critical for data isolation. It ensures that the underlying TenantBindingDataSource configures the database connection with the correct app.tenant_id, which enforces RLS for all subsequent queries.

3. Delegation to Repository: The service calls authModeRepository.bootstrapTenantAdmin(tenantId, adminEmail). This repository method handles the atomic database operation to pro<customer>e the tenant's authentication mode from pristine to protected and associate the admin role with the provided email. The source specifies that this underlying database operation is idempotent, replay-safe, and uses an advisory lock to prevent race conditions.

4. Handling the Result:

   • If bootstrapTenantAdmin returns true, it means the administrator was successfully seeded. The service logs an INFO message and publishes a TenantAuthModeChangedEvent. This event immediately invalidates any cached authentication or authorization data for that tenant, ensuring the changes take effect without waiting for a cache TTL to expire.
   • If it returns false, the tenant was already bootstrapped. The service logs a DEBUG message and takes no further action.

5. Error Handling: If any exception occurs during the database operation, it is caught. The service logs a WARN message containing only the exception's class name (to avoid logging PII) and returns false. This fail-safe design prevents a single tenant's bootstrap failure from crashing the entire fleet reconciliation process. The system will automatically retry bootstrapping the failed tenant during the next reconciliation cycle.

6. Context Cleanup: In a finally block, the service guarantees that the original TenantContext is restored. This ensures that the background thread executing the reconciliation is not left permanently bound to a single tenant's context, which is essential for the stability and correctness of the multi-tenant system.

API Reference

The service exposes a single public method for initiating the bootstrap process.

bootstrapFirstAdmin

This method bootstraps the first administrator for a specified tenant. The operation is idempotent; it is a no-op if the tenant's auth_mode is already protected.

Parameters

Returns

A boolean value:

• true: The administrator was successfully seeded in this call.
• false: The operation was a no-op because the tenant was already bootstrapped, the inputs were invalid, or an error occurred during processing.

Troubleshooting

The service emits structured logs to indicate the outcome of a bootstrap attempt.

| Log Message Prefix | Level | Cause | --- | --- | | S2R-SAAS-BOOTSTRAP skipped | DEBUG | The tenantId was null, or the adminEmail was null, blank, or did not contain an @ character. The bootstrap was not attempted. | S2R-SAAS-BOOTSTRAP no-op | DEBUG | The tenant was already bootstrapped (its auth_mode was already protected). This is expected during subsequent reconciliations for an active tenant. | S2R-SAAS-BOOTSTRAP first-admin seeded | INFO | The bootstrap was successful. The tenant's first admin was created and its auth mode was transitioned from pristine to protected. | S2R-SAAS-BOOTSTRAP failed | WARN | An unexpected exception occurred during the database operation. The log includes the tenant ID and the exception class name. The operation will be retried on the next fleet reconciliation cycle. The exception message is intentionally omitted to avoid logging PII. |

See Also

• Fleet Reconciliation: The upstream process that consumes signed fleet-state documents and invokes this service.
• Tenant Context: The mechanism used to ensure strict data isolation between tenants.
• Auth Mode Repository: The data access component responsible for the underlying database transactions for authentication and authorization.

All SOAP-to-REST docs