MySQL :: MySQL Connector/C++ 开发者指南 :: 5.3 身份验证支持

版本 9.0

MySQL Connector/C++ 开发者指南 / 构建 Connector/C++ 应用程序 / 身份验证支持

5.3 身份验证支持

对于使用旧版 JDBC API（即不使用 X DevAPI 或 X DevAPI for C）连接到服务器，Connector/C++ 支持不同的客户端身份验证插件和以下身份验证方法：

LDAP 身份验证

LDAP 身份验证允许 Connector/C++（8.0.22 及更高版本）应用程序使用简单的 LDAP 身份验证或使用 SCRAM-SHA-1 身份验证方法的 SASL LDAP 身份验证连接到 MySQL 服务器。LDAP 身份验证需要使用 MySQL 企业版发行版中的服务器。有关 LDAP 身份验证插件的更多信息，请参阅 LDAP 可插拔身份验证。

Connector/C++ 二进制发行版包括提供客户端 LDAP 身份验证插件的库，以及插件所需的任何依赖库。

注意

在 Connector/C++ 8.0.23 中，删除了对 mysql-client-plugins 包的依赖。现在，只有在 Connector/C++ 应用程序使用具有 LDAP 身份验证的商业 MySQL 服务器帐户进行连接的主机上才需要此软件包。在这种情况下，还必须安装其他库：使用 RPM 软件包的安装需要 cyrus-sasl-scram，使用 Debian 软件包的安装需要 libsasl2-modules-gssapi-mit。这些 SASL 软件包提供了使用 SCRAM-SHA-256 和 GSSAPI/Kerberos 身份验证方法进行 LDAP 所需的支持。

如果 Connector/C++ 是从压缩的 tar 文件或 Zip 存档安装的，则应用程序需要将 OPT_PLUGIN_DIR 连接选项设置为相应的目录，以便可以找到捆绑的插件库。（或者，将所需的插件库复制到客户端库预期的默认目录。）

例如

sql::ConnectOptionsMap connection_properties;

// To use simple LDAP authentication ...

connection_properties["userName"] = "simple_ldap_user_name";
connection_properties["password"] = "simple_ldap_password";
connection_properties[OPT_ENABLE_CLEARTEXT_PLUGIN]=true;

// To use SASL LDAP authentication using SCRAM-SHA-1 ...

connection_properties["userName"] = "sasl_ldap_user_name";
connection_properties["password"] = "sasl_ldap_scram_password";

// Needed if Connector/C++ was installed from tar file or Zip archive ...

connection_properties[OPT_PLUGIN_DIR] = "${INSTALL_DIR}/lib{64}/plugin";

auto *driver = get_driver_instance();
auto *con = driver->connect(connection_properties);

// Execute statements ...

con->close();

Kerberos 身份验证

Kerberos 身份验证允许 Connector/C++ 应用程序为使用 authentication_kerberos 服务器端身份验证插件的帐户建立连接，前提是可以从 Kerberos 获得正确的 Kerberos 票证。此功能在运行 Linux 的客户端主机上可用（从 8.0.26 开始）。

在 Windows 上（从 8.0.32 开始），OPT_AUTHENTICATION_KERBEROS_CLIENT_MODE 连接选项可以设置为 SSPI（默认）或 GSSAPI。该选项允许在运行时为 Windows 上的 authentication_kerberos_client 身份验证插件选择 SSPI 或 GSSAPI。Connector/C++ 通过 MIT kerberos 库实现了 GSSAPI 模式，并且该模式与 Windows 上的 Java SE 安全工具（例如，klist 和 kinit 命令）兼容。在此模式下，Windows 主机上的票证搜索仅限于 MIT Kerberos 缓存。如果缓存中没有票证，即使 Windows 票证有效，连接也会失败。

以前，Connector/C++ 仅通过 Windows SSPI Kerberos 库支持 Kerberos 身份验证（从 8.0.27 开始）。SSPI 无法获取使用 kinit 命令生成的缓存凭据。在 SSPI 模式下，如果客户端用户未提供密码且身份验证方法仅考虑 Windows 票证，则使用 Windows 单点登录票证进行身份验证。如果票证丢失或无效，即使 Kerberos 缓存包含有效的票证，连接也会失败。有关更多信息，请参阅 SSPI 模式下 Windows 客户端的命令。

在以下情况下，可以在不提供用户名的情况下连接到 Kerberos 身份验证的帐户：

用户已分配 Kerberos 主体名称，该主体名称存在 MySQL Kerberos 帐户，并且用户拥有所需的票证。
必须使用 OPT_DEFAULT_AUTH 连接选项将默认身份验证方法设置为 authentication_kerberos_client 客户端身份验证插件。

可以在不提供密码的情况下进行连接，前提是用户在 Linux 上的 Kerberos 缓存或 Windows 上的 MIT Kerberos 缓存中拥有所需的票证（例如，由 kinit 或类似命令创建）。

注意

SSPI Kerberos 库与 Java SE 安全工具不兼容。要使用 kinit 命令，客户端应用程序必须将 OPT_AUTHENTICATION_KERBEROS_CLIENT_MODE 连接选项设置为 GSSAPI。

如果 Kerberos 缓存（或 MIT Kerberos 缓存）中不存在所需的票证并且提供了密码，则 Connector/C++ 将使用该密码从 Kerberos 获取票证。如果在缓存中找到了所需的票证，则将忽略提供的任何密码，并且连接可能会成功，即使密码不正确。

在运行 Windows 的客户端主机上，可以通过设置 KRB5_CONFIG 环境变量来覆盖 MIT Kerberos 配置文件的默认位置，并使用 KRB5CCNAME 环境变量覆盖默认的 MIT Kerberos 凭据缓存名称（例如，KRB5CCNAME=DIR:/mydir/）。

