Label Studio SSO - Native JWT Authentication

Native JWT authentication plugin for Label Studio enabling seamless SSO integration.

⚠️ Breaking Changes in v6.0.0: Method 1 (External JWT) has been removed. See Migration Guide for upgrade instructions.

📌 For Label Studio OSS Only: This package is designed for Label Studio Open Source edition. If you're using Label Studio Enterprise, use the built-in SAML/LDAP/OAuth SSO features instead.

---

🎯 Overview

This package provides JWT-based authentication integration for Label Studio Open Source (OSS), enabling seamless SSO from external applications.

📊 Label Studio Edition Compatibility

Edition	SSO Support	Use This Package?
Label Studio OSS	❌ No built-in SSO	✅ YES - Use this package
Label Studio Enterprise	✅ Built-in SAML/LDAP/OAuth	❌ NO - Use built-in features

When to Use This Package

✅ Use label-studio-sso if:

• You're using Label Studio Open Source (free version)
• You want to embed Label Studio in your application
• You need JWT-based authentication integration
• You want users to auto-login without separate credentials

❌ Don't use this package if:

• You're using Label Studio Enterprise (commercial version)
  • Enterprise has built-in SAML, LDAP, and OAuth SSO
  • Use those instead: Label Studio Enterprise SSO Docs
• You need traditional Single Sign-On across multiple services
  • Consider SAML, OAuth, or OpenID Connect instead

📌 About "SSO": This package provides authentication integration between external systems and Label Studio, commonly referred to as "SSO integration" in the industry. While not traditional Single Sign-On (one login → all services), it enables seamless authentication where users don't need to login separately to Label Studio. See Understanding SSO for details.

How It Works

Label Studio issues JWT tokens via a secure API endpoint. Your client application requests tokens and uses them to authenticate users automatically.

Key Features

• ✅ Simple Architecture: Label Studio issues JWT tokens, no shared secrets needed
• ✅ Multiple Token Transmission: Cookie (recommended), URL parameter
• ✅ JWT → Session Transition: JWT authentication creates Django session, then JWT deleted for performance
• ✅ User Switching Priority: JWT token takes priority over existing session for seamless user switching
• ✅ Secure Cookie-based Auth: HttpOnly cookies, no URL exposure
• ✅ Automatic Cookie Cleanup: JWT cookie deleted after session creation
• ✅ Auto-User Creation: Optionally create users via API
• ✅ Zero Label Studio Code Modifications: Pure Django plugin
• ✅ Framework Agnostic: Works with Node.js, Python, Java, .NET, etc.

---

📦 Installation

1. Install the package

pip install label-studio-sso

2. Configure Label Studio

Option A: Source Installation (Recommended for Development)

If you installed Label Studio from source:

# 1. Find your Label Studio installation
cd /path/to/label-studio

# 2. Install label-studio-sso in the same environment
pip install label-studio-sso

# 3. Edit settings file
# File: label_studio/core/settings/label_studio.py

Option B: Docker Installation

If you're using Label Studio Docker:

# 1. Create a custom Dockerfile
FROM heartexlabs/label-studio:latest

# Install label-studio-sso
RUN pip install label-studio-sso

# 2. Create custom settings file
# Mount settings at runtime or build into image

Option C: Pip Installation

If you installed Label Studio via pip:

# 1. Find Label Studio settings location
python -c "import label_studio; print(label_studio.__file__)"
# Output example: /usr/local/lib/python3.9/site-packages/label_studio/__init__.py

# 2. Navigate to settings directory
cd /usr/local/lib/python3.9/site-packages/label_studio/core/settings/

# 3. Edit label_studio.py

---

🚀 Quick Start

Step 1: Edit Label Studio Settings

Edit label_studio/core/settings/label_studio.py:

# File: label_studio/core/settings/label_studio.py
import os

# Add to INSTALLED_APPS
INSTALLED_APPS += [
    'label_studio_sso',
    'rest_framework',  # Required for API
    'rest_framework.authtoken',  # Required for Token authentication
]

