Add doc for SAML SSO (#385)

Author: byn9826

README.md

@@ -55,6 +55,7 @@
   - Discord Sign-In
   - Apple Sign-In
   - OIDC Auth Provider Sign-In
+  - SAML SSO Sign-In (Node.js environment only) [SAML SSO Setup Doc](https://auth.valuemelody.com/saml-sso-setup.html)
 - <b>Multi-Factor Authentication</b> [How to setup MFA](https://auth.valuemelody.com/q_a.html#how-to-setup-mfa)
   - Email MFA
   - OTP MFA
@@ -68,6 +69,7 @@
   - change_email
   - reset_mfa
   - manage_passkey
+  - saml_sso_[idp_name]
 - <b>Organization</b>:
   - Branding config override
   - Organization users
@@ -106,6 +108,7 @@
 - Manage Scopes
 - Manage Roles
 - Manage Organizations
+- Manage SAML SSO IDPs
 - Manage Logs
 - Admin Panel Access Control [Custom Role Access for the Admin Panel](https://auth.valuemelody.com/admin-panel-setup.html#custom-role-access-for-the-admin-panel)
 

docs/README.md

@@ -20,6 +20,9 @@ actions:
   - text: Social Sign-In Provider Setup
     link: /social-sign-in-provider-setup.html
     type: secondary
+  - text: SAML SSO Setup
+    link: /saml-sso-setup.html
+    type: secondary
   - text: Admin Panel Setup
     link: /admin-panel-setup.html
     type: primary

docs/auth-server-configuration.md

@@ -98,6 +98,10 @@ Melody Auth offers a range of customizable options to tailor the authentication
 - **Default:** []
 - **Description:** A list of origins that are allowed to use embedded auth APIs.
 
+### ENABLE_SAML_SSO_AS_SP
+- **Default:** false
+- **Description:** Toggles the SAML SSO as a Service Provider (SP) feature. If `true`, users can sign in with configured SAML SSO.
+
 ## Auth Configs
 
 ### AUTHORIZATION_CODE_EXPIRES_IN

docs/saml-sso-setup.md

@@ -0,0 +1,39 @@
+# SAML SSO Setup
+
+SAML SSO is currently supported only in the Node.js environment of Melody Auth.
+
+## 1. Generate SAML SP certificate and key
+
+```bash
+npm run node:saml:secret:generate
+```
+
+## 2. Enable SAML SSO in `wrangler.toml`
+Ensure that SAML SSO as a Service Provider (SP) is enabled in your server/wrangler.toml configuration file:
+
+```toml
+ENABLE_SAML_SSO_AS_SP=true
+```
+
+## 3. Register a SAML Identity Provider (IdP) via Admin Panel
+
+- Go to admin panel
+- Click "Manage SAML"
+- Click "Create" button
+- Define a unique name for the IDP, and fill in necessary information
+- Click "Save" button
+
+## 4. Trigger Login via SAML SSO in the Frontend
+
+Use the loginRedirect function provided by your Melody Auth frontend SDK (e.g., @melody-auth/react) to initiate the login process:
+
+```
+  const {
+    loginRedirect
+  } = useAuth()
+
+  loginRedirect({
+    locale: locale || undefined, org: 'default',
+    policy: 'saml_sso_[idp_name]' # Replace [idp_name] with the name of the IDP you created in admin panel
+  })
+```

docs/zh/README.md

@@ -20,6 +20,9 @@ actions:
   - text: 社交登录提供商设置
     link: /zh/social-sign-in-provider-setup.html
     type: secondary
+  - text: SAML SSO 设置
+    link: /zh/saml-sso-setup.html
+    type: secondary
   - text: 管理面板设置
     link: /zh/admin-panel-setup.html
     type: primary

docs/zh/auth-server-configuration.md

@@ -98,6 +98,9 @@ Melody Auth 提供了一系列可自定义选项，以便您根据实际需求
 - **默认值：** []
 - **说明：** 允许使用嵌入式认证 API 的前端应用源列表。
 
+### ENABLE_SAML_SSO_AS_SP
+- **默认值：** false
+- **说明：** 是否启用 SAML SSO 作为服务提供方（SP）功能。若设为 `true`，用户可通过配置的 SAML SSO 登录。
 
 ## 认证相关配置
 

docs/zh/saml-sso-setup.md

@@ -0,0 +1,39 @@
+# SAML SSO 设置
+
+SAML SSO 当前仅在 Melody Auth 的 Node.js 环境中支持。
+
+## 1. 生成 SAML SP 证书和密钥
+
+```bash
+npm run node:saml:secret:generate
+```
+
+## 2. 在 wrangler.toml 中启用 SAML SSO
+确保在服务器的 server/wrangler.toml 配置文件中启用了作为服务提供方（SP）的 SAML SSO：
+
+```toml
+ENABLE_SAML_SSO_AS_SP=true
+```
+
+## 3. 通过管理面板注册一个 SAML 身份提供商（IdP）
+
+- 进入管理面板
+- 点击 “管理 SAML”
+- 点击 “创建” 按钮
+- 为 IDP 定义一个唯一名称，并填写必要信息
+- 点击 “保存” 按钮
+
+## 4. 在前端触发 SAML SSO 登录
+
+使用 Melody Auth 前端 SDK（例如 @melody-auth/react）提供的 loginRedirect 函数来发起登录流程：
+
+```
+  const {
+    loginRedirect
+  } = useAuth()
+
+  loginRedirect({
+    locale: locale || undefined, org: 'default',
+    policy: 'saml_sso_[idp_name]' # 将 [idp_name] 替换为你在管理面板中创建的 IDP 名称
+  })
+```

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "melody-auth",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "A turnkey OAuth & authentication system.",
   "license": "MIT",
   "author": "Baozier",

package.json

@@ -32,7 +32,7 @@ ENABLE_USER_ATTRIBUTE=false
 BLOCKED_POLICIES=[] # A list of policy names that should be blocked (change_password, change_email, reset_mfa, manage_passkey, update_info), preventing end users from triggering them
 ENABLE_PASSWORDLESS_SIGN_IN=false # Please set up your mailer first https://auth.valuemelody.com/email-provider-setup.html. Setting this option to true will automatically override ENABLE_SIGN_UP, ENABLE_PASSWORD_SIGN_IN, ENABLE_PASSWORD_RESET, ALLOW_PASSKEY_ENROLLMENT to false. Also, make sure to disable email MFA in order to use this feature.
 EMBEDDED_AUTH_ORIGINS=[] # List of origins that are allowed to use embedded auth APIs.
-ENABLE_SAML_SSO_AS_SP=false # Experimental feature, do not use
+ENABLE_SAML_SSO_AS_SP=false # Experimental feature, only support in Node.js environment
 
 # Auth
 AUTHORIZATION_CODE_EXPIRES_IN=300