@things-factory/integration-label-studio 9.1.19

package/INTEGRATION.md

@@ -0,0 +1,279 @@
+# Label Studio Integration Guide
+
+This document explains how to integrate Label Studio with Things Factory using subdomain-based cookie sharing for SSO authentication.
+
+## Architecture Overview
+
+The integration uses **subdomain cookie sharing** instead of proxying, which simplifies deployment and improves performance.
+
+### Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. Frontend calls SSO setup endpoint                            │
+│    GET /label-studio/sso/setup                                  │
+│    Credentials: include                                         │
+└────────────────────┬────────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. Backend requests JWT from Label Studio                       │
+│    POST http://label.example.com:8080/api/sso/token             │
+│    Authorization: Token {apiToken}                              │
+│    Body: { email: "user@example.com" }                          │
+└────────────────────┬────────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 3. Backend sets cookie with shared domain                       │
+│    Set-Cookie: ls_auth_token={jwt}                              │
+│    Domain: .example.com  ← Shared across all *.example.com      │
+│    Path: /                                                      │
+│    SameSite: Lax                                                │
+└────────────────────┬────────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 4. Frontend loads Label Studio in iframe                        │
+│    <iframe src="http://label.example.com:8080/projects/1">      │
+│    Cookie is automatically sent with request                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Configuration
+
+### 1. Domain Setup
+
+Both Things Factory and Label Studio must be accessible via subdomain pattern:
+
+**Development (localhost):**
+```
+Things Factory:  http://app.dataset.localhost:3000
+Label Studio:    http://label.dataset.localhost:8080
+```
+
+**Production:**
+```
+Things Factory:  https://app.example.com
+Label Studio:    https://label.example.com
+```
+
+**Important:** Modern browsers automatically resolve `*.localhost` to `127.0.0.1`, so no `/etc/hosts` modification is needed for development.
+
+### 2. Label Studio Configuration
+
+Create or update `.env` file in Label Studio installation:
+
+```bash
+# JWT SSO Settings
+JWT_SSO_SECRET=your-secret-key-here
+JWT_SSO_ALGORITHM=HS256
+JWT_SSO_TOKEN_PARAM=token
+JWT_SSO_EMAIL_CLAIM=email
+JWT_SSO_USERNAME_CLAIM=username
+JWT_SSO_FIRST_NAME_CLAIM=first_name
+JWT_SSO_LAST_NAME_CLAIM=last_name
+JWT_SSO_AUTO_CREATE_USERS=true
+JWT_SSO_COOKIE_NAME=ls_auth_token
+
+# CORS and CSRF Settings
+CSRF_TRUSTED_ORIGINS=http://app.dataset.localhost:3000,http://label.dataset.localhost:8080
+ALLOWED_HOSTS=localhost,label.dataset.localhost,*.dataset.localhost
+
+# CSP Settings - Allow iframe embedding
+ENABLE_CSP=False
+
+# Session Settings
+SESSION_COOKIE_SAMESITE=Lax
+SESSION_COOKIE_SECURE=0  # Set to 1 for HTTPS
+SESSION_COOKIE_HTTPONLY=0
+SESSION_COOKIE_PATH=/
+```
+
+### 3. Things Factory Configuration
+
+Add Label Studio configuration to your Things Factory config file:
+
+**config/default.json:**
+```json
+{
+  "labelStudio": {
+    "serverUrl": "http://label.dataset.localhost:8080",
+    "apiToken": "your-label-studio-api-token",
+    "cookieDomain": ".dataset.localhost"
+  }
+}
+```
+
+**config/production.json:**
+```json
+{
+  "labelStudio": {
+    "serverUrl": "https://label.example.com",
+    "apiToken": "your-label-studio-api-token",
+    "cookieDomain": ".example.com"
+  }
+}
+```
+
+### 4. Get Label Studio API Token
+
+1. Start Label Studio and login as admin
+2. Navigate to **Account & Settings** → **Access Token**
+3. Click **Create new token**
+4. Copy the token and add it to Things Factory configuration
+
+## Usage
+
+### Embedding Label Studio
+
+Use the `<label-studio-wrapper>` component to embed Label Studio:
+
+```typescript
+import '@things-factory/integration-label-studio/client'
+
+// In your component
+render() {
+  const projectId = 123
+  const path = `/projects/${projectId}`
+
+  return html`
+    <label-studio-wrapper .path=${path}></label-studio-wrapper>
+  `
+}
+```
+
+### API Endpoints
+
+The integration provides the following endpoints:
+
+**SSO Setup:**
+```
+GET /label-studio/sso/setup
+```
+Sets up SSO authentication by acquiring JWT token and setting cookie.
+
+**Health Check:**
+```
+GET /label-studio/sso/health
+```
+Returns Label Studio integration status.
+
+**Configuration:**
+```
+GET /label-studio/sso/config
+```
+Returns current Label Studio configuration.
+
+## Development Setup
+
+### 1. Start Label Studio
+
+```bash
+cd /path/to/label-studio
+label-studio start --host label.dataset.localhost --port 8080
+```
+
+### 2. Start Things Factory
+
+```bash
+cd /path/to/things-factory
+DEBUG=things-factory:* yarn workspace @things-factory/your-app run serve:dev
+```
+
+### 3. Access Application
+
+Open browser to:
+```
+http://app.dataset.localhost:3000
+```
+
+## Troubleshooting
+
+### Cookie Not Set
+
+**Symptom:** SSO setup succeeds but cookie doesn't appear in browser
+
+**Solutions:**
+1. Verify `cookieDomain` in Things Factory config matches your domain pattern
+2. Check Label Studio `ALLOWED_HOSTS` includes your subdomain
+3. Ensure both services use same root domain (e.g., both use `*.dataset.localhost`)
+
+### CORS Errors
+
+**Symptom:** Browser blocks requests with CORS errors
+
+**Solutions:**
+1. Add Things Factory domain to Label Studio's `CSRF_TRUSTED_ORIGINS`
+2. Verify `ALLOWED_HOSTS` includes all subdomain patterns
+3. Check `ENABLE_CSP=False` in Label Studio configuration
+
+### Authentication Loop
+
+**Symptom:** Label Studio keeps showing login page
+
+**Solutions:**
+1. Verify JWT SSO settings in Label Studio `.env`
+2. Check cookie is being sent with iframe requests (browser DevTools → Network)
+3. Ensure `JWT_SSO_COOKIE_NAME=ls_auth_token` matches implementation
+
+### Token Expiration
+
+**Symptom:** Users get logged out after 10 minutes
+
+**Solution:**
+Label Studio JWT tokens expire after 600 seconds (10 minutes) by default. The integration automatically handles re-authentication on page refresh.
+
+## Security Considerations
+
+### Production Checklist
+
+- ✅ Use HTTPS for all services
+- ✅ Set `SESSION_COOKIE_SECURE=1` in Label Studio
+- ✅ Set `httpOnly: true` in SSO route cookie options
+- ✅ Use strong `JWT_SSO_SECRET`
+- ✅ Limit `ALLOWED_HOSTS` to specific domains
+- ✅ Enable CSRF protection
+- ✅ Use firewall rules to restrict Label Studio access
+
+### Cookie Domain Best Practices
+
+**Do:**
+- Use `.example.com` for sharing across all subdomains
+- Use specific subdomain pattern for restricted access
+
+**Don't:**
+- Use `.localhost` (it's a Public Suffix, browsers block it)
+- Use broad TLDs like `.com` (browsers will reject it)
+
+## Migration from Proxy Approach
+
+If you're migrating from the previous proxy-based integration:
+
+### Changes Required
+
+1. **Configuration:**
+   - Add `cookieDomain` to Label Studio config
+   - Update Label Studio `.env` with CORS settings
+
+2. **Frontend:**
+   - No changes needed - component interface remains the same
+   - Iframe URLs now point directly to Label Studio (not proxied)
+
+3. **Nginx/Proxy:**
+   - Remove proxy rules for `/label-studio/*` paths
+   - Label Studio should be directly accessible on its subdomain
+
+### Benefits of Subdomain Approach
+
+- ✅ **Simpler deployment** - No complex proxy configuration
+- ✅ **Better performance** - No proxy overhead
+- ✅ **Easier debugging** - Direct access to Label Studio
+- ✅ **Standard approach** - Follows common SSO patterns
+- ✅ **Better caching** - Browser can cache Label Studio assets
+
+## References
+
+- [Label Studio SSO Documentation](https://labelstud.io/guide/auth_setup.html#JWT-SSO)
+- [Cookie Domain Specification](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#define_where_cookies_are_sent)
+- [Public Suffix List](https://publicsuffix.org/)