Skip to main content

企业功能

单点登录（SSO）

为你的 Virex 组织配置 SAML 2.0 或 OpenID Connect SSO，支持 Okta、Azure AD、Google Workspace 等身份提供商。

单点登录（SSO）允许你的团队使用现有身份提供商登录 Virex。它通过集中化认证简化访问管理并提升安全性。

支持的身份提供商

Virex 支持通过 SAML 2.0 和 OpenID Connect（OIDC）接入 SSO：

SAML 2.0

  • Okta
  • Azure Active Directory
  • OneLogin
  • PingIdentity
  • JumpCloud
  • 任何符合 SAML 2.0 标准的 IdP

OpenID Connect

  • Google Workspace
  • Auth0
  • Keycloak
  • 任何符合 OIDC 标准的提供商

前提条件

配置 SSO 之前：

  1. 企业版套餐 — SSO 仅在企业版套餐中提供
  2. 已验证的域名 — 你的邮箱域名必须已在 Virex 中完成验证
  3. IdP 管理员权限 — 你需要身份提供商的管理员权限

SAML 2.0 配置

第 1 步：获取 Virex SAML 信息

在 Virex 控制台中，进入 Settings → Security → SSO，记录以下信息：

字段 值
ACS URL https://auth.virex.example.com/saml/acs/{org-id}
Entity ID https://virex.example.com/saml/{org-id}
Sign-on URL https://auth.virex.example.com/saml/login/{org-id}

第 2 步：配置你的 IdP

Okta

  1. 在 Okta 管理后台，进入 Applications → Create App Integration

  2. 选择 SAML 2.0

  3. 配置：

    • Single sign-on URL：第 1 步中的 ACS URL
    • Audience URI：第 1 步中的 Entity ID
    • Name ID format：EmailAddress
    • Application username：Email

  4. 添加属性声明（attribute statements）：

名称 值
email user.email
firstName user.firstName
lastName user.lastName
  1. 下载 IdP 元数据 XML 文件

Azure AD

  1. 在 Azure 门户中，进入 Enterprise Applications → New Application

  2. 选择 Create your own application

  3. 选择 Integrate any other application (Non-gallery)

  4. 进入 Single sign-on → SAML

  5. 配置 Basic SAML Configuration：

    • Identifier (Entity ID)：你的 Entity ID
    • Reply URL (ACS URL)：你的 ACS URL
    • Sign on URL：你的 Sign-on URL

  6. 配置 User Attributes & Claims：

    • emailaddress → user.mail
    • givenname → user.givenname
    • surname → user.surname

  7. 下载 Federation Metadata XML

第 3 步：将 IdP 元数据上传到 Virex

  1. 进入 Settings → Security → SSO
  2. 点击 Configure SAML
  3. 上传你的 IdP 元数据 XML 文件
  4. 点击 Save Configuration

第 4 步：测试连接

  1. 点击 Test SSO Connection
  2. 你将被重定向到你的 IdP
  3. 使用 IdP 凭据进行认证
  4. 确认你被重定向回 Virex

OpenID Connect 配置

第 1 步：创建 OIDC 应用

在你的身份提供商中创建一个新的 OIDC 应用，配置如下：

字段 值
Redirect URI https://auth.virex.example.com/oidc/callback/{org-id}
Grant Type Authorization Code
Response Type code

第 2 步：配置 Virex

  1. 进入 Settings → Security → SSO
  2. 点击 Configure OIDC
  3. 输入你的 IdP 信息：
Client ID: your-client-id
Client Secret: your-client-secret
Issuer URL: https://your-idp.com
  1. 点击 Save Configuration

Google Workspace 示例

  1. 打开 Google Cloud Console
  2. 创建新的 OAuth 2.0 Client ID
  3. 将授权重定向 URI 设置为你的 Virex 回调 URL
  4. 将 Client ID 和 Client Secret 复制到 Virex

用户预置

即时（JIT）预置

默认情况下，用户首次通过 SSO 登录时会在 Virex 中自动创建：

// Default JIT settings
{
  jitProvisioning: true,
  defaultRole: 'developer',
  autoJoinTeams: ['engineering']
}

SCIM 预置

如需自动化的用户生命周期管理，请启用 SCIM：

  1. 进入 Settings → Security → SCIM
  2. 生成 SCIM 令牌
  3. 在你的 IdP 中配置：
    • SCIM Base URL：https://api.virex.example.com/scim/v2
    • Bearer Token：你生成的令牌

SCIM 支持：

  • 用户创建 — IdP 中的新用户会自动在 Virex 中创建
  • 用户更新 — 资料变更自动同步
  • 用户停用 — 从 IdP 移除的用户将失去 Virex 访问权限
  • 群组同步 — IdP 群组映射到 Virex 团队

角色映射

将 IdP 群组或属性映射到 Virex 角色：

// Role mapping configuration
{
  roleMapping: {
    // Map IdP groups to Virex roles
    groups: {
      'Engineering': 'developer',
      'DevOps': 'admin',
      'Management': 'viewer'
    },
    // Or map based on attributes
    attributes: {
      'department': {
        'Engineering': 'developer',
        'Operations': 'admin'
      }
    },
    // Default role if no mapping matches
    default: 'viewer'
  }
}

强制启用 SSO

SSO 配置完成后，可以强制所有用户使用 SSO：

  1. 进入 Settings → Security → SSO
  2. 启用 Require SSO for all users
  3. 可选：允许特定用户使用密码登录（例如服务账号）

强制启用后：

  • 用户必须通过 SSO 认证
  • 密码登录将被禁用
  • 现有会话在过期前仍然有效

会话管理

配置 SSO 会话行为：

{
  session: {
    // Session duration (max 24 hours with SSO)
    duration: '8h',
    // Require re-authentication for sensitive actions
    reauthForSensitive: true,
    // Idle timeout
    idleTimeout: '1h'
  }
}

会话终止

当用户在你的 IdP 中被停用时：

  • 使用 SCIM：访问权限立即被撤销
  • 未使用 SCIM：访问权限在下一次会话刷新时（1 小时内）被撤销

强制立即终止会话：

virex users revoke-sessions user@example.com

故障排查

“Invalid SAML Response”

常见原因：

  1. 时钟偏差 — 确保 IdP 与 Virex 的时间同步
  2. ACS URL 错误 — 确认 URL 完全一致
  3. 证书过期 — 在 Virex 中更新 IdP 证书

“User not found”

如果 JIT 预置被禁用，需要先手动创建用户：

virex users create user@example.com --sso-only

“Attribute mapping failed”

确认你的 IdP 是否发送了必需属性：

virex sso debug --last-login user@example.com

该命令会显示收到的原始 SAML 断言或 OIDC 声明。

IdP 变更后用户无法访问

清除 SSO 缓存：

virex sso clear-cache

安全最佳实践

  1. 启用 SCIM — 确保被停用的用户立即失去访问权限
  2. 使用较短的会话时长 — 降低会话被窃取的风险
  3. 在 IdP 侧要求 MFA — Virex 会遵循 IdP 的 MFA 要求
  4. 监控 SSO 日志 — 定期审查认证事件
  5. 测试灾难恢复 — 确保 IdP 宕机时仍能访问 Virex

应急访问

当 SSO 不可用时，可使用应急访问：

  1. 在 Settings → Security → SSO 中指定应急（bypass）用户
  2. 这些用户可以使用邮箱/密码登录
  3. 应急用户应仅限于必要人员
virex sso add-bypass admin@example.com