openGauss数据库连接报错：SCRAM机制不被客户端支持

Question

**问题描述：** 在使用客户端工具或应用程序连接openGauss数据库时，出现连接失败错误，提示“SCRAM mechanism not supported by client”或类似信息。该问题通常发生在openGauss启用了基于SCRAM（Salted Challenge Response Authentication Mechanism）的认证机制，而连接客户端不支持该认证方式的情况下。常见于旧版本的JDBC驱动、psql工具或第三方数据库连接工具。需如何排查并解决客户端与服务端认证机制不兼容的问题？

Answer 1

一、问题概述：SCRAM认证机制不被客户端支持

在使用客户端工具连接openGauss数据库时，出现错误提示：“SCRAM mechanism not supported by client”，表明客户端不支持服务端所启用的SCRAM认证机制。该问题通常出现在旧版本JDBC驱动、psql工具或第三方数据库连接工具中。

1.1 SCRAM认证机制简介

SCRAM（Salted Challenge Response Authentication Mechanism）是一种基于挑战-响应机制的认证协议，具备较高的安全性，广泛用于现代数据库系统中。openGauss自特定版本起默认启用SCRAM认证方式。

1.2 常见报错信息

• SCRAM mechanism not supported by client
• Authentication failed: unsupported authentication method
• connection refused due to authentication failure

二、问题分析：客户端与服务端认证机制不兼容

2.1 服务端配置检查

openGauss的认证方式通常在pg_hba.conf文件中配置，需检查是否启用了SCRAM认证方式。例如：

local   all             all                                     scram-sha-256

2.2 客户端支持情况分析

SCRAM认证需要客户端驱动或工具版本支持。例如：

客户端工具/驱动	是否支持SCRAM	建议版本
JDBC驱动（JDBC 42.2.5以下）	否	升级至42.2.5及以上
psql工具（openGauss自带）	是	建议使用最新版
DBeaver等第三方工具	部分支持	需确认驱动版本

2.3 连接方式与协议兼容性

某些连接方式（如通过JDBC URL连接）可能因协议版本不兼容导致认证失败。需检查连接字符串是否包含必要的参数，如preferType或sslmode。

三、解决方案与操作步骤

3.1 升级客户端驱动或工具版本

若客户端使用旧版本JDBC驱动，需升级至支持SCRAM的版本：

<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.2.5</version>
</dependency>

3.2 修改openGauss服务端认证方式

如短期内无法升级客户端，可临时将认证方式降级为MD5或Trust：

# 修改 pg_hba.conf 文件
local   all             all                                     trust

修改后需执行gs_ctl reload命令使配置生效。

3.3 使用兼容模式连接

部分客户端可通过配置连接参数启用兼容模式。例如JDBC连接字符串中添加：

jdbc:postgresql://localhost:5432/db?preferType=SCRAM-SHA-256

3.4 检查SSL配置

某些客户端要求SSL连接时才支持SCRAM认证，需在连接参数中启用SSL：

sslmode=require

四、流程图：SCRAM连接失败问题排查流程

graph TD
A[连接失败提示SCRAM机制不支持] --> B{是否使用最新客户端驱动？}
B -- 是 --> C{是否启用SCRAM认证？}
B -- 否 --> D[升级客户端驱动或工具]
C -- 是 --> E[尝试修改服务端认证为MD5或Trust]
C -- 否 --> F[检查连接参数是否启用SSL或兼容模式]
E --> G[重启服务并测试连接]
F --> H[调整连接参数后重试]