Enterprise SSO & SCIM: SSO and SCIM provisioning for B2B enterprise customers with directory synchronization --- # DOCUMENT BOUNDARY --- # Add Modular SCIM provisioning > Automate user provisioning with SCIM. Directory API and webhooks for real-time user data sync This guide shows you how to automate user provisioning with SCIM using Scalekit’s Directory API and webhooks. You’ll learn to sync user data in real-time, create webhook endpoints for instant updates, and build automated provisioning workflows that keep your application’s user data synchronized with your customers’ directory providers. With [SCIM Provisioning](/directory/guides/user-provisioning-basics) from Scalekit, you can: * Use **webhooks** to listen for events from your customers’ directory providers (e.g., user updates, group changes) * Use **REST APIs** to list users, groups, and directories on demand Scalekit abstracts the complexities of various directory providers, giving you a single interface to automate user lifecycle management. This enables you to create accounts for new hires during onboarding, deactivate accounts when employees depart, and adjust access levels as employees change roles.  ### Build with a coding agent * Claude Code ```bash /plugin marketplace add scalekit-inc/claude-code-authstack ``` ```bash /plugin install modular-scim@scalekit-auth-stack ``` * Codex ```bash curl -fsSL https://raw.githubusercontent.com/scalekit-inc/codex-authstack/main/install.sh | bash ``` ```bash # Restart Codex # Plugin Directory -> Scalekit Auth Stack -> install modular-scim ``` * GitHub Copilot CLI ```bash copilot plugin marketplace add scalekit-inc/github-copilot-authstack ``` ```bash copilot plugin install modular-scim@scalekit-auth-stack ``` * 40+ agents ```bash npx skills add scalekit-inc/skills --skill implementing-scim-provisioning ``` [Continue building with AI →](/dev-kit/build-with-ai/scim/) ## User provisioning with Scalekit’s directory API [Section titled “User provisioning with Scalekit’s directory API”](#user-provisioning-with-scalekits-directory-api) Scalekit’s directory API allows you to fetch information about users, groups, and directories associated with an organization on-demand. This approach is ideal for scheduled synchronization tasks, bulk data imports, or when you need to ensure your application’s user data matches the latest directory provider state. Let’s explore how to use the Directory API to retrieve user and group data programmatically. 1. ### Setting up the SDK [Section titled “Setting up the SDK”](#setting-up-the-sdk) Before you begin, ensure that your organization [has a directory set up in Scalekit](/guides/user-management/scim-provisioning/). Scalekit offers language-specific SDKs for fast SSO integration. Use the installation instructions below for your technology stack: * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` Navigate to **Dashboard > Developers > Settings > API Credentials** to obtain your credentials. Store your credentials securely in environment variables: .env ```shell 1 # Get these values from Dashboard > Developers > Settings > API Credentials 2 SCALEKIT_ENVIRONMENT_URL='https://b2b-app-dev.scalekit.com' 3 SCALEKIT_CLIENT_ID='' 4 SCALEKIT_CLIENT_SECRET='' ``` 2. ### Initialize the SDK and make your first API call [Section titled “Initialize the SDK and make your first API call”](#initialize-the-sdk-and-make-your-first-api-call) Initialize the Scalekit client with your environment variables and make your first API call to list organizations. * cURL Terminal ```bash 1 # Security: Replace with a valid access token from Scalekit 2 # This token authorizes your API requests to access organization data 3 4 # Use case: Verify API connectivity and test authentication 5 # Examples: Initial setup testing, debugging integration issues 6 7 curl -L "https://$SCALEKIT_ENVIRONMENT_URL/api/v1/organizations?page_size=5" \ 8 -H "Authorization: Bearer " ``` * Node.js Node.js ```javascript 1 import { ScalekitClient } from '@scalekit-sdk/node'; 2 3 // Initialize Scalekit client with environment variables 4 // Security: Always use environment variables for sensitive credentials 5 const scalekit = new ScalekitClient( 6 process.env.SCALEKIT_ENVIRONMENT_URL, 7 process.env.SCALEKIT_CLIENT_ID, 8 process.env.SCALEKIT_CLIENT_SECRET, 9 ); 10 11 try { 12 // Use case: Retrieve organizations for bulk user provisioning workflows 13 // Examples: Multi-tenant applications, enterprise customer onboarding 14 const { organizations } = await scalekit.organization.listOrganization({ 15 pageSize: 5, 16 }); 17 18 console.log(`Organization name: ${organizations[0].display_name}`); 19 console.log(`Organization ID: ${organizations[0].id}`); 20 } catch (error) { 21 console.error('Failed to list organizations:', error); 22 // Handle error appropriately for your application 23 } ``` * Python Python ```python 1 from scalekit import ScalekitClient 2 import os 3 4 # Initialize the SDK client with environment variables 5 # Security: Use os.getenv() to securely access credentials 6 scalekit_client = ScalekitClient( 7 env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), 8 client_id=os.getenv("SCALEKIT_CLIENT_ID"), 9 client_secret=os.getenv("SCALEKIT_CLIENT_SECRET") 10 ) 11 12 try: 13 # Use case: Sync user data across multiple organizations 14 # Examples: Scheduled provisioning tasks, HR system integration 15 org_list = scalekit_client.organization.list_organizations(page_size=100) 16 17 if org_list: 18 print(f'Organization details: {org_list[0]}') 19 print(f'Organization ID: {org_list[0].id}') 20 except Exception as error: 21 print(f'Error listing organizations: {error}') 22 # Implement appropriate error handling for your use case ``` * Go Go ```go 1 package main 2 3 import ( 4 "context" 5 "fmt" 6 "os" 7 8 "github.com/scalekit/scalekit-go" 9 ) 10 11 // Initialize Scalekit client with environment variables 12 // Security: Always load credentials from environment, not hardcoded 13 scalekitClient := scalekit.NewScalekitClient( 14 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 15 os.Getenv("SCALEKIT_CLIENT_ID"), 16 os.Getenv("SCALEKIT_CLIENT_SECRET"), 17 ) 18 19 // Use case: Get specific organization for directory sync operations 20 // Examples: Targeted user provisioning, organization-specific workflows 21 organization, err := scalekitClient.Organization.GetOrganization( 22 ctx, 23 organizationId, 24 ) 25 if err != nil { 26 // Handle error appropriately for your application 27 return fmt.Errorf("failed to get organization: %w", err) 28 } ``` * Java Java ```java 1 import com.scalekit.ScalekitClient; 2 3 // Initialize Scalekit client with environment variables 4 // Security: Use System.getenv() to securely access credentials 5 ScalekitClient scalekitClient = new ScalekitClient( 6 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 7 System.getenv("SCALEKIT_CLIENT_ID"), 8 System.getenv("SCALEKIT_CLIENT_SECRET") 9 ); 10 11 try { 12 // Use case: List organizations for automated provisioning workflows 13 // Examples: Enterprise customer setup, multi-tenant management 14 ListOrganizationsResponse organizations = scalekitClient.organizations() 15 .listOrganizations(5, ""); 16 17 if (!organizations.getOrganizations().isEmpty()) { 18 Organization firstOrg = organizations.getOrganizations().get(0); 19 System.out.println("Organization name: " + firstOrg.getDisplayName()); 20 System.out.println("Organization ID: " + firstOrg.getId()); 21 } 22 } catch (ScalekitException error) { 23 System.err.println("Failed to list organizations: " + error.getMessage()); 24 // Implement appropriate error handling 25 } ``` 3. ### Retrieve a directory [Section titled “Retrieve a directory”](#retrieve-a-directory) After successfully listing organizations, you’ll need to retrieve the specific directory to begin syncing user and group data. You can retrieve directories using either the organization and directory IDs, or fetch the primary directory for an organization. * Node.js Node.js ```javascript 1 try { 2 // Use case: Get specific directory when organization has multiple directories 3 // Examples: Department-specific provisioning, multi-division companies 4 const { directory } = await scalekit.directory.getDirectory('', ''); 5 console.log(`Directory name: ${directory.name}`); 6 7 // Use case: Get primary directory for simple provisioning workflows 8 // Examples: Small organizations, single-directory setups 9 const { directory } = await scalekit.directory.getPrimaryDirectoryByOrganizationId(''); 10 console.log(`Primary directory ID: ${directory.id}`); 11 } catch (error) { 12 console.error('Failed to retrieve directory:', error); 13 // Handle error appropriately for your application 14 } ``` * Python Python ```python 1 try: 2 # Use case: Access specific directory for targeted user sync operations 3 # Examples: Regional offices, business unit-specific provisioning 4 directory = scalekit_client.directory.get_directory( 5 organization_id='', directory_id='' 6 ) 7 print(f'Directory name: {directory.name}') 8 9 # Use case: Get primary directory for streamlined user management 10 # Examples: Standard employee provisioning, main company directory 11 primary_directory = scalekit_client.directory.get_primary_directory_by_organization_id( 12 organization_id='' 13 ) 14 print(f'Primary directory ID: {primary_directory.id}') 15 except Exception as error: 16 print(f'Error retrieving directory: {error}') 17 # Implement appropriate error handling ``` * Go Go ```go 1 // Use case: Retrieve specific directory for granular access control 2 // Examples: Multi-tenant environments, department-level provisioning 3 directory, err := scalekitClient.Directory().GetDirectory(ctx, organizationId, directoryId) 4 if err != nil { 5 return fmt.Errorf("failed to get directory: %w", err) 6 } 7 fmt.Printf("Directory name: %s\n", directory.Name) 8 9 // Use case: Get primary directory for simplified user management 10 // Examples: Automated provisioning workflows, bulk user imports 11 directory, err := scalekitClient.Directory().GetPrimaryDirectoryByOrganizationId(ctx, organizationId) 12 if err != nil { 13 return fmt.Errorf("failed to get primary directory: %w", err) 14 } 15 fmt.Printf("Primary directory ID: %s\n", directory.ID) ``` * Java Java ```java 1 try { 2 // Use case: Access specific directory for detailed user management 3 // Examples: Custom provisioning logic, directory-specific rules 4 Directory directory = scalekitClient.directories() 5 .getDirectory("", ""); 6 System.out.println("Directory name: " + directory.getName()); 7 8 // Use case: Get primary directory for standard provisioning workflows 9 // Examples: Employee onboarding, automated user sync 10 Directory primaryDirectory = scalekitClient.directories() 11 .getPrimaryDirectoryByOrganizationId(""); 12 System.out.println("Primary directory ID: " + primaryDirectory.getId()); 13 } catch (ScalekitException error) { 14 System.err.println("Failed to retrieve directory: " + error.getMessage()); 15 // Implement appropriate error handling 16 } ``` 4. ### List users in a directory [Section titled “List users in a directory”](#list-users-in-a-directory) Once you have the directory information, you can fetch users within that directory. This is commonly used for bulk user synchronization and maintaining an up-to-date user database. * Node.js Node.js ```javascript 1 try { 2 // Use case: Bulk user synchronization and provisioning 3 // Examples: New customer onboarding, scheduled user data sync 4 const { users } = await scalekit.directory.listDirectoryUsers('', ''); 5 6 // Process each user for provisioning or updates 7 users.forEach(user => { 8 console.log(`User email: ${user.email}, Name: ${user.name}`); 9 // TODO: Implement your user provisioning logic here 10 }); 11 } catch (error) { 12 console.error('Failed to list directory users:', error); 13 // Handle error appropriately for your application 14 } ``` * Python Python ```python 1 try: 2 # Use case: Automated user provisioning workflows 3 # Examples: HR system integration, bulk user imports 4 directory_users = scalekit_client.directory.list_directory_users( 5 organization_id='', directory_id='' 6 ) 7 8 # Process each user for local database updates 9 for user in directory_users: 10 print(f'User email: {user.email}, Name: {user.name}') 11 # TODO: Implement your user synchronization logic here 12 except Exception as error: 13 print(f'Error listing directory users: {error}') 14 # Implement appropriate error handling ``` * Go Go ```go 1 // Configure pagination options for large user directories 2 options := &ListDirectoryUsersOptions{ 3 PageSize: 50, // Adjust based on your needs 4 PageToken: "", 5 } 6 7 // Use case: Paginated user retrieval for large directories 8 // Examples: Enterprise customer provisioning, regular sync jobs 9 directoryUsers, err := scalekitClient.Directory().ListDirectoryUsers(ctx, organizationId, directoryId, options) 10 if err != nil { 11 return fmt.Errorf("failed to list directory users: %w", err) 12 } 13 14 // Process each user 15 for _, user := range directoryUsers.Users { 16 fmt.Printf("User email: %s, Name: %s\n", user.Email, user.Name) 17 // TODO: Implement your user provisioning logic 18 } ``` * Java Java ```java 1 // Configure options for user listing with pagination 2 var options = ListDirectoryResourceOptions.builder() 3 .pageSize(50) // Adjust based on your requirements 4 .pageToken("") 5 .includeDetail(true) // Include detailed user information 6 .build(); 7 8 try { 9 // Use case: Enterprise user management and synchronization 10 // Examples: Scheduled sync tasks, user provisioning automation 11 ListDirectoryUsersResponse usersResponse = scalekitClient.directories() 12 .listDirectoryUsers(directory.getId(), organizationId, options); 13 14 // Process each user for provisioning 15 for (User user : usersResponse.getUsers()) { 16 System.out.println("User email: " + user.getEmail() + ", Name: " + user.getName()); 17 // TODO: Implement your user provisioning logic here 18 } 19 } catch (ScalekitException error) { 20 System.err.println("Failed to list directory users: " + error.getMessage()); 21 // Implement appropriate error handling 22 } ``` 5. ### List groups in a directory [Section titled “List groups in a directory”](#list-groups-in-a-directory) Groups are essential for implementing role-based access control (RBAC) in your application. After retrieving users, you can fetch groups to manage permissions and access levels based on organizational structure. * Node.js Node.js ```javascript 1 try { 2 // Use case: Role-based access control implementation 3 // Examples: Department-level permissions, project-based access 4 const { groups } = await scalekit.directory.listDirectoryGroups( 5 '', 6 '', 7 ); 8 9 // Process each group for RBAC setup 10 groups.forEach(group => { 11 console.log(`Group name: ${group.name}, ID: ${group.id}`); 12 // TODO: Implement your group-based permission logic here 13 }); 14 } catch (error) { 15 console.error('Failed to list directory groups:', error); 16 // Handle error appropriately for your application 17 } ``` * Python Python ```python 1 try: 2 # Use case: Department-based access control 3 # Examples: Engineering vs Sales permissions, project team access 4 directory_groups = scalekit_client.directory.list_directory_groups( 5 directory_id='', organization_id='' 6 ) 7 8 # Process each group for permission mapping 9 for group in directory_groups: 10 print(f'Group name: {group.name}, ID: {group.id}') 11 # TODO: Implement your group-based permission logic here 12 except Exception as error: 13 print(f'Error listing directory groups: {error}') 14 # Implement appropriate error handling ``` * Go Go ```go 1 // Configure pagination for group listing 2 options := &ListDirectoryGroupsOptions{ 3 PageSize: 25, // Adjust based on expected group count 4 PageToken: "", 5 } 6 7 // Use case: Organizational role management 8 // Examples: Enterprise role hierarchy, department-based access 9 directoryGroups, err := scalekitClient.Directory().ListDirectoryGroups(ctx, organizationId, directoryId, options) 10 if err != nil { 11 return fmt.Errorf("failed to list directory groups: %w", err) 12 } 13 14 // Process each group for RBAC implementation 15 for _, group := range directoryGroups.Groups { 16 fmt.Printf("Group name: %s, ID: %s\n", group.Name, group.ID) 17 // TODO: Implement your group-based permission logic 18 } ``` * Java Java ```java 1 // Configure options for detailed group information 2 var options = ListDirectoryResourceOptions.builder() 3 .pageSize(25) // Adjust based on your requirements 4 .pageToken("") 5 .includeDetail(true) // Include group membership details 6 .build(); 7 8 try { 9 // Use case: Enterprise permission management 10 // Examples: Role assignments, access level configurations 11 ListDirectoryGroupsResponse groupsResponse = scalekitClient.directories() 12 .listDirectoryGroups(directory.getId(), organizationId, options); 13 14 // Process each group for permission mapping 15 for (Group group : groupsResponse.getGroups()) { 16 System.out.println("Group name: " + group.getName() + ", ID: " + group.getId()); 17 // TODO: Implement your group-based permission logic here 18 } 19 } catch (ScalekitException error) { 20 System.err.println("Failed to list directory groups: " + error.getMessage()); 21 // Implement appropriate error handling 22 } ``` Scalekit’s Directory API provides a simple way to fetch user and group information on-demand. Refer to our [API reference](https://docs.scalekit.com/apis/) to explore more capabilities. ## Realtime user provisioning with webhooks [Section titled “Realtime user provisioning with webhooks”](#realtime-user-provisioning-with-webhooks) While the Directory API is perfect for scheduled synchronization, webhooks enable immediate, real-time user provisioning. When directory providers send events to Scalekit, we forward them instantly to your application, allowing you to respond to user changes as they happen. This approach is ideal for scenarios requiring immediate action, such as new employee onboarding or emergency access revocation. 1. ### Create a secure webhook endpoint [Section titled “Create a secure webhook endpoint”](#create-a-secure-webhook-endpoint) Create a webhook endpoint to receive real-time events from directory providers. After implementing your endpoint, register it in **Dashboard > Webhooks** where you’ll receive a secret for payload verification. Critical security requirement Always verify webhook signatures before processing events. This prevents unauthorized parties from triggering your provisioning logic and protects against replay attacks. * Node.js Express.js ```javascript 1 app.post('/webhook', async (req, res) => { 2 // Security: ALWAYS verify requests are from Scalekit before processing 3 // This prevents unauthorized parties from triggering your provisioning logic 4 5 const event = req.body; 6 const headers = req.headers; 7 const secret = process.env.SCALEKIT_WEBHOOK_SECRET; 8 9 try { 10 // Verify webhook signature to prevent replay attacks and forged requests 11 await scalekit.verifyWebhookPayload(secret, headers, event); 12 } catch (error) { 13 console.error('Webhook signature verification failed:', error); 14 // Return 400 for invalid signatures - this prevents processing malicious requests 15 return res.status(400).json({ error: 'Invalid signature' }); 16 } 17 18 try { 19 // Use case: Real-time user provisioning based on directory events 20 // Examples: New hire onboarding, emergency access revocation, role changes 21 const { email, name } = event.data; 22 23 // Process the webhook event based on its type 24 switch (event.type) { 25 case 'organization.directory.user_created': 26 await createUserAccount(email, name); 27 break; 28 case 'organization.directory.user_updated': 29 await updateUserAccount(email, name); 30 break; 31 case 'organization.directory.user_deleted': 32 await deactivateUserAccount(email); 33 break; 34 default: 35 console.log(`Unhandled event type: ${event.type}`); 36 } 37 38 res.status(201).json({ message: 'Webhook processed successfully' }); 39 } catch (processingError) { 40 console.error('Failed to process webhook event:', processingError); 41 res.status(500).json({ error: 'Processing failed' }); 42 } 43 }); ``` * Python FastAPI ```python 1 from fastapi import FastAPI, Request, HTTPException 2 import os 3 import json 4 5 app = FastAPI() 6 7 @app.post("/webhook") 8 async def api_webhook(request: Request): 9 # Security: ALWAYS verify webhook signatures before processing events 10 # This prevents unauthorized webhook calls and replay attacks 11 12 headers = request.headers 13 body = await request.json() 14 15 try: 16 # Verify webhook payload using the secret from Scalekit dashboard 17 # Get this from Dashboard > Webhooks after registering your endpoint 18 is_valid = scalekit_client.verify_webhook_payload( 19 secret=os.getenv("SCALEKIT_WEBHOOK_SECRET"), 20 headers=headers, 21 payload=json.dumps(body).encode('utf-8') 22 ) 23 24 if not is_valid: 25 raise HTTPException(status_code=400, detail="Invalid webhook signature") 26 27 except Exception as verification_error: 28 print(f"Webhook verification failed: {verification_error}") 29 raise HTTPException(status_code=400, detail="Webhook verification failed") 30 31 # Use case: Instant user provisioning based on directory events 32 # Examples: Automated onboarding, immediate access revocation, role updates 33 try: 34 event_type = body.get("type") 35 event_data = body.get("data", {}) 36 email = event_data.get("email") 37 name = event_data.get("name") 38 39 if event_type == "organization.directory.user_created": 40 await create_user_account(email, name) 41 elif event_type == "organization.directory.user_updated": 42 await update_user_account(email, name) 43 elif event_type == "organization.directory.user_deleted": 44 await deactivate_user_account(email) 45 46 return JSONResponse(status_code=201, content={"status": "processed"}) 47 48 except Exception as processing_error: 49 print(f"Failed to process webhook: {processing_error}") 50 raise HTTPException(status_code=500, detail="Event processing failed") ``` * Java Spring Boot ```java 1 @PostMapping("/webhook") 2 public ResponseEntity webhook( 3 @RequestBody String body, 4 @RequestHeader Map headers) { 5 6 // Security: ALWAYS verify webhook signatures before processing 7 // This prevents malicious webhook calls and protects against replay attacks 8 9 String secret = System.getenv("SCALEKIT_WEBHOOK_SECRET"); 10 11 try { 12 // Verify webhook signature using Scalekit SDK 13 boolean isValid = scalekitClient.webhook() 14 .verifyWebhookPayload(secret, headers, body.getBytes()); 15 16 if (!isValid) { 17 return ResponseEntity.badRequest().body("Invalid webhook signature"); 18 } 19 20 } catch (Exception verificationError) { 21 System.err.println("Webhook verification failed: " + verificationError.getMessage()); 22 return ResponseEntity.badRequest().body("Webhook verification failed"); 23 } 24 25 try { 26 // Use case: Real-time user lifecycle management 27 // Examples: Employee onboarding, access termination, role modifications 28 ObjectMapper mapper = new ObjectMapper(); 29 JsonNode rootNode = mapper.readTree(body); 30 31 String eventType = rootNode.get("type").asText(); 32 JsonNode data = rootNode.get("data"); 33 34 switch (eventType) { 35 case "organization.directory.user_created": 36 String email = data.get("email").asText(); 37 String name = data.get("name").asText(); 38 createUserAccount(email, name); 39 break; 40 case "organization.directory.user_updated": 41 updateUserAccount(data); 42 break; 43 case "organization.directory.user_deleted": 44 deactivateUserAccount(data.get("email").asText()); 45 break; 46 default: 47 System.out.println("Unhandled event type: " + eventType); 48 } 49 50 return ResponseEntity.status(HttpStatus.CREATED).body("Webhook processed"); 51 52 } catch (Exception processingError) { 53 System.err.println("Failed to process webhook event: " + processingError.getMessage()); 54 return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) 55 .body("Event processing failed"); 56 } 57 } ``` * Go Go ```go 1 // Security: Store webhook secret securely in environment variables 2 // Get this from Dashboard > Webhooks after registering your endpoint 3 webhookSecret := os.Getenv("SCALEKIT_WEBHOOK_SECRET") 4 5 http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) { 6 // Security: ALWAYS verify webhook signatures before processing events 7 // This prevents unauthorized webhook calls and replay attacks 8 9 if r.Method != http.MethodPost { 10 http.Error(w, "Method not allowed", http.StatusMethodNotAllowed) 11 return 12 } 13 14 body, err := io.ReadAll(r.Body) 15 if err != nil { 16 http.Error(w, err.Error(), http.StatusBadRequest) 17 return 18 } 19 defer r.Body.Close() 20 21 // Extract webhook headers for verification 22 headers := map[string]string{ 23 "webhook-id": r.Header.Get("webhook-id"), 24 "webhook-signature": r.Header.Get("webhook-signature"), 25 "webhook-timestamp": r.Header.Get("webhook-timestamp"), 26 } 27 28 // Verify webhook signature to prevent malicious requests 29 _, err = scalekitClient.VerifyWebhookPayload(webhookSecret, headers, body) 30 if err != nil { 31 http.Error(w, "Invalid webhook signature", http.StatusBadRequest) 32 return 33 } 34 35 // Use case: Instant user provisioning and lifecycle management 36 // Examples: Real-time onboarding, emergency access revocation, role synchronization 37 var webhookEvent WebhookEvent 38 if err := json.Unmarshal(body, &webhookEvent); err != nil { 39 http.Error(w, "Invalid webhook payload", http.StatusBadRequest) 40 return 41 } 42 43 switch webhookEvent.Type { 44 case "organization.directory.user_created": 45 err = createUserAccount(webhookEvent.Data.Email, webhookEvent.Data.Name) 46 case "organization.directory.user_updated": 47 err = updateUserAccount(webhookEvent.Data) 48 case "organization.directory.user_deleted": 49 err = deactivateUserAccount(webhookEvent.Data.Email) 50 default: 51 fmt.Printf("Unhandled event type: %s\n", webhookEvent.Type) 52 } 53 54 if err != nil { 55 http.Error(w, "Failed to process webhook", http.StatusInternalServerError) 56 return 57 } 58 59 w.WriteHeader(http.StatusCreated) 60 w.Write([]byte(`{"status": "processed"}`)) 61 }) ``` 2. ### Register your webhook endpoint [Section titled “Register your webhook endpoint”](#register-your-webhook-endpoint) After implementing your secure webhook endpoint, register it in the Scalekit dashboard to start receiving events: 1. Navigate to **Dashboard > Webhooks** 2. Click **+Add Endpoint** 3. Enter your webhook endpoint URL (e.g., `https://your-app.com/api/webhooks/scalekit`) 4. Add a meaningful description for your reference 5. Select the event types you want to receive. Common choices include: * `organization.directory.user_created` - New user provisioning * `organization.directory.user_updated` - User profile changes * `organization.directory.user_deleted` - User deactivation * `organization.directory.group_created` - New group creation * `organization.directory.group_updated` - Group modifications Once registered, your webhook endpoint will start receiving event payloads from directory providers in real-time. 3. ### Process webhook events [Section titled “Process webhook events”](#process-webhook-events) Scalekit standardizes event payloads across different directory providers, ensuring consistent data structure regardless of whether your customers use Azure AD, Okta, Google Workspace, or other providers. When directory changes occur, Scalekit sends events with the following structure: Webhook event payload ```json 1 { 2 "id": "evt_1234567890", 3 "type": "organization.directory.user_created", 4 "data": { 5 "email": "john.doe@company.com", 6 "name": "John Doe", 7 "organization_id": "org_12345", 8 "directory_id": "dir_67890" 9 }, 10 "timestamp": "2024-01-15T10:30:00Z" 11 } ``` You have now successfully implemented and registered a webhook endpoint, enabling your application to receive real-time events for automated user provisioning. Your system can now respond instantly to directory changes, providing seamless user lifecycle management. Refer to our [webhook implementation guide](/authenticate/implement-workflows/implement-webhooks/) for the complete list of available event types and payload structures. --- # DOCUMENT BOUNDARY --- # Modular SSO quickstart > Enable enterprise SSO for any customer in minutes with built-in SAML and OIDC integrations Enterprise customers often require Single Sign-On (SSO) support for their applications. Rather than building custom integrations for every identity provider such as Okta, Entra ID, or JumpCloud and managing their OIDC and SAML protocols, you can let Scalekit handle those connections with each of your customer’s identity providers. Modular SSO is designed for applications that maintain their own user database and session management. This lightweight integration focuses solely on identity verification, giving you complete control over user data and authentication flows. Choose Modular SSO when you: * Want to manage user records in your own database * Prefer to implement custom session management logic * Need to integrate SSO without changing your existing authentication architecture * Already have existing user management infrastructure ### Build with a coding agent * Claude Code ```bash /plugin marketplace add scalekit-inc/claude-code-authstack ``` ```bash /plugin install modular-sso@scalekit-auth-stack ``` * GitHub Copilot CLI ```bash copilot plugin marketplace add scalekit-inc/github-copilot-authstack ``` ```bash copilot plugin install modular-sso@scalekit-auth-stack ``` * 40+ agents ```bash npx skills add scalekit-inc/skills --skill modular-sso ``` [Continue building with AI →](/dev-kit/build-with-ai/sso/) 1. ## Set up Scalekit [Section titled “Set up Scalekit”](#set-up-scalekit) Use the following instructions to install the SDK for your technology stack. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` Since we will using Modular SSO, you need to disable complete auth: 1. Go to Dashboard > Authentication > General 2. Under “Full-Stack Auth” section, click “Disable Full-Stack Auth” Now you’re ready to start integrating SSO into your app! 2. ## Redirect the users to their enterprise identity provider login page [Section titled “Redirect the users to their enterprise identity provider login page”](#redirect-the-users-to-their-enterprise-identity-provider-login-page) Use the Scalekit SDK to construct authorization URL with your redirect URI and required scopes. Scalekit will automatically redirect the user to the user’s enterprise identity provider login page to authenticate. * Node.js authorization-url.js ```javascript 1 import { Scalekit } from '@scalekit-sdk/node'; 2 3 const scalekit = new ScalekitClient( 4 '', // Your Scalekit environment URL 5 '', // Unique identifier for your app 6 '', 7 ); 8 9 const options = {}; 10 11 // Specify which SSO connection to use (choose one based on your use case) 12 // These identifiers are evaluated in order of precedence: 13 14 // 1. connectionId (highest precedence) - Use when you know the exact SSO connection 15 options['connectionId'] = 'conn_15696105471768821'; 16 17 // 2. organizationId - Routes to organization's SSO (useful for multi-tenant apps) 18 // If org has multiple connections, the first active one is selected 19 options['organizationId'] = 'org_15421144869927830'; 20 21 // 3. loginHint (lowest precedence) - Extracts domain from email to find connection 22 // Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 23 options['loginHint'] = 'user@example.com'; 24 25 // redirect_uri: Your callback endpoint that receives the authorization code 26 // Must match the URL registered in your Scalekit dashboard 27 const redirectUrl = 'https://your-app.com/auth/callback'; 28 29 const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options); 30 // Redirect user to this URL to begin SSO authentication ``` * Python authorization\_url.py ```python 1 from scalekit import ScalekitClient, AuthorizationUrlOptions 2 3 scalekit = ScalekitClient( 4 '', # Your Scalekit environment URL 5 '', # Unique identifier for your app 6 '' 7 ) 8 9 options = AuthorizationUrlOptions() 10 11 # Specify which SSO connection to use (choose one based on your use case) 12 # These identifiers are evaluated in order of precedence: 13 14 # 1. connection_id (highest precedence) - Use when you know the exact SSO connection 15 options.connection_id = 'conn_15696105471768821' 16 17 # 2. organization_id - Routes to organization's SSO (useful for multi-tenant apps) 18 # If org has multiple connections, the first active one is selected 19 options.organization_id = 'org_15421144869927830' 20 21 # 3. login_hint (lowest precedence) - Extracts domain from email to find connection 22 # Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 23 options.login_hint = 'user@example.com' 24 25 # redirect_uri: Your callback endpoint that receives the authorization code 26 # Must match the URL registered in your Scalekit dashboard 27 redirect_uri = 'https://your-app.com/auth/callback' 28 29 authorization_url = scalekit_client.get_authorization_url( 30 redirect_uri=redirect_uri, 31 options=options 32 ) 33 # Redirect user to this URL to begin SSO authentication ``` * Go authorization\_url.go ```go 1 import ( 2 "github.com/scalekit-inc/scalekit-sdk-go" 3 ) 4 5 func main() { 6 scalekitClient := scalekit.NewScalekitClient( 7 "", // Your Scalekit environment URL 8 "", // Unique identifier for your app 9 "" 10 ) 11 12 options := scalekitClient.AuthorizationUrlOptions{} 13 14 // Specify which SSO connection to use (choose one based on your use case) 15 // These identifiers are evaluated in order of precedence: 16 17 // 1. ConnectionId (highest precedence) - Use when you know the exact SSO connection 18 options.ConnectionId = "conn_15696105471768821" 19 20 // 2. OrganizationId - Routes to organization's SSO (useful for multi-tenant apps) 21 // If org has multiple connections, the first active one is selected 22 options.OrganizationId = "org_15421144869927830" 23 24 // 3. LoginHint (lowest precedence) - Extracts domain from email to find connection 25 // Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 26 options.LoginHint = "user@example.com" 27 28 // redirectUrl: Your callback endpoint that receives the authorization code 29 // Must match the URL registered in your Scalekit dashboard 30 redirectUrl := "https://your-app.com/auth/callback" 31 32 authorizationURL := scalekitClient.GetAuthorizationUrl( 33 redirectUrl, 34 options, 35 ) 36 // Redirect user to this URL to begin SSO authentication 37 } ``` * Java AuthorizationUrl.java ```java 1 package com.scalekit; 2 3 import com.scalekit.ScalekitClient; 4 import com.scalekit.internal.http.AuthorizationUrlOptions; 5 6 public class Main { 7 8 public static void main(String[] args) { 9 ScalekitClient scalekitClient = new ScalekitClient( 10 "", // Your Scalekit environment URL 11 "", // Unique identifier for your app 12 "" 13 ); 14 15 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 16 17 // Specify which SSO connection to use (choose one based on your use case) 18 // These identifiers are evaluated in order of precedence: 19 20 // 1. connectionId (highest precedence) - Use when you know the exact SSO connection 21 options.setConnectionId("con_13388706786312310"); 22 23 // 2. organizationId - Routes to organization's SSO (useful for multi-tenant apps) 24 // If org has multiple connections, the first active one is selected 25 options.setOrganizationId("org_13388706786312310"); 26 27 // 3. loginHint (lowest precedence) - Extracts domain from email to find connection 28 // Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 29 options.setLoginHint("user@example.com"); 30 31 // redirectUrl: Your callback endpoint that receives the authorization code 32 // Must match the URL registered in your Scalekit dashboard 33 String redirectUrl = "https://your-app.com/auth/callback"; 34 35 try { 36 String url = scalekitClient 37 .authentication() 38 .getAuthorizationUrl(redirectUrl, options) 39 .toString(); 40 // Redirect user to this URL to begin SSO authentication 41 } catch (Exception e) { 42 System.out.println(e.getMessage()); 43 } 44 } 45 } ``` * Direct URL (No SDK) OAuth2 authorization URL ```sh /oauth/authorize? response_type=code& # OAuth2 authorization code flow client_id=& # Your Scalekit client ID redirect_uri=& # URL-encoded callback URL scope=openid profile email& # "offline_access" is required to receive a refresh token organization_id=org_15421144869927830& # (Optional) Route by organization connection_id=conn_15696105471768821& # (Optional) Specific SSO connection login_hint=user@example.com # (Optional) Extract domain from email ``` **SSO identifiers** (choose one or more, evaluated in order of precedence): * `connection_id` - Direct to specific SSO connection (highest precedence) * `organization_id` - Route to organization’s SSO * `domain_hint` - Lookup connection by domain * `login_hint` - Extract domain from email (lowest precedence). Domain must be registered to the organization (manually via Dashboard or through admin portal when [onboarding an enterprise customer](/sso/guides/onboard-enterprise-customers/)) Example with actual values ```http https://tinotat-dev.scalekit.dev/oauth/authorize? response_type=code& client_id=skc_88036702639096097& redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback& scope=openid%20profile%20email& organization_id=org_15421144869927830 ``` Enterprise users see their identity provider’s login page. Users verify their identity through the authentication policies set by their organization’s administrator. Post successful verification, the user profile is [normalized](/sso/guides/user-profile-details/) and sent to your app. If your application needs to verify whether an SSO connection exists for a specific domain before proceeding, you can use the [list connections by domain SDK method](/guides/user-auth/check-sso-domain/). For details on how Scalekit determines which SSO connection to use, refer to the [SSO identifier precedence rules](/sso/guides/authorization-url/#parameter-precedence). 3. ## Get user details from the callback [Section titled “Get user details from the callback”](#get-user-details-from-the-callback) After successful authentication, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user’s profile information and session tokens. 1. Add a callback endpoint in your application (typically `https://your-app.com/auth/callback`) 2. [Register](/guides/dashboard/redirects/#allowed-callback-urls) it in your Scalekit dashboard > Authentication > Redirect URLS > Allowed Callback URLs In authentication flow, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user’s profile information. * Node.js Fetch user profile ```javascript 1 // Extract authentication parameters from the callback request 2 const { 3 code, 4 error, 5 error_description, 6 idp_initiated_login, 7 connection_id, 8 relay_state 9 } = req.query; 10 11 if (error) { 12 // Handle authentication errors returned from the identity provider 13 } 14 15 // Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 16 17 const result = await scalekit.authenticateWithCode(code, redirectUri); 18 const userEmail = result.user.email; 19 20 // Create a session for the authenticated user and grant appropriate access permissions ``` * Python Fetch user profile ```py 1 # Extract authentication parameters from the callback request 2 code = request.args.get('code') 3 error = request.args.get('error') 4 error_description = request.args.get('error_description') 5 idp_initiated_login = request.args.get('idp_initiated_login') 6 connection_id = request.args.get('connection_id') 7 relay_state = request.args.get('relay_state') 8 9 if error: 10 raise Exception(error_description) 11 12 # Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 13 14 result = scalekit.authenticate_with_code(code, '') 15 16 # Access normalized user profile information 17 user_email = result.user.email 18 19 # Create a session for the authenticated user and grant appropriate access permissions ``` * Go Fetch user profile ```go 1 // Extract authentication parameters from the callback request 2 code := r.URL.Query().Get("code") 3 error := r.URL.Query().Get("error") 4 errorDescription := r.URL.Query().Get("error_description") 5 idpInitiatedLogin := r.URL.Query().Get("idp_initiated_login") 6 connectionID := r.URL.Query().Get("connection_id") 7 relayState := r.URL.Query().Get("relay_state") 8 9 if error != "" { 10 // Handle authentication errors returned from the identity provider 11 } 12 13 // Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 14 15 result, err := scalekitClient.AuthenticateWithCode(r.Context(), code, redirectUrl) 16 17 if err != nil { 18 // Handle token exchange or validation errors 19 } 20 21 // Access normalized user profile information 22 userEmail := result.User.Email 23 24 // Create a session for the authenticated user and grant appropriate access permissions ``` * Java Fetch user profile ```java 1 // Extract authentication parameters from the callback request 2 String code = request.getParameter("code"); 3 String error = request.getParameter("error"); 4 String errorDescription = request.getParameter("error_description"); 5 String idpInitiatedLogin = request.getParameter("idp_initiated_login"); 6 String connectionID = request.getParameter("connection_id"); 7 String relayState = request.getParameter("relay_state"); 8 9 if (error != null && !error.isEmpty()) { 10 // Handle authentication errors returned from the identity provider 11 return; 12 } 13 14 // Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 15 16 try { 17 AuthenticationResponse result = scalekit.authentication().authenticateWithCode(code, redirectUrl); 18 String userEmail = result.getIdTokenClaims().getEmail(); 19 20 // Create a session for the authenticated user and grant appropriate access permissions 21 } catch (Exception e) { 22 // Handle token exchange or validation errors 23 } ``` The `result` object * Node.js Validate tokens ```js 1 // Validate and decode the ID token from the authentication result 2 const idTokenClaims = await scalekit.validateToken(result.idToken); 3 4 // Validate and decode the access token 5 const accessTokenClaims = await scalekit.validateToken(result.accessToken); ``` * Python Validate tokens ```py 1 # Validate and decode the ID token from the authentication result 2 id_token_claims = scalekit_client.validate_token(result["id_token"]) 3 4 # Validate and decode the access token 5 access_token_claims = scalekit_client.validate_token(result["access_token"]) ``` * Go Validate tokens ```go 1 // Create a background context for the API call 2 ctx := context.Background() 3 4 // Validate and decode the access token (uses JWKS from the client) 5 accessTokenClaims, err := scalekitClient.GetAccessTokenClaims(ctx, result.AccessToken) 6 if err != nil { 7 // handle error 8 } ``` * Java Validate tokens ```java 1 // Validate and decode the ID token 2 Map idTokenClaims = scalekitClient.validateToken(result.getIdToken()); 3 4 // Validate and decode the access token 5 Map accessTokenClaims = scalekitClient.validateToken(result.getAccessToken()); ``` - Auth result ```js 1 { 2 user: { 3 email: 'john@example.com', 4 familyName: 'Doe', 5 givenName: 'John', 6 username: 'john@example.com', 7 id: 'conn_70087756662964366;dcc62570-6a5a-4819-b11b-d33d110c7716' 8 }, 9 idToken: 'eyJhbGciOiJSU..bcLQ', 10 accessToken: 'eyJhbGciO..', 11 expiresIn: 899 12 } ``` - ID token (decoded) ```js 1 { 2 iss: '', // Issuer: Scalekit environment URL (must match your environment) 3 aud: [ 'skc_70087756327420046' ], // Audience: Your client ID (must match for validation) 4 azp: 'skc_70087756327420046', // Authorized party: Usually same as aud 5 sub: 'conn_70087756662964366;e964d135-35c7-4a13-a3b4-2579a1cdf4e6', // Subject: Connection ID and IdP user ID (SSO-specific format) 6 oid: 'org_70087756646187150', // Organization ID: User's organization 7 exp: 1758952038, // Expiration: Unix timestamp (validate token hasn't expired) 8 iat: 1758692838, // Issued at: Unix timestamp when token was issued 9 at_hash: 'yMGIBg7BkmIGgD6_dZPEGQ', // Access token hash: For token binding validation 10 c_hash: '4x7qsXnlRw6dRC6twnuENw', // Authorization code hash: For code binding validation 11 amr: [ 'conn_70087756662964366' ], // Authentication method reference: SSO connection ID used for authentication 12 email: 'john@example.com', // User's email address 13 preferred_username: 'john@example.com', // Preferred username (often same as email for SSO) 14 family_name: 'Doe', // User's last name 15 given_name: 'John', // User's first name 16 sid: 'ses_91646612652163629', // Session ID: Links token to user session 17 client_id: 'skc_70087756327420046' // Client ID: Your application identifier 18 } ``` - Access token (decoded) ```js 1 { 2 "iss": "", // Issuer: Scalekit environment URL (must match your environment) 3 "aud": ["skc_70087756327420046"], // Audience: Your client ID (must match for validation) 4 "sub": "conn_70087756662964366;dcc62570-6a5a-4819-b11b-d33d110c7716", // Subject: Connection ID and IdP user ID (SSO-specific format) 5 "exp": 1758693916, // Expiration: Unix timestamp (validate token hasn't expired) 6 "iat": 1758693016, // Issued at: Unix timestamp when token was issued 7 "nbf": 1758693016, // Not before: Unix timestamp (token valid from this time) 8 "jti": "tkn_91646913048216109", // JWT ID: Unique token identifier 9 "client_id": "skc_70087756327420046" // Client ID: Your application identifier 10 } ``` 4. ## Handle IdP-initiated SSO Recommended [Section titled “Handle IdP-initiated SSO ”](#handle-idp-initiated-sso-) When users start the login process from their identity provider’s portal (rather than your application), this is called IdP-initiated SSO. Scalekit converts these requests to secure SP-initiated flows automatically. Your initiate login endpoint receives an `idp_initiated_login` JWT parameter containing the user’s organization and connection details. Decode this token and generate a new authorization URL to complete the authentication flow securely. ```sh https://yourapp.com/login?idp_initiated_login= ``` Configure your initiate login endpoint in [Dashboard > Authentication > Redirects](/guides/dashboard/redirects/#initiate-login-url) * Node.js handle-idp-initiated.js ```javascript 1 // Your initiate login endpoint receives the IdP-initiated login token 2 const { idp_initiated_login, error, error_description } = req.query; 3 4 if (error) { 5 return res.status(400).json({ message: error_description }); 6 } 7 8 // When users start login from their IdP portal, convert to SP-initiated flow 9 if (idp_initiated_login) { 10 // Decode the JWT to extract organization and connection information 11 const claims = await scalekit.getIdpInitiatedLoginClaims(idp_initiated_login); 12 13 const options = { 14 connectionId: claims.connection_id, // Specific SSO connection 15 organizationId: claims.organization_id, // User's organization 16 loginHint: claims.login_hint, // User's email for context 17 state: claims.relay_state // Preserve state from IdP 18 }; 19 20 // Generate authorization URL and redirect to complete authentication 21 const authorizationURL = scalekit.getAuthorizationUrl( 22 'https://your-app.com/auth/callback', 23 options 24 ); 25 26 return res.redirect(authorizationURL); 27 } ``` * Python handle\_idp\_initiated.py ```python 1 # Your initiate login endpoint receives the IdP-initiated login token 2 idp_initiated_login = request.args.get('idp_initiated_login') 3 error = request.args.get('error') 4 error_description = request.args.get('error_description') 5 6 if error: 7 raise Exception(error_description) 8 9 # When users start login from their IdP portal, convert to SP-initiated flow 10 if idp_initiated_login: 11 # Decode the JWT to extract organization and connection information 12 claims = await scalekit.get_idp_initiated_login_claims(idp_initiated_login) 13 14 options = AuthorizationUrlOptions() 15 options.connection_id = claims.get('connection_id') # Specific SSO connection 16 options.organization_id = claims.get('organization_id') # User's organization 17 options.login_hint = claims.get('login_hint') # User's email for context 18 options.state = claims.get('relay_state') # Preserve state from IdP 19 20 # Generate authorization URL and redirect to complete authentication 21 authorization_url = scalekit.get_authorization_url( 22 redirect_uri='https://your-app.com/auth/callback', 23 options=options 24 ) 25 26 return redirect(authorization_url) ``` * Go handle\_idp\_initiated.go ```go 1 // Your initiate login endpoint receives the IdP-initiated login token 2 idpInitiatedLogin := r.URL.Query().Get("idp_initiated_login") 3 errorDesc := r.URL.Query().Get("error_description") 4 5 if errorDesc != "" { 6 http.Error(w, errorDesc, http.StatusBadRequest) 7 return 8 } 9 10 // When users start login from their IdP portal, convert to SP-initiated flow 11 if idpInitiatedLogin != "" { 12 // Decode the JWT to extract organization and connection information 13 claims, err := scalekitClient.GetIdpInitiatedLoginClaims(r.Context(), idpInitiatedLogin) 14 if err != nil { 15 http.Error(w, err.Error(), http.StatusInternalServerError) 16 return 17 } 18 19 options := scalekit.AuthorizationUrlOptions{ 20 ConnectionId: claims.ConnectionID, // Specific SSO connection 21 OrganizationId: claims.OrganizationID, // User's organization 22 LoginHint: claims.LoginHint, // User's email for context 23 } 24 25 // Generate authorization URL and redirect to complete authentication 26 authUrl, err := scalekitClient.GetAuthorizationUrl( 27 "https://your-app.com/auth/callback", 28 options 29 ) 30 31 if err != nil { 32 http.Error(w, err.Error(), http.StatusInternalServerError) 33 return 34 } 35 36 http.Redirect(w, r, authUrl.String(), http.StatusFound) 37 } ``` * Java HandleIdpInitiated.java ```java 1 // Your initiate login endpoint receives the IdP-initiated login token 2 @GetMapping("/login") 3 public RedirectView handleInitiateLogin( 4 @RequestParam(required = false, name = "idp_initiated_login") String idpInitiatedLoginToken, 5 @RequestParam(required = false) String error, 6 @RequestParam(required = false, name = "error_description") String errorDescription, 7 HttpServletResponse response) throws IOException { 8 9 if (error != null) { 10 response.sendError(HttpStatus.BAD_REQUEST.value(), errorDescription); 11 return null; 12 } 13 14 // When users start login from their IdP portal, convert to SP-initiated flow 15 if (idpInitiatedLoginToken != null) { 16 // Decode the JWT to extract organization and connection information 17 IdpInitiatedLoginClaims claims = scalekit 18 .authentication() 19 .getIdpInitiatedLoginClaims(idpInitiatedLoginToken); 20 21 if (claims == null) { 22 response.sendError(HttpStatus.BAD_REQUEST.value(), "Invalid token"); 23 return null; 24 } 25 26 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 27 options.setConnectionId(claims.getConnectionID()); // Specific SSO connection 28 options.setOrganizationId(claims.getOrganizationID()); // User's organization 29 options.setLoginHint(claims.getLoginHint()); // User's email for context 30 31 // Generate authorization URL and redirect to complete authentication 32 String authUrl = scalekit 33 .authentication() 34 .getAuthorizationUrl("https://your-app.com/auth/callback", options) 35 .toString(); 36 37 response.sendRedirect(authUrl); 38 return null; 39 } 40 41 return null; 42 } ``` This approach provides enhanced security by converting IdP-initiated requests to standard SP-initiated flows, protecting against SAML assertion theft and replay attacks. Learn more: [IdP-initiated SSO implementation guide](/sso/guides/idp-init-sso/) 5. ## Test your SSO integration [Section titled “Test your SSO integration”](#test-your-sso-integration) Validate your implementation using the **IdP Simulator** and **Test Organization** included in your development environment. Test all three scenarios before deploying to production. Your environment includes a pre-configured test organization (found in **Dashboard > Organizations**) with domains like `@example.com` and `@example.org` for testing. Pass one of the following connection selectors in your authorization URL: * Email address with `@example.com` or `@example.org` domain * Test organization’s connection ID * Organization ID This opens the SSO login page (IdP Simulator) that simulates your customer’s identity provider login experience.  For detailed testing instructions and scenarios, see our [Complete SSO testing guide](/sso/guides/test-sso/) 6. ## Set up SSO with your existing authentication system [Section titled “Set up SSO with your existing authentication system”](#set-up-sso-with-your-existing-authentication-system) Many applications already use an authentication provider such as Auth0, Firebase, or AWS Cognito. To enable single sign-on (SSO) using Scalekit, configure Scalekit to work with your current authentication provider. ### Auth0 Integrate Scalekit with Auth0 for enterprise SSO [Know more →](/guides/integrations/auth-systems/auth0) ### Firebase Auth Add enterprise authentication to Firebase projects [Know more →](/guides/integrations/auth-systems/firebase) ### AWS Cognito Configure Scalekit with AWS Cognito user pools [Know more →](/guides/integrations/auth-systems/aws-cognito) 7. ## Onboard enterprise customers [Section titled “Onboard enterprise customers”](#onboard-enterprise-customers) Enable SSO for your enterprise customers by creating an organization in Scalekit and providing them access to the Admin Portal. Your customers configure their identity provider settings themselves through a self-service portal. **Create an organization** for your customer in [Dashboard > Organizations](https://app.scalekit.com/organizations), then provide Admin Portal access using one of these methods: * Shareable link Generate a secure link your customer can use to access the Admin Portal: generate-portal-link.js ```javascript // Generate a one-time Admin Portal link for your customer const portalLink = await scalekit.organization.generatePortalLink( 'org_32656XXXXXX0438' // Your customer's organization ID ); // Share this link with your customer's IT admin via email or messaging // Example: '/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43 console.log('Admin Portal URL:', portalLink.location); ``` Send this link to your customer’s IT administrator through email, Slack, or your preferred communication channel. They can configure their SSO connection without any developer involvement. * Embedded portal Embed the Admin Portal directly in your application using an iframe: embed-portal.js ```javascript // Generate a secure portal link at runtime const portalLink = await scalekit.organization.generatePortalLink(orgId); // Return the link to your frontend to embed in an iframe res.json({ portalUrl: portalLink.location }); ``` admin-settings.html ```html ``` Customers configure SSO without leaving your application, maintaining a consistent user experience. Learn more: [Embedded Admin Portal guide](/guides/admin-portal/#embed-the-admin-portal) **Enable domain verification** for seamless user experience. Once your customer verifies their domain (e.g., `@megacorp.org`), users can sign in without selecting their organization. Scalekit automatically routes them to the correct identity provider based on their email domain. **Pre-check SSO availability** before redirecting users. This prevents failed redirects when a user’s domain doesn’t have SSO configured: * Node.js check-sso-availability.js ```javascript 1 // Extract domain from user's email address 2 const domain = email.split('@')[1].toLowerCase(); // e.g., "megacorp.org" 3 4 // Check if domain has an active SSO connection 5 const connections = await scalekit.connections.listConnectionsByDomain({ 6 domain 7 }); 8 9 if (connections.length > 0) { 10 // Domain has SSO configured - redirect to identity provider 11 const authUrl = scalekit.getAuthorizationUrl(redirectUri, { 12 domainHint: domain // Automatically routes to correct IdP 13 }); 14 return res.redirect(authUrl); 15 } else { 16 // No SSO for this domain - show alternative login methods 17 return showPasswordlessLogin(); 18 } ``` * Python check\_sso\_availability.py ```python 1 # Extract domain from user's email address 2 domain = email.split('@')[1].lower() # e.g., "megacorp.org" 3 4 # Check if domain has an active SSO connection 5 connections = scalekit_client.connections.list_connections_by_domain( 6 domain=domain 7 ) 8 9 if len(connections) > 0: 10 # Domain has SSO configured - redirect to identity provider 11 options = AuthorizationUrlOptions() 12 options.domain_hint = domain # Automatically routes to correct IdP 13 14 auth_url = scalekit_client.get_authorization_url( 15 redirect_uri=redirect_uri, 16 options=options 17 ) 18 return redirect(auth_url) 19 else: 20 # No SSO for this domain - show alternative login methods 21 return show_passwordless_login() ``` * Go check\_sso\_availability.go ```go 1 // Extract domain from user's email address 2 parts := strings.Split(email, "@") 3 domain := strings.ToLower(parts[1]) // e.g., "megacorp.org" 4 5 // Check if domain has an active SSO connection 6 connections, err := scalekitClient.Connections.ListConnectionsByDomain(domain) 7 if err != nil { 8 // Handle error 9 return err 10 } 11 12 if len(connections) > 0 { 13 // Domain has SSO configured - redirect to identity provider 14 options := scalekit.AuthorizationUrlOptions{ 15 DomainHint: domain, // Automatically routes to correct IdP 16 } 17 18 authUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options) 19 if err != nil { 20 return err 21 } 22 23 c.Redirect(http.StatusFound, authUrl.String()) 24 } else { 25 // No SSO for this domain - show alternative login methods 26 return showPasswordlessLogin() 27 } ``` * Java CheckSsoAvailability.java ```java 1 // Extract domain from user's email address 2 String[] parts = email.split("@"); 3 String domain = parts[1].toLowerCase(); // e.g., "megacorp.org" 4 5 // Check if domain has an active SSO connection 6 List connections = scalekitClient 7 .connections() 8 .listConnectionsByDomain(domain); 9 10 if (connections.size() > 0) { 11 // Domain has SSO configured - redirect to identity provider 12 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 13 options.setDomainHint(domain); // Automatically routes to correct IdP 14 15 String authUrl = scalekitClient 16 .authentication() 17 .getAuthorizationUrl(redirectUri, options) 18 .toString(); 19 20 return new RedirectView(authUrl); 21 } else { 22 // No SSO for this domain - show alternative login methods 23 return showPasswordlessLogin(); 24 } ``` This check ensures users only see SSO options when available, improving the login experience and reducing confusion. --- # DOCUMENT BOUNDARY --- # Add users to organizations > Ways in which users join or get added to organizations The journey of a user into your application begins with how they join an organization. A smooth onboarding experience sets the tone for their entire interaction with your product, while administrators need flexible options to manage their organization members. Scalekit supports a variety of ways for users to join organizations. This guide covers methods ranging from manual additions in the dashboard to fully automated provisioning. ## Enable user invitations through your app [Section titled “Enable user invitations through your app”](#enable-user-invitations-through-your-app) Scalekit lets you add user invitation features to your app, allowing users to invite others to join their organization. 1. #### Begin the invite flow [Section titled “Begin the invite flow”](#begin-the-invite-flow) When a user clicks the invite button in your application, retrieve the `organization_id` from their ID token or the application’s context. Then, call the Scalekit SDK with the invitee’s email address to send the invitation. * Node.js Express.js invitation API ```javascript 1 // POST /api/organizations/:orgId/invite 2 app.post('/api/organizations/:orgId/invite', async (req, res) => { 3 const { orgId } = req.params 4 const { email } = req.body 5 6 try { 7 // Create user and add to organization with invitation 8 const { user } = await scalekit.user.createUserAndMembership(orgId, { 9 email, 10 sendInvitationEmail: true, // Scalekit sends the invitation email 11 }) 12 13 res.json({ 14 message: 'Invitation sent successfully', 15 userId: user.id, 16 email: user.email 17 }) 18 } catch (error) { 19 res.status(400).json({ error: error.message }) 20 } 21 }) ``` * Python Django invitation API ```python 1 # Python - Django invitation API 2 @api_view(['POST']) 3 def invite_user_to_organization(request, org_id): 4 email = request.data.get('email') 5 6 try: 7 # Create user and add to organization with invitation 8 user_response = scalekit_client.user.create_user_and_membership(org_id, { 9 'email': email, 10 'send_invitation_email': True, # Scalekit sends the invitation email 11 }) 12 13 return JsonResponse({ 14 'message': 'Invitation sent successfully', 15 'user_id': user_response['user']['id'], 16 'email': user_response['user']['email'] 17 }) 18 except Exception as error: 19 return JsonResponse({'error': str(error)}, status=400) ``` * Go Gin invitation API ```go 1 // Go - Gin invitation API 2 func inviteUserToOrganization(c *gin.Context) { 3 orgID := c.Param("orgId") 4 5 var req struct { 6 Email string `json:"email"` 7 } 8 9 if err := c.ShouldBindJSON(&req); err != nil { 10 c.JSON(400, gin.H{"error": err.Error()}) 11 return 12 } 13 14 // Create user and add to organization with invitation 15 userResp, err := scalekitClient.User.CreateUserAndMembership(ctx, orgID, scalekit.CreateUserAndMembershipRequest{ 16 Email: req.Email, 17 SendInvitationEmail: scalekit.Bool(true), // Scalekit sends the invitation email 18 }) 19 20 if err != nil { 21 c.JSON(400, gin.H{"error": err.Error()}) 22 return 23 } 24 25 c.JSON(200, gin.H{ 26 "message": "Invitation sent successfully", 27 "user_id": userResp.User.Id, 28 "email": userResp.User.Email, 29 }) 30 } ``` * Java Spring Boot invitation API ```java 1 // Java - Spring Boot invitation API 2 @PostMapping("/api/organizations/{orgId}/invite") 3 public ResponseEntity> inviteUserToOrganization( 4 @PathVariable String orgId, 5 @RequestBody InviteRequest request, 6 HttpSession session 7 ) { 8 try { 9 // Create user and add to organization with invitation 10 CreateUser createUser = CreateUser.newBuilder() 11 .setEmail(request.email()) 12 .setSendInvitationEmail(true) // Scalekit sends the invitation email 13 .build(); 14 15 CreateUserAndMembershipResponse response = scalekitClient.users() 16 .createUserAndMembership(orgId, createUser); 17 18 return ResponseEntity.ok(Map.of( 19 "message", "Invitation sent successfully", 20 "user_id", response.getUser().getId(), 21 "email", response.getUser().getEmail() 22 )); 23 } catch (Exception error) { 24 return ResponseEntity.badRequest().body( 25 Map.of("error", error.getMessage()) 26 ); 27 } 28 } ``` This sends a email invitation to invitee to join the organization. 2. #### Set up initiate login endpoint [Section titled “Set up initiate login endpoint”](#set-up-initiate-login-endpoint) After the invitee clicks the invitation link they receive via email, Scalekit will handle verifying their identity in the background through the unique link embedded. Once verified, Scalekit automatically tries to log the invitee into your application by redirecting them to your app’s [configured initiate login endpoint](/guides/dashboard/intitate-login-endpoint/). Let’s go ahead and implement this endpoint. * Node.js routes/auth.js ```javascript 1 // Handle indirect auth entry points 2 app.get('/login', (req, res) => { 3 const redirectUri = 'http://localhost:3000/auth/callback'; 4 const options = { 5 scopes: ['openid', 'profile', 'email', 'offline_access'] 6 }; 7 8 const authorizationUrl = scalekit.getAuthorizationUrl(redirectUri, options); 9 res.redirect(authorizationUrl); 10 }); ``` * Python routes/auth.py ```python 1 from flask import redirect 2 from scalekit import AuthorizationUrlOptions 3 4 # Handle indirect auth entry points 5 @app.route('/login') 6 def login(): 7 redirect_uri = 'http://localhost:3000/auth/callback' 8 options = AuthorizationUrlOptions( 9 scopes=['openid', 'profile', 'email', 'offline_access'] 10 ) 11 12 authorization_url = scalekit_client.get_authorization_url(redirect_uri, options) 13 return redirect(authorization_url) ``` * Go routes/auth.go ```go 1 // Handle indirect auth entry points 2 r.GET("/login", func(c *gin.Context) { 3 redirectUri := "http://localhost:3000/auth/callback" 4 options := scalekitClient.AuthorizationUrlOptions{ 5 Scopes: []string{"openid", "profile", "email", "offline_access"} 6 } 7 8 authorizationUrl, _ := scalekitClient.GetAuthorizationUrl(redirectUri, options) 9 c.Redirect(http.StatusFound, authorizationUrl.String()) 10 }) ``` * Java AuthController.java ```java 1 import org.springframework.web.bind.annotation.GetMapping; 2 import org.springframework.web.bind.annotation.RestController; 3 import java.net.URL; 4 5 // Handle indirect auth entry points 6 @GetMapping("/login") 7 public String login() { 8 String redirectUri = "http://localhost:3000/auth/callback"; 9 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 10 options.setScopes(Arrays.asList("openid", "profile", "email", "offline_access")); 11 12 URL authorizationUrl = scalekitClient.authentication().getAuthorizationUrl(redirectUri, options); 13 return "redirect:" + authorizationUrl.toString(); 14 } ``` This redirection ensures that the invitee is logged into your application after they accept the invitation. User won’t see a login page along the way since the identity is already verified through the unique link embedded in the invitation email. The user will get an invitation email from Scalekit to accept the invitation. ## Enable Just-In-Time (JIT) provisioning [Section titled “Enable Just-In-Time (JIT) provisioning”](#enable-just-in-time-jit-provisioning) Organization administrators, especially at enterprises, prefer to have users verify their identity through their preferred identity provider (such as Okta, Microsoft Entra ID, etc.). This is particularly useful for enterprises with many users who need to ensure that only organization members can access the application. Scalekit will provision the user accounts in your app automatically when they sign in through SSO for the first time and map the user to the same organization. [Learn more](/authenticate/manage-users-orgs/jit-provisioning/) ## Enable SCIM provisioning [Section titled “Enable SCIM provisioning”](#enable-scim-provisioning) Enterprises often rely on user directory providers (such as Okta, Microsoft Entra ID, etc.) to handle user management. This enables their organization administrators to control and manage access for organization members efficiently. Scalekit supports SCIM provisioning, allowing your app to connect with these user directory providers so that user accounts are automatically created or removed in your app when users join or leave the organization. This automation is especially valuable for enterprise customers who want to ensure their licenses or seats are allocated efficiently, with organization admins managing access based on user groups. [Learn more](/authenticate/manage-users-orgs/scim-provisioning/) ## Add users through dashboard [Section titled “Add users through dashboard”](#add-users-through-dashboard) For administrative or support purposes, the Scalekit dashboard allows you to add new members directly to a customer’s organization 1. In the Scalekit dashboard, navigate to **Dashboard > Organizations**. 2. Select the organization you want to add a user to. 3. Go to the **Users** tab and click Invite User. 4. Fill out the invitation form: * Email Address: The user’s email * Role: Assign a role from the dropdown (e.g., Admin, Member, or a custom organization role) * Personal Information (Optional): Add the user’s first name, last name, and display name 5. Click **Send Invitation** The user will receive an email with a link to accept the invitation and join your organization. Once they accept, their status will update in the Users tab. --- # DOCUMENT BOUNDARY --- # Remove users from organizations > Remove users from organizations through dashboard management and API while maintaining security and compliance As your application grows and teams evolve, your administrators will need to manage user access when employees leave, change roles, or when administrators need to revoke access for security reasons. Proper user removal ensures that access control remains accurate, licenses are managed efficiently, and security is maintained across your organization. When a user is removed from an organization, they immediately lose access to that organization’s resources. The user’s account remains in Scalekit, but their membership status changes, and they can no longer access organization-specific data or features. * User loses access to ONE specific organization * User account remains in Scalekit * User can still access OTHER organizations they belong to * Reversible - user can be re-added later - Node.js Remove users from organizations ```javascript 1 // Use case: Remove user during offboarding workflow triggered by HR system 2 await scalekit.user.deleteMembership({ 3 organizationId: 'org_12345', 4 userId: 'usr_67890' 5 }) ``` - Python Remove users from organizations ```python 1 # Use case: Remove user during offboarding workflow triggered by HR system 2 scalekit_client.users.delete_membership( 3 organization_id="org_12345", 4 user_id="usr_67890" 5 ) ``` - Go Remove users from organizations ```go 1 // Use case: Remove user during offboarding workflow triggered by HR system 2 err := scalekitClient.User().DeleteMembership(ctx, "org_123", "user_456", false) 3 if err != nil { 4 log.Printf("Failed to remove user: %v", err) 5 return err 6 } ``` - Java Remove users from organizations ```java 1 // Use case: Remove user during offboarding workflow triggered by HR system 2 try { 3 scalekitClient.user().deleteMembership("org_123", "user_456"); 4 } catch (Exception e) { 5 log.error("Failed to remove user: " + e.getMessage()); 6 throw e; 7 } ``` The membership is removed, effectively dropping the user’s access to the specified organization. ```diff 1 { 2 "user": { 3 "id": "usr_96194455173857548", 4 "environment_id": "env_58345499215790610", 5 "create_time": "2025-10-25T14:46:03.300Z", 6 "update_time": "2025-10-31T11:33:31.639425Z", 7 "email": "saifshine7+locksmith@gmail.com", 8 "external_id": "hitman", 9 "memberships": [ 10 { 11 "organization_id": "org_96194455157080332", 12 "membership_status": "ACTIVE", 13 "roles": [ 14 { 15 "id": "role_69229687729029148", 16 "name": "admin", 17 "display_name": "Admin" 18 } 19 ], 20 "name": "", 21 "metadata": {}, 22 "display_name": "" 23 }, 24 - { 25 "organization_id": "org_67609586521080405", 26 "membership_status": "PENDING_INVITE", 27 "roles": [ 28 - { 29 "id": "role_69229700009951260", 30 "name": "member", 31 "display_name": "Member" 32 - } 33 - ], 34 "name": "Megasoft Inc", 35 "metadata": {}, 36 "display_name": "Megasoft Inc", 37 "created_at": "2025-10-31T12:38:42.270Z", 38 "expires_at": "2025-11-15T12:38:42.231316Z" 39 - } 40 ], 41 "user_profile": { 42 "id": "usp_96194455173923084", 43 "first_name": "Saif", 44 "last_name": "Shines", 45 "name": "", 46 "locale": "", 47 "email_verified": true, 48 "phone_number": "80384873", 49 "metadata": {}, 50 "custom_attributes": {} 51 }, 52 "metadata": {} 53 } 54 } ``` User removal from an organization involves several important considerations and behaviors. * When a user is removed from an organization and has no other organizational memberships, Scalekit will automatically delete their user account. * Your application is responsible for handling the transfer or deletion of the user’s resources when they are removed from an organization. * Scalekit immediately terminates the user’s active session upon removal from an organization. * Removing a user from one organization does not impact their memberships in other organizations. * When a user is removed from an organization, that organization will be automatically removed from the user’s organization switcher options. ## Automate user removal with directory sync [Section titled “Automate user removal with directory sync”](#automate-user-removal-with-directory-sync) When organizations use enterprise directory providers with [SCIM provisioning](/guides/user-management/scim-provisioning/), users are automatically removed from Scalekit organizations when they’re deprovisioned in the source directory. This ensures consistent access control across all systems without requiring manual intervention. When a user is removed from your enterprise directory provider (such as Okta, Azure AD, or JumpCloud): 1. The directory provider sends a SCIM DELETE request to Scalekit 2. Scalekit automatically removes the user’s membership from the organization by marking the `memberships.membership_status` as `INACTIVE` 3. The user immediately loses access to organization resources 4. Your application receives webhook notifications about the membership change This automation is particularly valuable for enterprise customers who manage large numbers of users and need to ensure that license allocation and access control remain synchronized with their directory provider. ## Remove users in the Scalekit dashboard [Section titled “Remove users in the Scalekit dashboard”](#remove-users-in-the-scalekit-dashboard) Use the Scalekit dashboard when administrators need to manually remove users for compliance, security, support or administrative purposes. This approach provides direct control and visibility into the removal process, making it ideal for situations requiring manual oversight. 1. Sign in to the Scalekit dashboard and navigate to **Dashboard** > **Organizations**. Select the organization from which you want to remove users. 2. Click on the **Users** tab to view all organization members. Locate the user you want to remove from the user list. You can use the search functionality to quickly find specific users by name or email. 3. Click the **Actions** menu (three dots) next to the user’s name and select **Remove from organization**. A confirmation dialog will appear to prevent accidental removals. 4. Review the confirmation dialog to ensure you’re removing the correct user. Click **Remove user** to confirm. The user will immediately lose access to the organization and its resources. --- # DOCUMENT BOUNDARY --- # Add Modular SSO > Enable enterprise SSO for any customer in minutes with built-in SAML and OIDC integrations Enterprise customers often require Single Sign-On (SSO) support for their applications. Rather than building custom integrations for every identity provider—such as Okta, Entra ID, or JumpCloud—and managing the detailed configuration of OIDC and SAML protocols, there are more scalable approaches available. Modular SSO is designed for applications that maintain their own user database and session management. This lightweight integration focuses solely on identity verification, giving you complete control over user data and authentication flows. Choose Modular SSO when you: * Want to manage user records in your own database * Prefer to implement custom session management logic * Need to integrate SSO without changing your existing authentication architecture * Already have existing user management infrastructure ### Build with a coding agent * Claude Code ```bash /plugin marketplace add scalekit-inc/claude-code-authstack ``` ```bash /plugin install modular-sso@scalekit-auth-stack ``` * Codex ```bash curl -fsSL https://raw.githubusercontent.com/scalekit-inc/codex-authstack/main/install.sh | bash ``` ```bash # Restart Codex # Plugin Directory -> Scalekit Auth Stack -> install modular-sso ``` * GitHub Copilot CLI ```bash copilot plugin marketplace add scalekit-inc/github-copilot-authstack ``` ```bash copilot plugin install modular-sso@scalekit-auth-stack ``` * 40+ agents ```bash npx skills add scalekit-inc/skills --skill modular-sso ``` [Continue building with AI →](/dev-kit/build-with-ai/sso/) 1. ## Configure “Modular Auth” mode [Section titled “Configure “Modular Auth” mode”](#configure-modular-auth-mode) Ensure your environment is configured in Modular Auth mode. 1. Go to Dashboard > Settings > Authentication Mode 2. Select “Modular Auth” and save Now you’re ready to start integrating SSO into your app! Next, we’ll cover how to use the SDK to authenticate users. 2. ## Set up Scalekit [Section titled “Set up Scalekit”](#set-up-scalekit) Use the following instructions to install the SDK for your technology stack. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` Configure your environment with API credentials. Navigate to **Dashboard > Developers > Settings > API credentials** and copy these values to your `.env` file: .env ```sh SCALEKIT_ENVIRONMENT_URL= # Example: https://acme.scalekit.dev or https://auth.acme.com (if custom domain is set) SCALEKIT_CLIENT_ID= # Example: skc_1234567890abcdef SCALEKIT_CLIENT_SECRET= # Example: test_abcdef1234567890 ``` ### Register redirect URL for your app [Section titled “Register redirect URL for your app”](#register-redirect-url-for-your-app) You need to register redirect URL for your application. Go to **Scalekit dashboard** → **Authentication** → **Redirect URLs** and configure: * **Allowed callback URLs**: The endpoint where users are sent after successful authentication to exchange authorization codes and retrieve profile information. [Learn more](/guides/dashboard/redirects/#allowed-callback-urls) * **Initiate login URL**: The endpoint in your app that redirects users to Scalekit’s `/authorize` endpoint. Required when user starts sign-in directly from their identity provider (IdP-initiated SSO). [Learn more](/guides/dashboard/redirects/#initiate-login-url) 3. ## Redirect the users to their enterprise identity provider login page [Section titled “Redirect the users to their enterprise identity provider login page”](#redirect-the-users-to-their-enterprise-identity-provider-login-page) Create an authorization URL to redirect users to Scalekit’s sign-in page. Use the Scalekit SDK to construct this URL with your redirect URI and required scopes. * Node.js authorization-url.js ```javascript 1 import { Scalekit } from '@scalekit-sdk/node'; 2 3 const scalekit = new ScalekitClient( 4 '', // Your Scalekit environment URL 5 '', // Unique identifier for your app 6 '', 7 ); 8 9 const options = {}; 10 11 // Specify which SSO connection to use (choose one based on your use case) 12 // These identifiers are evaluated in order of precedence: 13 14 // 1. connectionId (highest precedence) - Use when you know the exact SSO connection 15 options['connectionId'] = 'conn_15696105471768821'; 16 17 // 2. organizationId - Routes to organization's SSO (useful for multi-tenant apps) 18 // If org has multiple connections, the first active one is selected 19 options['organizationId'] = 'org_15421144869927830'; 20 21 // 3. loginHint (lowest precedence) - Extracts domain from email to find connection 22 // Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 23 options['loginHint'] = 'user@example.com'; 24 25 // redirect_uri: Your callback endpoint that receives the authorization code 26 // Must match the URL registered in your Scalekit dashboard 27 const redirectUrl = 'https://your-app.com/auth/callback'; 28 29 const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options); 30 // Redirect user to this URL to begin SSO authentication ``` * Python authorization\_url.py ```python 1 from scalekit import ScalekitClient, AuthorizationUrlOptions 2 3 scalekit = ScalekitClient( 4 '', # Your Scalekit environment URL 5 '', # Unique identifier for your app 6 '' 7 ) 8 9 options = AuthorizationUrlOptions() 10 11 # Specify which SSO connection to use (choose one based on your use case) 12 # These identifiers are evaluated in order of precedence: 13 14 # 1. connection_id (highest precedence) - Use when you know the exact SSO connection 15 options.connection_id = 'conn_15696105471768821' 16 17 # 2. organization_id - Routes to organization's SSO (useful for multi-tenant apps) 18 # If org has multiple connections, the first active one is selected 19 options.organization_id = 'org_15421144869927830' 20 21 # 3. login_hint (lowest precedence) - Extracts domain from email to find connection 22 # Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 23 options.login_hint = 'user@example.com' 24 25 # redirect_uri: Your callback endpoint that receives the authorization code 26 # Must match the URL registered in your Scalekit dashboard 27 redirect_uri = 'https://your-app.com/auth/callback' 28 29 authorization_url = scalekit_client.get_authorization_url( 30 redirect_uri=redirect_uri, 31 options=options 32 ) 33 # Redirect user to this URL to begin SSO authentication ``` * Go authorization\_url.go ```go 1 import ( 2 "github.com/scalekit-inc/scalekit-sdk-go" 3 ) 4 5 func main() { 6 scalekitClient := scalekit.NewScalekitClient( 7 "", // Your Scalekit environment URL 8 "", // Unique identifier for your app 9 "" 10 ) 11 12 options := scalekitClient.AuthorizationUrlOptions{} 13 14 // Specify which SSO connection to use (choose one based on your use case) 15 // These identifiers are evaluated in order of precedence: 16 17 // 1. ConnectionId (highest precedence) - Use when you know the exact SSO connection 18 options.ConnectionId = "conn_15696105471768821" 19 20 // 2. OrganizationId - Routes to organization's SSO (useful for multi-tenant apps) 21 // If org has multiple connections, the first active one is selected 22 options.OrganizationId = "org_15421144869927830" 23 24 // 3. LoginHint (lowest precedence) - Extracts domain from email to find connection 25 // Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 26 options.LoginHint = "user@example.com" 27 28 // redirectUrl: Your callback endpoint that receives the authorization code 29 // Must match the URL registered in your Scalekit dashboard 30 redirectUrl := "https://your-app.com/auth/callback" 31 32 authorizationURL := scalekitClient.GetAuthorizationUrl( 33 redirectUrl, 34 options, 35 ) 36 // Redirect user to this URL to begin SSO authentication 37 } ``` * Java AuthorizationUrl.java ```java 1 package com.scalekit; 2 3 import com.scalekit.ScalekitClient; 4 import com.scalekit.internal.http.AuthorizationUrlOptions; 5 6 public class Main { 7 8 public static void main(String[] args) { 9 ScalekitClient scalekitClient = new ScalekitClient( 10 "", // Your Scalekit environment URL 11 "", // Unique identifier for your app 12 "" 13 ); 14 15 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 16 17 // Specify which SSO connection to use (choose one based on your use case) 18 // These identifiers are evaluated in order of precedence: 19 20 // 1. connectionId (highest precedence) - Use when you know the exact SSO connection 21 options.setConnectionId("con_13388706786312310"); 22 23 // 2. organizationId - Routes to organization's SSO (useful for multi-tenant apps) 24 // If org has multiple connections, the first active one is selected 25 options.setOrganizationId("org_13388706786312310"); 26 27 // 3. loginHint (lowest precedence) - Extracts domain from email to find connection 28 // Domain must be registered to the organization (manually via Dashboard or through admin portal during enterprise onboarding) 29 options.setLoginHint("user@example.com"); 30 31 // redirectUrl: Your callback endpoint that receives the authorization code 32 // Must match the URL registered in your Scalekit dashboard 33 String redirectUrl = "https://your-app.com/auth/callback"; 34 35 try { 36 String url = scalekitClient 37 .authentication() 38 .getAuthorizationUrl(redirectUrl, options) 39 .toString(); 40 // Redirect user to this URL to begin SSO authentication 41 } catch (Exception e) { 42 System.out.println(e.getMessage()); 43 } 44 } 45 } ``` * Direct URL (No SDK) OAuth2 authorization URL ```sh /oauth/authorize? response_type=code& # OAuth2 authorization code flow client_id=& # Your Scalekit client ID redirect_uri=& # URL-encoded callback URL scope=openid profile email& # Note: "offline_access" scope is not supported in Modular SSO organization_id=org_15421144869927830& # (Optional) Route by organization connection_id=conn_15696105471768821& # (Optional) Specific SSO connection login_hint=user@example.com # (Optional) Extract domain from email ``` **SSO identifiers** (choose one or more, evaluated in order of precedence): * `connection_id` - Direct to specific SSO connection (highest precedence) * `organization_id` - Route to organization’s SSO * `domain_hint` - Lookup connection by domain * `login_hint` - Extract domain from email (lowest precedence). Domain must be registered to the organization (manually via Dashboard or through admin portal when [onboarding an enterprise customer](/sso/guides/onboard-enterprise-customers/)) Example with actual values ```http https://tinotat-dev.scalekit.dev/oauth/authorize? response_type=code& client_id=skc_88036702639096097& redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback& scope=openid%20profile%20email& organization_id=org_15421144869927830 ``` Enterprise users see their identity provider’s login page. Users verify their identity through the authentication policies set by their organization’s administrator. Post successful verification, the user profile is [normalized](/sso/guides/user-profile-details/) and sent to your app. For details on how Scalekit determines which SSO connection to use, refer to the [SSO identifier precedence rules](/sso/guides/authorization-url/#parameter-precedence). 4. ## Handle IdP-initiated SSO Recommended [Section titled “Handle IdP-initiated SSO ”](#handle-idp-initiated-sso-) When users start the login process from their identity provider’s portal (rather than your application), this is called IdP-initiated SSO. Scalekit converts these requests to secure SP-initiated flows automatically. Your initiate login endpoint receives an `idp_initiated_login` JWT parameter containing the user’s organization and connection details. Decode this token and generate a new authorization URL to complete the authentication flow securely. ```sh https://yourapp.com/login?idp_initiated_login= ``` Configure your initiate login endpoint in [Dashboard > Authentication > Redirects](/guides/dashboard/redirects/#initiate-login-url) * Node.js handle-idp-initiated.js ```javascript 1 // Your initiate login endpoint receives the IdP-initiated login token 2 const { idp_initiated_login, error, error_description } = req.query; 3 4 if (error) { 5 return res.status(400).json({ message: error_description }); 6 } 7 8 // When users start login from their IdP portal, convert to SP-initiated flow 9 if (idp_initiated_login) { 10 // Decode the JWT to extract organization and connection information 11 const claims = await scalekit.getIdpInitiatedLoginClaims(idp_initiated_login); 12 13 const options = { 14 connectionId: claims.connection_id, // Specific SSO connection 15 organizationId: claims.organization_id, // User's organization 16 loginHint: claims.login_hint, // User's email for context 17 state: claims.relay_state // Preserve state from IdP 18 }; 19 20 // Generate authorization URL and redirect to complete authentication 21 const authorizationURL = scalekit.getAuthorizationUrl( 22 'https://your-app.com/auth/callback', 23 options 24 ); 25 26 return res.redirect(authorizationURL); 27 } ``` * Python handle\_idp\_initiated.py ```python 1 # Your initiate login endpoint receives the IdP-initiated login token 2 idp_initiated_login = request.args.get('idp_initiated_login') 3 error = request.args.get('error') 4 error_description = request.args.get('error_description') 5 6 if error: 7 raise Exception(error_description) 8 9 # When users start login from their IdP portal, convert to SP-initiated flow 10 if idp_initiated_login: 11 # Decode the JWT to extract organization and connection information 12 claims = await scalekit.get_idp_initiated_login_claims(idp_initiated_login) 13 14 options = AuthorizationUrlOptions() 15 options.connection_id = claims.get('connection_id') # Specific SSO connection 16 options.organization_id = claims.get('organization_id') # User's organization 17 options.login_hint = claims.get('login_hint') # User's email for context 18 options.state = claims.get('relay_state') # Preserve state from IdP 19 20 # Generate authorization URL and redirect to complete authentication 21 authorization_url = scalekit.get_authorization_url( 22 redirect_uri='https://your-app.com/auth/callback', 23 options=options 24 ) 25 26 return redirect(authorization_url) ``` * Go handle\_idp\_initiated.go ```go 1 // Your initiate login endpoint receives the IdP-initiated login token 2 idpInitiatedLogin := r.URL.Query().Get("idp_initiated_login") 3 errorDesc := r.URL.Query().Get("error_description") 4 5 if errorDesc != "" { 6 http.Error(w, errorDesc, http.StatusBadRequest) 7 return 8 } 9 10 // When users start login from their IdP portal, convert to SP-initiated flow 11 if idpInitiatedLogin != "" { 12 // Decode the JWT to extract organization and connection information 13 claims, err := scalekitClient.GetIdpInitiatedLoginClaims(r.Context(), idpInitiatedLogin) 14 if err != nil { 15 http.Error(w, err.Error(), http.StatusInternalServerError) 16 return 17 } 18 19 options := scalekit.AuthorizationUrlOptions{ 20 ConnectionId: claims.ConnectionID, // Specific SSO connection 21 OrganizationId: claims.OrganizationID, // User's organization 22 LoginHint: claims.LoginHint, // User's email for context 23 } 24 25 // Generate authorization URL and redirect to complete authentication 26 authUrl, err := scalekitClient.GetAuthorizationUrl( 27 "https://your-app.com/auth/callback", 28 options 29 ) 30 31 if err != nil { 32 http.Error(w, err.Error(), http.StatusInternalServerError) 33 return 34 } 35 36 http.Redirect(w, r, authUrl.String(), http.StatusFound) 37 } ``` * Java HandleIdpInitiated.java ```java 1 // Your initiate login endpoint receives the IdP-initiated login token 2 @GetMapping("/login") 3 public RedirectView handleInitiateLogin( 4 @RequestParam(required = false, name = "idp_initiated_login") String idpInitiatedLoginToken, 5 @RequestParam(required = false) String error, 6 @RequestParam(required = false, name = "error_description") String errorDescription, 7 HttpServletResponse response) throws IOException { 8 9 if (error != null) { 10 response.sendError(HttpStatus.BAD_REQUEST.value(), errorDescription); 11 return null; 12 } 13 14 // When users start login from their IdP portal, convert to SP-initiated flow 15 if (idpInitiatedLoginToken != null) { 16 // Decode the JWT to extract organization and connection information 17 IdpInitiatedLoginClaims claims = scalekit 18 .authentication() 19 .getIdpInitiatedLoginClaims(idpInitiatedLoginToken); 20 21 if (claims == null) { 22 response.sendError(HttpStatus.BAD_REQUEST.value(), "Invalid token"); 23 return null; 24 } 25 26 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 27 options.setConnectionId(claims.getConnectionID()); // Specific SSO connection 28 options.setOrganizationId(claims.getOrganizationID()); // User's organization 29 options.setLoginHint(claims.getLoginHint()); // User's email for context 30 31 // Generate authorization URL and redirect to complete authentication 32 String authUrl = scalekit 33 .authentication() 34 .getAuthorizationUrl("https://your-app.com/auth/callback", options) 35 .toString(); 36 37 response.sendRedirect(authUrl); 38 return null; 39 } 40 41 return null; 42 } ``` This approach provides enhanced security by converting IdP-initiated requests to standard SP-initiated flows, protecting against SAML assertion theft and replay attacks. Learn more: [IdP-initiated SSO implementation guide](/sso/guides/idp-init-sso/) 5. ## Get user details from the callback [Section titled “Get user details from the callback”](#get-user-details-from-the-callback) After successful authentication, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user’s profile information and session tokens. 1. Add a callback endpoint in your application (typically `https://your-app.com/auth/callback`) 2. [Register](/guides/dashboard/redirects/#allowed-callback-urls) it in your Scalekit dashboard > Authentication > Redirect URLS > Allowed Callback URLs In authentication flow, Scalekit redirects to your callback URL with an authorization code. Your application exchanges this code for the user’s profile information. * Node.js Fetch user profile ```javascript 1 // Extract authentication parameters from the callback request 2 const { 3 code, 4 error, 5 error_description, 6 idp_initiated_login, 7 connection_id, 8 relay_state 9 } = req.query; 10 11 if (error) { 12 // Handle authentication errors returned from the identity provider 13 } 14 15 // Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 16 17 const result = await scalekit.authenticateWithCode(code, redirectUri); 18 const userEmail = result.user.email; 19 20 // Create a session for the authenticated user and grant appropriate access permissions ``` * Python Fetch user profile ```py 1 # Extract authentication parameters from the callback request 2 code = request.args.get('code') 3 error = request.args.get('error') 4 error_description = request.args.get('error_description') 5 idp_initiated_login = request.args.get('idp_initiated_login') 6 connection_id = request.args.get('connection_id') 7 relay_state = request.args.get('relay_state') 8 9 if error: 10 raise Exception(error_description) 11 12 # Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 13 14 result = scalekit.authenticate_with_code(code, '') 15 16 # Access normalized user profile information 17 user_email = result.user.email 18 19 # Create a session for the authenticated user and grant appropriate access permissions ``` * Go Fetch user profile ```go 1 // Extract authentication parameters from the callback request 2 code := r.URL.Query().Get("code") 3 error := r.URL.Query().Get("error") 4 errorDescription := r.URL.Query().Get("error_description") 5 idpInitiatedLogin := r.URL.Query().Get("idp_initiated_login") 6 connectionID := r.URL.Query().Get("connection_id") 7 relayState := r.URL.Query().Get("relay_state") 8 9 if error != "" { 10 // Handle authentication errors returned from the identity provider 11 } 12 13 // Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 14 15 result, err := scalekitClient.AuthenticateWithCode(r.Context(), code, redirectUrl) 16 17 if err != nil { 18 // Handle token exchange or validation errors 19 } 20 21 // Access normalized user profile information 22 userEmail := result.User.Email 23 24 // Create a session for the authenticated user and grant appropriate access permissions ``` * Java Fetch user profile ```java 1 // Extract authentication parameters from the callback request 2 String code = request.getParameter("code"); 3 String error = request.getParameter("error"); 4 String errorDescription = request.getParameter("error_description"); 5 String idpInitiatedLogin = request.getParameter("idp_initiated_login"); 6 String connectionID = request.getParameter("connection_id"); 7 String relayState = request.getParameter("relay_state"); 8 9 if (error != null && !error.isEmpty()) { 10 // Handle authentication errors returned from the identity provider 11 return; 12 } 13 14 // Recommended: Process IdP-initiated login flows (when users start from their SSO portal) 15 16 try { 17 AuthenticationResponse result = scalekit.authentication().authenticateWithCode(code, redirectUrl); 18 String userEmail = result.getIdTokenClaims().getEmail(); 19 20 // Create a session for the authenticated user and grant appropriate access permissions 21 } catch (Exception e) { 22 // Handle token exchange or validation errors 23 } ``` The `result` object * Node.js Validate tokens ```js 1 // Validate and decode the ID token from the authentication result 2 const idTokenClaims = await scalekit.validateToken(result.idToken); 3 4 // Validate and decode the access token 5 const accessTokenClaims = await scalekit.validateToken(result.accessToken); ``` * Python Validate tokens ```py 1 # Validate and decode the ID token from the authentication result 2 id_token_claims = scalekit_client.validate_token(result["id_token"]) 3 4 # Validate and decode the access token 5 access_token_claims = scalekit_client.validate_token(result["access_token"]) ``` * Go Validate tokens ```go 1 // Validate and decode the access token (uses JWKS from the client) 2 accessTokenClaims, err := scalekitClient.GetAccessTokenClaims(ctx, result.AccessToken) 3 if err != nil { 4 // handle error 5 } ``` * Java Validate tokens ```java 1 // Validate and decode the ID token 2 Map idTokenClaims = scalekitClient.validateToken(result.getIdToken()); 3 4 // Validate and decode the access token 5 Map accessTokenClaims = scalekitClient.validateToken(result.getAccessToken()); ``` - Auth result ```js 1 { 2 user: { 3 email: 'john@example.com', 4 familyName: 'Doe', 5 givenName: 'John', 6 username: 'john@example.com', 7 id: 'conn_70087756662964366;dcc62570-6a5a-4819-b11b-d33d110c7716' 8 }, 9 idToken: 'eyJhbGciOiJSU..bcLQ', 10 accessToken: 'eyJhbGciO..', 11 expiresIn: 899 12 } ``` - ID token (decoded) ```js 1 { 2 amr: [ 'conn_70087756662964366' ], // SSO connection ID 3 at_hash: 'yMGIBg7BkmIGgD6_dZPEGQ', 4 aud: [ 'skc_70087756327420046' ], 5 azp: 'skc_70087756327420046', 6 c_hash: '4x7qsXnlRw6dRC6twnuENw', 7 client_id: 'skc_70087756327420046', 8 email: 'john@example.com', 9 exp: 1758952038, 10 family_name: 'Doe', 11 given_name: 'John', 12 iat: 1758692838, 13 iss: '', 14 oid: 'org_70087756646187150', 15 preferred_username: 'john@example.com', 16 sid: 'ses_91646612652163629', 17 sub: 'conn_70087756662964366;e964d135-35c7-4a13-a3b4-2579a1cdf4e6' 18 } ``` - Access token (decoded) ```js 1 { 2 "iss": "", 3 "sub": "conn_70087756662964366;dcc62570-6a5a-4819-b11b-d33d110c7716", 4 "aud": [ 5 "skc_70087756327420046" 6 ], 7 "exp": 1758693916, 8 "iat": 1758693016, 9 "nbf": 1758693016, 10 "client_id": "skc_70087756327420046", 11 "jti": "tkn_91646913048216109" 12 } ``` 6. ## Test your SSO integration [Section titled “Test your SSO integration”](#test-your-sso-integration) Validate your implementation using the **IdP Simulator** and **Test Organization** included in your development environment. Test all three scenarios before deploying to production. Your environment includes a pre-configured test organization (found in **Dashboard > Organizations**) with domains like `@example.com` and `@example.org` for testing. Pass one of the following connection selectors in your authorization URL: * Email address with `@example.com` or `@example.org` domain * Test organization’s connection ID * Organization ID This opens the SSO login page (IdP Simulator) that simulates your customer’s identity provider login experience.  For detailed testing instructions and scenarios, see our [Complete SSO testing guide](/sso/guides/test-sso/) 7. ## Set up SSO with your existing authentication system [Section titled “Set up SSO with your existing authentication system”](#set-up-sso-with-your-existing-authentication-system) Many applications already use an authentication provider such as Auth0, Firebase, or AWS Cognito. To enable single sign-on (SSO) using Scalekit, configure Scalekit to work with your current authentication provider. ### Auth0 Integrate Scalekit with Auth0 for enterprise SSO [Know more →](/guides/integrations/auth-systems/auth0) ### Firebase Auth Add enterprise authentication to Firebase projects [Know more →](/guides/integrations/auth-systems/firebase) ### AWS Cognito Configure Scalekit with AWS Cognito user pools [Know more →](/guides/integrations/auth-systems/aws-cognito) 8. ## Onboard enterprise customers [Section titled “Onboard enterprise customers”](#onboard-enterprise-customers) Enable SSO for your enterprise customers by creating an organization in Scalekit and providing them access to the Admin Portal. Your customers configure their identity provider settings themselves through a self-service portal. **Create an organization** for your customer in [Dashboard > Organizations](https://app.scalekit.com/organizations), then provide Admin Portal access using one of these methods: * Shareable link Generate a secure link your customer can use to access the Admin Portal: generate-portal-link.js ```javascript // Generate a one-time Admin Portal link for your customer const portalLink = await scalekit.organization.generatePortalLink( 'org_32656XXXXXX0438' // Your customer's organization ID ); // Share this link with your customer's IT admin via email or messaging // Example: '/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43 console.log('Admin Portal URL:', portalLink.location); ``` Send this link to your customer’s IT administrator through email, Slack, or your preferred communication channel. They can configure their SSO connection without any developer involvement. * Embedded portal Embed the Admin Portal directly in your application using an iframe: embed-portal.js ```javascript // Generate a secure portal link at runtime const portalLink = await scalekit.organization.generatePortalLink(orgId); // Return the link to your frontend to embed in an iframe res.json({ portalUrl: portalLink.location }); ``` admin-settings.html ```html ``` Customers configure SSO without leaving your application, maintaining a consistent user experience. Listen for UI events from the embedded portal to respond to configuration changes, such as when SSO is enabled or the session expires. See the [Admin portal UI events reference](/reference/admin-portal/ui-events/) for details on handling these events. Learn more: [Embedded Admin Portal guide](/guides/admin-portal/#embed-the-admin-portal) **Enable domain verification** for seamless user experience. Once your customer verifies their domain (e.g., `@megacorp.org`), users can sign in without selecting their organization. Scalekit automatically routes them to the correct identity provider based on their email domain. **Pre-check SSO availability** before redirecting users. This prevents failed redirects when a user’s domain doesn’t have SSO configured: * Node.js check-sso-availability.js ```javascript 1 // Extract domain from user's email address 2 const domain = email.split('@')[1].toLowerCase(); // e.g., "megacorp.org" 3 4 // Check if domain has an active SSO connection 5 const connections = await scalekit.connections.listConnectionsByDomain({ 6 domain 7 }); 8 9 if (connections.length > 0) { 10 // Domain has SSO configured - redirect to identity provider 11 const authUrl = scalekit.getAuthorizationUrl(redirectUri, { 12 domainHint: domain // Automatically routes to correct IdP 13 }); 14 return res.redirect(authUrl); 15 } else { 16 // No SSO for this domain - show alternative login methods 17 return showPasswordlessLogin(); 18 } ``` * Python check\_sso\_availability.py ```python 1 # Extract domain from user's email address 2 domain = email.split('@')[1].lower() # e.g., "megacorp.org" 3 4 # Check if domain has an active SSO connection 5 connections = scalekit_client.connections.list_connections_by_domain( 6 domain=domain 7 ) 8 9 if len(connections) > 0: 10 # Domain has SSO configured - redirect to identity provider 11 options = AuthorizationUrlOptions() 12 options.domain_hint = domain # Automatically routes to correct IdP 13 14 auth_url = scalekit_client.get_authorization_url( 15 redirect_uri=redirect_uri, 16 options=options 17 ) 18 return redirect(auth_url) 19 else: 20 # No SSO for this domain - show alternative login methods 21 return show_passwordless_login() ``` * Go check\_sso\_availability.go ```go 1 // Extract domain from user's email address 2 parts := strings.Split(email, "@") 3 domain := strings.ToLower(parts[1]) // e.g., "megacorp.org" 4 5 // Check if domain has an active SSO connection 6 connections, err := scalekitClient.Connections.ListConnectionsByDomain(domain) 7 if err != nil { 8 // Handle error 9 return err 10 } 11 12 if len(connections) > 0 { 13 // Domain has SSO configured - redirect to identity provider 14 options := scalekit.AuthorizationUrlOptions{ 15 DomainHint: domain, // Automatically routes to correct IdP 16 } 17 18 authUrl, err := scalekitClient.GetAuthorizationUrl(redirectUri, options) 19 if err != nil { 20 return err 21 } 22 23 c.Redirect(http.StatusFound, authUrl.String()) 24 } else { 25 // No SSO for this domain - show alternative login methods 26 return showPasswordlessLogin() 27 } ``` * Java CheckSsoAvailability.java ```java 1 // Extract domain from user's email address 2 String[] parts = email.split("@"); 3 String domain = parts[1].toLowerCase(); // e.g., "megacorp.org" 4 5 // Check if domain has an active SSO connection 6 List connections = scalekitClient 7 .connections() 8 .listConnectionsByDomain(domain); 9 10 if (connections.size() > 0) { 11 // Domain has SSO configured - redirect to identity provider 12 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 13 options.setDomainHint(domain); // Automatically routes to correct IdP 14 15 String authUrl = scalekitClient 16 .authentication() 17 .getAuthorizationUrl(redirectUri, options) 18 .toString(); 19 20 return new RedirectView(authUrl); 21 } else { 22 // No SSO for this domain - show alternative login methods 23 return showPasswordlessLogin(); 24 } ``` This check ensures users only see SSO options when available, improving the login experience and reducing confusion. --- # DOCUMENT BOUNDARY --- # Admin portal > Implement Scalekit's self-serve admin portal to let customers configure SSO via a shareable link or embedded iframe The admin portal provides a self-serve interface for customers to configure single sign-on (SSO) and directory sync (SCIM) connections. Scalekit hosts the portal and provides two integration methods: generate a shareable link through the dashboard or programmatically embed the portal in your application using an iframe. This guide shows you how to implement both integration methods. For the broader customer onboarding workflow, see [Onboard enterprise customers](/sso/guides/onboard-enterprise-customers/). ## Generate shareable portal link No-code Generate a shareable link through the Scalekit dashboard to give customers access to the admin portal. This method requires no code and is ideal for quick setup. ### Create the portal link 1. Log in to the [Scalekit dashboard](https://app.scalekit.com) 2. Navigate to **Dashboard > Organizations** 3. Select the target organization 4. Click **Generate link** to create a shareable admin portal link The generated link follows this format: Portal link example ```http https://your-app.scalekit.dev/magicLink/2cbe56de-eec4-41d2-abed-90a5b82286c4_p ``` ### Link properties | Property | Details | | -------------- | ------------------------------------------------------------------------------- | | **Expiration** | Links expire after 7 days | | **Revocation** | Revoke links anytime from the dashboard | | **Sharing** | Share via email, Slack, or any preferred channel | | **Security** | Anyone with the link can view and update the organization’s connection settings | Security consideration Treat portal links as sensitive credentials. Anyone with the link can view and modify the organization’s SSO and SCIM configuration. ## Embed the admin portal Programmatic Embed the admin portal directly in your application using an iframe. This allows customers to configure SSO and SCIM without leaving your app, creating a seamless experience within your settings or admin interface. The portal link must be generated programmatically on each page load for security. Each generated link is single-use and expires after 1 minute, though once loaded, the session remains active for up to 6 hours. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` ### Generate portal link Use the Scalekit SDK to generate a unique, embeddable admin portal link for an organization. Call this API endpoint each time you render the page containing the iframe. * Node.js Express.js ```javascript 1 import { Scalekit } from '@scalekit-sdk/node'; 2 3 const scalekit = new Scalekit( 4 process.env.SCALEKIT_ENVIRONMENT_URL, 5 process.env.SCALEKIT_CLIENT_ID, 6 process.env.SCALEKIT_CLIENT_SECRET, 7 ); 8 9 async function generatePortalLink(organizationId) { 10 const link = await scalekit.organization.generatePortalLink(organizationId); 11 return link.location; // Use as iframe src 12 } ``` * Python Flask ```python 1 from scalekit import Scalekit 2 import os 3 4 scalekit_client = Scalekit( 5 environment_url=os.environ.get("SCALEKIT_ENVIRONMENT_URL"), 6 client_id=os.environ.get("SCALEKIT_CLIENT_ID"), 7 client_secret=os.environ.get("SCALEKIT_CLIENT_SECRET") 8 ) 9 10 def generate_portal_link(organization_id): 11 link = scalekit_client.organization.generate_portal_link(organization_id) 12 return link.location # Use as iframe src ``` * Go Gin ```go 1 import ( 2 "context" 3 "os" 4 5 "github.com/scalekit/sdk-go" 6 ) 7 8 scalekitClient := scalekit.New( 9 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 10 os.Getenv("SCALEKIT_CLIENT_ID"), 11 os.Getenv("SCALEKIT_CLIENT_SECRET"), 12 ) 13 14 func generatePortalLink(organizationID string) (string, error) { 15 ctx := context.Background() 16 link, err := scalekitClient.Organization().GeneratePortalLink(ctx, organizationID) 17 if err != nil { 18 return "", err 19 } 20 return link.Location, nil // Use as iframe src 21 } ``` * Java Spring Boot ```java 1 import com.scalekit.client.Scalekit; 2 import com.scalekit.client.models.Link; 3 import com.scalekit.client.models.Feature; 4 import java.util.Arrays; 5 6 Scalekit scalekitClient = new Scalekit( 7 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 8 System.getenv("SCALEKIT_CLIENT_ID"), 9 System.getenv("SCALEKIT_CLIENT_SECRET") 10 ); 11 12 public String generatePortalLink(String organizationId) { 13 Link portalLink = scalekitClient.organizations() 14 .generatePortalLink(organizationId, Arrays.asList(Feature.sso, Feature.dir_sync)); 15 return portalLink.getLocation(); // Use as iframe src 16 } ``` The API returns a JSON object with the portal link. Use the `location` property as the iframe `src`: API response ```json { "id": "8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "location": "https://random-subdomain.scalekit.dev/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "expireTime": "2024-10-03T13:35:50.563013Z" } ``` Embed portal in iframe ```html ``` Embed the portal in your application’s settings or admin section where customers manage authentication configuration. ### Configuration and session | Setting | Requirement | | --------------------- | ----------------------------------------------------------------------------- | | **Redirect URI** | Add your application domain at **Dashboard > Developers > API Configuration** | | **iframe attributes** | Include `allow="clipboard-write"` for copy-paste functionality | | **Dimensions** | Minimum recommended height: 600px | | **Link expiration** | Generated links expire after 1 minute if not loaded | | **Session duration** | Portal session remains active for up to 6 hours once loaded | | **Single-use** | Each generated link can only be used once to initialize a session | ## Customize the admin portal Match the admin portal to your brand identity. Configure branding at **Dashboard > Settings > Branding**: | Option | Description | | ---------------- | --------------------------------------------------------- | | **Logo** | Upload your company logo (displayed in the portal header) | | **Accent color** | Set the primary color to match your brand palette | | **Favicon** | Provide a custom favicon for browser tabs | For additional customization options including custom domains, see the [Custom domain guide](/guides/custom-domain/). [SSO integrations ](/guides/integrations/sso-integrations/)Administrator guides to set up SSO integrations [Portal events ](/reference/admin-portal/ui-events/)Listen to the browser events emitted from the embedded admin portal --- # DOCUMENT BOUNDARY --- # Code samples > Code samples demonstrating Single Sign-On implementations with Express.js, .NET Core, Firebase, AWS Cognito, and Next.js ### [Add SSO to Express.js apps](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/sso-express-example) [Implement Scalekit SSO in a Node.js Express application. Includes middleware setup for secure session handling](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/sso-express-example) ### [Add SSO to .NET Core apps](https://github.com/scalekit-inc/dotnet-example-apps) [Secure .NET Core applications with Scalekit SSO. Demonstrates authentication pipelines and user claims management](https://github.com/scalekit-inc/dotnet-example-apps) ### [Add SSO to Spring Boot apps](https://github.com/scalekit-developers/scalekit-springboot-example) [Integrate Scalekit SSO with Spring Security. Shows how to configure security filters and protect Java endpoints](https://github.com/scalekit-developers/scalekit-springboot-example) ### [Add SSO to Python FastAPI](https://github.com/scalekit-developers/scalekit-fastapi-example) [Add enterprise SSO to FastAPI services using Scalekit. Includes async route protection and user session validation](https://github.com/scalekit-developers/scalekit-fastapi-example) ### [Add SSO to Go applications](https://github.com/scalekit-developers/scalekit-go-example) [Implement Scalekit SSO in Go. Features idiomatically written middleware for securing HTTP handlers](https://github.com/scalekit-developers/scalekit-go-example) ### [Add SSO to Next.js apps](https://github.com/scalekit-developers/scalekit-nextjs-demo) [Secure Next.js applications with Scalekit. Covers both App Router and Pages Router authentication patterns](https://github.com/scalekit-developers/scalekit-nextjs-demo) ### Scalekit SSO + Your own auth system ### [Connect Firebase Auth with SSO](https://github.com/scalekit-inc/scalekit-firebase-sso) [Enable Enterprise SSO for Firebase apps using Scalekit. Learn to link Scalekit identities with Firebase Authentication](https://github.com/scalekit-inc/scalekit-firebase-sso) ### [Connect AWS Cognito with SSO](https://github.com/scalekit-inc/scalekit-cognito-sso) [Add Enterprise SSO to Cognito user pools via Scalekit. Step-by-step guide to federating identity providers](https://github.com/scalekit-inc/scalekit-cognito-sso) ### [Cognito + Scalekit for Next.js](https://github.com/scalekit-inc/nextjs-example-apps/tree/main/cognito-scalekit) [Integrate Cognito and Scalekit SSO in Next.js. Uses OIDC protocols to secure your full-stack React application](https://github.com/scalekit-inc/nextjs-example-apps/tree/main/cognito-scalekit) ## Admin portal ### [Embed admin portal](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/embed-admin-portal-sample) [Embed the Scalekit Admin Portal into your app via **iframe**. Node.js example for generating secure admin sessions](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/embed-admin-portal-sample) --- # DOCUMENT BOUNDARY --- # Admin portal > Implement Scalekit's self-serve admin portal to let customers configure SCIM via a shareable link or embedded iframe The admin portal provides a self-serve interface for customers to configure single sign-on (SSO) and directory sync (SCIM) connections. Scalekit hosts the portal and provides two integration methods: generate a shareable link through the dashboard or programmatically embed the portal in your application using an iframe. This guide shows you how to implement both integration methods. For the broader customer onboarding workflow, see [Onboard enterprise customers](/sso/guides/onboard-enterprise-customers/). ## Generate shareable portal link No-code Generate a shareable link through the Scalekit dashboard to give customers access to the admin portal. This method requires no code and is ideal for quick setup. ### Create the portal link 1. Log in to the [Scalekit dashboard](https://app.scalekit.com) 2. Navigate to **Dashboard > Organizations** 3. Select the target organization 4. Click **Generate link** to create a shareable admin portal link The generated link follows this format: Portal link example ```http https://your-app.scalekit.dev/magicLink/2cbe56de-eec4-41d2-abed-90a5b82286c4_p ``` ### Link properties | Property | Details | | -------------- | ------------------------------------------------------------------------------- | | **Expiration** | Links expire after 7 days | | **Revocation** | Revoke links anytime from the dashboard | | **Sharing** | Share via email, Slack, or any preferred channel | | **Security** | Anyone with the link can view and update the organization’s connection settings | Security consideration Treat portal links as sensitive credentials. Anyone with the link can view and modify the organization’s SSO and SCIM configuration. ## Embed the admin portal Programmatic Embed the admin portal directly in your application using an iframe. This allows customers to configure SSO and SCIM without leaving your app, creating a seamless experience within your settings or admin interface. The portal link must be generated programmatically on each page load for security. Each generated link is single-use and expires after 1 minute, though once loaded, the session remains active for up to 6 hours. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` ### Generate portal link Use the Scalekit SDK to generate a unique, embeddable admin portal link for an organization. Call this API endpoint each time you render the page containing the iframe. * Node.js Express.js ```javascript 1 import { Scalekit } from '@scalekit-sdk/node'; 2 3 const scalekit = new Scalekit( 4 process.env.SCALEKIT_ENVIRONMENT_URL, 5 process.env.SCALEKIT_CLIENT_ID, 6 process.env.SCALEKIT_CLIENT_SECRET, 7 ); 8 9 async function generatePortalLink(organizationId) { 10 const link = await scalekit.organization.generatePortalLink(organizationId); 11 return link.location; // Use as iframe src 12 } ``` * Python Flask ```python 1 from scalekit import Scalekit 2 import os 3 4 scalekit_client = Scalekit( 5 environment_url=os.environ.get("SCALEKIT_ENVIRONMENT_URL"), 6 client_id=os.environ.get("SCALEKIT_CLIENT_ID"), 7 client_secret=os.environ.get("SCALEKIT_CLIENT_SECRET") 8 ) 9 10 def generate_portal_link(organization_id): 11 link = scalekit_client.organization.generate_portal_link(organization_id) 12 return link.location # Use as iframe src ``` * Go Gin ```go 1 import ( 2 "context" 3 "os" 4 5 "github.com/scalekit/sdk-go" 6 ) 7 8 scalekitClient := scalekit.New( 9 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 10 os.Getenv("SCALEKIT_CLIENT_ID"), 11 os.Getenv("SCALEKIT_CLIENT_SECRET"), 12 ) 13 14 func generatePortalLink(organizationID string) (string, error) { 15 ctx := context.Background() 16 link, err := scalekitClient.Organization().GeneratePortalLink(ctx, organizationID) 17 if err != nil { 18 return "", err 19 } 20 return link.Location, nil // Use as iframe src 21 } ``` * Java Spring Boot ```java 1 import com.scalekit.client.Scalekit; 2 import com.scalekit.client.models.Link; 3 import com.scalekit.client.models.Feature; 4 import java.util.Arrays; 5 6 Scalekit scalekitClient = new Scalekit( 7 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 8 System.getenv("SCALEKIT_CLIENT_ID"), 9 System.getenv("SCALEKIT_CLIENT_SECRET") 10 ); 11 12 public String generatePortalLink(String organizationId) { 13 Link portalLink = scalekitClient.organizations() 14 .generatePortalLink(organizationId, Arrays.asList(Feature.sso, Feature.dir_sync)); 15 return portalLink.getLocation(); // Use as iframe src 16 } ``` The API returns a JSON object with the portal link. Use the `location` property as the iframe `src`: API response ```json { "id": "8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "location": "https://random-subdomain.scalekit.dev/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "expireTime": "2024-10-03T13:35:50.563013Z" } ``` Embed portal in iframe ```html ``` Embed the portal in your application’s settings or admin section where customers manage authentication configuration. ### Configuration and session | Setting | Requirement | | --------------------- | ----------------------------------------------------------------------------- | | **Redirect URI** | Add your application domain at **Dashboard > Developers > API Configuration** | | **iframe attributes** | Include `allow="clipboard-write"` for copy-paste functionality | | **Dimensions** | Minimum recommended height: 600px | | **Link expiration** | Generated links expire after 1 minute if not loaded | | **Session duration** | Portal session remains active for up to 6 hours once loaded | | **Single-use** | Each generated link can only be used once to initialize a session | ## Customize the admin portal Match the admin portal to your brand identity. Configure branding at **Dashboard > Settings > Branding**: | Option | Description | | ---------------- | --------------------------------------------------------- | | **Logo** | Upload your company logo (displayed in the portal header) | | **Accent color** | Set the primary color to match your brand palette | | **Favicon** | Provide a custom favicon for browser tabs | For additional customization options including custom domains, see the [Custom domain guide](/guides/custom-domain/). [SSO integrations ](/guides/integrations/sso-integrations/)Administrator guides to set up SSO integrations [Portal events ](/reference/admin-portal/ui-events/)Listen to the browser events emitted from the embedded admin portal --- # DOCUMENT BOUNDARY --- # Explore sample apps > Explore sample apps for building an Admin Portal and integrating webhooks. Find code examples to streamline SCIM provisioning and user management. Whether you’re building an Admin Portal or implementing webhooks, we’ve got you covered with practical samples and upcoming language-specific examples. ### Admin Portal [Section titled “Admin Portal”](#admin-portal) Our [admin portal](/guides/admin-portal) sample demonstrates key features and functionality for administrative users. It showcase how the admin portal can be integrated with your application to provide efficient and seamless way for IT admins to configure SCIM Provisioning. [Check out the sample app](https://github.com/scalekit-developers/nodejs-example-apps/tree/main/embed-admin-portal-sample) ### NextJS webhook demo [Section titled “NextJS webhook demo”](#nextjs-webhook-demo) This sample application built with NextJS illustrates the implementation and usage of webhooks in a real-world scenario. It provides a practical example of how to integrate webhook functionality into your projects. [Check out the sample app](https://github.com/scalekit-developers/nextjs-example-apps/tree/main/webhook-events) --- # DOCUMENT BOUNDARY --- # Code samples > Code samples demonstrating SCIM provisioning examples and integration patterns for user and group management ### [Handle SCIM webhooks](https://github.com/scalekit-inc/nextjs-example-apps/tree/main/webhook-events) [Process SCIM directory updates in Next.js. Example shows how to verify webhook signatures and sync user data](https://github.com/scalekit-inc/nextjs-example-apps/tree/main/webhook-events) ### [Embed admin portal](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/embed-admin-portal-sample) [Securely embed the Scalekit Admin Portal via iframe. Node.js example for managing directory sync and organizational settings](https://github.com/scalekit-inc/nodejs-example-apps/tree/main/embed-admin-portal-sample) --- # DOCUMENT BOUNDARY --- # Automatically assign roles > Automatically assign roles to users in your application by mapping directory provider groups to application roles using Scalekit Manually assigning roles to users in your application consumes time and creates room for errors for your customers (usually, administrators). Scalekit monitors role changes in connected directories and notifies your application through webhooks. You use the event payload to keep user roles in your application in sync with directory groups in near real time. ## How group-based role assignment works [Section titled “How group-based role assignment works”](#how-group-based-role-assignment-works) Organization administrators commonly manage varying access levels by grouping users in their directory. For example, to manage access levels to GitHub, they create groups for each role and assign users to those groups. In this case a **Maintainer** group includes all the users who should have maintainer access to the repository. This enables your application to take necessary actions such as creating or modifying user roles as directed by the organization’s administrators. ## Set up automatic role assignment [Section titled “Set up automatic role assignment”](#set-up-automatic-role-assignment) To enable administrators to map directory groups to roles in your app, complete these steps: 1. Open the Scalekit dashboard. 2. Go to **Roles & Permissions**. 3. Use the **Roles** and **Permissions** sections to configure your application’s authorization model. 4. Register your app’s roles and permissions so Scalekit can reference them in mappings and webhook events. Select **Add role** to create a new role. Choose clear display names and descriptions for your roles. This helps customers understand and align the roles with the access levels they already maintain in their directory.  The roles page lists a couple of sample roles by default. You can edit or remove these and add new roles that match your application’s authorization model.  Specify the default roles your app wants to assign to the organization creator and to members who belong to the same organization. All added roles are available for you to select as default roles.  ### Connect organization groups to app roles [Section titled “Connect organization groups to app roles”](#connect-organization-groups-to-app-roles) After you create roles, they represent the roles in your app that you want directory groups to control. Users receive role assignments in your app based on the groups they belong to in their directory. You can set up this mapping in two ways: 1. Configure mappings in the Scalekit dashboard on behalf of organization administrators. Select the organization and go to the **SCIM provisioning** tab. 2. Share the [admin portal link](/guides/admin-portal#generate-shareable-portal-link) with organization administrators so they can configure the mappings themselves. Scalekit automatically displays mapping options in both the Scalekit dashboard and the admin portal. This allows administrators to connect organization groups to app roles without custom logic in your application.  ## Handle role update events [Section titled “Handle role update events”](#handle-role-update-events) Scalekit continuously monitors updates from your customers’ directory providers and sends event payloads to your application through a registered webhook endpoint. To set up these endpoints and manage subscriptions, use the **Webhooks** option in the Scalekit dashboard. Listen for the `organization.directory.user_updated` event to determine a user’s roles from the payload. Scalekit automatically includes role information that is relevant to your app, based on the roles you configured in the Scalekit dashboard. * Node.js Create a webhook endpoint for role updates ```javascript 1 // Webhook endpoint to receive directory role updates 2 app.post('/webhook', async (req, res) => { 3 // Extract event data from the webhook payload 4 const event = req.body; 5 const { email, roles } = event.data; 6 7 console.log('Received directory role update for:', email); 8 9 // Extract role_name from the roles array, if present 10 const roleName = Array.isArray(roles) && roles.length > 0 ? roles[0].role_name : null; 11 console.log('Role name received:', roleName); 12 13 // Business logic: update user role and permissions in your app 14 if (roleName) { 15 await assignRole(roleName, email); 16 console.log('Updated access for user:', email); 17 } 18 19 res.status(201).json({ 20 message: 'Role processed', 21 }); 22 }); ``` * Python Create a webhook endpoint for role updates ```python 1 import json 2 from fastapi import FastAPI, Request 3 from fastapi.responses import JSONResponse 4 5 app = FastAPI() 6 7 8 @app.post("/webhook") 9 async def api_webhook(request: Request): 10 # Parse request body from the webhook payload 11 body = await request.body() 12 payload = json.loads(body.decode()) 13 14 # Extract user data 15 user_roles = payload["data"].get("roles", []) 16 user_email = payload["data"].get("email") 17 18 print("User roles:", user_roles) 19 print("User email:", user_email) 20 21 # Business logic: assign role in your app 22 if user_roles and user_email: 23 await assign_role(user_roles[0], user_email) 24 25 return JSONResponse( 26 status_code=201, 27 content={"message": "Role processed"}, 28 ) ``` * Java Create a webhook endpoint for role updates ```java 1 @PostMapping("/webhook") 2 public ResponseEntity> webhook(@RequestBody String body, @RequestHeader Map headers) { 3 ObjectMapper mapper = new ObjectMapper(); 4 5 try { 6 JsonNode node = mapper.readTree(body); 7 JsonNode roles = node.get("data").get("roles"); 8 String email = node.get("data").get("email").asText(); 9 10 System.out.println("Roles: " + roles); 11 System.out.println("Email: " + email); 12 13 // TODO: Add role to user in your application 14 15 Map responseBody = new HashMap<>(); 16 responseBody.put("message", "Role processed"); 17 return ResponseEntity.status(HttpStatus.CREATED).body(responseBody); 18 } catch (IOException e) { 19 return ResponseEntity.status(HttpStatus.BAD_REQUEST).build(); 20 } 21 } ``` * Go Create a webhook endpoint for role updates ```go 1 mux.HandleFunc("POST /webhook", func(w http.ResponseWriter, r *http.Request) { 2 // Read request body from the webhook payload 3 bodyBytes, err := io.ReadAll(r.Body) 4 if err != nil { 5 http.Error(w, err.Error(), http.StatusBadRequest) 6 return 7 } 8 9 // Parse webhook payload 10 var body struct { 11 Data map[string]interface{} `json:"data"` 12 } 13 14 if err := json.Unmarshal(bodyBytes, &body); err != nil { 15 http.Error(w, err.Error(), http.StatusBadRequest) 16 return 17 } 18 19 // Extract user data 20 roles, _ := body.Data["roles"] 21 email, _ := body.Data["email"] 22 23 fmt.Println("Roles:", roles) 24 fmt.Println("Email:", email) 25 26 w.WriteHeader(http.StatusCreated) 27 _, _ = w.Write([]byte(`{"message":"Role processed"}`)) 28 }) ``` Refer to the list of [directory webhook events](/directory/reference/directory-events/) you can subscribe to for more event types. --- # DOCUMENT BOUNDARY --- # Production readiness checklist > A focused checklist for launching your Scalekit SCIM provisioning integration, based on core enterprise authentication launch checks. As you prepare to launch SCIM provisioning to production, you should confirm that your configuration satisfies the SCIM-specific items from the authentication launch checklist. This page extracts the SCIM provisioning items from the main authentication [production readiness checklist](/authenticate/launch-checklist/) and organizes them for your directory rollout. **Verify production environment configuration** Confirm that your environment URL (`SCALEKIT_ENVIRONMENT_URL`), client ID (`SCALEKIT_CLIENT_ID`), and client secret (`SCALEKIT_CLIENT_SECRET`) are correctly configured for your production environment and match your production Scalekit dashboard settings. **Configure SCIM webhook endpoints** Configure webhook endpoints to receive SCIM events in your production environment, and ensure they use HTTPS and correct domain configuration. **Verify webhook security with signature validation** Implement signature validation for incoming SCIM webhooks so only Scalekit can trigger provisioning changes. See [webhook best practices](/guides/webhooks-best-practices/) for guidance. **Test user provisioning, updates, and deprovisioning** Test user provisioning flows (create), deprovisioning flows (deactivate or delete), and user profile updates to ensure your application responds correctly to each event type. **Validate group-based role assignment** Set up group-based role assignment and synchronization, and verify that group membership changes in the identity provider correctly map to roles and permissions in your application. **Handle duplicate and invalid data scenarios** Test error scenarios such as duplicate users, conflicting identifiers, and invalid data payloads so your integration fails safely and surfaces actionable errors. **Align SCIM with user and organization models** Confirm that your SCIM implementation matches your user and organization data model, including how you represent organizations, teams, and role assignments in your system. **Finalize admin portal configuration for directory admins** Ensure directory admins can configure SCIM connections in the admin portal, and that your branding and access controls are correct for enterprise customers. --- # DOCUMENT BOUNDARY --- # Onboard enterprise customers > Complete workflow for enabling SCIM provisioning and self-serve directory sync configuration for your enterprise customers Enterprise provisioning with SCIM enables you to automatically create, update, and deactivate users in your application based on changes in your customers’ directory providers such as Okta, Microsoft Entra ID, or Google Workspace. This gives enterprise customers centralized user lifecycle management while reducing manual administration and access drift.  This guide walks you through the complete workflow for onboarding enterprise customers with SCIM provisioning. You’ll learn how to create organizations, provide admin portal access, enable directory sync, and verify that provisioning works end to end. Before onboarding enterprise customers with provisioning, ensure you have completed the [SCIM quickstart](/directory/scim/quickstart/) to set up basic directory sync in your application. ## Table of contents * [Create organization](#create-organization) * [Provide admin portal access](#provide-admin-portal-access) * [Customer configures SCIM provisioning](#customer-configures-scim-provisioning) * [Verify provisioning and run test sync](#verify-provisioning-and-run-test-sync) 1. ## Create organization Create an organization in Scalekit to represent your enterprise customer: * Log in to the [Scalekit dashboard](https://app.scalekit.com) * Navigate to **Dashboard > Organizations** * Click **Create Organization** * Enter the organization name and relevant details * Save the organization Each organization in Scalekit represents one of your enterprise customers and can have its own directory sync settings, SSO configuration, and domain associations. 2. ## Provide admin portal access Give your customer’s IT administrator access to the self-serve admin portal to configure their directory and SCIM connection. Scalekit provides two integration methods: **Option 1: Share a no-code link** Quick setup Generate and share a link to the admin portal: * Select the organization from **Dashboard > Organizations** * Click **Generate link** in the organization overview * Share the link with your customer’s IT admin via email, Slack, or your preferred channel The link remains valid for 7 days and can be revoked anytime from the dashboard. **Link properties:** | Property | Details | | -------------- | ------------------------------------------------------------------------------- | | **Expiration** | Links expire after 7 days | | **Revocation** | Revoke links anytime from the dashboard | | **Sharing** | Share via email, Slack, or any preferred channel | | **Security** | Anyone with the link can view and update the organization’s connection settings | The generated link follows this format: Portal link example ```http https://your-app.scalekit.dev/magicLink/2cbe56de-eec4-41d2-abed-90a5b82286c4_p ``` Security consideration Treat portal links as sensitive credentials. Anyone with the link can view and modify the organization’s SSO and SCIM configuration. **Option 2: Embed the portal** Seamless experience Embed the admin portal directly in your application so customers can configure SCIM provisioning and SSO without leaving your interface. The portal link must be generated programmatically on each page load for security. Each generated link is single-use and expires after 1 minute, though once loaded, the session remains active for up to 6 hours. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` ### Generate portal link Use the Scalekit SDK to generate a unique, embeddable admin portal link for an organization. Call this API endpoint each time you render the page containing the iframe: * Node.js Express.js ```javascript 1 import { Scalekit } from '@scalekit-sdk/node'; 2 3 const scalekit = new Scalekit( 4 process.env.SCALEKIT_ENVIRONMENT_URL, 5 process.env.SCALEKIT_CLIENT_ID, 6 process.env.SCALEKIT_CLIENT_SECRET, 7 ); 8 9 async function generatePortalLink(organizationId) { 10 const link = await scalekit.organization.generatePortalLink(organizationId); 11 return link.location; // Use as iframe src 12 } ``` * Python Flask ```python 1 from scalekit import Scalekit 2 import os 3 4 scalekit_client = Scalekit( 5 environment_url=os.environ.get("SCALEKIT_ENVIRONMENT_URL"), 6 client_id=os.environ.get("SCALEKIT_CLIENT_ID"), 7 client_secret=os.environ.get("SCALEKIT_CLIENT_SECRET") 8 ) 9 10 def generate_portal_link(organization_id): 11 link = scalekit_client.organization.generate_portal_link(organization_id) 12 return link.location # Use as iframe src ``` * Go Gin ```go 1 import ( 2 "context" 3 "os" 4 5 "github.com/scalekit/sdk-go" 6 ) 7 8 scalekitClient := scalekit.New( 9 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 10 os.Getenv("SCALEKIT_CLIENT_ID"), 11 os.Getenv("SCALEKIT_CLIENT_SECRET"), 12 ) 13 14 func generatePortalLink(organizationID string) (string, error) { 15 ctx := context.Background() 16 link, err := scalekitClient.Organization().GeneratePortalLink(ctx, organizationID) 17 if err != nil { 18 return "", err 19 } 20 return link.Location, nil // Use as iframe src 21 } ``` * Java Spring Boot ```java 1 import com.scalekit.client.Scalekit; 2 import com.scalekit.client.models.Link; 3 import com.scalekit.client.models.Feature; 4 import java.util.Arrays; 5 6 Scalekit scalekitClient = new Scalekit( 7 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 8 System.getenv("SCALEKIT_CLIENT_ID"), 9 System.getenv("SCALEKIT_CLIENT_SECRET") 10 ); 11 12 public String generatePortalLink(String organizationId) { 13 Link portalLink = scalekitClient.organizations() 14 .generatePortalLink(organizationId, Arrays.asList(Feature.sso, Feature.dir_sync)); 15 return portalLink.getLocation(); // Use as iframe src 16 } ``` The API returns a JSON object with the portal link. Use the `location` property as the iframe `src`: API response ```json { "id": "8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "location": "https://random-subdomain.scalekit.dev/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "expireTime": "2024-10-03T13:35:50.563013Z" } ``` Embed portal in iframe ```html ``` Embed the portal in your application’s settings or admin section where customers manage authentication configuration. Listen for UI events from the embedded portal to respond to configuration changes, such as when directory sync is enabled, provisioning is tested, or the session expires. See the [Admin portal UI events reference](/reference/admin-portal/ui-events/) for details on handling these events. ### Configuration and session | Setting | Requirement | | --------------------- | ----------------------------------------------------------------------------- | | **Redirect URI** | Add your application domain at **Dashboard > Developers > API Configuration** | | **iframe attributes** | Include `allow="clipboard-write"` for copy-paste functionality | | **Dimensions** | Minimum recommended height: 600px | | **Link expiration** | Generated links expire after 1 minute if not loaded | | **Session duration** | Portal session remains active for up to 6 hours once loaded | | **Single-use** | Each generated link can only be used once to initialize a session | 3. ## Customer configures SCIM provisioning After receiving admin portal access, your customer’s IT administrator: * Opens the admin portal (via shared link or embedded iframe) * Selects their directory integration (Okta, Microsoft Entra ID, Google Workspace, etc.) * Follows the provider-specific SCIM or directory sync setup guide * Enters the required configuration (SCIM endpoint URL, access token, and any required headers) * Tests user provisioning from their directory to your application * Activates the SCIM connection Once configured, the directory sync or SCIM connection appears as active in your organization’s settings. 4. ## Verify provisioning and run test sync After SCIM provisioning is configured, verify that user and group changes flow correctly from the customer’s directory into your application. This ensures your enterprise onboarding is reliable before rolling out broadly. To verify provisioning: * Create a test user in the customer’s directory and assign them to the appropriate groups or applications * Confirm that the user appears in your application’s organization with the expected attributes (name, email, roles, and status) * Update the user’s attributes or group memberships in the directory and verify that changes propagate to your application * Deactivate or delete the test user in the directory and ensure their access is revoked in your application ## Customize the admin portal Match the admin portal to your brand identity. Configure branding at **Dashboard > Settings > Branding**: | Option | Description | | ---------------- | --------------------------------------------------------- | | **Logo** | Upload your company logo (displayed in the portal header) | | **Accent color** | Set the primary color to match your brand palette | | **Favicon** | Provide a custom favicon for browser tabs | For additional customization options including custom domains, see the [Custom domain guide](/guides/custom-domain/). --- # DOCUMENT BOUNDARY --- # Review SCIM protocol > Learn about core components, resources, schemas, and real-world implementation scenarios for identity management across cloud applications through SCIM System for Cross-domain Identity Management (SCIM) is an [open standard API specification](https://datatracker.ietf.org/doc/html/rfc7643#section-2) designed to manage identities across cloud applications easily and scalably. The specification suite builds upon experience with existing schemas and deployments, emphasizing: * Simplicity of development and integration * Application of existing authentication, authorization, and privacy models Its intent is to reduce the cost and complexity of user management operations by providing: * A common user schema * An extension model; e.g., enterprise user * Binding documents to provide patterns for exchanging this schema using HTTP ## SCIM protocol: Key components [Section titled “SCIM protocol: Key components”](#scim-protocol-key-components) SCIM is a HTTP based protocol and uses structured [JSON](https://datatracker.ietf.org/doc/html/rfc7159) payloads to exchange resource information between the SCIM client and service provider. To identify the SCIM protocol resources, the `application/scim+json` media type is used. ### SCIM service provider [Section titled “SCIM service provider”](#scim-service-provider) SCIM service provider is any business application that provisions users and groups by synchronizing the changes made in a SCIM client, including creates, updates, and deletes. The synchronization enables end users to have seamless access to the business application for which they’re assigned, with up-to-date profiles and permissions. Scalekit acts as the SCIM service provider on your behalf and integrates with your customer’s identity providers or directory providers (e.g. Okta, Azure AD, Google Workspace, etc.) to provision users and groups. ### SCIM client [Section titled “SCIM client”](#scim-client) SCIM client facilitates provisioning, or managing user lifecycle events, through SCIM endpoints exposed by the SCIM service provider. Identity providers and HRMS act as very popular SCIM clients as they are treated as the source of truth for user identity data. Some of the most common SCIM clients are [Okta](https://www.okta.com), [Microsoft Entra ID (aka Azure AD)](https://www.microsoft.com/en-in/security/business/identity-access/microsoft-entra-id). ### SCIM endpoints [Section titled “SCIM endpoints”](#scim-endpoints) SCIM endpoints are the entry points to the SCIM API. They are the endpoints that the SCIM client will call to provision users and groups. The following are the most popular SCIM endpoints that any SCIM service provider should support: * `/Users` * `/Groups` ### SCIM methods [Section titled “SCIM methods”](#scim-methods) As SCIM is built on top of REST, SCIM methods are the HTTP methods that are used to perform CRUD operations on the SCIM resources. The following are the most common SCIM methods: * GET * POST * PUT * PATCH * DELETE ### SCIM authentication [Section titled “SCIM authentication”](#scim-authentication) SCIM uses OAuth 2.0 bearer token authentication to authenticate requests to the SCIM API. The token is a string that is used to authenticate the SCIM API requests to the SCIM service provider. The token is passed in the HTTP Authorization header using the Bearer scheme. ## SCIM resources [Section titled “SCIM resources”](#scim-resources) SCIM resources are the core building blocks of the SCIM protocol. They represent entities such as users, groups, and organizational units. Each resource has a set of attributes that describe the entity. While SCIM user resource has the basic attributes of a user like email address, phone number, and name, it is extensible by defining new JSON schemas that a service provider can choose to implement. An enterprise user is an example of a SCIM user extension resource. Enterprise user resource has attributes such as employee number, department, and manager which are valuable for enterprise implementation of user management using SCIM v2. Example SCIM user representation ```json 1 { 2 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 3 "userName": "bjensen", 4 "name": { 5 "givenName": "Barbara", 6 "familyName": "Jensen" 7 }, 8 "emails": [ 9 { 10 "value": "bjensen@example.com", 11 "type": "work", 12 "primary": true 13 } 14 ], 15 "entitlements": [ 16 { 17 "value": "Employee", 18 "type": "role" 19 } 20 ] 21 } ``` ### SCIM schema [Section titled “SCIM schema”](#scim-schema) SCIM schema is the core of the SCIM protocol. It is a JSON schema that defines the structure of the SCIM resources. The following are the most common SCIM schemas: * [Core SCIM user schema](https://datatracker.ietf.org/doc/html/rfc7643#section-4.1) * [Enterprise user schema](https://datatracker.ietf.org/doc/html/rfc7643#section-4.3) * [Group schema](https://datatracker.ietf.org/doc/html/rfc7643#section-4.2) ## Putting everything together [Section titled “Putting everything together”](#putting-everything-together) Now that you have a high level understanding of the SCIM protocol and different components involved, let’s put everything together to take a scenario of how SCIM protocol facilitates user provisioning from an identity provider to a SCIM service provider like Scalekit. ### Scenario: New employee onboarding [Section titled “Scenario: New employee onboarding”](#scenario-new-employee-onboarding) 1. ACME Inc. hires a new employee, John Doe. 2. ACME Inc. adds John Doe to their Okta directory. 3. Okta send a SCIM `POST /Users` request to a pre-registered SCIM service provider (your B2B application) with John Doe’s information as per the SCIM protocol. 4. You authenticate the request using the OAuth 2.0 bearer token authentication & validate the request payload. 5. You provision John Doe as a new user in your B2B application using the user payload. ### Scenario: Employee termination [Section titled “Scenario: Employee termination”](#scenario-employee-termination) 1. ACME Inc. terminates John Doe’s employment. 2. ACME Inc. removes John Doe from their Okta directory. 3. Okta send a SCIM `DELETE /Users/john.doe` request to a pre-registered SCIM service provider (your B2B application) as per the SCIM protocol. 4. You authenticate the request using the OAuth 2.0 bearer token authentication & validate the request payload. 5. You deactivate John Doe as an existing user in your B2B application using the user payload. ### Scenario: Employee transfer [Section titled “Scenario: Employee transfer”](#scenario-employee-transfer) 1. ACME Inc. transfers John Doe to a different department. 2. ACME Inc. updates John Doe’s information in their Okta directory. 3. Okta send a SCIM `PATCH /Users/john.doe` request to a pre-registered SCIM service provider (your B2B application) as per the SCIM protocol. 4. You authenticate the request using the OAuth 2.0 bearer token authentication & validate the request payload. 5. You update John Doe’s information in your B2B application using the user payload. SCIM create user request ```http 1 POST /Users HTTP/1.1 2 Host: yourapp.scalekit.com/directory/dir_12442/scim/v2 3 Accept: application/scim+json 4 Content-Type: application/scim+json 5 Authorization: Bearer YOUR_SCIM_API_TOKEN 6 7 { 8 "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"], 9 "userName":"bjensen", 10 "externalId":"bjensen", 11 "name":{ 12 "formatted":"Ms. Barbara J Jensen III", 13 "familyName":"Jensen", 14 "givenName":"Barbara" 15 } 16 } ``` ## Scalekit’s SCIM implementation [Section titled “Scalekit’s SCIM implementation”](#scalekits-scim-implementation) Scalekit’s SCIM implementation is built upon the principles of simplicity, security, and scalability. It provides a normalized implementation of the SCIM protocol across different identity providers & directory providers. This allows you to focus on integrating with Scalekit’s API & leave the complexities of SCIM protocol implementation to us. While not all directory providers implement SCIM or support all SCIM features, Scalekit aims to abstract these complexities & provide a seamless experience for provisioning users and groups. ### Webhooks [Section titled “Webhooks”](#webhooks) Scalekit supports webhooks as a mechanism to send real-time updates to your application about user provisioning and deprovisioning events to your application as and when there are changes detected in your customer’s SCIM compliant directory providers. We also normalize the webhook payloads across different directory providers to ensure that you can focus on building your application without having to worry about the nuances of each directory provider’s SCIM implementations. --- # DOCUMENT BOUNDARY --- # Understanding SCIM Provisioning > The business case for implementing SCIM Scaling organizations utilize a growing array of applications to support their employees’ productivity. To efficiently and securely manage access to these applications, organization administrators employ Directory Providers. These providers automate crucial workflows, such as granting access to new employees or revoking access for departing staff. Directory providers, like Entra ID (formerly Azure Active Directory), serve as the authoritative source for user information and access rights. Organizations expect your application to accommodate their directory provider requirements. Consequently, you must design systems capable of interfacing with various directory providers used by their customers. Scalekit serves as an intermediary component in your B2B application architecture, providing a streamlined interface to access user information programmatically and in real-time.  This solution allows your application to: 1. Automatically determine user roles (e.g., admin, member) 2. Retrieve user access permissions 3. Tailor the user experience accordingly and securely By integrating Scalekit, you can meet enterprise requirements without diverting focus from your core product development. This approach significantly reduces the engineering effort and time typically required to implement compatibility with various directory providers. Explore the compelling reasons to implement SCIM Provisioning in your B2B SaaS app: Implementing SCIM allows you to offer a more attractive, enterprise-grade solution. ## Next steps [Section titled “Next steps”](#next-steps) Now that you understand the importance of directories and how implementing SCIM Provisioning can step up your app to enterprise-grade status, it’s time to put this knowledge into action. Here are some suggested next steps: 1. Dive into our [Quickstart](/directory/scim/quickstart/) guide to learn how to set up SCIM Provisioning for your app. This practical guide will walk you through the implementation process step-by-step. 2. Start small by simulating directory events. This hands-on approach allows you to test and familiarize yourself with the system without affecting live data. 3. Explore our sample apps to picture all the moving components in a typical app. --- # DOCUMENT BOUNDARY --- # Directory events > Explore webhook events related to directory operations in Scalekit, including user and group creation, updates, and deletions. This page documents the webhook events related to directory operations in Scalekit. ## Table of contents * [Directory connection events](#directory-connection-events) * [`organization.directory_enabled`](#organizationdirectory_enabled) * [`organization.directory_disabled`](#organizationdirectory_disabled) * [Directory User Events](#directory-user-events) * [`organization.directory.user_created`](#organizationdirectoryuser_created) * [`organization.directory.user_updated`](#organizationdirectoryuser_updated) * [`organization.directory.user_deleted`](#organizationdirectoryuser_deleted) * [Directory Group Events](#directory-group-events) * [`organization.directory.group_created`](#organizationdirectorygroup_created) * [`organization.directory.group_updated`](#organizationdirectorygroup_updated) * [`organization.directory.group_deleted`](#organizationdirectorygroup_deleted) *** ## Directory connection events ### `organization.directory_enabled` This webhook is triggered when a directory sync is enabled. The event type is `organization.directory_enabled` organization.directory\_enabled ```json 1 { 2 "environment_id": "env_27758032200925221", 3 "id": "evt_55136848686613000", 4 "object": "Directory", 5 "occurred_at": "2025-01-15T08:55:22.802860294Z", 6 "organization_id": "org_55135410258444802", 7 "spec_version": "1", 8 "type": "organization.directory_enabled", 9 "data": { 10 "directory_type": "SCIM", 11 "enabled": false, 12 "id": "dir_55135622825771522", 13 "organization_id": "org_55135410258444802", 14 "provider": "OKTA", 15 "updated_at": "2025-01-15T08:55:22.792993454Z" 16 } 17 } ``` | Field | Type | Description | | ----------------- | ------- | ------------------------------------------------------------- | | `id` | string | Unique identifier for the directory connection | | `directory_type` | string | The type of directory synchronization | | `enabled` | boolean | Indicates if the directory sync is enabled | | `environment_id` | string | Identifier for the environment | | `last_sync_at` | null | Timestamp of the last synchronization, null if not yet synced | | `organization_id` | string | Identifier for the organization | | `provider` | string | The provider of the directory | | `updated_at` | string | Timestamp of when the configuration was last updated | | `occurred_at` | string | Timestamp of when the event occurred | ### `organization.directory_disabled` This webhook is triggered when a directory sync is disabled. The event type is `organization.directory_disabled` organization.directory\_disabled ```json 1 { 2 "spec_version": "1", 3 "id": "evt_53891640779079756", 4 "type": "organization.directory_disabled", 5 "occurred_at": "2025-01-06T18:45:21.057814Z", 6 "environment_id": "env_53814739859406915", 7 "organization_id": "org_53879494091473415", 8 "object": "Directory", 9 "data": { 10 "directory_type": "SCIM", 11 "enabled": false, 12 "id": "dir_53879621145330183", 13 "organization_id": "org_53879494091473415", 14 "provider": "OKTA", 15 "updated_at": "2025-01-06T18:45:21.04978184Z" 16 } 17 } ``` | Field | Type | Description | | ----------------- | ------- | -------------------------------------------------------------------------------- | | `directory_type` | string | Type of directory protocol used for synchronization | | `enabled` | boolean | Indicates whether the directory synchronization is currently enabled or disabled | | `id` | string | Unique identifier for the directory connection | | `last_sync_at` | string | Timestamp of the most recent directory synchronization | | `organization_id` | string | Unique identifier of the organization associated with this directory | | `provider` | string | Identity provider for the directory connection | | `status` | string | Current status of the directory synchronization process | | `updated_at` | string | Timestamp of the most recent update to the directory connection | | `occurred_at` | string | Timestamp of when the event occurred | ## Directory User Events ### `organization.directory.user_created` This webhook is triggered when a new directory user is created. The event type is `organization.directory.user_created` organization.directory.user\_created ```json 1 { 2 "spec_version": "1", 3 "id": "evt_53891546994442316", 4 "type": "organization.directory.user_created", 5 "occurred_at": "2025-01-06T18:44:25.153954Z", 6 "environment_id": "env_53814739859406915", 7 "organization_id": "org_53879494091473415", 8 "object": "DirectoryUser", 9 "data": { 10 "active": true, 11 "cost_center": "QAUZJUHSTYCN", 12 "custom_attributes": { 13 "mobile_phone_number": "1-579-4072" 14 }, 15 "department": "HNXJPGISMIFN", 16 "division": "MJFUEYJOKICN", 17 "dp_id": "", 18 "email": "flavio@runolfsdottir.co.duk", 19 "employee_id": "AWNEDTILGaIZN", 20 "family_name": "Jaquelin", 21 "given_name": "Dayton", 22 "groups": [ 23 { 24 "id": "dirgroup_12312312312312", 25 "name": "Group Name" 26 } 27 ], 28 "id": "diruser_53891546960887884", 29 "language": "se", 30 "locale": "LLWLEWESPLDC", 31 "name": "QURGUZZDYMFU", 32 "nickname": "DTUODYKGFPPC", 33 "organization": "AUIITQVUQGVH", 34 "organization_id": "org_53879494091473415", 35 "phone_number": "1-579-4072", 36 "preferred_username": "kuntala1233a", 37 "profile": "YMIUQUHKGVAX", 38 "raw_attributes": {}, 39 "title": "FKQBHCWJXZSC", 40 "user_type": "RBQFJSQEFAEH", 41 "zoneinfo": "America/Araguaina", 42 "roles": [ 43 { 44 "role_name": "billing_admin" 45 } 46 ] 47 } 48 } ``` | Field | Type | Description | | -------------------- | ------- | ---------------------------------------------------------------------------------- | | `id` | string | Unique ID of the Directory User | | `organization_id` | string | Unique ID of the Organization to which this directory user belongs | | `dp_id` | string | Unique ID of the User in the Directory Provider (IdP) system | | `preferred_username` | string | Preferred username of the directory user | | `email` | string | Email of the directory user | | `active` | boolean | Indicates if the directory user is active | | `name` | string | Fully formatted name of the directory user | | `roles` | array | Array of roles assigned to the directory user | | `groups` | array | Array of groups to which the directory user belongs | | `given_name` | string | Given name of the directory user | | `family_name` | string | Family name of the directory user | | `nickname` | string | Nickname of the directory user | | `picture` | string | URL of the directory user’s profile picture | | `phone_number` | string | Phone number of the directory user | | `address` | object | Address of the directory user | | `custom_attributes` | object | Custom attributes of the directory user | | `raw_attributes` | object | Raw attributes of the directory user as received from the Directory Provider (IdP) | ### `organization.directory.user_updated` This webhook is triggered when a directory user is updated. The event type is `organization.directory.user_updated` organization.directory.user\_updated ```json 1 { 2 "spec_version": "1", 3 "id": "evt_53891546994442316", 4 "type": "organization.directory.user_updated", 5 "occurred_at": "2025-01-06T18:44:25.153954Z", 6 "environment_id": "env_53814739859406915", 7 "organization_id": "org_53879494091473415", 8 "object": "DirectoryUser", 9 "data": { 10 "id": "diruser_12312312312312", 11 "organization_id": "org_53879494091473415", 12 "dp_id": "", 13 "preferred_username": "", 14 "email": "john.doe@example.com", 15 "active": true, 16 "name": "John Doe", 17 "roles": [ 18 { 19 "role_name": "billing_admin" 20 } 21 ], 22 "groups": [ 23 { 24 "id": "dirgroup_12312312312312", 25 "name": "Group Name" 26 } 27 ], 28 "given_name": "John", 29 "family_name": "Doe", 30 "nickname": "Jhonny boy", 31 "picture": "https://image.com/profile.jpg", 32 "phone_number": "1234567892", 33 "address": { 34 "postal_code": "64112", 35 "state": "Missouri", 36 "formatted": "123, Oxford Lane, Kansas City, Missouri, 64112" 37 }, 38 "custom_attributes": { 39 "attribute1": "value1", 40 "attribute2": "value2" 41 }, 42 "raw_attributes": {} 43 } 44 } ``` | Field | Type | Description | | -------------------- | ------- | ---------------------------------------------------------------------------------- | | `id` | string | Unique ID of the Directory User | | `organization_id` | string | Unique ID of the Organization to which this directory user belongs | | `dp_id` | string | Unique ID of the User in the Directory Provider (IdP) system | | `preferred_username` | string | Preferred username of the directory user | | `email` | string | Email of the directory user | | `active` | boolean | Indicates if the directory user is active | | `name` | string | Fully formatted name of the directory user | | `roles` | array | Array of roles assigned to the directory user | | `groups` | array | Array of groups to which the directory user belongs | | `given_name` | string | Given name of the directory user | | `family_name` | string | Family name of the directory user | | `nickname` | string | Nickname of the directory user | | `picture` | string | URL of the directory user’s profile picture | | `phone_number` | string | Phone number of the directory user | | `address` | object | Address of the directory user | | `custom_attributes` | object | Custom attributes of the directory user | | `raw_attributes` | object | Raw attributes of the directory user as received from the Directory Provider (IdP) | #### `organization.directory.user_deleted` This webhook is triggered when a directory user is deleted. The event type is `organization.directory.user_deleted` organization.directory.user\_deleted ```json 1 { 2 "spec_version": "1", 3 "id": "evt_53891546994442316", 4 "type": "organization.directory.user_deleted", 5 "occurred_at": "2025-01-06T18:44:25.153954Z", 6 "environment_id": "env_53814739859406915", 7 "organization_id": "org_53879494091473415", 8 "object": "DirectoryUser", 9 "data": { 10 "id": "diruser_12312312312312", 11 "organization_id": "org_12312312312312", 12 "dp_id": "", 13 "email": "john.doe@example.com" 14 } 15 } ``` | Field | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------ | | `id` | string | Unique ID of the Directory User | | `organization_id` | string | Unique ID of the Organization to which this directory user belongs | | `dp_id` | string | Unique ID of the User in the Directory Provider (IdP) system | | `email` | string | Email of the directory user | ## Directory Group Events ### `organization.directory.group_created` This webhook is triggered when a new directory group is created. The event type is `organization.directory.group_created` organization.directory.group\_created ```json 1 { 2 "spec_version": "1", 3 "id": "evt_38862741515010639", 4 "environment_id": "env_32080745237316098", 5 "object": "DirectoryGroup", 6 "occurred_at": "2024-09-25T02:26:39.036398577Z", 7 "organization_id": "org_38609339635728478", 8 "type": "organization.directory.group_created", 9 "data": { 10 "directory_id": "dir_38610496391217780", 11 "display_name": "Avengers", 12 "external_id": null, 13 "id": "dirgroup_38862741498233423", 14 "organization_id": "org_38609339635728478", 15 "raw_attributes": {} 16 } 17 } ``` | Field | Type | Description | | ----------------- | ------ | --------------------------------------------------------- | | `directory_id` | string | Unique identifier for the directory | | `display_name` | string | Display name of the directory group | | `external_id` | null | External identifier for the group, null if not specified | | `id` | string | Unique identifier for the directory group | | `organization_id` | string | Identifier for the organization associated with the group | | `raw_attributes` | object | Raw attributes of the directory provider | ### `organization.directory.group_updated` This webhook is triggered when a directory group is updated. The event type is `organization.directory.group_updated` organization.directory.group\_updated ```json 1 { 2 "spec_version": "1", 3 "id": "evt_38864948910162368", 4 "organization_id": "org_38609339635728478", 5 "type": "organization.directory.group_updated", 6 "environment_id": "env_32080745237316098", 7 "object": "DirectoryGroup", 8 "occurred_at": "2024-09-25T02:48:34.745030921Z", 9 "data": { 10 "directory_id": "dir_38610496391217780", 11 "display_name": "Avengers", 12 "external_id": "", 13 "id": "dirgroup_38862741498233423", 14 "organization_id": "org_38609339635728478", 15 "raw_attributes": {} 16 } 17 } ``` | Field | Type | Description | | ----------------- | ------ | --------------------------------------------------------- | | `directory_id` | string | Unique identifier for the directory | | `display_name` | string | Display name of the directory group | | `external_id` | null | External identifier for the group, null if not specified | | `id` | string | Unique identifier for the directory group | | `organization_id` | string | Identifier for the organization associated with the group | | `raw_attributes` | object | Raw attributes of the directory group | ### `organization.directory.group_deleted` This webhook is triggered when a directory group is deleted. The event type is `organization.directory.group_deleted` organization.directory.group\_deleted ```json 1 { 2 "spec_version": "1", 3 "id": "evt_40650399597723966", 4 "environment_id": "env_12205603854221623", 5 "object": "DirectoryGroup", 6 "occurred_at": "2024-10-07T10:25:26.289331747Z", 7 "organization_id": "org_39802449573184223", 8 "type": "organization.directory.group_deleted", 9 "data": { 10 "directory_id": "dir_39802485862301855", 11 "display_name": "Admins", 12 "dp_id": "7c66a173-79c6-4270-ac78-8f35a8121e0a", 13 "id": "dirgroup_40072007005503806", 14 "organization_id": "org_39802449573184223", 15 "raw_attributes": {} 16 } 17 } ``` | Field | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------- | | `directory_id` | string | Unique identifier for the directory | | `display_name` | string | Display name of the directory group | | `dp_id` | string | Unique identifier for the group in the directory provider system | | `id` | string | Unique identifier for the directory group | | `organization_id` | string | Identifier for the organization associated with the group | | `raw_attributes` | object | Raw attributes of the directory group as received from the provider | --- # DOCUMENT BOUNDARY --- # Ways to implement SSO logins > Implement single sign-on on your login page using three UX strategies: identifier-driven, SSO button, or organization-specific pages. Single sign-on (SSO) login requires careful UX design to balance enterprise authentication requirements with user experience. Your login page must accommodate both SSO users (who authenticate through their organization’s identity provider) and non-SSO users (who use passwords or social authentication). This guide presents three proven UX strategies for adding SSO to your login page. Each strategy offers different trade-offs between user experience, implementation complexity, and administrative control. Choose the approach that best fits your users’ needs and your application’s architecture. The right strategy depends on your user base: identifier-driven flows work best when admins control authentication methods, explicit SSO buttons give users choice, and organization-specific login pages simplify enterprise deployments.  ## Strategy 1: Identifier-driven single sign-on [Section titled “Strategy 1: Identifier-driven single sign-on”](#strategy-1-identifier-driven-single-sign-on) Collect the user’s email address first. Use the email domain or organization identifier to determine whether to route to SSO or password-based authentication.  Users don’t choose the authentication method. This reduces cognitive load and works well when admins mandate SSO after users have already logged in with passwords. Popular products like [Google](https://accounts.google.com), [Microsoft](https://login.microsoftonline.com), and [AWS](https://console.aws.amazon.com/console/) use this strategy. ## Strategy 2: Login with single sign-on button [Section titled “Strategy 2: Login with single sign-on button”](#strategy-2-login-with-single-sign-on-button) Add a “Login with SSO” button to your login page. This presents all authentication options and lets users choose their preferred method.  If a user attempts password login but their admin mandates SSO, force SSO-based authentication instead of showing an error. Popular products like [Cal.com](https://app.cal.com/auth/login) and [Notion](https://www.notion.so/login) use this strategy. ## Strategy 3: organization-specific login page [Section titled “Strategy 3: organization-specific login page”](#strategy-3-organization-specific-login-page) Serve different login pages for each organization instead of a single login page. For example, `https://customer1.b2b-app.com/login` and `https://customer2.b2b-app.com/login`. Show only the authentication methods applicable to that organization based on the URL. Popular products like [Zendesk](https://www.zendesk.com/in/login/) and [Slack](https://scalekit.slack.com/) use this strategy. The drawback is that users must remember their organization URL to access the login page. *** ## Next steps [Section titled “Next steps”](#next-steps) After implementing your chosen SSO login strategy: * [Pre-check SSO by domain](/guides/user-auth/check-sso-domain/) - Validate email domains have active SSO before redirecting * [Complete login with code exchange](/authenticate/fsa/complete-login/) - Exchange authorization codes for user data and tokens * [Manage user sessions](/authenticate/fsa/manage-session/) - Store and validate session tokens securely --- # DOCUMENT BOUNDARY --- # Authorization URL to initiate SSO > Learn how to construct and implement authorization URLs in Scalekit to initiate secure Single Sign-on (SSO) flows with your identity provider. The authorization endpoint is where your application redirects users to begin the authentication process. Scalekit powers this endpoint and handles redirecting users to the appropriate identity provider. Example authorization URL ```sh https://SCALEKIT_ENVIRONMENT_URL/oauth/authorize? response_type=code& client_id=skc_1234& scope=openid%20profile& redirect_uri=https%3A%2F%2Fyoursaas.com%2Fcallback& organization_id=org_1243412& state=aHR0cHM6Ly95b3Vyc2Fhcy5jb20vZGVlcGxpbms%3D ``` ## Parameters [Section titled “Parameters”](#parameters) | Parameter | Requirement | Description | | ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | | `client_id` | Required | Your unique client identifier from the API credentials page | | `nonce` | Optional | Random value for replay protection | | `organization_id` | Required\* | Identifier for the organization initiating SSO | | `connection_id` | Required\* | Identifier for the specific SSO connection | | `domain` | Required\* | Domain portion of email addresses configured for an organization | | `provider` | Required\* | Social login provider name. Supported providers: `google`, `microsoft`, `github`, `gitlab`, `linkedin`, `salesforce` | | `response_type` | Required | Must be set to `code` | | `redirect_uri` | Required | URL where Scalekit sends the response. Must match an authorized redirect URI | | `scope` | Required | Must be set to `openid email profile` | | `state` | Optional | Opaque string for request-response correlation | | `login_hint` | Optional | User’s email address for prefilling the login form | \* You must provide one of `organization_id`, `connection_id`, `domain`, or `provider`. If you identify SSO connection using `domain` or `login_hint`, the domain must be registered to the organization. Register domains in **Dashboard > Organizations > General**, or let customers add them via the admin portal. See [Onboard enterprise customers](/sso/guides/onboard-enterprise-customers/). ## SDK usage [Section titled “SDK usage”](#sdk-usage) Use Scalekit SDKs to generate authorization URLs programmatically. This approach handles parameter encoding and validation automatically. * Node.js ```diff 1 import { ScalekitClient } from '@scalekit-sdk/node'; 2 3 const scalekit = new ScalekitClient( 4 'https://your-subdomain.scalekit.dev', 5 '', 6 '' 7 ); 8 9 const options = { 10 loginHint: 'user@example.com', 11 organizationId: 'org_123235245', 12 }; 13 14 +const authorizationURL = scalekit.getAuthorizationUrl(redirectUri, options); 15 // Example generated URL: 16 // https://your-subdomain.scalekit.dev/oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile&redirect_uri=https%3A%2F%2Fyoursaas.com%2Fcallback&organization_id=org_123235245&login_hint=user%40example.com&state=abc123 ``` * Python ```diff 1 from scalekit import ScalekitClient, AuthorizationUrlOptions 2 3 scalekit = ScalekitClient( 4 'https://your-subdomain.scalekit.dev', 5 '', 6 '' 7 ) 8 9 options = AuthorizationUrlOptions( 10 organization_id="org_12345", 11 login_hint="user@example.com", 12 ) 13 14 +authorization_url = scalekit.get_authorization_url( 15 + redirect_uri, 16 + options 17 +) 18 # Example generated URL: 19 # https://your-subdomain.scalekit.dev/oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile&redirect_uri=https%3A%2F%2Fyoursaas.com%2Fcallback&organization_id=org_12345&login_hint=user%40example.com&state=abc123 ``` * Go ```diff 1 import ( 2 "github.com/scalekit-inc/scalekit-sdk-go" 3 ) 4 5 func main() { 6 scalekitClient := scalekit.NewScalekitClient( 7 "https://your-subdomain.scalekit.dev", 8 "", 9 "" 10 ) 11 12 options := scalekitClient.AuthorizationUrlOptions{ 13 OrganizationId: "org_12345", 14 LoginHint: "user@example.com", 15 } 16 17 +authorizationURL := scalekitClient.GetAuthorizationUrl( 18 +redirectUrl, 19 +options, 20 + ) 21 // Example generated URL: 22 // https://your-subdomain.scalekit.dev/oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile&redirect_uri=https%3A%2F%2Fyoursaas.com%2Fcallback&organization_id=org_12345&login_hint=user%40example.com&state=abc123 23 } ``` * Java ```diff 1 package com.scalekit; 2 3 import com.scalekit.ScalekitClient; 4 import com.scalekit.internal.http.AuthorizationUrlOptions; 5 6 public class Main { 7 public static void main(String[] args) { 8 ScalekitClient scalekitClient = new ScalekitClient( 9 "https://your-subdomain.scalekit.dev", 10 "", 11 "" 12 ); 13 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 14 // Option 1: Authorization URL with the organization ID 15 options.setOrganizationId("org_13388706786312310"); 16 // Option 2: Authorization URL with the connection ID 17 options.setConnectionId("con_13388706786312310"); 18 // Option 3: Authorization URL with login hint 19 options.setLoginHint("user@example.com"); 20 21 try { 22 +String url = scalekitClient.authentication().getAuthorizationUrl(redirectUrl, options).toString(); 23 // Example generated URL: 24 // https://your-subdomain.scalekit.dev/oauth/authorize?response_type=code&client_id=skc_1234&scope=openid%20profile&redirect_uri=https%3A%2F%2Fyoursaas.com%2Fcallback&organization_id=org_13388706786312310&connection_id=con_13388706786312310&login_hint=user%40example.com&state=abc123 25 } catch (Exception e) { 26 System.out.println(e.getMessage()); 27 } 28 } 29 } ``` ## Parameter precedence [Section titled “Parameter precedence”](#parameter-precedence) When you provide multiple connection parameters, Scalekit follows a specific precedence order to determine which identity provider to use: 1. `provider` (highest precedence): If present, Scalekit ignores all other connection parameters and directs users to the specified social login provider. For example, `provider=google` redirects users to Google’s login screen. See [Social Login](/authenticate/auth-methods/social-logins/) for more details. 2. `connection_id`: Takes highest precedence among enterprise SSO parameters. Scalekit uses this specific connection if you provide a valid connection ID. If the connection ID is invalid, the authorization request fails. 3. `organization_id`: Scalekit uses this parameter when no valid `connection_id` is provided. It selects the SSO connection configured for the specified organization. 4. `domain`: Scalekit uses this parameter when neither `connection_id` nor `organization_id` are provided. It selects the SSO connection configured for the specified domain. 5. `login_hint` (lowest precedence): Scalekit extracts the domain portion from the email address and uses the corresponding SSO connection mapped to that organization. The domain must be registered to the organization either manually from the Scalekit Dashboard or through the admin portal when [onboarding an enterprise customer](/sso/guides/onboard-enterprise-customers/). ## Common scenarios [Section titled “Common scenarios”](#common-scenarios) --- # DOCUMENT BOUNDARY --- # Handle identity provider initiated SSO > Learn how to securely implement IdP-initiated Single Sign-On for your application This guide shows you how to securely implement Identity Provider (IdP)-initiated Single Sign-On for your application. When users log into your application directly from their identity provider’s portal, Scalekit converts the IdP-initiated request to a Service Provider (SP)-initiated flow for enhanced security. The workflow converts the traditional IdP-initiated flow to a secure SP-initiated flow by: 1. The user logs into their identity provider portal and selects your application 2. The identity provider sends user details as assertions to Scalekit 3. Scalekit redirects to your initiate login endpoint with a JWT token 4. Your application validates the JWT and generates a new SP-initiated authorization URL To securely implement IdP-initiated SSO, follow these steps to convert incoming IdP-initiated requests to SP-initiated flows: 1. Set up an initiate login endpoint and register it in **Dashboard > Developers > Redirect URLs > Initiate Login URL** 2. Extract information from the JWT token containing organization, connection, and user details 3. Convert to SP-initiated flow using the extracted parameters to generate a new authorization URL 4. Handle errors with proper callback processing and error handling best practices ## Implementation examples [Section titled “Implementation examples”](#implementation-examples) Use the extracted parameters to initiate a new SSO request. This converts the IdP-initiated flow to a secure SP-initiated flow. Here are implementation examples: * Node.js Express.js ```javascript 1 // Security: ALWAYS verify requests are from Scalekit before processing 2 // This prevents unauthorized parties from triggering your interceptor logic 3 4 // Use case: Handle IdP-initiated SSO requests from enterprise customer portals 5 // Examples: Okta dashboard, Azure AD portal, Google Workspace apps 6 7 const express = require('express'); 8 const app = express(); 9 10 app.get('/login', async (req, res) => { 11 try { 12 // Your Initiate Login Endpoint receives a JWT 13 const { error_description, idp_initiated_login } = req.query; 14 15 if (error_description) { 16 return res.redirect('/login?error=auth_failed'); 17 } 18 19 // Decode the JWT and extract claims 20 if (idp_initiated_login) { 21 const { 22 connection_id, 23 organization_id, 24 login_hint, 25 relay_state 26 } = await scalekit.getIdpInitiatedLoginClaims(idp_initiated_login); 27 28 // Use ONE of the following properties for authorization 29 const options = {}; 30 if (connection_id) options.connectionId = connection_id; 31 if (organization_id) options.organizationId = organization_id; 32 if (login_hint) options.loginHint = login_hint; 33 if (relay_state) options.state = relay_state; 34 35 // Generate Authorization URL for SP-initiated flow 36 const url = scalekit.getAuthorizationUrl( 37 process.env.REDIRECT_URI, 38 options 39 ); 40 41 return res.redirect(url); 42 } 43 44 // Handle regular login flow here 45 res.redirect('/login'); 46 } catch (error) { 47 console.error('IdP-initiated login error:', error); 48 res.redirect('/login?error=auth_failed'); 49 } 50 }); ``` * Python Flask ```python 1 # Security: ALWAYS verify requests are from Scalekit before processing 2 # This prevents unauthorized parties from triggering your interceptor logic 3 4 # Use case: Handle IdP-initiated SSO requests from enterprise customer portals 5 # Examples: Okta dashboard, Azure AD portal, Google Workspace apps 6 7 from flask import Flask, request, redirect, url_for 8 import os 9 10 app = Flask(__name__) 11 12 @app.route('/login') 13 def login(): 14 try: 15 # Your Initiate Login Endpoint receives a JWT 16 error_description = request.args.get('error_description') 17 idp_initiated_login = request.args.get('idp_initiated_login') 18 19 if error_description: 20 return redirect(url_for('login', error='auth_failed')) 21 22 # Decode the JWT and extract claims 23 if idp_initiated_login: 24 claims = await scalekit_client.get_idp_initiated_login_claims(idp_initiated_login) 25 26 # Extract claims with fallbacks 27 connection_id = claims.get('connection_id') 28 organization_id = claims.get('organization_id') 29 login_hint = claims.get('login_hint') 30 relay_state = claims.get('relay_state') 31 32 # Create authorization options 33 options = AuthorizationUrlOptions() 34 if connection_id: 35 options.connection_id = connection_id 36 if organization_id: 37 options.organization_id = organization_id 38 if login_hint: 39 options.login_hint = login_hint 40 if relay_state: 41 options.state = relay_state 42 43 # Generate Authorization URL for SP-initiated flow 44 authorization_url = scalekit_client.get_authorization_url( 45 redirect_uri=os.getenv('REDIRECT_URI'), 46 options=options 47 ) 48 49 return redirect(authorization_url) 50 51 # Handle regular login flow here 52 return redirect(url_for('login')) 53 except Exception as error: 54 print(f"IdP-initiated login error: {error}") 55 return redirect(url_for('login', error='auth_failed')) ``` * Go Gin ```go 1 // Security: ALWAYS verify requests are from Scalekit before processing 2 // This prevents unauthorized parties from triggering your interceptor logic 3 4 // Use case: Handle IdP-initiated SSO requests from enterprise customer portals 5 // Examples: Okta dashboard, Azure AD portal, Google Workspace apps 6 7 package main 8 9 import ( 10 "net/http" 11 "github.com/gin-gonic/gin" 12 ) 13 14 func (a *App) handleLogin(c *gin.Context) { 15 // Your Initiate Login Endpoint receives a JWT 16 errDescription := c.Query("error_description") 17 idpInitiatedLogin := c.Query("idp_initiated_login") 18 19 if errDescription != "" { 20 c.Redirect(http.StatusFound, "/login?error=auth_failed") 21 return 22 } 23 24 // Decode the JWT and extract claims 25 if idpInitiatedLogin != "" { 26 claims, err := scalekitClient.GetIdpInitiatedLoginClaims(c.Request.Context(), idpInitiatedLogin) 27 if err != nil { 28 http.Error(c.Writer, err.Error(), http.StatusInternalServerError) 29 return 30 } 31 32 // Create authorization options with ONE of the following properties 33 options := scalekit.AuthorizationUrlOptions{} 34 if claims.ConnectionID != "" { 35 options.ConnectionId = claims.ConnectionID 36 } 37 if claims.OrganizationID != "" { 38 options.OrganizationId = claims.OrganizationID 39 } 40 if claims.LoginHint != "" { 41 options.LoginHint = claims.LoginHint 42 } 43 if claims.RelayState != "" { 44 options.State = claims.RelayState 45 } 46 47 // Generate Authorization URL for SP-initiated flow 48 authUrl, err := scalekitClient.GetAuthorizationUrl(redirectUrl, options) 49 if err != nil { 50 http.Error(c.Writer, err.Error(), http.StatusInternalServerError) 51 return 52 } 53 54 c.Redirect(http.StatusFound, authUrl.String()) 55 return 56 } 57 58 // Handle regular login flow here 59 c.Redirect(http.StatusFound, "/login") 60 } ``` * Java Spring Boot ```java 1 // Security: ALWAYS verify requests are from Scalekit before processing 2 // This prevents unauthorized parties from triggering your interceptor logic 3 4 // Use case: Handle IdP-initiated SSO requests from enterprise customer portals 5 // Examples: Okta dashboard, Azure AD portal, Google Workspace apps 6 7 import org.springframework.web.bind.annotation.*; 8 import org.springframework.web.servlet.view.RedirectView; 9 import javax.servlet.http.HttpServletResponse; 10 11 @RestController 12 public class AuthController { 13 14 @GetMapping("/login") 15 public RedirectView handleLogin( 16 @RequestParam(required = false, name = "error_description") String errorDescription, 17 @RequestParam(required = false, name = "idp_initiated_login") String idpInitiatedLoginToken, 18 HttpServletResponse response) throws IOException { 19 20 if (errorDescription != null) { 21 return new RedirectView("/login?error=auth_failed"); 22 } 23 24 // Decode the JWT and extract claims 25 if (idpInitiatedLoginToken != null) { 26 IdpInitiatedLoginClaims claims = scalekitClient.authentication() 27 .getIdpInitiatedLoginClaims(idpInitiatedLoginToken); 28 29 if (claims == null) { 30 response.sendError(HttpStatus.BAD_REQUEST.value(), 31 "Invalid idp_initiated_login token"); 32 return null; 33 } 34 35 // Create authorization options with ONE of the following 36 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 37 if (claims.getConnectionID() != null) { 38 options.setConnectionId(claims.getConnectionID()); 39 } 40 if (claims.getOrganizationID() != null) { 41 options.setOrganizationId(claims.getOrganizationID()); 42 } 43 if (claims.getLoginHint() != null) { 44 options.setLoginHint(claims.getLoginHint()); 45 } 46 if (claims.getRelayState() != null) { 47 options.setState(claims.getRelayState()); 48 } 49 50 // Generate Authorization URL for SP-initiated flow 51 String url = scalekitClient.authentication() 52 .getAuthorizationUrl(redirectUrl, options) 53 .toString(); 54 55 response.sendRedirect(url); 56 return null; 57 } 58 59 // Handle regular login flow here 60 return new RedirectView("/login"); 61 } 62 } ``` ## Implementation details [Section titled “Implementation details”](#implementation-details) ### Endpoint setup [Section titled “Endpoint setup”](#endpoint-setup) Your initiate login endpoint will receive requests with the following format: ```sh https://yourapp.com/login?idp_initiated_login= ``` ### JWT token structure [Section titled “JWT token structure”](#jwt-token-structure) The `idp_initiated_login` parameter contains a signed JWT with organization, connection, and user details. ### Error callback format [Section titled “Error callback format”](#error-callback-format) If errors occur, the redirect URI will receive a callback with this format: ```sh https://{your-subdomain}.scalekit.dev/callback ?error="" &error_description="

