文档下载建议反馈入口

  • 概述
  • 认证规则匹配机制
    • 规则格式及字段说明
    • 时间段匹配规则
    • 支持的认证方式
  • 配置示例
    • 基于密码的身份认证
    • 基于证书的身份认证
    • 双因子身份认证
    • GSSAPI 身份认证

身份认证与鉴别

概述

身份认证与鉴别是 KaiwuDB 安全体系的关键组件之一，用于验证客户端的身份，并基于认证结果决定是否允许访问数据库。KaiwuDB 采用基于主机的身份认证（Host-Based Authentication, 简称 HBA）机制，支持灵活的认证策略配置，能够满足不同网络环境与安全等级的需求。

认证规则匹配机制

KaiwuDB 通过集群参数 server.host_based_authentication.configuration 定义一条或多条主机认证规则，每条规则指定连接的访问控制条件。系统收到客户端连接请求后，从上到下依序匹配规则，一旦匹配成功，即按该规则进行身份验证和访问控制。

规则格式及字段说明

每条 HBA 规则由以下六个字段组成，字段之间以空格分隔：

<type> <database> <user> <period> <address> <method>
字段位置字段名称描述
1type指定连接类型。支持以下参数设置：
- local：Unix 域套接字连接
- host：TCP/IP 连接（含 SSL/非 SSL）
- hostssl：仅 SSL 加密的 TCP/IP 连接
- hostnossl：仅非 SSL 的 TCP/IP 连接
2database目前只支持设置为 all 以匹配所有数据库。
3user用户名，可设置为 all 匹配所有用户。
4period允许或拒绝连接的时间范围，支持精细化的周期表达式，详见时间段匹配规则。设置为 all 时表示不限时间。
5address指定规则允许或阻止的 IP 地址范围，支持以下格式：
- all：表示所有 IP 地址
- 单个 IP 地址：如 192.168.1.100
- 包含掩码的 IP 地址：如 192.168.1.0/24
- 不带掩码的 IP 地址 + IP 掩码：如 192.168.1.0 255.255.255.0
6method身份认证方式，控制用户如何通过认证。详见支持的认证方式。

时间段匹配规则

KaiwuDB 支持按周期定义的时间段控制，即仅在指定时间范围内允许或拒绝客户端连接。该机制支持以下周期粒度：

  • yearly：按年周期，如每年 3 月 1 日至 11 月 30 日
  • monthly：按月周期，如每月 1 日至 15 日
  • weekly：按周周期，如每周一中午到周三傍晚
  • daily：按日周期，如每天中午至下午或跨天时间段

跨周期时间段支持

所有周期粒度均支持跨周期时间段定义，例如 yearly 11-30 23:00:00 - 03-01 12:00:00 表示每年 11 月 30 日 23:00 至次年 3 月 1 日 12:00。

多时间段定义

系统支持在单条规则中指定多个时间段，时间段之间使用逗号分隔，例如 daily 09:00:00 - 12:00:00，daily 14:00:00 - 18:00:00。系统会根据当前时间匹配时间段，满足任一时间段即视为匹配成功。

时间段格式示例

示例含义
yearly 03-01 12:00:00 - 11-30 23:00:00每年 3 月 1 日 12:00 至 11 月 30 日 23:00
weekly Monday 12:00:00 - Wednesday 18:00:00每周一中午至周三晚上
monthly 01 12:00:00 - 15 18:00:00每月 1 日中午至 15 日 18:00
daily 12:00:00 - 18:00:00每日中午至 18:00
daily 18:00:00 - 02:00:00每日 18:00 至次日凌晨 2:00

支持的认证方式

方法名称描述特性是否需要 SSL
cert基于客户端证书进行身份验证高安全性、不可伪造是
cert+password同时要求证书和密码验证（双因子）最高安全级别是
cert-password（默认设置）可选择使用证书或密码验证灵活、兼顾迁移场景是
password基于用户名密码验证常见方式、便于管理是
gss使用 GSSAPI 进行身份验证。GSSAPI 身份认证支持设置 include_realm 验证选项。当 include_realm 设置为 0 时，系统会从 Kerberos 主体名称中去除域名（Realm）部分。这样系统可以只使用主体名的主要部分（通常是用户名）来进行认证和授权，而无需考虑完整的 Kerberos 领域。应用程序独立于底层安全协议，通过标准接口交互是
trust允许满足匹配规则的连接开发测试方便，安全性低否
reject拒绝满足匹配规则的连接精确控制访问黑名单否

