Scalekit Authentication Implementation

Overview

This skill helps you implement Scalekit authentication across different use cases. Choose the implementation path that matches your needs:

Implementation Paths

1. Full-Stack Authentication - Complete auth system for web apps

• User sign-up, login, logout
• Session management with tokens
• Social login (Google, GitHub, etc.)
• Best for: New applications or replacing existing auth

2. Modular SSO - Add Enterprise SSO to existing applications

• SAML/OIDC for enterprise customers
• Keep your existing auth system
• No user migration needed
• Best for: B2B SaaS adding enterprise SSO

3. MCP Server Authentication - Secure Model Context Protocol servers

• OAuth 2.1 for MCP clients (Claude Desktop, Cursor, VS Code)
• Scalekit-managed or custom auth integration
• Scope-based permissions
• Best for: MCP server developers

Quick Start: Choose Your Path

Path 1: Full-Stack Authentication

When to use: Building a new app or replacing authentication

Quickstart: full-stack-auth/quickstart.md

Templates:

• Node.js + Express
• Next.js App Router
• Python + FastAPI

What you get:

• Complete login/signup flows
• Session management
• Token refresh
• Logout handling
• Social & enterprise login

---

Path 2: Modular SSO

When to use: Adding Enterprise SSO to existing authentication

Quickstart: modular-sso/quickstart.md

Templates:

• Node.js + Express SSO

What you get:

• SAML/OIDC support
• Integration with Auth0/Firebase/Cognito
• Keep existing users and sessions
• Enterprise customer onboarding
• Admin portal for SSO setup

---

Path 3: MCP Server Authentication

When to use: Securing Model Context Protocol servers

Quickstarts:

• OAuth 2.1 with Scalekit - Scalekit manages auth
• Custom Auth Integration - Use your existing auth

What you get:

• OAuth 2.1 compliance
• MCP client support
• Token validation
• Scope-based permissions
• Discovery endpoint

---

Prerequisites

Before implementing any path, ensure you have:

1. Scalekit Account: Sign up at https://scalekit.com
2. Environment Variables: From Scalekit Dashboard → Settings
   • SCALEKIT_ENVIRONMENT_URL
   • SCALEKIT_CLIENT_ID
   • SCALEKIT_CLIENT_SECRET
3. Callback URLs Registered: In Scalekit Dashboard → Settings

Validate your setup:

python scripts/validate_env.py

Common Implementation Steps

Step 1: Install SDK

Node.js:

npm install @scalekit-sdk/node

Python:

pip install scalekit-sdk-python

Step 2: Initialize Client

Node.js:

import { Scalekit } from '@scalekit-sdk/node';

const scalekit = new Scalekit(
  process.env.SCALEKIT_ENVIRONMENT_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET
);

Python:

from scalekit import ScalekitClient

scalekit = ScalekitClient(
    env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET")
)

Step 3: Follow Your Implementation Path

Choose your path above and follow the quickstart guide.

Decision Helper

Not sure which path to use?

I need to add authentication to a new web app: → Use Full-Stack Authentication

I have authentication but need to add SSO for enterprise customers: → Use Modular SSO

I'm building an MCP server and need OAuth: → Use MCP Server Authentication (OAuth 2.1)

I have an MCP server and want to use my existing auth: → Use MCP Server Authentication (Custom Auth)

I need to add login to an existing app with no auth: → Use Full-Stack Authentication

Enterprise customers require SAML but I have password-based auth: → Use Modular SSO (keeps your password auth)

Key Concepts

Full-Stack Auth vs Modular SSO

Full-Stack Auth:

• Scalekit handles ALL authentication
• Replaces your auth system
• Tokens managed by Scalekit
• Complete user database in Scalekit

Modular SSO:

• Scalekit handles only SSO protocols
• Keeps your existing auth
• YOUR sessions and tokens
• YOUR user database

OAuth 2.1 for MCP Servers

• MCP clients (Claude Desktop) expect OAuth 2.1
• Scalekit provides OAuth server
• Discovery via .well-known/oauth-protected-resource
• Bearer tokens in requests
• Scope-based permissions

Security Best Practices

Token Storage

✅ DO:

• Use HttpOnly cookies for tokens
• Set secure: true in production (HTTPS)
• Use sameSite: 'strict' for CSRF protection
• Short token lifetimes (5-60 minutes)

❌ DON'T:

• Store tokens in localStorage
• Store tokens in sessionStorage
• Expose tokens to JavaScript

Token Validation

Always validate tokens server-side:

// ✅ Server-side validation
const claims = await scalekit.validateToken(token, {
  issuer: process.env.SCALEKIT_ENVIRONMENT_URL,
  audience: process.env.SCALEKIT_CLIENT_ID
});
req.user = claims; // Trust these claims

