Tenant Onboarding
Goal
Add a new Tenant to a running Keymate platform. At the end of this guide, the new Tenant has its own isolated environment with identity provider configuration, authorization policies, and API gateway routing — ready for users to be provisioned.
Audience
Platform engineers and operators responsible for onboarding new customers, business units, or organizational divisions as Tenants on the Keymate platform.
Prerequisites
- A running Keymate platform (Helm-based or GitOps-based)
- Administrative access to the platform
- Tenant details: name, domain, initial admin contact, environment requirements (dev/staging/production)
Before You Start
- Understand the Tenant model. In Keymate, a Tenant is the top-level isolation boundary. Each Tenant has its own identity configuration, authorization policies, and data. Tenants do not share access or visibility into each other's resources.
- Plan the environment structure. Decide which environments (development, staging, production) the new Tenant needs. Each environment operates independently with its own configuration.
- Prepare credentials. The new Tenant needs initial admin credentials, domain configuration, and optionally an identity federation setup if the Tenant uses an external identity provider.
The platform enforces Tenant isolation at every layer. Configuration errors during onboarding can leave a Tenant without proper access. Always verify the result before handing off to the Tenant administrator.
How Tenant Isolation Works
Each Tenant in Keymate is isolated across all platform layers:
| Layer | Isolation mechanism |
|---|---|
| Identity | Separate identity realm with independent users, groups, and federation settings |
| Authorization | Independent authorization model with Tenant-scoped policies and relationships |
| API Gateway | Tenant-specific routing rules and access enforcement |
| Data | Logical data separation — Tenant data is scoped and not visible to other Tenants |
| Observability | Tenant-tagged telemetry for filtered monitoring and alerting |
Steps
1. Define the Tenant
Create the Tenant definition with the required metadata.
Required information:
| Field | Description | Example |
|---|---|---|
| Tenant name | Unique identifier for the Tenant | acme-corp |
| Display name | Human-readable name | Acme Corporation |
| Domain | Primary domain for the Tenant | acme.example.com |
| Environments | Which environments to provision | dev, production |
| Admin contact | Initial administrator email | admin@example.com |
2. Create the Tenant identity realm
Configure the identity provider with a new realm for the Tenant. This creates the isolated identity boundary.
This step creates:
- A dedicated authentication realm
- Initial admin user with temporary credentials
- Default authentication flows (login, registration, password reset)
- Federation configuration slots (for connecting external identity providers later)
3. Initialize the authorization model
Set up the authorization foundation for the new Tenant.
This step creates:
- Tenant-scoped authorization store
- Default administrative roles (Tenant Admin, Organization Admin)
- Base policy structure for the Tenant
- Initial relationship tuples for admin access
4. Configure API gateway routing
Add routing rules that direct traffic for the Tenant's domain to the correct backend services.
This step creates:
- Domain-based routing rules for the Tenant
- TLS certificate provisioning for the Tenant domain (if using automated TLS)
- Rate limiting and access policies specific to the Tenant
5. Set up environment-specific configuration
If the Tenant requires multiple environments (dev, staging, production), configure each one with environment-specific settings.
Per environment:
- Separate configuration values (database connections, feature flags, external integrations)
- Environment-specific domain (e.g.,
dev.acme.example.com,acme.example.com) - Independent scaling and resource allocation
See Multi-Environment Management for detailed environment setup guidance.
6. Verify the Tenant setup
Confirm that you configured the new Tenant correctly and can access it.
Verification steps:
| Check | How to verify |
|---|---|
| Identity realm accessible | Navigate to the Tenant's login URL and confirm the login page loads |
| Admin user can authenticate | Log in with the initial admin credentials |
| Authorization model initialized | Verify the admin user has Tenant Admin role |
| API gateway routing works | Access the Tenant's domain and confirm it routes to the correct services |
| Tenant isolation confirmed | Verify the new Tenant cannot see data or configuration from other Tenants |
7. Hand off to the Tenant administrator
Provide the initial Tenant administrator with:
- Login URL for their environment
- Temporary admin credentials (require password change on first login)
- Link to the Keymate documentation for Tenant administration
- Contact information for platform support
Validation Scenario
Scenario
Verify that a newly onboarded Tenant is fully operational and properly isolated.
Expected Result
- The Tenant login page loads at the configured domain
- The admin user can log in and access the administration interface
- The admin user can create Organizations and users within their Tenant
- The Tenant cannot access or see data from any other Tenant
- API requests through the gateway are correctly routed and authorized
How to Verify
- Authentication: Log in as the Tenant admin at the Tenant-specific URL
- Authorization: Verify the admin has the correct roles and can perform expected operations
- Isolation: Attempt to access another Tenant's resources and confirm denial
- Routing: Send API requests to the Tenant's domain and verify correct responses
Troubleshooting
- Login page not loading. Check DNS resolution for the Tenant domain. Verify API gateway routing rules are applied. Check TLS certificate status.
- Admin user cannot log in. Verify you created the identity realm correctly. Check that the admin user exists and credentials are correct.
- Authorization errors after login. Verify you initialized the authorization model with the correct admin roles. Check that relationship tuples for admin access are present.
- Tenant can see other Tenants' data. This indicates a misconfiguration in Tenant isolation. Check that the identity realm, authorization store, and data scoping are all correctly Tenant-bound. Escalate immediately if isolation is broken.
Create a standard onboarding checklist for your team that covers all seven steps. Repeatable Tenant onboarding reduces errors and shortens the time to activate new customers.
Next Steps
- Customization Overview — Configure Tenant-specific settings and overrides
- Multi-Environment Management — Set up dev, staging, and production for the Tenant
- Multi-Stage Environments — Understand the multi-environment deployment model