说明

使用密码认证时，由于密码以明文形式从客户端发送到服务器端，为确保密码安全，需要使用 SSL 加密连接。客户端工具提示输入用户密码时不会回显输入的密码。

配置示例

本节提供 KaiwuDB 常见身份认证方式的配置示例，展示如何配置不同的认证方式并使用 kwbase CLI 工具连接数据库。

说明

以下示例假设已采用 TLS 安全模式部署并启动 KaiwuDB 数据库。

基于密码的身份认证

非三权分立模式

  1. root 用户登录数据库。

  2. root 用户创建用户并为用户设置密码。

    以下示例创建 user1 用户，并为 user1 用户设置密码。

    CREATE USER user1 WITH PASSWORD '11aa!!AA';

  3. root 用户配置基于密码的认证参数。

    以下示例允许 user1 用户在任意时间段使用密码登录数据库。

    SET CLUSTER SETTING server.host_based_authentication.configuration = "host all user1 all all password";

  4. user1 用户连接数据库。

    ./kwbase sql --url "postgresql://user1:KaiwuDB_u1@localhost:26257/defaultdb" -u user1;
-- 按照提示 Enter password: ，输入正确的密码，回车即可连接成功。

三权分立模式

  1. secroot 用户登录数据库。

  2. secroot 用户授予 sysroot 用户创建角色的权限。

    ALTER USER sysroot WITH CREATEROLE;

  3. secroot 用户配置基于密码的认证参数。

    以下示例允许 user1 用户在每年 3 月 1 日 09:00 至 3 月 31 日 18:00 期间使用密码登录数据库。

    SET CLUSTER SETTING server.host_based_authentication.configuration = "host all user1 'yearly 03-01 09:00:00 - 03-31 18:00:00' all password";

  4. secroot 用户退出数据库。

  5. sysroot 用户登录数据库。

  6. sysroot 用户创建用户并为用户设置密码。

    以下示例创建 user1 用户，并为 user1 用户设置密码。

    CREATE USER user1 WITH PASSWORD '11aa!!AA';

  7. user1 用户在允许的时间段内连接数据库。

    ./kwbase sql --url "postgresql://user1:KaiwuDB_u1@localhost:26257/defaultdb" -u user1;
-- 按照提示 Enter password: ，输入正确的密码，回车即可连接成功。

基于证书的身份认证

非三权分立模式

  1. root 用户登录数据库。

  2. root 用户创建用户。

    以下示例创建 user2 用户。

    CREATE USER user2;

  3. root 用户配置认证参数。

    以下示例允许 user2 用户在每周周一 09:00 至周五 18:00 期间使用证书登录数据库。

    SET CLUSTER SETTING server.host_based_authentication.configuration = "host all user2 'weekly Monday 09:00:00 - Friday 18:00:00' all cert";

  4. root 用户为用户生成证书。

    ./kwbase cert create-client user2 --certs-dir=certs --ca-key=certs/ca.key

  5. user2 用户在允许的时间段内连接数据库。

    ./kwbase sql --url "postgresql://user2:KaiwuDB_u2@localhost:26257/defaultdb?sslmode=require&sslrootcert=certs/ca.crt&sslcert=certs/client.user2.crt&sslkey=certs/client.user2.key"

三权分立模式

  1. secroot 用户登录数据库。

  2. secroot 用户授予 sysroot 用户创建角色的权限。

    ALTER USER sysroot WITH CREATEROLE;

  3. secroot 用户配置认证参数。

    以下示例允许 user2 用户每天 09:00 至 18:00 期间使用证书登录数据库。

    SET CLUSTER SETTING server.host_based_authentication.configuration = "host all user2 'daily 09:00:00 - 18:00:00' all cert";

  4. secroot 用户退出数据库。

  5. sysroot 用户登录数据库。

  6. sysroot 用户创建用户。

    以下示例创建 user2 用户。

    CREATE USER user2;

  7. sysroot 用户为用户生成证书。

    ./kwbase cert create-client user2 --certs-dir=certs --ca-key=certs/ca.key

  8. user2 用户在允许的时间段内连接数据库。

    ./kwbase sql --url "postgresql://user2:KaiwuDB_u2@localhost:26257/defaultdb?sslmode=require&sslrootcert=certs/ca.crt&sslcert=certs/client.user2.crt&sslkey=certs/client.user2.key"

双因子身份认证