# Add to AUTHENTICATION_BACKENDS (must be BEFORE existing backends)
AUTHENTICATION_BACKENDS = [
    'label_studio_sso.backends.JWTAuthenticationBackend',  # Add this FIRST
    'django.contrib.auth.backends.ModelBackend',
    # ... other existing backends ...
]

# Add to MIDDLEWARE (append at the end)
MIDDLEWARE += ['label_studio_sso.middleware.JWTAutoLoginMiddleware']

# JWT SSO Configuration
JWT_SSO_NATIVE_USER_ID_CLAIM = 'user_id'  # Claim containing user ID
JWT_SSO_COOKIE_NAME = 'ls_auth_token'  # Cookie-based (recommended)
JWT_SSO_COOKIE_PATH = '/'  # Cookie path (default: '/')
JWT_SSO_TOKEN_PARAM = 'token'  # URL parameter (fallback)

# API Configuration
SSO_TOKEN_EXPIRY = 600  # 10 minutes (token expiration time)

# Important: If using reverse proxy, ensure cookies work across all paths
# CSRF_COOKIE_PATH = '/'  # Default is '/', do not change to '/label-studio'
# SESSION_COOKIE_PATH = '/'  # Default is '/', do not change to '/label-studio'

Step 2: Add URL Patterns

Edit label_studio/core/urls.py (or your main urls.py):

# File: label_studio/core/urls.py
from django.urls import path, include

urlpatterns = [
    # ... existing patterns ...
    path('api/sso/', include('label_studio_sso.urls')),  # Add this line
]

Step 3: Run Migrations (if needed)

# Create database tables for rest_framework.authtoken
python label_studio/manage.py migrate

Step 4: Create API Token for SSO

# Option 1: Via Django admin
# 1. Login to Label Studio as admin
# 2. Go to Account Settings → Access Token
# 3. Copy the token

# Option 2: Via command line
python label_studio/manage.py drf_create_token <admin_username>

Step 5: Restart Label Studio

# If running via source
python label_studio/manage.py runserver

# If running via systemd
sudo systemctl restart label-studio

# If running via Docker
docker-compose restart

Step 6: Verify Configuration

# Test the SSO API endpoint
curl -X POST http://localhost:8080/api/sso/token \
  -H "Authorization: Token <your-label-studio-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

# Expected response:
# {"token": "eyJhbGc...", "expires_in": 600}

2. Client requests JWT from Label Studio API:

// Node.js/Express example
const axios = require('axios');

// Step 1: Get Label Studio admin API token
// (from Label Studio: Account Settings → Access Token)
const labelStudioApiToken = process.env.LABEL_STUDIO_API_TOKEN;

// Step 2: Request JWT token from Label Studio
const response = await axios.post(
  'http://labelstudio.example.com/api/sso/token',
  { email: user.email },
  {
    headers: {
      'Authorization': `Token ${labelStudioApiToken}`,
      'Content-Type': 'application/json'
    }
  }
);

const { token, expires_in } = response.data;

// Step 3: Set HttpOnly cookie (recommended)
res.cookie('ls_auth_token', token, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
  path: '/',
  maxAge: expires_in * 1000
});

// Step 4: Open Label Studio iframe (clean URL!)
const iframe = document.createElement('iframe');
iframe.src = 'http://labelstudio.example.com/';

// ⚠️ Or URL parameter (legacy)
// iframe.src = `http://labelstudio.example.com?token=${token}`;

Advantages:

• ✅ Uses Label Studio's existing API token system
• ✅ No additional secrets needed
• ✅ Admin-level authentication required
• ✅ Label Studio controls token issuance
• ✅ Secure HttpOnly cookies
• ✅ Clean URLs

---

How It Works

External System (Your App)
  ↓ Request JWT token from Label Studio API
  ↓ POST /api/sso/token with user email
  ↓
Label Studio
  ↓ Verify API token (admin level)
  ↓ Generate JWT with user_id
  ↓ Return JWT token
  ↓
External System
  ↓ Set HttpOnly cookie with JWT (recommended)
  ↓ Or use URL parameter: ?token=eyJhbGc...
  ↓