// ❌ Never trust client-provided data
const userId = req.cookies.userId; // Can be forged!

Session Management

See reference/session-management.md for comprehensive patterns.

Validation Scripts

Test your configuration before deploying:

# Validate environment variables
python scripts/validate_env.py

# Test Scalekit connectivity
python scripts/test_connection.py

# Interactive auth flow test
python scripts/test_auth_flow.py

Reference Documentation

Full-Stack Auth

• Quickstart Guide
• Session Management
• Security Best Practices

Modular SSO

• Quickstart Guide
• Express Integration

MCP Authentication

• OAuth 2.1 Quickstart
• Custom Auth Integration
• Python FastMCP Template

Framework Support

Framework	Full-Stack Auth	Modular SSO	MCP Auth
Node.js + Express	✅	✅	✅
Next.js (App Router)	✅	Coming	✅
Python + FastAPI	✅	Coming	✅
Python + FastMCP	-	-	✅
Django	Coming	Coming	Coming
Ruby on Rails	Coming	Coming	-
Go	Coming	Coming	✅

Common Issues & Troubleshooting

Redirect URI Mismatch

Error: "redirect_uri_mismatch"

Solution:

• Callback URL must match exactly
• Include protocol (http:// or https://)
• Include port if not 80/443
• Check Scalekit Dashboard → Settings → Redirect URIs

Token Validation Fails

Error: "Invalid or expired token"

Solutions:

• Verify token in Bearer header: Authorization: Bearer <token>
• Check issuer matches environment URL
• Ensure audience includes correct resource
• Token may have expired

Session Not Persisting

Symptoms: Users logged out immediately

Solutions:

• Set secure: false for localhost (HTTP)
• Check sameSite attribute
• Verify browser accepts cookies
• Check cookie domain and path

CORS Errors

Symptoms: Requests blocked by CORS

Solutions:

• Configure CORS middleware
• Set credentials: 'include' in fetch
• Specify exact origin (not wildcard)
• For cross-site: sameSite: 'none' + secure: true

Getting Help

For implementation questions:

• Review quickstart guides for your path
• Check framework-specific templates
• See reference documentation

For Scalekit questions:

• Documentation: https://docs.scalekit.com
• Support: support@scalekit.com

Advanced Features

Role-Based Access Control (RBAC)

Use token claims for authorization:

async function requireRole(req, res, next, role) {
  const claims = await scalekit.validateToken(req.cookies.accessToken, {
    issuer: process.env.SCALEKIT_ENVIRONMENT_URL,
    audience: process.env.SCALEKIT_CLIENT_ID
  });

  if (!claims.roles?.includes(role)) {
    return res.status(403).json({ error: 'Forbidden' });
  }

  next();
}

Organization-Based Access

Multi-tenant applications:

const claims = await scalekit.validateToken(token, {
  issuer: process.env.SCALEKIT_ENVIRONMENT_URL,
  audience: process.env.SCALEKIT_CLIENT_ID
});
const orgId = claims.org_id;

// Only allow access to organization's data
const data = await db.getData({ organization_id: orgId });

Custom Claims

Add custom data to tokens:

// When submitting user to Scalekit
await scalekit.auth.updateLoginUserDetails(connectionId, loginRequestId, {
  sub: user.id,
  email: user.email,
  custom_field: 'custom_value', // Custom claim
  roles: user.roles,
  organization_id: user.orgId
});

// Later, in token validation
const claims = await scalekit.validateToken(token, {
  issuer: process.env.SCALEKIT_ENVIRONMENT_URL,
  audience: process.env.SCALEKIT_CLIENT_ID
});
console.log(claims.custom_field); // 'custom_value'

Next Steps by Path

After Full-Stack Auth

1. Enable social login (Google, GitHub, Microsoft)
2. Add role-based access control
3. Customize login UI
4. Set up email notifications
5. Consider adding enterprise SSO

After Modular SSO

1. Enable domain verification
2. Set up SCIM for user provisioning
3. Add role mapping from IdP
4. Implement JIT provisioning
5. Create admin portal for customers

After MCP Authentication

1. Add more scopes for granular permissions
2. Implement rate limiting
3. Add audit logging
4. Test with multiple MCP clients
5. Document API for developers

Version Information

• Current Version: v1.0.0
• Includes:
  • Full-Stack Authentication
  • Modular SSO
  • MCP Server Authentication (OAuth 2.1 & Custom)
• Supported Languages: Node.js, Python
• Supported Frameworks: Express, Next.js, FastAPI

For the latest updates, see the GitHub repository.