elsa-core/doc/adr/0010-default-admin-user-bootstrap-for-initial-identity-access.md

# 10. Default Admin User Bootstrap for Initial Identity Access

Date: 2026-03-15

## Status

Accepted

## Context

Elsa exposes user-management endpoints for creating, listing, updating, and deleting users. Historically, privileged identity bootstrap concerns were tied to the `SecurityRoot` policy. That approach coupled two separate concerns:

1. **Bootstrap of the first administrative identity**
2. **Ongoing authorization for user management operations**

This coupling created unnecessary friction for integrators:

- Integrators had to understand and satisfy the `SecurityRoot` policy before they could manage users.
- The bootstrap story for the first administrator was implicit rather than explicit.
- User-management endpoints mixed initialization concerns with normal permission-based authorization.
- The `SecurityRoot` policy remained overloaded with responsibilities beyond truly sensitive identity operations.

At the same time, Elsa now provides a dedicated `DefaultAdminUser` feature that can provision an initial administrative role and user during application startup. This gives integrators a clear, explicit bootstrap mechanism that does not depend on runtime access to user-management endpoints.

## Decision

We will treat **initial administrator bootstrap** and **regular user management** as separate concerns.

### 1. Use `DefaultAdminUser` for Initial Bootstrap

Integrators who need an initial administrator account should use the `DefaultAdminUser` feature.

This feature is responsible for:

- Creating the configured admin role if it does not already exist
- Creating the configured admin user if it does not already exist
- Assigning the configured admin role to that user
- Allowing bootstrap through application configuration and startup, instead of through a special runtime policy gate

### 2. Remove the `SecurityRoot` Requirement from User-Management Endpoints

The following user-management endpoints are no longer gated by the `SecurityRoot` policy:

- `POST /identity/users`
- `GET /identity/users`
- `PUT /identity/users/{id}`
- `DELETE /identity/users/{id}`

These endpoints are authorized through their normal endpoint permissions (for example `create:user`, `read:user`, `update:user`, and `delete:user`).

### 3. Keep `SecurityRoot` for Narrow, Explicit Privileged Operations

The `SecurityRoot` policy remains available for operations that are still considered privileged bootstrap or security-root capabilities, such as:

- secret hashing utilities
- privileged application creation
- privileged role creation
- other explicitly designated security-root operations

This narrows the purpose of `SecurityRoot` and keeps it from being the default answer to first-user provisioning.

## Consequences

### Positive

- **Clear bootstrap story**: Integrators have an explicit, startup-driven way to provision the first administrator.
- **Cleaner separation of concerns**: Initial identity setup is no longer entangled with day-to-day user CRUD operations.
- **Permission-first authorization**: User-management endpoints now follow the same permission-oriented model as the rest of the API.
- **Reduced operational friction**: Environments can bootstrap an admin user without relying on a special runtime policy.
- **Better extensibility**: Integrators can replace or customize admin bootstrap through feature configuration rather than endpoint-specific access assumptions.

### Negative

- **More responsibility for integrators**: Deployments must intentionally configure `DefaultAdminUser` or provide another trusted bootstrap path if no administrator exists yet.
- **Migration awareness**: Existing documentation and operational guidance that referenced `SecurityRoot` for user bootstrap must be updated.
- **Potential misconfiguration risk**: A weak admin password remains a deployment concern and must be handled carefully by integrators.

### Neutral

- `SecurityRoot` still exists, but its scope is narrower and more explicit.
- User-management endpoints continue to require authentication and matching permissions; only the extra `SecurityRoot` gate is removed.
- Bootstrap behavior is now feature-driven rather than endpoint-driven.

## Implementation Notes

- `DefaultAdminUserFeature` and `AdminUserInitializer` provide the startup-time bootstrap mechanism.
- User-management endpoints should document only their permission requirements, not `SecurityRoot`.
- Authentication configuration may still use `SecurityRoot` for operations that intentionally remain root-level.
- Integrators should prefer environment-specific configuration for default admin credentials and rotate them according to their security practices.