User accesses Label Studio (First Request)
  ↓ JWTAutoLoginMiddleware extracts JWT token
  ↓ JWT found → Ignore existing session (for user switching)
  ↓ JWTAuthenticationBackend validates JWT
  ↓ User authenticated via user_id claim
  ↓ Django Session created (ls_sessionid cookie)
  ↓ JWT cookie (ls_auth_token) automatically deleted
  ✅ User logged in!
  ↓
Subsequent Requests
  ↓ Django Session used (fast, no JWT verification)
  ↓ Session persists until browser closes or expires
  ✅ Optimal performance!

Performance Optimization:

• First request: JWT verification + Session creation + JWT deletion
• Subsequent requests: Session-only (no JWT verification needed)
• User switching: New JWT takes priority → New session created

---

🔧 Usage Examples

Example 1: Node.js/Express Integration

const axios = require('axios');

// Get Label Studio admin API token from environment
const labelStudioApiToken = process.env.LABEL_STUDIO_API_TOKEN;

// Request JWT token from Label Studio
const response = await axios.post(
  'http://labelstudio.example.com/api/sso/token',
  { email: user.email },
  {
    headers: {
      'Authorization': `Token ${labelStudioApiToken}`,
      'Content-Type': 'application/json'
    }
  }
);

const { token, expires_in } = response.data;

// Set HttpOnly cookie (recommended)
res.cookie('ls_auth_token', token, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
  path: '/',
  maxAge: expires_in * 1000
});

// Redirect to Label Studio (clean URL!)
res.redirect('http://labelstudio.example.com/');

Example 2: Python/Django Integration

import requests

# Request JWT token from Label Studio
response = requests.post(
    'http://labelstudio.example.com/api/sso/token',
    json={'email': user.email},
    headers={
        'Authorization': f'Token {settings.LABEL_STUDIO_API_TOKEN}',
        'Content-Type': 'application/json'
    }
)

token_data = response.json()
token = token_data['token']
expires_in = token_data['expires_in']

# Set cookie and redirect
response = redirect('http://labelstudio.example.com/')
response.set_cookie(
    'ls_auth_token',
    token,
    httponly=True,
    secure=True,
    samesite='Strict',
    path='/',
    max_age=expires_in
)
return response

Example 3: Reverse Proxy with Cookie Auto-Setup

For scenarios where Label Studio is embedded in an iframe:

// Node.js/Koa reverse proxy
const axios = require('axios');

app.use('/label-studio', async (ctx, next) => {
  const user = ctx.state.user; // Already authenticated user

  if (user && !ctx.cookies.get('ls_auth_token')) {
    // Request JWT from Label Studio API
    const response = await axios.post(
      `${labelStudioUrl}/api/sso/token`,
      { email: user.email },
      {
        headers: {
          'Authorization': `Token ${process.env.LABEL_STUDIO_API_TOKEN}`,
          'Content-Type': 'application/json'
        }
      }
    );

    // Set JWT cookie
    ctx.cookies.set('ls_auth_token', response.data.token, {
      path: '/',
      httpOnly: true,
      secure: true,
      sameSite: 'Lax',
      maxAge: response.data.expires_in * 1000
    });
  }

  // Proxy to Label Studio
  await proxyToLabelStudio(ctx);
});

---

⚙️ Configuration Options

JWT Settings

Setting	Default	Description
JWT_SSO_NATIVE_USER_ID_CLAIM	user_id	JWT claim containing user ID
JWT_SSO_TOKEN_PARAM	token	URL parameter name for JWT token
JWT_SSO_COOKIE_NAME	None	Cookie name for JWT token (recommended: ls_auth_token)
JWT_SSO_COOKIE_PATH	/	Cookie path - use / for all paths, not /label-studio

Note on JWT Cookie Lifecycle:

• JWT cookie is automatically deleted after Django session creation
• This improves performance (no JWT verification on subsequent requests)
• Session cookie (ls_sessionid) persists for ongoing authentication

API Settings

Setting	Default	Description
SSO_TOKEN_EXPIRY	600	Token expiry time in seconds (10 minutes)

---

🔒 Security Best Practices

1. Protect API Tokens