" ``` After completing the SP-initiated flow, users are redirected back to your callback URL where you can complete the authentication process. Next, let’s look at how to test your IdP-initiated SSO implementation. ## Integrating with a downstream auth provider [Section titled “Integrating with a downstream auth provider”](#integrating-with-a-downstream-auth-provider) If your application uses a third-party service like [Firebase Authentication](/guides/integrations/auth-systems/firebase/) to manage user sessions, you must initiate its sign-in flow after completing **Step 3**. This process has two stages: first, the IdP redirects the user to your app via Scalekit, and second, your app triggers a new sign-in flow with Firebase using the Authorization URL you just generated. The example below shows how to pass the Authorization URL to the Firebase Web SDK. * Firebase (Web SDK) Firebase Web SDK ```javascript 1 import { getAuth, OAuthProvider, signInWithRedirect } from "firebase/auth"; 2 3 // Security: Configure OIDC provider properly to prevent token injection 4 const auth = getAuth(); 5 6 // "scalekit" is the OIDC provider you configured in Firebase 7 const scalekitProvider = new OAuthProvider("scalekit"); 8 9 // Use the authorizationUrl generated in Step 3 10 scalekitProvider.setCustomParameters({ 11 connection_id: "", // Enables Firebase to forward the connection ID to Scalekit 12 }); 13 14 // Initiate Firebase sign-in with Scalekit provider 15 signInWithRedirect(auth, scalekitProvider); ``` ## Security considerations [Section titled “Security considerations”](#security-considerations) While IdP-initiated SSO offers convenience, it comes with significant security risks. Scalekit’s approach converts the flow to SP-initiated to mitigate these vulnerabilities. ### Traditional IdP-initiated SSO security risks [Section titled “Traditional IdP-initiated SSO security risks”](#traditional-idp-initiated-sso-security-risks) **Stolen SAML assertions**: Attackers can steal SAML assertions and use them to gain unauthorized access. If an attacker manages to steal these assertions, they can: * Inject them into another service provider, gaining access to that user’s account * Inject them back into your application with altered assertions, potentially elevating their privileges With a stolen SAML assertion, an attacker can gain access to your application as the compromised user, bypassing the usual authentication process. ### How attackers steal SAML assertions [Section titled “How attackers steal SAML assertions”](#how-attackers-steal-saml-assertions) Attackers can steal SAML assertions through various methods: * **Man-in-the-middle (MITM) attacks**: Intercepting and replacing the SAML response during transmission * **Open redirect attacks**: Exploiting improper endpoint validation to redirect the SAML response to a malicious server * **Leaky logs and headers**: Sensitive information, including SAML assertions, can be leaked through logs or headers * **Browser-based attacks**: Exploiting browser vulnerabilities to steal SAML assertions ### The challenge for service providers [Section titled “The challenge for service providers”](#the-challenge-for-service-providers) The chief problem with stolen assertions is that everything appears legitimate to the service provider (your application). The message and assertion are valid, issued by the expected identity provider, and signed with the expected key. However, the service provider cannot verify whether the assertions are stolen or not. If you encounter issues implementing IdP-initiated SSO: 1. **Verify configuration**: Ensure your redirect URI is properly configured in **Dashboard > Developers > Redirect URLs** 2. **Check JWT processing**: Verify you’re correctly processing the JWT token from the `idp_initiated_login` parameter 3. **Validate error handling**: Ensure your error handling properly captures and processes any error messages 4. **Test connections**: Confirm the organization and connection IDs in the JWT are valid and active 5. **Review logs**: Check both your application logs and Scalekit dashboard logs for debugging information Common issues The most frequent issue is mismatched redirect URLs between your code and the Scalekit dashboard configuration. Ensure URLs match exactly, including protocol (http/https) and trailing slashes. --- # DOCUMENT BOUNDARY --- # Production readiness checklist > A focused checklist for launching your Scalekit SSO integration, based on the core enterprise authentication launch checks. As you prepare to launch enterprise SSO to production, you should confirm that your configuration satisfies the core enterprise checks from the authentication launch checklist. This page extracts the SSO-specific items from the main authentication [production readiness checklist](/authenticate/launch-checklist/) and organizes them for your SSO rollout. Use this checklist alongside the main launch checklist to validate that your SSO flows, admin experience, and network access are ready for enterprise customers. **Verify production environment configuration** Confirm that your environment URL (`SCALEKIT_ENVIRONMENT_URL`), client ID (`SCALEKIT_CLIENT_ID`), and client secret (`SCALEKIT_CLIENT_SECRET`) are correctly configured for your production environment and match your production Scalekit dashboard settings. **Verify SSO integrations with identity providers** Test SSO integrations with your target identity providers (for example, Okta, Azure AD, Google Workspace) using your production environment URL and credentials. **Configure SSO attribute mapping and identifiers** Configure SSO user attribute mapping (email, name, groups) and ensure you use consistent user identifiers (for example, email or `userPrincipalName`) across all SSO connections. **Verify redirect URIs and state validation** Confirm that your redirect URIs are correctly configured in both Scalekit and your identity providers, and that you validate the `state` parameter in callbacks to prevent CSRF attacks. **Test SP-initiated and IdP-initiated SSO flows** Test both SP-initiated and IdP-initiated SSO flows end-to-end in a staging environment before enabling them for production tenants. See [test SSO flows](/sso/guides/test-sso) for detailed scenarios. **Finalize admin portal setup and branding** Configure the self-service admin portal, apply your branding (logo, accent colors), and verify that enterprise admins can manage SSO connections and users as expected. **Review admin portal URL and DNS** Customize the admin portal URL to match your domain (for example, `https://sso.b2b-app.com`), update your `.env` configuration after CNAME setup, and confirm that your customers can access the portal from their networks. **Verify customer network and firewall access** Ask your enterprise customers to whitelist your Scalekit environment domain and related endpoints so SSO redirects and admin portal access work behind their VPNs and firewalls. **Harden error handling and monitoring for SSO** Test SSO error scenarios (for example, misconfigured connections, invalid assertions, and deactivated users), and set up logging and alerts so you can quickly detect and remediate SSO issues. --- # DOCUMENT BOUNDARY --- # Onboard enterprise customers > Complete workflow for enabling enterprise SSO and self-serve configuration for your customers Enterprise SSO enables users to authenticate to your application using their organization’s identity provider (IdP) such as Okta, Microsoft Entra ID, or Google Workspace. This provides enterprise customers with a secure, centralized authentication experience while reducing password management overhead.  This guide walks you through the complete workflow for onboarding enterprise customers with SSO. You’ll learn how to create organizations, provide admin portal access, enable domain-based SSO, and verify the integration. Before onboarding enterprise customers, ensure you have completed the [Full Stack Auth quickstart](/authenticate/fsa/quickstart/) to set up basic authentication in your application. ## Table of contents * [Create organization](#create-organization) * [Provide admin portal access](#provide-admin-portal-access) * [Customer configures SSO](#customer-configures-sso) * [Verify domain ownership](#verify-domain-ownership) 1. ## Create organization Create an organization in Scalekit to represent your enterprise customer: * Log in to the [Scalekit dashboard](https://app.scalekit.com) * Navigate to **Dashboard > Organizations** * Click **Create Organization** * Enter the organization name and relevant details * Save the organization Each organization in Scalekit represents one of your enterprise customers and can have its own SSO configuration, directory sync settings, and domain associations. 2. ## Provide admin portal access Give your customer’s IT administrator access to the self-serve admin portal to configure their identity provider. Scalekit provides two integration methods: **Option 1: Share a no-code link** Quick setup Generate and share a link to the admin portal: * Select the organization from **Dashboard > Organizations** * Click **Generate link** in the organization overview * Share the link with your customer’s IT admin via email, Slack, or your preferred channel The link remains valid for 7 days and can be revoked anytime from the dashboard. **Link properties:** | Property | Details | | -------------- | ------------------------------------------------------------------------------- | | **Expiration** | Links expire after 7 days | | **Revocation** | Revoke links anytime from the dashboard | | **Sharing** | Share via email, Slack, or any preferred channel | | **Security** | Anyone with the link can view and update the organization’s connection settings | The generated link follows this format: Portal link example ```http https://your-app.scalekit.dev/magicLink/2cbe56de-eec4-41d2-abed-90a5b82286c4_p ``` Security consideration Treat portal links as sensitive credentials. Anyone with the link can view and modify the organization’s SSO and SCIM configuration. **Option 2: Embed the portal** Seamless experience Embed the admin portal directly in your application so customers can configure SSO without leaving your interface. The portal link must be generated programmatically on each page load for security. Each generated link is single-use and expires after 1 minute, though once loaded, the session remains active for up to 6 hours. * Node.js ```bash npm install @scalekit-sdk/node ``` * Python ```sh pip install scalekit-sdk-python ``` * Go ```sh go get -u github.com/scalekit-inc/scalekit-sdk-go ``` * Java ```groovy /* Gradle users - add the following to your dependencies in build file */ implementation "com.scalekit:scalekit-sdk-java:2.0.11" ``` ```xml com.scalekit scalekit-sdk-java 2.0.11 ``` ### Generate portal link Use the Scalekit SDK to generate a unique, embeddable admin portal link for an organization. Call this API endpoint each time you render the page containing the iframe: * Node.js Express.js ```javascript 1 import { Scalekit } from '@scalekit-sdk/node'; 2 3 const scalekit = new Scalekit( 4 process.env.SCALEKIT_ENVIRONMENT_URL, 5 process.env.SCALEKIT_CLIENT_ID, 6 process.env.SCALEKIT_CLIENT_SECRET, 7 ); 8 9 async function generatePortalLink(organizationId) { 10 const link = await scalekit.organization.generatePortalLink(organizationId); 11 return link.location; // Use as iframe src 12 } ``` * Python Flask ```python 1 from scalekit import Scalekit 2 import os 3 4 scalekit_client = Scalekit( 5 environment_url=os.environ.get("SCALEKIT_ENVIRONMENT_URL"), 6 client_id=os.environ.get("SCALEKIT_CLIENT_ID"), 7 client_secret=os.environ.get("SCALEKIT_CLIENT_SECRET") 8 ) 9 10 def generate_portal_link(organization_id): 11 link = scalekit_client.organization.generate_portal_link(organization_id) 12 return link.location # Use as iframe src ``` * Go Gin ```go 1 import ( 2 "context" 3 "os" 4 5 "github.com/scalekit/sdk-go" 6 ) 7 8 scalekitClient := scalekit.New( 9 os.Getenv("SCALEKIT_ENVIRONMENT_URL"), 10 os.Getenv("SCALEKIT_CLIENT_ID"), 11 os.Getenv("SCALEKIT_CLIENT_SECRET"), 12 ) 13 14 func generatePortalLink(organizationID string) (string, error) { 15 ctx := context.Background() 16 link, err := scalekitClient.Organization().GeneratePortalLink(ctx, organizationID) 17 if err != nil { 18 return "", err 19 } 20 return link.Location, nil // Use as iframe src 21 } ``` * Java Spring Boot ```java 1 import com.scalekit.client.Scalekit; 2 import com.scalekit.client.models.Link; 3 import com.scalekit.client.models.Feature; 4 import java.util.Arrays; 5 6 Scalekit scalekitClient = new Scalekit( 7 System.getenv("SCALEKIT_ENVIRONMENT_URL"), 8 System.getenv("SCALEKIT_CLIENT_ID"), 9 System.getenv("SCALEKIT_CLIENT_SECRET") 10 ); 11 12 public String generatePortalLink(String organizationId) { 13 Link portalLink = scalekitClient.organizations() 14 .generatePortalLink(organizationId, Arrays.asList(Feature.sso, Feature.dir_sync)); 15 return portalLink.getLocation(); // Use as iframe src 16 } ``` The API returns a JSON object with the portal link. Use the `location` property as the iframe `src`: API response ```json { "id": "8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "location": "https://random-subdomain.scalekit.dev/magicLink/8930509d-68cf-4e2c-8c6d-94d2b5e2db43", "expireTime": "2024-10-03T13:35:50.563013Z" } ``` Embed portal in iframe ```html ``` Embed the portal in your application’s settings or admin section where customers manage authentication configuration. Listen for UI events from the embedded portal to respond to configuration changes, such as when SSO is enabled or the session expires. See the [Admin portal UI events reference](/reference/admin-portal/ui-events/) for details on handling these events. ### Configuration and session | Setting | Requirement | | --------------------- | ----------------------------------------------------------------------------- | | **Redirect URI** | Add your application domain at **Dashboard > Developers > API Configuration** | | **iframe attributes** | Include `allow="clipboard-write"` for copy-paste functionality | | **Dimensions** | Minimum recommended height: 600px | | **Link expiration** | Generated links expire after 1 minute if not loaded | | **Session duration** | Portal session remains active for up to 6 hours once loaded | | **Single-use** | Each generated link can only be used once to initialize a session | 3. ## Customer configures SSO After receiving admin portal access, your customer’s IT administrator: * Opens the admin portal (via shared link or embedded iframe) * Selects their identity provider (Okta, Microsoft Entra ID, Google Workspace, etc.) * Follows the provider-specific setup guide * Enters the required configuration (metadata URL, certificates, etc.) * Tests the connection * Activates the SSO connection Once configured, the SSO connection appears as active in your organization’s settings:  4. ## Verify domain ownership After SSO is configured, verify the organization’s email domains to enable automatic SSO routing. When domains are verified, users with matching email addresses are automatically redirected to their organization’s SSO login. **Verification methods:** * **DNS verification** Coming soon: Organization admins add a DNS TXT record to prove domain ownership through the admin portal * **Manual verification**: Request domain verification through the Scalekit dashboard when domain ownership is already established To manually verify a domain: * Navigate to **Dashboard > Organizations** and select the organization * Go to **Overview > Organization Domains** * Add the domain (e.g., `megacorp.com`) through the dashboard Once verified, users with email addresses from that domain (e.g., `user@megacorp.com`) can authenticate using their organization’s SSO.  ## Customize the admin portal Match the admin portal to your brand identity. Configure branding at **Dashboard > Settings > Branding**: | Option | Description | | ---------------- | --------------------------------------------------------- | | **Logo** | Upload your company logo (displayed in the portal header) | | **Accent color** | Set the primary color to match your brand palette | | **Favicon** | Provide a custom favicon for browser tabs | For additional customization options including custom domains, see the [Custom domain guide](/guides/custom-domain/). ## 5. Test the integration [Section titled “5. Test the integration”](#5-test-the-integration) Before rolling out SSO to your customers, thoroughly test the integration: * **Use the IdP Simulator** during development to test without configuring real identity providers * **Test with real providers** like Okta or Microsoft Entra ID in your staging environment * **Validate all scenarios**: SP-initiated SSO, IdP-initiated SSO, and error handling For complete testing instructions, see the [Test SSO integration guide](/sso/guides/test-sso/). --- # DOCUMENT BOUNDARY --- # Introduction to Single Sign-on > Learn to basics of Single Sign-On (SSO), including how SAML and OIDC protocols work, and how Scalekit simplifies enterprise authentication. Single Sign-On (SSO) streamlines user access by enabling a single authentication event to grant access to multiple applications with the same credentials. For example, logging into one Google service, such as Gmail, automatically authenticates you to YouTube, Google Drive, and other Google platforms. There are two key benefits to the users and organizations with a secure single sign-on implementation: 1. User can seamlessly access multiple applications using only one set of credentials. 2. User credentials are managed in a centralized identity system. This enables Admins to easily configure and manage authentication policies for all their users from the centralized identity provider. Furthermore, this integrated SSO mechanism enhances user convenience, boosts productivity, and reduces the risks associated with password fatigue and reuse. These security & administration benefits are driving factors for enterprise organizations to only procure SaaS applications that offer SSO-based authentication. ## Understand how Single Sign-On works [Section titled “Understand how Single Sign-On works”](#understand-how-single-sign-on-works) Fundamentally, Single Sign-on works by exchanging user information in a pre-determined format between two trusted parties - your application and your customer’s identity provider (aka IdP). Most of these interactions happen in the browser context as some steps need user intervention. To ensure secure exchange of user information between your application and your customer’s identity provider, most IdPs support two protocols: Secure Assertion Markup Language (SAML) or OpenID Connect (OIDC). The objective of both these protocols is same: allow secure user information exchange between the Service Provider (your application) and Identity Provider (your customer’s identity system). These protocols differ in how these systems trust each other, communicate, and exchange user information. Let’s understand these protocols at a high level. ## Understanding SAML protocol [Section titled “Understanding SAML protocol”](#understanding-saml-protocol) SAML 2.0 (Secure Assertion Markup Language) has been in use since 2005 and is also most widely implemented protocol. SAML exchanges user information using XML files via HTTPS or SOAP. But, before the user information is exchanged between the two parties, they need to establish the trust between them. Trust is established by exchanging information about each other as part of SAML configuration parameters like Assertion Consumer Service URL (ACS URL), Entity ID, X.509 Certificates, etc. After the trust has been established, subsequent user information can be exchanged in two ways - 1. Your application requesting for a user’s information - this is Service Provider initiated login flow 2. Or the identity provider directly shares user details via a pre-configured ACS URL - this is Identity Provider initiated login flow Let’s understand these two SSO flows. ### Implement Service Provider initiated flow [Section titled “Implement Service Provider initiated flow”](#implement-service-provider-initiated-flow)  For service provider initiated SSO flow, 1. User tries to access your application and your app identifies that the user’s credentials need to be verified by their identity provider. 2. Your application requests the identity provider for the user’s information. 3. The identity provider authenticates the user and returns user details as “assertions” to your application. 4. You validate assertions, retrieve the user information, and if everything checks, allow the user to successfully login to your application. As you can imagine, in this workflow, the user login behaviour starts from your application and that’s why this is termed as service provider initiated SSO (aka SP-initiated SSO) ### Implement Identity Provider initiated flow [Section titled “Implement Identity Provider initiated flow”](#implement-identity-provider-initiated-flow)  In case of Identity Provider initiated SSO, 1. User logs into their identity provider portal and selects your application from within the IdP portal. 2. Identity Provider sends the user details as assertions to your application. 3. You validate assertions, retrieve the user information, and if everything checks, allow the user to successfully login to your application. Since the user login workflow starts from the Identity Provider portal (and not from your application), this flow is called Identity Provider initiated SSO (aka IdP-initiated SSO). #### Mitigate security risks [Section titled “Mitigate security risks”](#mitigate-security-risks) IdP initiated SSO is susceptible to common security attacks like Man In the Middle attack, Stolen Assertion attack or Assertion Replay attack etc. Read the [IdP initiated SSO](/sso/guides/idp-init-sso) guide to understand these risks and how to mitigate them. ## Understanding OIDC protocol [Section titled “Understanding OIDC protocol”](#understanding-oidc-protocol) OpenID Connect (OIDC) is an authentication protocol based on top of OAuth 2.0 to simplify the user information exchange process between Relying Party (your application) and the OpenID Provider (your customer’s Identity Provider). The OIDC protocol exchanges user information via signed JSON Web Tokens (JWT) over HTTPS. Because of the simplified nature of handling JWTs, it is often used in modern web applications, native desktop clients and mobile applications. With the latest extensions to the OIDC protocol like Proof Key of Code Exchange (PKCE) and Demonstrating Proof of Possession (DPoP), the overall security of user exchange information is strengthened. In its current format, OIDC only supports SP initiated Login. In this flow: 1. User tries to access your application. You identify that this user’s credentials need to be verified by their Identity Provider. 2. Your application requests the user’s Identity Provider for the user’s information via an OAuth2 request. 3. Identity Provider authenticates the user and sends the user’s details with an authorization\_code to a pre-registered redirect\_url on your server. 4. You will exchange the code for the actual user details by providing your information with the Identity provider. 5. Identity Provider will then send the user information in the form of JWTs. You retrieve the user information from those assertions and if everything is valid, you will allow the user inside your application. #### Simplify SSO with Scalekit [Section titled “Simplify SSO with Scalekit”](#simplify-sso-with-scalekit) Scalekit serves as an intermediary, abstracting the complexities involved in handling SSO with SAML and OIDC protocols. By integrating with Scalekit in just a few lines of code, your application can connect with numerous IdPs efficiently, ensuring security and compliance. --- # DOCUMENT BOUNDARY --- # Map user attributes to IdP > Learn how to add and map custom user attributes, such as an employee number, from an Identity Provider (IdP) like Okta using Scalekit. Scalekit simplifies Single Sign-On (SSO) by managing user information between Identity Providers (IdPs) and B2B applications. The IdPs provide standard user properties, such as `email` and `firstname`, to your application, thus helping recognize the user. Consider a scenario where you want to get the employee number of the user logging into the application. This guide demonstrates how to add your own custom attribute (such as `employee_number`) and map its value from the Identity Provider. Broadly, we’ll go through two steps: 1. Create a new attribute in Scalekit 2. Set up the value that the Identity Provider should relay to this attribute ## Create a new attribute [Section titled “Create a new attribute”](#create-a-new-attribute) Let’s begin by signing into the Scalekit dashboard: 1. Navigate to **Dashboard > SSO > User Attributes** 2. Click **Add Attribute** 3. Add “Employee Number” as Display name  You’ll now notice “Employee Number” in the list of user attributes. Scalekit is now ready to receive this attribute from your customers’ Identity Providers (IdPs).  ## Set up IdP attributes Okta example [Section titled “Set up IdP attributes ”](#set-up-idp-attributes-) Now, we’ll set up an Identity Provider to send these details. For the purposes of this guide, we’ll use Okta as IdP to send the `employee_number` to Scalekit. However, similar functionality can be achieved using any other IdP. Note that in this specific Okta instance, the “Employee Number” is a default attribute that hasn’t been utilized yet. Before you proceed forward, it’s important to modify the profile’s `employee_number` attribute with any desired number for this example (for example, `1729`). For a detailed guide on how to achieve this, consult [Okta’s dedicated help article on updating profile attributes](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-edit-user-attributes.htm#:~:text=Click%20the%20Profile%20tab). Alternatively, you can [add a new custom attribute in the Okta Profile Editor](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-add-custom-user-attributes.htm#:~:text=In%20the%20Admin%20Console%20%2C%20go%20to%20Directory%20Profile%20Editor).  ## Test SSO for new attributes [Section titled “Test SSO for new attributes”](#test-sso-for-new-attributes) In the Scalekit dashboard, navigate to **Dashboard > Organizations**. 1. Select the organization that you’d like to add custom attribute to 2. Navigate to the SSO Connection 3. Click **Test Connection** - you’ll find this if the IdP has already been established  Upon testing the connection, if you notice the updated user profile (`employee_number` as `1729` in this example), this signifies a successful test. Subsequently, these details will be integrated into your B2B application through Scalekit. This ensures seamless recognition and handling of customer user attributes during the SSO authentication process. ## Reserved attribute names [Section titled “Reserved attribute names”](#reserved-attribute-names) Some attribute names are **reserved by Scalekit** and must not be used for custom attributes. Using a reserved name causes silent failures — the custom attribute value is silently dropped or overwritten during SSO. | Name | Purpose | | ----------------------------------- | --------------------------------------------------------- | | `roles` | Used by Scalekit for FSA role-based access control (RBAC) | | `permissions` | Used by Scalekit for FSA permissions | | `email` | Standard claim — always populated from IdP | | `email_verified` | Standard claim | | `name`, `given_name`, `family_name` | Standard profile claims | | `sub`, `oid`, `sid` | Internal Scalekit identifiers | If your IdP sends an attribute named `roles`, it **will not** appear as a custom attribute in the JWT. Instead, rename it to something unique (e.g., `user_role` or `idp_roles`) in both Scalekit and your IdP attribute mapping. ## Access custom attributes from the ID token [Section titled “Access custom attributes from the ID token”](#access-custom-attributes-from-the-id-token) After configuring a custom attribute in Scalekit, its value appears in the ID token as a JWT claim. Use the Scalekit SDK to validate the token and read the claim: * Node.js Read custom attributes from ID token ```typescript 1 import type { IdTokenClaim } from '@scalekit-sdk/node'; 2 3 // Validate the ID token and cast to include your custom attributes 4 const claims = await scalekit.validateToken>(idToken); 5 const employeeNumber = claims['employee_number']; 6 const userRole = claims['user_role']; // use 'user_role', not 'roles' ``` * Python Read custom attributes from ID token ```python 1 # Validate the ID token — returns a dict of all claims 2 claims = scalekit_client.validate_token(id_token) 3 employee_number = claims.get('employee_number') 4 user_role = claims.get('user_role') # use 'user_role', not 'roles' ``` * Go Read custom attributes from ID token ```go 1 // Validate the ID token — returns a map of all claims 2 claims, err := scalekitClient.ValidateToken(ctx, idToken) 3 if err != nil { 4 log.Fatal(err) 5 } 6 employeeNumber := claims["employee_number"] 7 userRole := claims["user_role"] // use "user_role", not "roles" ``` * Java Read custom attributes from ID token ```java 1 import java.util.Map; 2 3 // Validate the ID token — returns a map of all claims 4 Map claims = scalekitClient.authentication().validateToken(idToken); 5 Object employeeNumber = claims.get("employee_number"); 6 Object userRole = claims.get("user_role"); // use "user_role", not "roles" ``` --- # DOCUMENT BOUNDARY --- # SSO simulator > Test Enterprise SSO based authentication using our SSO Simulator without configuring SAML or OIDC based SSO with a real IdP After implementing Single Sign-On using our [Quickstart guide](/authenticate/sso/add-modular-sso/), you need to validate your integration for all possible scenarios. This guide shows you how to test your SSO implementation using two approaches: 1. **SSO Simulator (quick testing):** Test all SSO scenarios without external services. Your development environment includes a pre-configured test organization with an SSO connection to our SSO Simulator. 2. **Real identity provider (production-ready testing):** Test with actual identity providers like Okta or Microsoft Entra ID to simulate real customer scenarios. To ensure a successful SSO implementation, test all three scenarios described in this guide before deploying to production: SP-initiated SSO, IdP-initiated SSO, and error handling. ## Testing with SSO Simulator Quick testing [Section titled “Testing with SSO Simulator ”](#testing-with-sso-simulator-) The SSO Simulator allows you to test all SSO scenarios without requiring external services. Your development environment includes a pre-configured test organization with an SSO connection to our SSO Simulator and test domains like `@example.com` or `@example.org`. To locate the test organization, navigate to **Dashboard > Organizations** and select **Test Organization**.  ### Service provider (SP) initiated SSO Scenario 1 [Section titled “Service provider (SP) initiated SSO ”](#service-provider-sp-initiated-sso-) In this common scenario, users start the Single Sign-On process from your application’s login page.  #### Generate authorization URL [Section titled “Generate authorization URL”](#generate-authorization-url) Generate an authorization URL with your test organization ID. This redirects users to Scalekit’s hosted login page, which will then redirect to the SSO Simulator. * Node.js Express.js ```javascript 1 // Use your test organization ID from the dashboard 2 const options = { 3 organizationId: 'org_32656XXXXXX0438' // Replace with your test organization ID 4 }; 5 6 // Generate Authorization URL that redirects to SSO Simulator 7 const authorizationURL = scalekit.getAuthorizationUrl(redirectUrl, options); 8 9 // Redirect user to start SSO flow 10 res.redirect(authorizationURL); ``` * Python Flask ```python 1 # Use your test organization ID from the dashboard 2 options = { 3 "organizationId": 'org_32656XXXXXX0438' # Replace with your test organization ID 4 } 5 6 # Generate Authorization URL that redirects to SSO Simulator 7 authorization_url = scalekit_client.get_authorization_url( 8 redirect_url, 9 options, 10 ) 11 12 # Redirect user to start SSO flow 13 return redirect(authorization_url) ``` * Go Gin ```go 1 // Use your test organization ID from the dashboard 2 options := scalekit.AuthorizationUrlOptions{ 3 OrganizationId: "org_32656XXXXXX0438", // Replace with your test organization ID 4 } 5 6 // Generate Authorization URL that redirects to SSO Simulator 7 authorizationURL := scalekitClient.GetAuthorizationUrl( 8 redirectUrl, 9 options, 10 ) 11 12 // Redirect user to start SSO flow 13 c.Redirect(http.StatusFound, authorizationURL) ``` * Java Spring Boot ```java 1 // Use your test organization ID from the dashboard 2 AuthorizationUrlOptions options = new AuthorizationUrlOptions(); 3 options.setOrganizationId("org_32656XXXXXX0438"); // Replace with your test organization ID 4 5 // Generate Authorization URL that redirects to SSO Simulator 6 String authorizationURL = scalekitClient 7 .authentication() 8 .getAuthorizationUrl(redirectUrl, options) 9 .toString(); 10 11 // Redirect user to start SSO flow 12 return "redirect:" + authorizationURL; ``` #### Test the SSO flow [Section titled “Test the SSO flow”](#test-the-sso-flow) After generating the authorization URL, users are redirected to the SSO Simulator: 1. Select **User login via SSO** from the dropdown menu 2. Enter test user details (email, name, etc.) to simulate authentication 3. Click **Submit** to complete the simulation  After submitting the form, your application receives an `idToken` containing the user details you entered:  ### Identity provider (IdP) initiated SSO Scenario 2 [Section titled “Identity provider (IdP) initiated SSO ”](#identity-provider-idp-initiated-sso-) In this scenario, users start the sign-in process from their identity provider (typically through an applications catalog) rather than from your application’s login page. Your application must handle this flow by detecting IdP-initiated requests and converting them to SP-initiated SSO. If you haven’t implemented IdP-initiated SSO yet, follow our [IdP-initiated SSO implementation guide](/sso/guides/idp-init-sso) before testing this scenario.  #### Test IdP-initiated SSO flow [Section titled “Test IdP-initiated SSO flow”](#test-idp-initiated-sso-flow) 1. Generate the authorization URL using your test organization 2. When redirected to the SSO Simulator, select **IdP initiated SSO** from the dropdown menu 3. Enter test user details to simulate the login 4. Click **Submit** to complete the simulation  #### Verify callback handling [Section titled “Verify callback handling”](#verify-callback-handling) Your callback handler receives the IdP-initiated request and must process it correctly:  Your application should: 1. Detect the IdP-initiated request based on the request parameters 2. Retrieve connection details (`connection_id` or `organization_id`) from Scalekit 3. Generate a new authorization URL to convert the IdP-initiated flow to SP-initiated SSO 4. Complete the authentication flow ### Error handling Scenario 3 [Section titled “Error handling ”](#error-handling-) Your application should gracefully handle error scenarios to provide a good user experience. SSO failures can occur due to misconfiguration, incomplete user profiles, or integration issues. #### Test error scenarios [Section titled “Test error scenarios”](#test-error-scenarios) 1. Generate and redirect to the authorization URL 2. In the SSO Simulator, select **Error** from the dropdown menu 3. Verify your callback handler processes the error correctly 4. Ensure users see an appropriate error message  ## Testing with real identity providers Production-ready [Section titled “Testing with real identity providers ”](#testing-with-real-identity-providers-) After validating your SSO implementation with the SSO Simulator, test with real identity providers like Okta or Microsoft Entra ID to simulate actual customer scenarios. This ensures your integration works correctly with production identity systems. ### Setup your test environment [Section titled “Setup your test environment”](#setup-your-test-environment) To simulate a real customer onboarding scenario, create a new organization with a real SSO connection: 1. Create an organization at **Dashboard > Organizations** with a name that reflects a test customer 2. Generate an **Admin Portal link** from the organization’s overview page 3. Open the Admin Portal link and follow the integration guide to set up an SSO connection: * [Okta SAML integration guide](/guides/integrations/sso-integrations/okta-saml/) * [Microsoft Entra ID integration guide](/guides/integrations/sso-integrations/azure-ad-saml/) * [Other SSO integrations](/guides/integrations/) ### Service provider (SP) initiated SSO Scenario 1 [Section titled “Service provider (SP) initiated SSO ”](#service-provider-sp-initiated-sso--1) Test the most common SSO scenario where users start the authentication flow from your application’s login page.  #### Validate the flow [Section titled “Validate the flow”](#validate-the-flow) 1. **Generate authorization URL**: Create an authorization URL with your test organization’s ID (see [Authorization URL documentation](/sso/guides/authorization-url/)) 2. **User authentication**: Verify that Scalekit redirects users to the correct identity provider 3. **Callback handling**: Confirm your application receives the authorization code at your redirect URI 4. **Token exchange**: Verify you can exchange the authorization code for user details and tokens 5. **Session creation**: Ensure your application creates a session and logs the user in successfully Your application should successfully retrieve user details including email, name, and any custom attributes configured in the SSO connection. ### Identity provider (IdP) initiated SSO Scenario 2 [Section titled “Identity provider (IdP) initiated SSO ”](#identity-provider-idp-initiated-sso--1) Test the scenario where users start authentication from their identity provider’s application catalog.  #### Validate the flow [Section titled “Validate the flow”](#validate-the-flow-1) 1. **Initial callback**: User is redirected to your default redirect URI with IdP-initiated request parameters 2. **Detection logic**: Your application detects this as an IdP-initiated request (based on the request parameters) 3. **SP-initiated conversion**: Your application initiates SP-initiated SSO by generating an authorization URL 4. **IdP redirect**: User is redirected to the identity provider based on the authorization URL 5. **Final callback**: After authentication, user is redirected back with an authorization code and state parameter 6. **Token exchange**: Exchange the code for user details and complete the login For implementation details, see our [IdP-initiated SSO implementation guide](/sso/guides/idp-init-sso/). Default redirect URL configuration Ensure your default redirect URL is correctly configured at **Dashboard > Developers > Redirect URLs**. This URL receives IdP-initiated requests. ### Error handling Scenario 3 [Section titled “Error handling ”](#error-handling--1) Test how your application handles SSO failures. Common error scenarios include: * Misconfigured SSO connections (wrong certificates, invalid metadata) * Incomplete user profiles (missing required attributes) * Expired or revoked SSO connections * Network or integration issues with the identity provider #### Validate error handling [Section titled “Validate error handling”](#validate-error-handling) 1. Review the [SSO integration error codes](/sso/reference/sso-integration-errors/) documentation 2. Test each applicable error scenario by intentionally misconfiguring your SSO connection 3. Verify your application displays appropriate, user-friendly error messages 4. Ensure errors are logged for debugging purposes 5. Confirm users can retry authentication or contact support ## Next steps [Section titled “Next steps”](#next-steps) After thoroughly testing your SSO implementation: 1. Review the [SSO launch checklist](/sso/guides/launch-checklist/) to ensure production readiness 2. Configure the [Admin Portal](/guides/admin-portal/) for your customers to self-serve SSO setup 3. Implement [custom domain](/guides/custom-domain/) for a seamless branded experience 4. Set up [webhooks](/authenticate/implement-workflows/implement-webhooks/) to receive real-time authentication events --- # DOCUMENT BOUNDARY --- # Normalized user profile > Learn how Scalekit's normalized user profiles standardize identity data across providers, streamlining single sign-on (SSO) integration and user management. When a user logs in with SSO, each identity provider shares the user profile information in their own format. This adds complexity for the application developers to parse the user profile info and code related identity workflows. To make this seamless for developers, Scalekit normalizes the user profile info into a standard set of fields across all identity providers. This means that you’d always receive the user profile payload in a fixed set of fields, irrespective of the identity provider and protocol you interact with. This is one of our foundational aspects of the unified SSO solution. Sample normalized user profile ```json 1 { 2 "email": "john.doe@acmecorp.com", 3 "email_verified": true, 4 "family_name": "Doe", 5 "given_name": "John", 6 "locale": "en", 7 "name": "John Doe", 8 "picture": "https://lh3.googleusercontent.com/a/ACg8ocKNE4TZ...iEma17URCEf=s96-c", 9 "sub": "conn_17576372041941092;google-oauth2|104630259163176101050", 10 "identities": [ 11 { 12 "connection_id": "conn_17576372041941092", 13 "organization_id": "org_17002852291444836", 14 "connection_type": "OIDC", 15 "provider_name": "AUTH0", 16 "social": false, 17 "provider_raw_attributes": { 18 "aud": "ztTgHijLLguDXJQab0oiPyIcDLXXrJX6", 19 "email": "john.doe@acmecorp.com", 20 "email_verified": true, 21 "exp": 1714580633, 22 "family_name": "Doe", 23 "given_name": "John", 24 "iat": 1714544633, 25 "iss": "https://dev-rmmfmus2g7vverbf.us.auth0.com/", 26 "locale": "en", 27 "name": "John Doe", 28 "nickname": "john.doe", 29 "nonce": "Lof9SpxEzs9dhUlJzgrrbQ==", 30 "picture": "https://lh3.googleusercontent.com/a/ACg8ocKNE4T...17URCEf=s96-c", 31 "sid": "5yqRJIfjPh8c7lr1s2N-IbY6WR8VyaIZ", 32 "sub": "google-oauth2|104630259163176101050", 33 "updated_at": "2024-04-30T10:02:30.988Z" 34 } 35 } 36 ] 37 } ``` ## Full list of user profile attributes [Section titled “Full list of user profile attributes”](#full-list-of-user-profile-attributes) | Profile attribute | Data type | Description | | ----------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `sub` | string | An identifier for the user, as submitted by the identity provider that completed the single sign-on. | | `email` | string | The user’s email address. | | `email_verified` | boolean | True if the user’s e-mail address has been verified as claimed by the identity provider; otherwise false. | | `name` | string | Fully formatted user’s name | | `family_name` | string | The user’s surname or last name. | | `given_name` | string | The user’s given name or first name. | | `locale` | string | The user’s locale, represented by a BCP 47 language tag. Example: ‘en’ | | `picture` | string | The user’s profile picture in URL format | | `identities` | Array of [Identity objects](/sso/guides/user-profile-details/#identity-object-attributes) | Array of all identity information received from the identity providers in the raw format | ### Identity object attributes [Section titled “Identity object attributes”](#identity-object-attributes) | Identity attribute | Data type | Description | | ------------------------- | --------- | ----------------------------------------------------------------------------------------------------- | | `organization_id` | string | Unique ID of the organization to which this user belongs to | | `connection_id` | string | Unique ID of the connection for which this identity data is fetched from | | `connection_type` | string | type of the connection: SAML or OIDC | | `provider_name` | string | name of the connection provider. Example: Okta, Google, Auth0 | | `social` | boolean | Is the connection a social provider (like Google, Microsoft, GitHub etc) or an enterprise connection. | | `provider_raw_attributes` | object | key-value map of all the raw attributes received from the connection provider as-is | --- # DOCUMENT BOUNDARY --- # Error handling during single sign-on > Learn how to identify and resolve common single sign-on errors in Scalekit, ensuring a seamless authentication experience for your users Reference of error codes and how to handle them When users attempt to log in via single sign-on (SSO) using Scalekit, any issues encountered will result in error details being sent to your application’s redirect URI via the `error` and `error_description` query parameters. Proper error handling ensures a better user experience. ## Integration related errors [Section titled “Integration related errors”](#integration-related-errors) If there is any issue between Scalekit and your application, the following errors may occur: | Error | Error description | Possible resolution strategy | | ----------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | ``` invalid_redirect_uri ``` | Redirect URI is not part of the pre-approved list of redirect URIs | Add the valid URL in the Scalekit dashboard before using it | | ``` invalid_connection_selector ``` | Missing `organization_id` (or) `connection_id` (or) `domain` (or) `provider` in the authorization URL | Include at least one of these parameters in the request | | ``` no_active_connections ``` | There are no active SSO connections configured to process the single sign-on request | Ensure active SSO connections are set up | | ``` connection_not_active ``` | The configured connection is not active | Enable the SSO connection in the Scalekit dashboard | | ``` no_configured_connections ``` | No active SSO connections configured | Ensure active SSO connections are set up | | ``` invalid_organization_id ``` | Invalid organization ID | Verify and use a valid organization ID | | ``` invalid_connection_id ``` | Invalid connection ID | Verify and use a valid connection ID | | ``` domain_not_found ``` | No domain specified for the SSO connection(s) | Check domain configuration in Scalekit dashboard | | ``` invalid_user_domain ``` | User’s domain not allowed for this SSO connection | Ensure user domain is part of the allowed domains list | | ``` invalid_client ``` | The client application is not recognized or not configured correctly | Verify the `client_id` value in your authorization URL | | ``` application_not_active ``` | The application is inactive | Enable the application in the Scalekit dashboard | | ``` invalid_request ``` | The authorization request contains invalid or missing parameters | Review the authorization URL parameters | | ``` unauthorized ``` | The request is unauthorized | Verify that valid credentials are being used | | ``` user_not_active ``` | The user account is inactive | Activate the user account or contact the IT admin | | ``` server_error ``` | *actual error description from the server* | This must be a rare occurrence. Please reach out to us via your private slack channel or [via email](mailto:support@scalekit.com) | ## SSO configuration related errors [Section titled “SSO configuration related errors”](#sso-configuration-related-errors) If SSO configuration issues arise, you will encounter the following errors: | Error code | Error description | Possible resolution strategy | | ------------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ``` mandatory_attribute_missing ``` | Missing mandatory user attributes | Ensure all the mandatory user attributes are configured properly | | ``` invalid_id_token ``` | Invalid ID token | Check the identity provider’s functioning | | ``` failed_to_exchange_token ``` | Token exchange failure due to incorrect `client_secret` | Update the `client_secret` with the correct value | | ``` user_info_retrieve_failed ``` | User info retrieval failed, possibly due to an incorrect `client_secret` or other issues | Update the `client_secret` with the correct value. If unsuccessful, investigate further. Please reach out to us via your private slack channel or [via email](mailto:support@scalekit.com) | | ``` invalid_saml_metadata ``` | Incorrect SAML metadata configuration | Update SAML metadata URL with the correct value | | ``` invalid_saml_response ``` | Invalid SAML response | Review and fix SAML configuration settings | | ``` invalid_saml_request ``` | The SAML request is invalid | Check the SAML configuration in both Scalekit and the identity provider | | ``` invalid_saml_form_params ``` | The SAML form parameters are invalid or malformed | Review the SAML response format from the identity provider | | ``` signature_validation_failed ``` | Failed signature validation | Review and update the ACS URL in the identity provider’s settings | | ``` invalid_acs_url ``` | Invalid ACS URL | Review and update the ACS URL in the identity provider’s settings | | ``` invalid_assertion_url ``` | The assertion URL in the SAML request is invalid | Verify and update the ACS URL in the identity provider’s settings | | ``` invalid_status ``` | Invalid status | Review and update the SAML configuration settings in the identity provider | | ``` malformed_saml_response ``` | Marshalling error | Ensure SAML response is properly formatted | | ``` assertion_expired ``` | Expired SAML assertion | We received an expired SAML assertion. This could be because of clock skew between the identity provider’s server and our servers. Please reach out to us via your private slack channel or [via email](mailto:support@scalekit.com) | | ``` response_expired ``` | Expired SAML response | We received an expired SAML response. This could be because of clock skew between the identity provider’s server and our servers. Please reach out to us via your private slack channel or [via email](mailto:support@scalekit.com) | | ``` authentication_not_completed ``` | The authentication flow was not completed | Ensure the user completes the login process in the identity provider | | ``` user_login_required ``` | User login is required to continue | Redirect the user to the login page to complete authentication |