非三权分立模式

  1. root 用户登录数据库。

  2. root 用户创建用户并为用户设置密码。

    以下示例创建 user3 用户并为 user3 用户设置密码。

    CREATE USER user3 WITH PASSWORD '22bb!!BB';

  3. root 用户配置认证参数。

    以下示例允许 user3 用户每天 18:00 至次日 2:00 期间使用密码和证书登录数据库。

    SET CLUSTER SETTING server.host_based_authentication.configuration = "host all user3 'daily 18:00:00 - 02:00:00' all cert+password";

  4. root 用户为用户生成证书。

    ./kwbase cert create-client user3 --certs-dir=certs --ca-key=certs/ca.key;

  5. user3 用户在允许的时间段内连接数据库。

    ./kwbase sql --url "postgresql://user3:KaiwuDB_u3@localhost:26257/defaultdb?sslmode=require&sslrootcert=certs/ca.crt&sslcert=certs/client.user3.crt&sslkey=certs/client.user3.key";
-- 按照提示 Enter password: ，输入正确的密码，回车即可连接成功。

三权分立模式

  1. secroot 用户登录数据库。

  2. secroot 用户授予 sysroot 用户创建角色的权限。

    ALTER USER sysroot WITH CREATEROLE;

  3. secroot 用户配置认证参数。

    以下示例允许 user3 用户每天 18:00 至次日 2:00 期间使用密码和证书登录数据库。

    SET CLUSTER SETTING server.host_based_authentication.configuration = "host all user3 'daily 18:00:00 - 02:00:00' all cert+password";

  4. secroot 用户退出数据库。

  5. sysroot 用户登录数据库。

  6. sysroot 用户创建用户并为用户设置密码。

    以下示例创建 user3 用户并为 user3 用户设置密码。

    CREATE USER user3 WITH PASSWORD '22bb!!BB';

  7. sysroot 用户为用户生成证书。

    ./kwbase cert create-client user3 --certs-dir=certs --ca-key=certs/ca.key;

  8. user3 用户在允许的时间段内连接数据库。

    ./kwbase sql --url "postgresql://user3:KaiwuDB_u3@localhost:26257/defaultdb?sslmode=require&sslrootcert=certs/ca.crt&sslcert=certs/client.user3.crt&sslkey=certs/client.user3.key";
-- 按照提示 Enter password: ，输入正确的密码，回车即可连接成功。

GSSAPI 身份认证

通用安全服务应用程序接口（Generic Security Service Application Program Interface，GSSAPI）是一种用于在应用程序之间进行安全通信的标准接口。KaiwuDB 支持通过调用 GSSAPI 接口，使用 Kerberos 协议实现用户身份鉴别以及安全的登录和通信。 使用 GSSAPI 进行用户身份认证，需要完成以下配置：

  • Kerberos 服务器
    • 安装 Kerberos 服务器和 Kerberos 管理服务器。
    • 配置 Kerberos 服务。
  • KaiwuDB 服务器或 KaiwuDB 数据库集群
    • 创建证书，启用 GSSAPI 身份认证。
    • 创建用户并向用户授权。
    • 配置 Kerberos 服务。
  • KaiwuDB 客户端
    • 安装和配置 Kerberos 客户端。
    • 生成 KaiwuDB 用户的票据。
    • 使用 kwbase CLI 工具连接 KaiwuDB 数据库。

说明

Kerberos 服务器、KaiwuDB 服务器和 KaiwuDB 客户端位于同一主机和不同主机时，访问方式有所不同。

  • 当 Kerberos 服务器、KaiwuDB 服务器和 KaiwuDB 客户端位于同一主机时，支持使用 localhost 或 IP 地址和端口号的方式访问。
  • 当 Kerberos 服务器、KaiwuDB 服务器和 KaiwuDB 客户端位于不同主机时，只能通过 IP 地址和端口号的方式访问。

Kerberos 服务器端配置

  1. 安装 Kerberos 服务器和 Kerberos 管理服务器。

    sudo apt-get install krb5-kdc krb5-admin-server

    根据认证配置交互提示，配置以下参数。

    • 默认的 Kerberos 领域：例如 KAIWUDB.COM。
    • Kerberos 服务器（KDC）：Kerberos 服务器的主机名，例如 krb5_host。
    • Kerberos 管理服务器：Kerberos 管理服务器的主机名，例如 krb5_host。

    说明

    • Kerberos 服务器 和 Kerberos 管理服务器的取值必须保持一致。
    • 安装过程中，系统自动启动 Kerberos 服务器 和 Kerberos 管理服务器，启动失败为正常现象。

  2. 创建 Kerberos 新域。

    在此过程中，用户需要设置超级管理员密码。该密码也用于 Kerberos 客户端生成票据。

    sudo krb5_newrealm

  3. 更新 Kerberos 服务器所在主机的配置文件（/etc/hosts），添加 Realm 和访问 IP 地址的映射关系。

    //通过 localhost 访问。
