implementing-modular-sso

用途

本技能面向已有用户管理系统的应用，指导开发者使用 Scalekit 实现企业级 SSO 与认证流程。它覆盖的是 Modular SSO 模式：用户与会话由应用自己管理，Scalekit 负责对接企业身份提供商（IdP）。资料同时说明，若希望由 Scalekit 管理用户与会话，应使用 SaaSKit（Full-Stack Auth）模式，本技能不覆盖该路径。

主要能力

支持 SAML/OIDC 的模块化 SSO 接入。
支持 IdP 发起的登录（IdP-initiated SSO），将其转换为安全的 SP 发起流程，以防范 SAML 断言窃取与重放攻击。
提供 Admin Portal，供企业客户自助完成 SSO 配置，并支持将 Portal 以 iframe 嵌入应用。
提供内置 IdP 模拟器用于测试，环境预置了 @example.com、@example.org 测试组织。
提供按域名预检 SSO 可用性、域名验证、多租户路由、分步认证、登出等常见模式。

使用方式

实施流程分为八步：配置 Modular Auth 模式、安装并配置 SDK、生成授权 URL、处理 IdP 发起的 SSO、处理认证回调、校验 Token 并提取用户资料、测试 SSO 集成、设置客户接入流程。

SDK 安装命令：

Node.js：npm install @scalekit-sdk/node

Python：pip install scalekit-sdk-python

Go：go get github.com/scalekit-inc/scalekit-sdk-go/v2

Java：

<dependency>
  <groupId>com.scalekit</groupId>
  <artifactId>scalekit-sdk-java</artifactId>
</dependency>

环境变量需配置 SCALEKIT_ENVIRONMENT_URL、SCALEKIT_CLIENT_ID、SCALEKIT_CLIENT_SECRET，从 Dashboard > Developers > Settings > API credentials 获取。

生成授权 URL 时需传入连接选择器之一，优先级为 connectionId > organizationId > loginHint。也可不使用 SDK，直接拼接授权 URL：

<SCALEKIT_ENVIRONMENT_URL>/oauth/authorize?
  response_type=code&
  client_id=<CLIENT_ID>&
  redirect_uri=<CALLBACK_URL>&
  scope=openid profile email&
  organization_id=<ORG_ID>

回调端点需创建为 /auth/callback，并在 Dashboard > Authentication > Redirect URLs > Allowed Callback URLs 中注册。IdP 发起的登录需在 Dashboard > Authentication > Redirects 设置 initiate login endpoint（如 https://yourapp.com/login）。

适用场景

适用于已有用户管理、需要为企业客户提供 SSO 登录的应用，尤其是多租户 SaaS、需要按邮箱域名自动路由到客户 IdP、需要客户 IT 管理员自助配置 SSO 的场景。资料也给出与 Auth0、Firebase、Cognito 等现有会话层集成的简要指引，但强调这不是 Modular SSO 的主路径。

限制与安全要求

必须在信任任何声明前校验 ID Token 与 Access Token，不得从未校验的 Token 中提取用户身份。
所有回调 URL 必须先在 Dashboard 注册，否则会报 Invalid redirect_uri 错误。
授权 URL 必须传入 organization_id、connectionId 或 loginHint 之一，否则 Scalekit 无法确定路由到哪个 IdP。
构建授权 URL 时必须保留 IdP 发起登录声明中的 relay_state，以防 SAML 断言重放。
不得尝试自动化 Scalekit Dashboard UI；遇到用户操作步骤时，应打印清单、等待用户确认后再继续编码。
生产部署前需完成安全清单：环境变量安全存储、全端点强制 HTTPS、会话 Cookie 使用 secure 与 httpOnly、启用 CSRF 防护、认证端点限流、日志不暴露 Token 等。
资料提到 ID Token 15 分钟过期、Access Token 5 分钟过期（可在 Dashboard 配置），但未提供收费、价格或平台支持范围等信息。

技能介绍

用途

主要能力

使用方式

适用场景

限制与安全要求

相关技能