System Bootstrap Behavior

TokenIDP bootstrap is the first-run initialization process that prepares a new TokenIDP environment for operation.

During bootstrap, the platform can apply database migrations, create the initial system tenant, create default API resources and scopes, create the initial administrator role and permissions, create the initial administrator account, and create default client applications and configuration records.

Bootstrap is intended for first installation, local development, and controlled environment initialization. It should not be treated as a permanent runtime mechanism. Once an environment has been initialized successfully, bootstrap should be disabled and the temporary administrator credentials should be rotated.

Bootstrap Execution Rules

The current startup gate is implemented in DependencyInjection.cs:

if (!app.Environment.IsProduction() && opts.Enable)

This means bootstrap execution depends on both the ASP.NET Core environment name and Bootstrap:Enable=true.

If the environment is Production, bootstrap does not execute even when Bootstrap:Enable=true.

If the environment is not Production, bootstrap executes during application startup when Bootstrap:Enable=true. This includes Development, Staging, incorrectly configured production deployments, and custom environment names that are not recognized as Production.

The environment check reduces the chance of accidental production bootstrap execution, but it does not remove the need for operational discipline. A deployment using the wrong environment name can still execute bootstrap logic against the configured database.

Startup Sequence

When bootstrap executes, startup performs two important operations.

  1. Database migrations are applied using db.Database.MigrateAsync().
  2. The bootstrap workflow executes through SystemBootstrapper.BootstrapAsync().

Because these actions run during application startup, startup may modify schema, seed records, normalize existing configuration, and recreate missing operational objects.

This behavior is useful for a fresh development or initialization environment. It is not a substitute for controlled production change management, where schema migration and privileged seed operations should be explicit and auditable.

Bootstrap Behavior After First Installation

Most bootstrap operations are implemented as "ensure" operations instead of destructive recreation.

  • Existing system tenant is reused, but may be normalized or reactivated.
  • Existing admin API resource is reused, but missing scopes may be added.
  • Existing admin client is reused, but redirect and logout URIs and missing scopes or resources may be updated.
  • Existing permissions are skipped if already present.
  • Existing Administrator role is reused, but missing permissions may be added.
  • Existing administrator account is reused and its password is not reset if the user already exists.
  • Missing default configuration records may still be created.

The primary risk is not duplicate data creation. The larger operational risk is repeated execution of bootstrap logic against a live database, especially when the configured database is shared with a production or production-like environment.

Operational Risks

Leaving bootstrap enabled outside controlled environments can produce unexpected operational changes.

  • If the administrator account is deleted, bootstrap may recreate it using Bootstrap:AdminTempPassword.
  • If the system tenant is disabled, bootstrap may reactivate it.
  • If admin client redirect URIs in configuration change, bootstrap may update the stored client configuration.
  • Missing scopes or permissions may be re-added automatically.
  • Automatic database migrations may execute during startup in non-production environments.
  • Temporary bootstrap credentials remain privileged seed secrets while present in configuration.

The largest risk is environment misconfiguration. Even though bootstrap currently does not execute in Production environments, a deployment configured with an incorrect environment name may still execute bootstrap logic against the configured production database.

Production Guidance

Warning

Leaving bootstrap enabled increases operational risk and should not be considered a safe long-term production configuration.

Bootstrap should only be enabled during first installation. Disable it immediately after successful environment initialization.

Temporary administrator passwords should be rotated immediately after the initial administrator account is created. Treat bootstrap values as privileged seed credentials while they exist in configuration.

Production deployments should use controlled migration workflows instead of automatic startup migrations. Database schema changes should be planned, reviewed, and applied through the deployment process used for production infrastructure.

Environment names should be validated carefully during deployment automation. Confirm that production hosts run with the expected Production environment name and that non-production hosts do not point at production databases.

Recommended Operational Workflow

  1. Deploy TokenIDP.
  2. Enable bootstrap temporarily.
  3. Start the application once.
  4. Verify tenant, admin user, scopes, and client configuration.
  5. Rotate temporary administrator credentials.
  6. Disable Bootstrap:Enable.
  7. Restart the application.
  8. Validate that bootstrap no longer executes.

Summary

Bootstrap is a controlled initialization mechanism for preparing a new TokenIDP environment. It creates and normalizes foundational identity platform records so the system can be administered after first startup.

After initialization, ongoing operation should rely on normal administrative workflows, controlled migrations, and explicit configuration management. Bootstrap should not remain enabled as a standing runtime feature.