127.0.0.1 krb5_host
//通过 IP 地址和端口号访问，示例中 IP 地址为 Kerberos 服务器的地址。
<krb5_host_address:ip> krb5_host

  4. （可选）命令查看 Kerberos 服务状态。

    systemctl status krb5-kdc
systemctl status krb5-admin-server

  5. 创建用户主体和服务主体。

    // 创建用户主体。
kadmin.local -q "addprinc kwuser@KAIWUDB.COM" 
// 通过 localhost 访问，创建服务主体。
kadmin.local -q "addprinc postgres/localhost@KAIWUDB.COM" 
// 通过 IP 地址和端口号访问，创建服务主体。
kadmin.local -q "addprinc postgres/kaiwu_host@KAIWUDB.COM"

  6. 为服务主体创建 Keytab 文件。

    Keytab 文件用于在不输入密码的情况下对主体（用户或服务）进行身份验证。

    // 通过 localhost 访问。
kadmin.local -q "ktadd -k keytab postgres/localhost@KAIWUDB.COM"
// 通过 IP 地址和端口号访问。
kadmin.local -q "ktadd -k keytab postgres/kaiwu_host@KAIWUDB.COM"

    创建完成后，系统会在指定目录下生成一个 Keytab 文件。用户可以自定义 Keytab 文件名，例如 krb5.keytab。用户需要将 Keytab 文件复制到 KaiwuDB 服务器主机的指定目录下。

  7. （可选）查看 Keytab 文件，确认是否配置成功。

    klist -k /path/to/file.keytab

KaiwuDB 服务器端配置

说明

  • 以下示例假设在部署并启动 KaiwuDB 数据库前，已配置从 Kerberos 服务器复制的 Keytab 文件的环境变量。用户可以使用 chmod -R 777 keytab 命令设置 Keytab 文件的权限，确保可以正常访问 Keytab 文件。

    EXPORT KRB5_KTNAME=<path_to_your_keytab_file>

  • 以下示例假设已采用 TLS 安全模式部署并启动 KaiwuDB 数据库。

非三权分立模式

  1. root 用户登录数据库。

  2. root 用户创建用户。

    以下示例创建 kwuser 用户。

    CREATE USER kwuser;

  3. root 用户为用户授权。

    以下示例授权 kwuser 用户对 defaultdb 数据库执行所有操作。

    GRANT ALL ON DATABASE defaultdb to kwuser;

  4. root 用户配置认证参数。

    以下示例允许 kwuser 用户在任意时间段通过 GSSAPI 登录数据库。

    SET CLUSTER SETTING server.host_based_authentication.configuration = "host all kwuser all all gss include_realm=0";

  5. root 用户为用户生成证书。

    ./kwbase cert create-client kwuser --certs-dir=certs --ca-key=certs/ca.key;

  6. 更新 KaiwuDB 服务器所在的主机配置文件（/etc/hosts），添加服务主体、 Kerberos 服务器和访问 IP 地址映射关系。

    // 通过 localhost 访问。
127.0.0.1 krb5_host
// 通过 IP 地址和端口号访问。注意，两个配置项的顺序不可以改变，否则系统报错。
<kaiwudb_host_address:ip> kaiwu_host
<krb5_host_address:ip> krb5_host
三权分立模式

  1. secroot 用户登录数据库。

  2. secroot 用户授予 sysroot 用户创建角色的权限。

    ALTER USER sysroot WITH CREATEROLE;

  3. secroot 用户配置基于密码的认证参数。

    以下示例允许 kwuser 用户在任意时间段通过 GSSAPI 登录数据库。

    SET CLUSTER SETTING server.host_based_authentication.configuration = "host all kwuser all all gss include_realm=0";

  4. secroot 用户退出数据库。

  5. sysroot 用户登录数据库。

  6. sysroot 用户创建用户。

    以下示例创建 kwuser 用户。

    CREATE USER kwuser;

  7. sysroot 用户为用户授权。

    以下示例授权 kwuser 用户对 defaultdb 数据库执行所有操作。

    GRANT ALL ON DATABASE defaultdb to kwuser;

  8. root 用户为用户生成证书。

    ./kwbase cert create-client kwuser --certs-dir=certs --ca-key=certs/ca.key

  9. 更新 KaiwuDB 服务器所在的主机配置文件（/etc/hosts），添加服务主体、 Kerberos 服务器和访问 IP 地址的映射关系。

    // 通过 localhost 访问。