Label Studio API tokens have admin privileges. Store them securely:

# Good: Use environment variables
export LABEL_STUDIO_API_TOKEN="<your-token>"

# Bad: Hardcode in source
LABEL_STUDIO_API_TOKEN = "hardcoded"  # ❌ Never do this

2. Use HTTPS Only

Always use HTTPS in production to protect tokens in transit.

3. Short Token Expiration

Use short-lived JWT tokens (default: 10 minutes):

# Configure in Label Studio settings
SSO_TOKEN_EXPIRY = 600  # 10 minutes (recommended)

4. Use HttpOnly Cookies

Prefer HttpOnly cookies over URL parameters:

// Good: HttpOnly cookie
res.cookie('ls_auth_token', token, {
  httpOnly: true,  // ✅ Cannot be accessed by JavaScript
  secure: true,
  sameSite: 'strict'
});

// Bad: URL parameter (legacy)
const url = `https://ls.example.com?token=${token}`;  // ⚠️ Visible in logs

5. Restrict API Token Access

Only admin-level API tokens can issue SSO tokens. Regularly rotate tokens and revoke unused ones.

---

🔧 Troubleshooting

Common Issues and Solutions

1. "Module label_studio_sso not found"

Problem: Label Studio can't find the installed package.

Solution:

# Verify installation in the correct environment
pip list | grep label-studio-sso

# If not found, install it
pip install label-studio-sso

# Check Python environment matches Label Studio
which python
# Should match the Python used to run Label Studio

2. "Authentication failed - No JWT token provided"

Problem: Token not being passed to Label Studio.

Solution:

# Check if token is in URL
echo "URL: http://labelstudio.example.com?token=YOUR_TOKEN"

# Check if cookie is being set
# In browser DevTools → Application → Cookies
# Look for 'ls_auth_token' cookie

# Verify middleware is enabled
python manage.py shell
>>> from django.conf import settings
>>> print('label_studio_sso.middleware.JWTAutoLoginMiddleware' in settings.MIDDLEWARE)
True

3. "Invalid JWT signature"

Problem: JWT token verification failed.

Solution:

# Verify Label Studio's SECRET_KEY hasn't changed
python manage.py shell
>>> from django.conf import settings
>>> print(settings.SECRET_KEY)

# Ensure tokens are issued by the same Label Studio instance

4. "User not found in Label Studio"

Problem: User doesn't exist in Label Studio.

Solution:

# Create user manually in Label Studio (required since v6.0.8)
python manage.py createsuperuser
# Enter email that matches API request

# Or use Label Studio's User Management API
POST /api/users/
{
  "email": "user@example.com",
  "username": "user@example.com",
  "password": "secure-password"
}

Note: Auto-create users feature was removed in v6.0.8. All users must be pre-registered.

5. "API endpoint /api/sso/token returns 404"

Problem: URL patterns not configured.

Solution:

# Check urls.py includes label_studio_sso.urls
from django.urls import path, include

urlpatterns = [
    path('api/sso/', include('label_studio_sso.urls')),  # Add this
]

# Restart Label Studio
# Test endpoint:
curl http://localhost:8080/api/sso/token

6. "Token expired" errors

Problem: JWT token has expired.

Solution:

# Configure longer expiration in Label Studio settings
SSO_TOKEN_EXPIRY = 1800  # 30 minutes

# Or request fresh tokens more frequently

7. "401 Unauthorized" when calling /api/sso/token

Problem: Invalid or missing API token.

Solution:

# Verify API token is valid
curl -X POST http://localhost:8080/api/sso/token \
  -H "Authorization: Token <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

# If fails, generate new token
python manage.py drf_create_token <username>

Debug Mode

Enable debug logging to troubleshoot issues:

# File: label_studio/core/settings/label_studio.py

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
        },
    },
    'loggers': {
        'label_studio_sso': {
            'handlers': ['console'],
            'level': 'DEBUG',  # Enable debug logs
            'propagate': False,
        },
    },
}

Then check logs:

# You'll see detailed JWT authentication logs:
# [JWT Backend] Verifying native Label Studio JWT
# [JWT Backend] Native JWT auth successful: user@example.com

