Managing Users

Control user access to your self-hosted Stormkit instance with sign-up modes, domain whitelisting, and approval workflows

Available since: Stormkit v1.25.0

User management allows administrators to control who can sign up and access your self-hosted Stormkit instance. This feature provides fine-grained control over user registrations, making it ideal for organizations that need to restrict access to specific team members or domains.

Accessing User Management

1. Open Your Profile

   Click on your profile in the top right corner.

2. Navigate to Admin

   Select Admin from the dropdown menu.

3. Go to Authentication Settings

   Navigate to Authentication or go directly to /admin/auth-config.

Sign-Up Modes

Stormkit offers three different sign-up modes to control how users can register for your instance.

Off (No New Users Allowed)

• Completely disables new user registrations
• Existing users can continue to log in normally
• Use case: Lock down your instance to current users only

With this mode enabled, no new users can register, even if they have valid credentials from configured Git providers.

On (All Users Allowed)

• Allows anyone to sign up freely
• New users are automatically approved upon registration
• No approval required
• Use case: Open environments, development instances, or public deployments

This is the most permissive mode and is suitable for development environments where you want easy access for team members.

Approval Mode (Waitlist)

Enterprise Edition only - This feature requires an Enterprise Edition license.

• Requires admin approval for new user registrations
• Users can sign up, but their accounts remain pending until approved
• Supports domain-based whitelisting for automatic approval
• Use case: Production environments requiring strict access control

Domain Whitelisting

Enterprise Edition only - Domain whitelisting requires an Enterprise Edition license.

When using Approval Mode, you can configure domain whitelisting to automatically approve or deny users based on their email domain.

Allow Specific Domains

To automatically approve users from specific domains, enter the domains separated by commas:

example.org, stormkit.io, yourcompany.com

Users with email addresses from these domains will be automatically approved, while all others will require manual approval.

Example:

• [e-mail] → ✅ Auto-approved
• [e-mail] → ✅ Auto-approved
• [e-mail] → ⏳ Requires approval

Deny Specific Domains

To automatically reject users from specific domains, prefix each domain with an exclamation mark (!):

!spam.com, !blocked-domain.org, !competitor.com

Users with email addresses from these domains will be automatically rejected, while all others will require manual approval.

Example:

• [e-mail] → ❌ Auto-rejected
• [e-mail] → ❌ Auto-rejected
• [e-mail] → ⏳ Requires approval

Important: You cannot mix allowed and denied domains in the same whitelist. All domains must either be in allow mode (without !) or deny mode (with !).

Domain Matching Rules

• Domain matching is case-insensitive
• Whitespace around domains is automatically trimmed
• Subdomains are not automatically included (e.g., example.com does not match subdomain.example.com)

Managing Pending Users

Enterprise Edition only - Pending user management requires an Enterprise Edition license.

When Approval Mode is enabled, users who sign up will appear in the Pending Users section.

Approving Users

1. Navigate to Pending Users

   Scroll to the Pending Users section in /admin/auth-config.

2. Select Users

   Check the boxes next to users you want to approve.

3. Click Approve

   Click the Approve button.

4. Confirm

   Approved users will receive immediate access to the Stormkit instance.

Rejecting Users

1. Navigate to Pending Users

   Go to the Pending Users section in /admin/auth-config.

2. Select Users

   Check the boxes next to users you want to reject.

3. Click Reject

   Click the Reject button.

4. Confirm

   Rejected users will be removed from the pending list and cannot access the instance.

Rejected users can attempt to sign up again, but they will re-enter the pending state unless their domain is on the deny list.

Configuration Examples

Scenario 1: Company-Only Access

Goal: Only allow users with @yourcompany.com email addresses.

Configuration:

• Sign-up mode: Approval Mode (Enterprise Edition)
• Domain whitelist: yourcompany.com

Result:

• [e-mail] → ✅ Auto-approved
• [e-mail] → ⏳ Requires manual approval

Scenario 2: Block Competitors

Goal: Automatically reject users from known competitor domains.

Configuration:

• Sign-up mode: Approval Mode (Enterprise Edition)
• Domain whitelist: !competitor1.com, !competitor2.com

Result:

• [e-mail] → ❌ Auto-rejected
• [e-mail] → ⏳ Requires manual approval

Scenario 3: Development Environment

Goal: Allow anyone to sign up during development.

Configuration:

• Sign-up mode: On (All users allowed)
• Domain whitelist: (not applicable)

Result:

• All users → ✅ Auto-approved

Scenario 4: Locked Production Instance

Goal: Prevent any new registrations in production.

Configuration:

• Sign-up mode: Off (No new users)

Result:

• All new users → ❌ Registration disabled
• Existing users → ✅ Can still log in

Best Practices

Security Recommendations

Follow these security best practices for user management:

• Use Approval Mode for production environments to maintain strict access control
• Configure domain whitelisting to reduce manual approval overhead for trusted domains
• Regularly review pending users to ensure timely access for legitimate users
• Monitor user activity through audit logs
• Remove access for inactive or former team members promptly

Operational Guidelines

• Set clear policies on who should have access
• Document approval criteria for your team
• Respond to pending users within a reasonable timeframe (e.g., 24 hours)
• Communicate changes to sign-up policies with your team
• Test configuration changes in a non-production environment first

Domain Whitelist Tips

• Start with a narrow whitelist and expand as needed
• Use deny lists sparingly - they require ongoing maintenance
• Consider subdomains carefully (they must be listed explicitly)
• Keep the whitelist up to date when your organization changes email domains

Technical Notes

Persistence

• User management configuration is stored in the database
• Settings persist across service restarts
• Configuration changes take effect immediately

Behavior Details

• Changes to sign-up mode affect new registrations immediately
• Existing approved users are not affected by configuration changes
• Existing pending users are affected by changes to domain whitelisting
• Domain matching is case-insensitive for email addresses

Database Storage

User registration data is stored in PostgreSQL:

# Database configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=stormkit_db
POSTGRES_USER=stormkit_admin

Troubleshooting

Users Not Appearing in Pending List

Possible causes:

• Sign-up mode is set to “On” (auto-approval enabled)
• User’s domain is in the allow whitelist (auto-approved)
• User already has an approved account

Solution:

• Verify sign-up mode is set to “Approval Mode”
• Check domain whitelist configuration
• Search for the user in approved users list

Domain Whitelist Not Working

Possible causes:

• Mixed allow/deny domains (not supported)
• Extra whitespace in domain names
• Subdomain matching expectations

Solution:

• Ensure all domains use consistent format (all allow or all deny)
• Trim whitespace around domain names
• Add subdomains explicitly if needed

Cannot Enable Approval Mode

Cause: Approval Mode requires an Enterprise Edition license.

Solution:

• Upgrade to Enterprise Edition
• Use “On” or “Off” modes (available in Community Edition)

Environment Variables

User management doesn’t require specific environment variables, but relies on core Stormkit configuration:

.env

# Database connection (required)
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_DB=stormkit_db
POSTGRES_USER=stormkit_admin
POSTGRES_PASSWORD=your_password

# Application URLs (required)
STORMKIT_APP_URL=https://yourdomain.com
STORMKIT_API_URL=https://api.yourdomain.com

Next Steps

Authentication

Configure Git provider authentication

Custom Images

Build custom Docker images