Comprehensive authentication implementation guide for Scalekit. Supports full-stack auth, modular SSO (SAML/OIDC), and MCP OAuth 2.1. Includes FastMCP support.

version
1.1.0

Install

/plugin install scalekit-auth@scalekit-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add scalekit-inc/claude-auth-skill.

Contents

Discovered from source

Skills 1

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:

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:

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:

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

Modular SSO

MCP Authentication

Framework Support

FrameworkFull-Stack AuthModular SSOMCP Auth
Node.js + Express✅✅✅
Next.js (App Router)✅Coming✅
Python + FastAPI✅Coming✅
Python + FastMCP--✅
DjangoComingComingComing
Ruby on RailsComingComing-
GoComingComing✅

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:

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.

Commands 3

Initialize Scalekit Authentication Project

I'll help you set up a new project with Scalekit authentication.

Step 1: Gather Information

First, let's understand your project:

  1. What framework are you using?

    • Node.js + Express
    • Next.js (App Router)
    • Python + FastAPI
    • Other (tell me which one)
  2. What authentication path do you need?

    • Full-Stack Authentication (complete auth system)
    • Modular SSO (add SSO to existing auth)
    • MCP Server Authentication (OAuth 2.1 for MCP)
  3. Do you have Scalekit credentials?

    • If yes: I'll help you set up environment variables
    • If no: I'll guide you to create a Scalekit account

Step 2: Setup Process

Once you answer the questions above, I will:

  1. Create the necessary environment configuration (.env file)
  2. Guide you through installing the Scalekit SDK
  3. Provide complete, working code for your framework
  4. Set up validation scripts to test your configuration
  5. Give you a production deployment checklist

Step 3: Validation

After setup, we'll run validation scripts to ensure everything works:

  • Environment variables configured correctly
  • Scalekit API connectivity verified
  • Authentication flow tested

Please answer the questions in Step 1, and I'll get started with your setup!

Validate Scalekit Configuration

I'll help you validate your Scalekit setup by running the validation scripts.

Validation Steps

  1. Check Environment Variables

    • Verify SCALEKIT_ENVIRONMENT_URL is set
    • Verify SCALEKIT_CLIENT_ID is set
    • Verify SCALEKIT_CLIENT_SECRET is set
    • Check callback URLs are configured
  2. Test Scalekit API Connectivity

    • Attempt connection to Scalekit API
    • Verify credentials are valid
    • Check network connectivity
  3. Test Authentication Flow (optional)

    • Interactive OAuth flow test
    • Verify token exchange works
    • Test callback handling

Running Validation Scripts

The Scalekit authentication plugin includes Python validation scripts. Let me check if they're available and run them for you.

Do you have:

  • Python 3.7+ installed?
  • Required packages (anthropic, python-dotenv)?
  • A .env file with Scalekit credentials?

Let me know and I'll run the appropriate validation scripts or help you set them up!

Scalekit Authentication Helper

Welcome to the Scalekit Authentication plugin! I'll help you implement Scalekit authentication in your application.

Choose Your Implementation Path

Ask yourself these questions:

Are you building a new application that needs authentication? → Use Full-Stack Authentication path

Do you have existing authentication but need to add Enterprise SSO (SAML/OIDC)? → Use Modular SSO path

Are you building an MCP server that needs OAuth 2.1? → Use MCP Server Authentication path

What would you like to do?

  1. Implement Full-Stack Authentication

    • Complete auth system for web apps
    • Handles login, signup, logout, sessions
    • Supports social login + enterprise SSO
    • Frameworks: Express, Next.js, FastAPI
  2. Add Modular SSO to Existing Auth

    • Keep your existing authentication
    • Add SAML/OIDC for enterprise customers
    • No user migration needed
    • Frameworks: Express, Next.js
  3. Secure MCP Server with OAuth 2.1

    • OAuth 2.1 compliance for MCP protocol
    • Scalekit-managed or custom auth
    • Works with Claude Desktop, Cursor, VS Code
  4. Validate Environment Setup

    • Check Scalekit credentials
    • Test API connectivity
    • Verify configuration

Please tell me which path you'd like to take, or ask me any questions about Scalekit authentication!

Sponsors

Details

Marketplace
scalekit-inc/claude-auth-skill
Category
Community