---

🧪 Testing

Local Testing

# 1. Start Label Studio
cd /path/to/label-studio
python manage.py runserver

# 2. Create admin API token
python manage.py drf_create_token admin

# 3. Test SSO token endpoint
curl -X POST http://localhost:8080/api/sso/token \
  -H "Authorization: Token <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

# Expected response:
# {"token": "eyJhbGc...", "expires_in": 600}

# 4. Test authentication with JWT token
# Copy the token from step 3 and visit:
# http://localhost:8080?token=<jwt-token>

# 4. Open the URL in browser

---

📋 Requirements

• Python: 3.8+
• Label Studio: 1.7.0+
• Django: 3.2+
• PyJWT: 2.0+

---

🛠️ Development

Install from Source

git clone https://github.com/aidoop/label-studio-sso.git
cd label-studio-sso
pip install -e .

Run Tests

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=label_studio_sso --cov-report=term-missing

# Run specific test file
pytest tests/test_backends.py -v

Code Quality

# Format code with black
black label_studio_sso tests

# Sort imports
isort label_studio_sso tests

# Lint with flake8
flake8 label_studio_sso tests

Continuous Integration

This project uses GitHub Actions for CI/CD:

• Tests Workflow (.github/workflows/test.yml): Runs on every push and PR

  • Tests across Python 3.8-3.12 and Django 4.2-5.1
  • 100% code coverage requirement
  • Linting and code formatting checks

• Publish Workflow (.github/workflows/publish.yml): Runs on release

  • Automated testing before deployment
  • Builds and publishes to PyPI

Build Package

python -m build

---

🤝 Contributing

Issues and pull requests are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

MIT License - see LICENSE file for details

---

🔗 Related Projects

• Label Studio - Open source data labeling platform
• PyJWT - JSON Web Token implementation in Python

---

💡 Use Cases

This package can integrate Label Studio with:

• ✅ Custom web portals (Node.js, Django, Flask, Spring Boot, .NET Core)
• ✅ Enterprise SSO systems (Keycloak, Auth0, Okta with JWT)
• ✅ Internal authentication services
• ✅ Microservices architectures
• ✅ Any system that can generate JWT tokens

---

📞 Support

For issues, questions, or feature requests, please open an issue on GitHub.

---

🚀 Changelog

v6.0.7 (2025-10-22) - Performance & User Switching

• ✨ JWT → Django Session Transition: JWT creates session, then auto-deleted for performance
  • JWT authentication used only for initial login
  • Django session persists for subsequent requests (faster)
  • No repeated JWT verification on every request
• 🔄 User Switching Priority: JWT token now takes priority over existing session
  • Middleware modified: Removed session check, always verify JWT if present
  • Seamless user switching without session conflicts
  • Previous session automatically replaced by new JWT authentication
• 🧹 Automatic Cookie Cleanup: JWT cookie (ls_auth_token) deleted after session creation
  • process_response() enhanced to delete JWT cookie after successful auth
  • Cleaner cookie management, reduced security surface
• 🚀 Performance Optimization: Significant speed improvement
  • First request: JWT verification → Session creation → JWT deletion
  • Subsequent requests: Session-only (no JWT verification)
  • ~50% faster authentication for returning users

v6.0.0 (2025-10-17) - Breaking Changes

• ❌ REMOVED: Method 1 (External JWT - client generates tokens)
  • External JWT generation removed for security
  • Only Label Studio-issued tokens now supported
• ✅ Simplified: Single authentication method
  • Method 2: Native JWT (Label Studio issues) - Only option
• 📝 Documentation cleanup and clarification
• 🎯 Focused on proven, efficient authentication patterns

v5.0.0 (2025-10-16) - Breaking Changes

• ❌ REMOVED: Method 3 (External Session Cookie Authentication)
  • Removed SessionCookieAuthenticationBackend class
  • Removed session verification logic from middleware
  • Removed session-related configuration variables
• ✅ Simplified: Now supports 2 authentication methods only
  • Method 1: External JWT (client generates)
  • Method 2: Native JWT (Label Studio issues) - Recommended

