Skip to content

Commit ad8ace7

Browse files
committed
docs: document dev login feature and authWithoutPassword event fix
- README.md: add Dev Login section under Authentication, add bullet to Developer-Friendly features list - CONFIG.md: add Dev Login Settings section with property reference, endpoint table, and usage notes - CLAUDE.md: add dev/ package to structure, add user.dev.* to configuration property groups Relates to #260
1 parent 5d785a8 commit ad8ace7

3 files changed

Lines changed: 64 additions & 0 deletions

File tree

CLAUDE.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ com.digitalsanctuary.spring.user
4242
├── api/ # REST endpoints (UserAPI)
4343
├── audit/ # Audit logging system
4444
├── controller/ # MVC controllers for HTML pages
45+
├── dev/ # Dev login auto-configuration (local profile only)
4546
├── dto/ # Data transfer objects
4647
├── event/ # Spring application events
4748
├── exceptions/ # Custom exceptions
@@ -110,6 +111,7 @@ All configuration uses `user.*` prefix in application.yml. Key property groups:
110111
- `user.roles-and-privileges` - Role-to-privilege mapping (applied on startup)
111112
- `user.role-hierarchy` - Role inheritance (e.g., ROLE_ADMIN > ROLE_MANAGER)
112113
- `user.gdpr.*` - GDPR features (enabled, exportBeforeDeletion, consentTracking)
114+
- `user.dev.*` - Dev login (autoLoginEnabled, loginRedirectUrl) — requires `local` profile
113115
- `user.purgetokens.cron.*` - Token cleanup schedule
114116
- `user.session.invalidation.warn-threshold` - Performance warning threshold
115117
- `user.actuallyDeleteAccount` - Hard delete vs disable

CONFIG.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,35 @@ WebAuthn requires two additional tables: `user_entities` and `user_credentials`.
105105
- Passkey labels are limited to 64 characters.
106106
- When a user account is deleted, all associated WebAuthn credentials and user entities are automatically cleaned up via the `UserPreDeleteEvent` listener. The database schema also uses `ON DELETE CASCADE` as a safety net.
107107

108+
## Dev Login Settings
109+
110+
Provides a reusable "login as" controller for local development, so consuming applications don't need to write boilerplate dev-login controllers. **This feature is disabled by default and requires both a property flag and the `local` Spring profile to activate.**
111+
112+
- **Auto-Login Enabled (`user.dev.auto-login-enabled`)**: Master toggle for the dev login feature. Defaults to `false`. Must be set to `true` **and** the `local` Spring profile must be active for the endpoints to be registered.
113+
- **Login Redirect URL (`user.dev.login-redirect-url`)**: The URL to redirect to after a successful dev login. Defaults to `/`.
114+
115+
**Example configuration:**
116+
```yaml
117+
# application-local.yml (only active with spring.profiles.active=local)
118+
user:
119+
dev:
120+
auto-login-enabled: true
121+
login-redirect-url: /dashboard
122+
```
123+
124+
**Endpoints** (only available when enabled with the `local` profile):
125+
126+
| Endpoint | Method | Description |
127+
|----------|--------|-------------|
128+
| `/dev/login-as/{email}` | GET | Authenticate as the specified user and redirect |
129+
| `/dev/users` | GET | List all enabled user emails |
130+
131+
**Important Notes:**
132+
- The `local` Spring profile **must** be active. Without it, the controller and warning beans are never registered regardless of the property value.
133+
- When enabled, `/dev/**` is automatically added to the unprotected URI list and CSRF-ignored URIs in `WebSecurityConfig`.
134+
- A prominent WARN-level banner is logged on startup when dev login is active.
135+
- **NEVER enable this in production.** It bypasses all password authentication.
136+
108137
## Mail Configuration
109138

110139
- **From Address (`spring.mail.fromAddress`)**: The email address used as the sender in outgoing emails.

README.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@ Check out the [Spring User Framework Demo Application](https://github.com/devond
103103
- Configuration-driven features
104104
- Comprehensive documentation
105105
- Demo application for reference
106+
- Built-in dev login controller for quick user switching during local development
106107

107108
- **GDPR Compliance** (opt-in)
108109
- Data export (Right of Access - Article 15)
@@ -709,6 +710,38 @@ To enable SSO:
709710
jwk-set-uri: ${DS_SPRING_USER_KEYCLOAK_PROVIDER_JWK_SET_URI}
710711
```
711712

713+
### Dev Login (Local Development)
714+
715+
The framework includes a built-in dev login controller that lets developers quickly switch between user accounts without entering passwords. This eliminates the need for consuming applications to write boilerplate dev-login controllers.
716+
717+
**Setup:**
718+
719+
1. Activate the `local` Spring profile (e.g., `spring.profiles.active=local`)
720+
2. Enable dev login in your configuration:
721+
722+
```yaml
723+
# application-local.yml
724+
user:
725+
dev:
726+
auto-login-enabled: true
727+
login-redirect-url: /dashboard # optional, defaults to /
728+
```
729+
730+
**Endpoints** (only available when enabled with the `local` profile):
731+
732+
| Endpoint | Method | Description |
733+
|----------|--------|-------------|
734+
| `/dev/login-as/{email}` | GET | Authenticate as the specified user and redirect |
735+
| `/dev/users` | GET | List all enabled user emails (JSON) |
736+
737+
**Example usage during development:**
738+
- Visit `http://localhost:8080/dev/users` to see available accounts
739+
- Visit `http://localhost:8080/dev/login-as/admin@example.com` to instantly log in as that user
740+
741+
**Security:** This feature requires **both** `user.dev.auto-login-enabled=true` **and** the `local` Spring profile to be active. A prominent warning banner is logged on startup when dev login is active. **Never enable this in production.**
742+
743+
See the [Configuration Guide](CONFIG.md) for all dev login settings.
744+
712745
## Extensibility
713746

714747
The framework is designed to be extended without modifying the core code.

0 commit comments

Comments
 (0)