有关使用 MIT Kerberos 配置和缓存的详细信息，请参阅：

KRB5_CONFIG：https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html
KRB5CCNAME：https://web.mit.edu/kerberos/krb5-1.12/doc/basic/ccache_def.html

有关 Kerberos 身份验证的更多信息，请参阅 Kerberos 可插拔身份验证。

OCI 身份验证

OCI 身份验证允许 Connector/C++ 应用程序为使用 authentication_oci 服务器端身份验证插件的帐户建立无密码连接，前提是可以使用正确的配置条目映射到特定 Oracle 云基础设施租户中的唯一用户。此支持已添加到 Connector/C++ 8.0.27 版本中。

为了确保正确的帐户映射，客户端 Oracle 云基础设施配置必须包含用于身份验证的 API 密钥的指纹（fingerprint 条目）和包含 API 密钥私钥部分的 PEM 文件的位置（key_file 条目）。这两个条目都应在配置文件的 [DEFAULT] 部分中指定。在 Connector/C++ 8.0.33 中，OPT_OCI_CLIENT_CONFIG_PROFILE 连接选项允许选择配置文件中的一个部分用于身份验证。默认情况下，OPT_OCI_CLIENT_CONFIG_PROFILE 的值为 [DEFAULT] 部分。

除非使用 OPT_OCI_CONFIG_FILE 连接选项指定了配置文件的备用路径，否则将使用以下默认位置：

Linux 或 Posix 主机类型上的 ~/.oci/config
Windows 主机类型上的 %HOMEDRIVE%%HOMEPATH%/.oci/config

如果未将 MySQL 用户名作为连接选项提供，则将替换为操作系统用户名。具体来说，如果客户端存在私钥和正确的 Oracle 云基础设施配置，则可以在不提供任何选项的情况下建立连接。

为了支持 Oracle 云基础设施临时密钥身份验证，Connector/C++ 8.0.33（及更高版本）从 security_token_file 条目获取令牌文件的位置。例如：

[DEFAULT]
fingerprint=59:8a:0b[...]
key_file=~/.oci/sessions/DEFAULT/oci_api_key.pem
tenancy=ocid1.tenancy.oc1.[...]
region=us-ashburn-1
security_token_file=~/.oci/sessions/DEFAULT/token

Connector/C++ 向服务器发送一个 JSON 属性（名为 "token"），其值为从 security_token_file 字段提取的值。如果配置文件中引用的目标文件不存在，或者文件超过了指定的最大值，则 Connector/C++ 将终止操作并返回一个包含原因的异常。

在以下情况下，Connector/C++ 在 JSON 有效负载中发送一个空的令牌值：

安全令牌文件为空。
找到了配置选项 security_token_file，但配置文件中的值为空。

在所有其他情况下，Connector/C++ 会将安全令牌文件的内容完整地添加到 JSON 文档中。

多因素身份验证

从 Connector/C++ 8.0.28 开始，应用程序可以使用多因素身份验证建立连接，例如在连接时最多可以指定三个密码。可以使用 OPT_PASSWORD1、OPT_PASSWORD2 和 OPT_PASSWORD3 连接选项分别指定第一个、第二个和第三个多因素身份验证密码。

OPT_PASSWORD1 是现有 OPT_PASSWORD 选项的别名；如果同时提供了两者，则 OPT_PASSWORD 将被忽略。有关此身份验证选项的更多信息，请参阅多因素身份验证。

WebAuthn (FIDO) 身份验证

对 MySQL 服务器的 WebAuthn 身份验证支持使用网络浏览器、智能卡、安全密钥和生物识别读取器等设备。WebAuthn 身份验证支持 FIDO 和 FIDO2 标准。为了确保使用旧版 JBDC API 的客户端应用程序在用户需要与 FIDO/FIDO2 设备交互时收到通知，Connector/C++ 8.2.0（及更高版本）在 MySQL_Driver 类的 setCallback() 方法中添加了一个名为 WebAuthn_Callback 的回调参数。WebAuthn_Callback 类有一个名为 ActionRequested() 的回调方法。

class WebAuthn_Callback
{
public:

  WebAuthn_Callback(std::function<void(SQLString)>);

  /**
  * Override this message to receive WebAuthn Action Requests
  */
  virtual void ActionRequested(sql::SQLString msg);

};

为使用 WebAuthn 身份验证的帐户显式设置 WebAuthn_Callback 回调。

注意

在 Windows 上，客户端应用程序必须以管理员身份运行。这是 authentication_webauthn 插件使用的 fido2.dll 库的要求。

客户端应用程序可以通过以下两种方式从连接器获取回调：

通过将函数或 lambda 传递给 WebAuthn_Callback。

driver->setCallBack(WebAuthn_Callback([](SQLString msg) {...}));

通过实现虚拟方法 ActionRequested。

class MyWindow : public WebAuthn_Callback
{
  void ActionRequested(sql::SQLString msg) override;
};

MyWindow window;
driver->setCallBack(window);

设置新的回调将始终删除之前的回调。要禁用活动的回调并恢复默认行为，请传递 nullptr 作为函数回调。示例

driver->setCallBack(WebAuthn_Callback(nullptr));

有关 WebAuthn 身份验证的更多信息，请参阅 WebAuthn 可插拔身份验证。

注意

Connector/C++ 8.0.29 增加了 authentication_fido 支持，在 8.2.0 中弃用了它，转而支持 authentication_webauthn，并在 8.4.0 中删除了 authentication_fido 支持。为了向后兼容，Fido_Callback 回调参数仍然保留，但它会调用 WebAuthn 身份验证。