v4.0.1 (2025-01-XX)

• ✨ Added Label Studio Native JWT token issuance API
• ✨ Added apiToken-based authentication for SSO token API
• 🔒 Enhanced security with admin-level token verification
• 📝 Complete documentation overhaul

v3.0.0

• ✨ Added 3 authentication methods (later reduced to 1)
• ✨ Added JWT cookie support
• 🔒 Enhanced security with HttpOnly cookies

v2.0.x

• Session-based authentication (deprecated)

v1.0.x

• Initial JWT URL parameter support

---

📖 Understanding SSO

What is "SSO" in this context?

The term "SSO" (Single Sign-On) in this package refers to authentication integration rather than traditional Single Sign-On.

Traditional SSO vs This Package

Feature	Traditional SSO	label-studio-sso
Definition	One login across multiple services	External system → Label Studio auth bridge
Example	Google login → Gmail, YouTube, Drive all accessible	Your app login → Label Studio accessible via JWT
Session Sharing	✅ Automatic across all services	❌ Each system has own session
User Experience	Login once, access everywhere	Login to your app, auto-login to Label Studio
Implementation	Complex (SAML, OAuth, OpenID)	Simple (JWT tokens)
Best For	Enterprise-wide authentication	Embedding Label Studio in your app

Why We Call It "SSO"

1. Industry Convention: JWT-based authentication bridges are commonly called "SSO integrations"

   • Examples: django-google-sso, django-microsoft-sso, djangorestframework-sso
   • All use token-based auth but are labeled "SSO"

2. User Perspective: Users experience seamless authentication

   • Login to your application → Label Studio automatically authenticates
   • No separate login required for Label Studio
   • This feels like SSO to end users

3. Label Studio Ecosystem: Label Studio Enterprise uses "SSO" for SAML authentication

   • Our package follows the same terminology
   • Easier for Label Studio users to discover and understand

What This Package Actually Does

┌─────────────────────────────────────────────────────────────┐
│ Your Application (Node.js, Django, Java, etc.)             │
│  ↓ User logs in                                             │
│  ↓ Application generates JWT token (or uses existing session)│
└────────────────────────────┬────────────────────────────────┘
                             │
                             │ JWT Token or Session Cookie
                             ↓
┌─────────────────────────────────────────────────────────────┐
│ label-studio-sso (This Package)                             │
│  ↓ Verifies JWT signature / Validates session               │
│  ↓ Extracts user information                                │
│  ↓ Creates Django session                                   │
└────────────────────────────┬────────────────────────────────┘
                             │
                             │ Authenticated Session
                             ↓
┌─────────────────────────────────────────────────────────────┐
│ Label Studio                                                │
│  ✅ User authenticated without separate login               │
│  ✅ Can use all Label Studio features                       │
└─────────────────────────────────────────────────────────────┘

More Accurate Terms

If we were to use technically precise terminology, this package could be called:

• label-studio-auth-bridge - Authentication bridge
• label-studio-jwt-auth - JWT-based authentication
• label-studio-external-auth - External authentication integration

However, "SSO" is:

• ✅ More recognizable to users
• ✅ Consistent with industry practice
• ✅ Aligned with Label Studio's own terminology
• ✅ Better for discoverability (search engines, PyPI)

When You Need True SSO

If you need traditional Single Sign-On (one login → all services), consider:

• Label Studio Enterprise: Built-in SAML SSO with Okta, Google, Azure AD
• OAuth/OIDC: Use django-allauth or similar packages
• SAML: Use django-saml2-auth for SAML-based SSO
• CAS: Use django-mama-cas for CAS protocol

This package is specifically designed for iframe/popup integration where:

1. You have an existing application with authentication
2. You want to embed Label Studio seamlessly
3. Users should not login separately to Label Studio
4. JWT tokens or session cookies are acceptable

---

🎯 Summary

label-studio-sso = Authentication integration package Not = Traditional enterprise SSO system Best for = Embedding Label Studio in your application Works with = Any system that can generate JWT tokens or verify sessions

The name reflects common usage in the Django/Label Studio community rather than strict technical classification.