单点登录 SSO 系统搭建教程

单点登录（Single Sign-On，SSO）允许用户只需登录一次，就可以访问所有关联的应用系统。对于在搬瓦工 VPS 上运行多个 Web 应用的用户来说，SSO 可以大幅提升管理效率和用户体验。本文将使用 Keycloak 搭建企业级的 SSO 认证中心。Keycloak 是 Red Hat 维护的开源身份和访问管理解决方案，支持 OpenID Connect、OAuth2 和 SAML 协议。

一、系统要求

内存：至少 2GB，推荐 4GB。
Docker：推荐 Docker Compose 部署。
数据库：PostgreSQL（推荐）或 MySQL。

二、Docker 部署 Keycloak

mkdir -p /opt/keycloak && cd /opt/keycloak

创建 docker-compose.yml：

version: '3.8'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    restart: always
    ports:
      - "8180:8080"
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://db:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak_password
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: 你的管理员密码
      KC_HOSTNAME: sso.example.com
      KC_PROXY_HEADERS: xforwarded
      KC_HTTP_ENABLED: "true"
    command: start
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    restart: always
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak_password
    volumes:
      - keycloak_db:/var/lib/postgresql/data

volumes:
  keycloak_db:

docker compose up -d

三、Nginx 反向代理

server {
    listen 80;
    listen 443 ssl http2;
    server_name sso.example.com;

    ssl_certificate /etc/letsencrypt/live/sso.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sso.example.com/privkey.pem;

    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;

    location / {
        proxy_pass http://127.0.0.1:8180;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port $server_port;
    }
}

nginx -t && systemctl reload nginx

四、配置 Realm 和客户端

访问 https://sso.example.com，使用管理员账号登录。

4.1 创建 Realm

Realm 是 Keycloak 的核心概念，代表一个独立的认证域。建议为你的应用创建专门的 Realm（不使用默认的 master Realm）：

在左上角下拉菜单中点击"Create Realm"。
填写 Realm 名称（如 "myapps"）。
启用并保存。

4.2 创建客户端

为每个需要接入 SSO 的应用创建客户端：

进入"Clients > Create Client"。
Client ID 填写应用标识（如 "webapp"）。
Client Protocol 选择 "openid-connect"。
设置 Valid Redirect URIs 为应用的回调地址。
根据应用类型选择 Access Type（confidential 适合服务端应用）。

4.3 创建用户

在"Users"中创建用户账号，设置密码和角色。也可以配置外部身份提供商（如 Google、GitHub）实现社交登录。

五、应用集成

5.1 Node.js 应用集成

npm install openid-client

const { Issuer } = require('openid-client');

async function setupOIDC() {
  const issuer = await Issuer.discover('https://sso.example.com/realms/myapps');
  const client = new issuer.Client({
    client_id: 'webapp',
    client_secret: '你的客户端密钥',
    redirect_uris: ['https://app.example.com/callback'],
    response_types: ['code'],
  });

  // 生成授权 URL
  const authUrl = client.authorizationUrl({
    scope: 'openid email profile',
  });

  // 处理回调
  async function handleCallback(req) {
    const params = client.callbackParams(req);
    const tokenSet = await client.callback(
      'https://app.example.com/callback',
      params
    );
    const userinfo = await client.userinfo(tokenSet.access_token);
    return userinfo;
  }
}

5.2 Nginx 身份验证代理

使用 oauth2-proxy 为不支持 OIDC 的应用添加 SSO 保护：

docker run -d \
  --name oauth2-proxy \
  -p 4180:4180 \
  quay.io/oauth2-proxy/oauth2-proxy:latest \
  --provider=keycloak-oidc \
  --client-id=webapp \
  --client-secret=你的密钥 \
  --oidc-issuer-url=https://sso.example.com/realms/myapps \
  --redirect-url=https://app.example.com/oauth2/callback \
  --email-domain=* \
  --cookie-secret=随机32字节Base64密钥 \
  --upstream=http://127.0.0.1:8080

六、多因素认证（MFA）

在 Keycloak 管理面板中启用多因素认证：

进入"Authentication > Required Actions"。
启用"Configure OTP"并设为默认必须。
用户下次登录时会被要求配置 TOTP（如 Google Authenticator）。

七、数据备份

# 备份 PostgreSQL 数据
docker compose exec db pg_dump -U keycloak keycloak > /root/backups/keycloak_$(date +%Y%m%d).sql

# 导出 Realm 配置
docker compose exec keycloak /opt/keycloak/bin/kc.sh export --dir /tmp/export --realm myapps
docker cp keycloak-keycloak-1:/tmp/export /root/backups/keycloak_realm_$(date +%Y%m%d)

总结

Keycloak 是功能最全面的开源 SSO 解决方案，支持 OIDC、OAuth2、SAML 等多种协议，内置用户管理、多因素认证、社交登录等企业级功能。在搬瓦工 VPS 上通过 Docker 部署方便快捷，建议使用 2GB 以上内存的方案。如果你只需要简单的 OAuth2 功能，可以参考更轻量的 Ory Hydra 方案。

选购搬瓦工 VPS 请查看全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 的折扣，通过 bwh81.net 进入官网购买。