Initial Customization

Customize these settings before launching your application.

---

1. Super Administrator Accounts

Super Administrators have full access to the application and bypass all authorization checks. These accounts are typically reserved for IT staff or core development team members.

Configuration

Add NetIDs to your .env file, or the .env.example file if they will be the same across environments:

.env

# Comma-separated list of NetIDs
SUPER_ADMIN_NETIDS=abc123,xyz789,def456

How It Works

The StakeholderSeeder runs automatically during php artisan db:rebuild and:

1. Looks up each NetID in the Northwestern Directory
2. Creates user accounts with their directory information (name, email, department, etc.)
3. Assigns the System-Managed role (full application access)
4. Skips existing users - safe to run multiple times (idempotent)

Initial Setup

After configuring SUPER_ADMIN_NETIDS, rebuild the database to provision administrators:

php artisan db:rebuild

Add Admins Later

To add administrators to an existing database without losing data:

php artisan db:seed --class=StakeholderSeeder

Caution

The StakeholderSeeder requires a valid Directory Search API key. Ensure DIRECTORY_SEARCH_API_KEY is configured before running.

---

2. Local Authentication (Passwordless)

Note

Local authentication allows external users (non-Northwestern) to access your application via emailed verification codes after an administrator invites them. Disable this if your app is Northwestern-only.

Configuration Options

Edit config/local-auth.php or set environment variables:

config/local-auth.php

# Enable/disable local authentication
LOCAL_AUTH_ENABLED=true

# Rate limit for login code requests per email (per hour)
LOCAL_AUTH_RATE_LIMIT_PER_HOUR=10

# Rate limit for login code requests per IP (per hour)
# Prevents a single IP from exhausting multiple accounts' per-email rate limits
LOCAL_AUTH_RATE_LIMIT_PER_IP_PER_HOUR=20

# Redirect destination after successful login
LOCAL_AUTH_REDIRECT_AFTER_LOGIN=/

Enabled

When to enable:

• Clients or partners without NetIDs
• Testing accounts for non-Northwestern users

Disabled

When to disable:

• Northwestern-only applications
• No external user requirements

Passwordless Code Settings

Edit config/local-auth.php to tune the OTP length, expiration, and lockout behavior.

'code' => [
    'digits' => 6,
    'expires_in_minutes' => 10,
    'max_attempts' => 8,
    'lock_minutes' => 15,
    'resend_cooldown_seconds' => 30,
],

How Local Auth Works

1. Admin creates a local user account through the Filament panel
2. Admin can trigger an immediate verification code, or the user can request one themselves
3. User receives an email with a verification code valid for a limited time
4. User enters the code and is authenticated (no password needed)
5. Code expires and becomes invalid after use

---

3. API Configuration

Note

The API layer is enabled by default. Disable it if your application doesn’t need programmatic access.

Core Settings

.env

# Master on/off switch for all API functionality
API_ENABLED=true

Tip

All rate limiters (API, authentication, support) are centralized in config/rate-limiting.php with env var overrides. See the API, Authentication, and Support Tickets pages for details on each limiter.

Request Logging

.env

# Enable API request logging
API_REQUEST_LOGGING_ENABLED=true

# Auto-delete logs older than this (days)
API_REQUEST_LOG_RETENTION_DAYS=90

# Slow request threshold for monitoring (milliseconds)
API_REQUEST_LOGGING_SLOW_THRESHOLD_MS=500

Sampling (High-Traffic Apps)

Performance Optimization

For high-throughput APIs, enable sampling to log only a percentage of successful requests. Errors are always logged regardless of sampling settings.

.env

# Enable probabilistic sampling
API_REQUEST_LOGGING_SAMPLING_ENABLED=true

# Sample rate (0.0 to 1.0) - 0.1 = 10% of successful requests
API_REQUEST_LOGGING_SAMPLE_RATE=0.1

---

4. Northwestern Integrations

NetID Update Webhook

The NetID Update webhook receives notifications when Northwestern users are deactivated, deprovisioned, or placed on security hold. This enables automatic role removal, or additional business logic, when users leave Northwestern.

If you have an EventHub subscription to the etidentity.ldap.netid.term topic:

1. Open routes/api.php

2. Uncomment the NetID Update webhook route:

   routes/api.php

   Route::middleware(['eventhub_hmac'])->prefix('eventhub')->group(function () {
       // Route::post('netid-update', App\Domains\User\Http\Controllers\Webhooks\NetIdUpdateController::class)->eventHubWebhook('etidentity.ldap.netid.term')->name('netid-update');
       Route::post('netid-update', App\Domains\User\Http\Controllers\Webhooks\NetIdUpdateController::class)->eventHubWebhook('etidentity.ldap.netid.term')->name('netid-update');
   });

   Important

   If your application employs a scale-to-zero database strategy for non-production environments, consider ONLY enabling this webhook in production by wrapping it in an environment check. Failure to do so may lead to excessive database spin-ups and an accumulation of messages being sent to the DLQ.

If you don’t have an EventHub subscription, leave this route commented out.

---

5. Environment Lockdown

The Environment Lockdown feature restricts application access to users who have been explicitly assigned application-specific roles. Users with only the default Northwestern User role (automatically assigned during SSO login), or no roles, are redirected to a lockdown page explaining they need to be granted access by an administrator.

This is most useful in non-production environments to prevent unauthorized users from accessing the application if they discover the URL.

Default Behavior

By default, lockdown is enabled for non-production environments and disabled for production, local development, CI, and tests:

config/platform.php

'lockdown' => [
    'enabled' => env('ENVIRONMENT_LOCKDOWN_ENABLED', match (env('APP_ENV')) {
        'production', 'local', 'testing', 'ci' => false,
        default => true,
    }),
],

Disabling for Specific Environments

To disable lockdown for a specific environment, add this to your .env file:

.env

ENVIRONMENT_LOCKDOWN_ENABLED=false

Tip

Useful for testing or for enabling lockdown in production during a closed beta launch.

Important: Production URL Configuration

Action Required

If you plan to use Environment Lockdown in your lower environments, you must configure the production URL. The lockdown page displays a link to the production environment so users know where to find the live application.

Option 1: Update Config Default (Recommended)

Edit config/platform.php to replace the default value:

config/platform.php

'production_url' => env('PRODUCTION_URL', 'https://northwestern.edu'),
'production_url' => env('PRODUCTION_URL', 'https://your-app.northwestern.edu'),

Option 2: Environment Variable

Add this to your .env file:

.env

PRODUCTION_URL=https://your-app.northwestern.edu

Exempted Routes

The following routes are always accessible, regardless of lockdown status:

• Authentication routes (OAuth, verification codes, logout)
• Impersonation routes (take/leave impersonation)
• The lockdown page itself

These exemptions ensure users can log in and administrators can manage impersonation. If you create additional routes that should be exempt, add them to the exempted_routes array in config/platform.php.

---

6. Project Cleanup

Important

Perform these cleanup tasks to personalize the starter kit for your project and remove references to the Northwestern Laravel Starter.

Find & Replace

1. Application Name

   Find: Northwestern Laravel Starter

   Replace: Your Application Name

2. Package/Project Identifier

   Find: northwestern-laravel-starter

   Replace: your-project-slug

Documentation Site

By default, the docs/ directory contains documentation for the starter kit itself. This can be removed entirely or modified to host your project’s documentation.

If you want to remove the documentation module, follow these steps:

rm .github/workflows/deploy-docs.yml
rm -rf docs/

If you keep it, update the DOCS_CNAME env var at the top of .github/workflows/deploy-docs.yml to point to your own domain.