127.0.0.1 krb5_host
// 通过 IP 地址和端口号访问。注意，两个配置项的顺序不可以改变，否则系统报错。
<kaiwudb_host_address:ip> kaiwu_host
<krb5_host_address:ip> krb5_host

KaiwuDB 客户端配置

  1. 安装并配置 Kerberos 客户端。

    说明

    Kerberos 客户端的所有配置项取值必须与 Kerberos 服务器配置保持一致。

    apt-get install krb5-user

    根据认证配置交互提示，配置以下参数。

    • 默认的 Kerberos 领域：例如 KAIWUDB.COM。
    • Kerberos 服务器（KDC）：Kerberos 服务器的主机名，例如 krb5_host。
    • Kerberos 管理服务器：Kerberos 管理服务器的主机名，例如 krb5_host。

  2. 更新 Kerberos 客户端所在主机的配置文件（/etc/hosts），添加 KaiwuDB 节点的域名、 Realm 和访问 IP 地址的映射关系。

    // 通过 localhost 访问。
127.0.0.1 krb5_host
// 通过 IP 地址和端口号访问。注意，两个配置项的顺序不可以改变，否则系统报错。
<kaiwudb_host_address:ip> kaiwu_host
<krb5_host_address:ip> krb5_host

  3. 生成票据。

    在此过程中，用户需要输入密码。该密码是创建 Kerberos 领域时设置的超级管理员密码。

    sudo kinit kwuser

  4. 查看票据。

    sudo klist

  5. kwuser 用户连接数据库。

    # 通过 localhost 访问。
./kwbase sql --url "postgresql://kwuser@localhost:26257/defaultdb?sslmode=verify-full&sslrootcert=certs/ca.crt";
# 通过 IP 地址和端口号访问
./kwbase sql --url "postgresql://kwuser@kaiwu_host:26258/defaultdb?sslmode=verify-full&sslrootcert=certs/ca.crt";

    说明

    如需使用 psql CLI 工具连接 KaiwuDB 数据库，设置 export PGGSSENCMODE=disable 环境变量。

    # 通过 localhost 访问。
psql "postgresql://localhost:26257/defaultdb?sslmode=verify-full&sslrootcert=certs/ca.crt" -U kwuser
# 通过 IP 地址和端口号访问
psql "postgresql://kaiwu_host:26258/defaultdb?sslmode=verify-full&sslrootcert=certs/ca.crt" -U kwuser

故障处理

报错信息故障说明
Key table entry not found在启动 KaiwuDB 之前，必须先配置 Keytab 文件，否则系统无法找到 keytab 文件。建议在重启 KaiwuDB 之后，也重新配置环境变量。
psql: error: connection to server at "localhost" (127.0.0.1), port 26257 failed: server closed the connection unexpectedly设置 export PGGSSENCMODE=disable 参数后才能通过 psql CLI 工具连接 KaiwuDB 数据库。
klist: No credentials cache foundKerberos 服务器配置文件（/etc/krb5.conf） 中 KDC 和 KAIWUDB.COM 名称不一致。
kinit: Cannot contact any KDC for realm 'KAIWUDB.COM' while getting initial credentialsKerberos 服务器配置文件（/etc/krb5.conf） 中 KDC 和 KAIWUDB.COM 名称不一致。
psql: error: could not translate host name "kaiwu_host" to address: Name or service not known主机配置文件（/etc/hosts）中未添加 kaiwu_host 参数。
psql: error: connection to server at "kaiwu_host" (10.180.154.177), port 26258 failed: GSSAPI continuation error: Unspecified GSS failure. Minor code may provide more information: Cannot contact any KDC for realm 'KAIWUDB.COM'主机配置文件（/etc/hosts）中未添加 realm_name 参数。
Error: pq: failed to get Kerberos ticket: "lookup 10.110.105.233: no such host"使用 IP 地址登录数据库时，可能会出现该报错。这与安装的 Kerberos 版本有关。建议使用 kaiwu_host 域名登录。例如 ./kwbase sql --url "postgresql://kwuser@kaiwu_host:36257/defaultdb?sslmode=verify-full&sslrootcert=certs/ca.crt"。