Initial Customization

Before launching your application, customize these key settings to fit your project’s needs.

---

1. Super Administrator Accounts

Super Administrators have full access to the entire application and bypass all authorization checks. Commonly, these users are 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 they are invited by an administrator. Disable this if your app is only intended for Northwestern users.

Configuration Options

Edit config/auth.php or set environment variables:

config/auth.php

# Enable/disable local authentication
LOCAL_AUTH_ENABLED=true

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

# 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 the local auth configuration in config/auth.php to tune the OTP length, expiration, and lockout behavior.

'local' => [
    '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

# Rate limiting (requests per minute)
API_RATE_LIMIT_ATTEMPTS=1800

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\Http\Controllers\Webhooks\NetIdUpdateController::class)->eventHubWebhook('etidentity.ldap.netid.term')->name('netid-update');
       Route::post('netid-update', App\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 feature is particularly useful for non-production where you want 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

This is useful if you need to temporarily disable lockdown for testing or if you want to enable it in production for 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/app.php to replace the default value:

config/app.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, list them in EnvironmentLockdown::EXEMPTED_ROUTES accordingly.

---

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/