SpringBoot(Java17)集成Gmail OAuth2.0读邮件遇凭证无效问题

我在SpringBoot（Java17）项目中实现Gmail邮件读取的Google OAuth2.0安全认证，目前用普通邮箱+应用密码能正常连接，但用OAuth2.0访问令牌时出现无效凭证错误，还触发未连接异常。

相关代码 #

Credential credential = gmailOAuth2Config.authorize();
String oauthToken = credential.getAccessToken();

String oauth2Token = "user=" + gmailEmail + "
auth=Bearer " + oauthToken + "

";
String base64AuthString = Base64.getEncoder().encodeToString(oauth2Token.getBytes(StandardCharsets.UTF_8));
System.out.println("Encoded SASL XOAUTH2 Token: " + base64AuthString);

Properties props = new Properties();
props.put("mail.imap.ssl.enable", "true");
props.put("mail.imap.sasl.enable", "true");
props.put("mail.imap.auth.mechanisms", "XOAUTH2");
props.put("mail.imap.auth.login.disable", "true");
props.put("mail.imap.auth.plain.disable", "true");

Session emailSession = Session.getInstance(props);
Store store = emailSession.getStore("imap");
//Store store = emailSession.getStore("imaps"); works!

try {
    store.connect("imap.gmail.com", gmailEmail, base64AuthString );
    store.connect("imap.gmail.com", gmailEmail, gmailPassword);//works
    System.out.println("Connected successfully to Gmail IMAP.");
} catch (jakarta.mail.AuthenticationFailedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
}

报错信息 #

2024-11-14T10:12:19.207+05:30 ERROR 11772 --- [emailservice] [   scheduling-1] c.d.emailservice.service.EmailService    : An error occurred while reading email inbox: Not connected

java.lang.IllegalStateException: Not connected
    at com.sun.mail.imap.IMAPStore.checkConnected(IMAPStore.java:1960) ~[jakarta.mail-2.0.1.jar:2.0.1]
    at com.sun.mail.imap.IMAPStore.getFolder(IMAPStore.java:1737) ~[jakarta.mail-2.0.1.jar:2.0.1]
    at com.doxmate.emailservice.service.EmailService.readEmail(EmailService.java:97) ~[classes/:na]
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:na]
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77) ~[na:na]
    at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[na:na]
    at java.base/java.lang.reflect.Method.invoke(Method.java:568) ~[na:na]
    at org.springframework.scheduling.support.ScheduledMethodRunnable.runInternal(ScheduledMethodRunnable.java:130) ~[spring-context-6.1.14.jar:6.1.14]
    at 

问题分析与修复步骤 #

1. 移除重复的connect调用
   代码中连续调用两次store.connect()，第一次OAuth2连接失败后，第二次用应用密码覆盖的操作会导致连接状态混乱。必须删除应用密码的connect语句，只保留OAuth2令牌的连接尝试。

2. 修复XOAUTH2令牌格式
   构建令牌时的分隔符是ASCII控制字符SOH（十六进制0x01），直接写
可能存在编码兼容问题，建议用\u0001显式表示：

   String oauth2Token = "user=" + gmailEmail + "\u0001auth=Bearer " + oauthToken + "\u0001\u0001";
   

3. 校验OAuth2权限范围
   检查Google Cloud项目中OAuth2客户端的授权范围，必须包含https://mail.google.com/或https://www.googleapis.com/auth/gmail.readonly，缺少权限会直接导致无效凭证错误。

4. 统一IMAP Store类型
   注释的getStore("imaps")能正常工作，建议直接使用imaps（默认SSL启用，端口993），简化配置：

   Store store = emailSession.getStore("imaps");
   

   同时可移除mail.imap.ssl.enable=true，因为imaps默认启用SSL。

5. 开启调试日志排查细节
   添加JavaMail调试配置，查看IMAP交互的具体错误信息：

   props.put("mail.debug", "true");
   

修复后的代码示例 #

Credential credential = gmailOAuth2Config.authorize();
String oauthToken = credential.getAccessToken();

// 用\u0001显式表示SOH分隔符
String oauth2Token = "user=" + gmailEmail + "\u0001auth=Bearer " + oauthToken + "\u0001\u0001";
String base64AuthString = Base64.getEncoder().encodeToString(oauth2Token.getBytes(StandardCharsets.UTF_8));
System.out.println("Encoded SASL XOAUTH2 Token: " + base64AuthString);

Properties props = new Properties();
props.put("mail.imap.sasl.enable", "true");
props.put("mail.imap.auth.mechanisms", "XOAUTH2");
props.put("mail.imap.auth.login.disable", "true");
props.put("mail.imap.auth.plain.disable", "true");
props.put("mail.debug", "true"); // 开启调试日志

Session emailSession = Session.getInstance(props);
Store store = emailSession.getStore("imaps"); // 使用imaps协议

try {
    store.connect("imap.gmail.com", gmailEmail, base64AuthString);
    System.out.println("Connected successfully to Gmail IMAP.");
    // 后续执行文件夹获取、邮件读取操作
} catch (jakarta.mail.AuthenticationFailedException e) {
    System.err.println("Authentication failed: " + e.getMessage());
} catch (Exception e) {
    System.err.println("Connection error: " + e.getMessage());
}

内容的提问来源于stack exchange，提问作者Jordan Fernando