Authentication Setup

Storm MCP Gateway uses enterprise-grade authentication powered by Keycloak to ensure your integrations remain secure. This guide covers all authentication methods and security configurations.

Authentication Overview

Storm MCP Gateway supports multiple authentication methods:

OAuth 2.0 - For seamless, secure authentication with third-party services
API Keys - For programmatic access and automation
SSO (Single Sign-On) - Enterprise identity provider integration
Multi-Factor Authentication - Additional security layer

Primary Authentication

OAuth 2.0 Login

The recommended authentication method for web access:

Navigate to Storm MCP Gateway
- Go to stormmcp.ai
- Click Sign In
Choose Your Provider
- Google - Use your Google account
- GitHub - Authenticate with GitHub
- Email - Traditional email/password
Grant Permissions
- Review requested permissions
- Click "Authorize" to proceed
Complete Setup
- First-time users: Complete profile setup
- Returning users: Redirected to dashboard

✅ Success

OAuth authentication automatically handles token refresh, keeping you signed in securely.

API Key Authentication

For programmatic access and client integrations:

Generating API Keys

Navigate to API Keys Section
- Go to Gateways page
- Click the key icon in the top right
Create New Key
Click "Generate New API Key" → Enter a descriptive name → Select expiration (optional) → Click "Generate"
Store Securely

⚠️ Warning

API keys are shown only once! Copy and store them immediately in a secure location.

Using API Keys

Include the API key in your requests:

# Header authentication
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.stormmcp.ai/v1/gateways

# Query parameter (less secure)
curl https://api.stormmcp.ai/v1/gateways?api_key=YOUR_API_KEY

API Key Best Practices

Rotate regularly - Generate new keys every 90 days
Use descriptive names - e.g., "Production-Cursor-Integration"
Set expiration dates - Automatic invalidation for temporary keys
Limit scope - Create separate keys for different purposes
Never commit to code - Use environment variables

MCP Client Authentication

Claude Desktop

Claude Desktop supports two authentication methods:

Option 1: OAuth (Recommended)

Click Claude Desktop button on your gateway
Select OAuth Authentication
Complete the browser authentication flow
Claude Desktop auto-configures

Option 2: API Key

Generate an API key (see above)
Click Claude Desktop button
Select API Key Authentication
Configuration is copied automatically

Cursor IDE

Cursor uses a deeplink protocol for authentication:

Click Cursor button on your gateway
Select authentication method:
- OAuth (opens browser)
- API Key (instant setup)
Cursor receives configuration automatically

Configuration format:

{
  "mcpServers": {
    "storm-gateway": {
      "command": "npx",
      "args": ["-y", "@storm-mcp/gateway-client"],
      "env": {
        "STORM_GATEWAY_URL": "https://gateway.stormmcp.ai/YOUR_ID",
        "STORM_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Enterprise SSO Integration

For enterprise customers using identity providers:

Supported Providers

Active Directory / LDAP
Okta
Auth0
PingIdentity
Azure AD
Google Workspace
Custom SAML 2.0

Configuration Steps

Contact Support
- Email enterprise@stormmcp.ai
- Provide your identity provider details
Configure IdP

 <EntityDescriptor> <SPSSODescriptor> <AssertionConsumerService Location="https://auth.stormmcp.ai/saml/callback" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/> </SPSSODescriptor> </EntityDescriptor>
Map Attributes
- Email → email
- Name → name
- Groups → groups (optional)
Test Integration
- Use test account first
- Verify attribute mapping
- Check group assignments

Multi-Factor Authentication (MFA)

Enhanced security with two-factor authentication:

Enabling MFA

Go to Settings → Security
Click Enable Two-Factor Authentication
Choose method:
- Authenticator App (recommended)
- SMS (requires phone verification)
- Email (backup option)

Authenticator App Setup

Install authenticator app:
- Google Authenticator
- Microsoft Authenticator
- Authy
- 1Password
Scan QR code or enter manual key
Enter verification code
Save backup codes securely

ℹ️ Info

Store backup codes in a secure location. They're your only recovery method if you lose access to your MFA device.

Role-Based Access Control (RBAC)

Storm MCP Gateway supports fine-grained permissions:

User Roles

Role	Permissions
Owner	Full access, billing, user management
Admin	Manage gateways, apps, view logs
Developer	Create/edit gateways, connect apps
Viewer	Read-only access to all resources

Managing Roles

Navigate to Settings → Team
Click Invite Member
Enter email and select role
User receives invitation email

Security Best Practices

Session Management

Auto-logout - Sessions expire after 24 hours of inactivity
Concurrent sessions - Limited to 5 active sessions
Session monitoring - View active sessions in Settings

Token Security

// Secure token storage
localStorage.setItem('token', encryptedToken);

// Token refresh
if (tokenExpired) {
  const newToken = await refreshToken();
  updateStoredToken(newToken);
}

IP Whitelisting (Enterprise)

Restrict access to specific IP ranges:

{
  "allowed_ips": [
    "192.168.1.0/24",
    "10.0.0.0/8",
    "203.0.113.0/32"
  ]
}

Troubleshooting Authentication

Common Issues

"Invalid credentials" error

Verify email/password
Check for typos
Try password reset

"Session expired" message

Normal after 24 hours
Click "Sign In" to refresh
Check "Remember me" for longer sessions

OAuth callback errors

Clear browser cookies
Check popup blockers
Try different browser

API key not working

# Verify key format
echo $STORM_API_KEY | base64 -d
# Should decode successfully

# Test key
curl -H "Authorization: Bearer $STORM_API_KEY" \
  https://api.stormmcp.ai/v1/auth/verify

MFA issues

Ensure device time is synced
Use backup codes if needed
Contact support for reset

Security Compliance

Storm MCP Gateway maintains compliance with:

SOC 2 Type II - Annual audits
ISO 27001 - Information security
GDPR - Data protection
HIPAA - Healthcare data (Enterprise)
PCI DSS - Payment card data

Next Steps

With authentication configured:

Support

Authentication questions?

📧 Security: security@stormmcp.ai
💬 Discord: #authentication
📖 Security Documentation