迁移微软授权代码流 `client_secret` 到 PKCE by CiiLu · Pull Request #5575 · HMCL-dev/HMCL

CiiLu · 2026-02-19T14:23:50Z

resolves #5566

https://learn.microsoft.com/zh-cn/entra/identity-platform/v2-oauth2-auth-code-flow

请不要在本机应用或单页应用中使用应用程序机密，因为 client_secret 无法可靠地存储在设备上。

兑换授权代码时，公共客户端（包括本机应用程序和单页应用）不得使用机密或证书。

目前建议将参数（code_challenge）用于所有应用程序类型（公共和机密客户端）

需要黄鱼在 entra 进行一些配置

huanghongxun · 2026-02-19T14:48:23Z

更新后，Microsoft Auth Server 是如何验证 client 是 HMCL？我看请求参数内只传递 client_id，不再传递 client_secret 了。
看起来生成codeVerifier和应用本身没啥关系？

CiiLu · 2026-02-19T15:20:49Z

看起来生成codeVerifier和应用本身没啥关系？

是。

本地应用不能安全保存 client_secret，所以不靠 secret 认证，而是用 PKCE。Authorization Code 会和 code_challenge 绑定，只有能提供匹配 code_verifier 的一方才能换到 token。

这里目的不是用来证明 client 就是 HMCL，而是用来证明当前换 token 的 client 是最初发起请求的 client ，目的是解决 Authorization Code 被截获后被他人兑换的问题。

huanghongxun · 2026-02-20T15:10:11Z

需要在entra上配置什么呢？client_secret不需要的话，已经不需要再换客户端证书了吧？

CiiLu · 2026-02-20T15:45:37Z

这个位置，HMCL 现在使用的应该是 Web / 单页应用程序，是需要 secret 的，换成移动和桌面应用程序应该就可以使用 PKCE 了。

可能需要注意一下旧版本兼容问题。

huanghongxun · 2026-02-20T22:54:13Z

所以是给移动桌面应用程序分类，将原来Web的RedirectURI重新添加一遍？

CiiLu · 2026-02-21T01:06:24Z

是，但是这样会导致旧版本在登录时直接报错（目前的问题是在之后刷新时报错）

~~所以本 PR 中同时更改了端口，目前为这几个 URI~~
~~http://localhost:29712/auth-response~~
~~http://localhost:29713/auth-response~~
~~http://localhost:29714/auth-response~~
~~http://localhost:29715/auth-response~~
~~http://localhost:29716/auth-response~~
~~需要保留旧版本登录兼容性的话原来的 Web URI 不用删除，只需要再移动和桌面应用程序添加这几个就行~~

Copilot

Pull request overview

将微软 OAuth 授权码流程从依赖 client_secret 迁移到 PKCE（S256），以符合公共客户端最佳实践并避免刷新时必须携带机密导致的失败（#5566）。

Changes:

在授权码登录流程中加入 PKCE：生成 code_challenge（S256）并在换取 token 时提交 code_verifier
刷新 token 请求中移除 client_secret 相关逻辑，并同步删除构建时注入的 secret 配置
在本地回调服务器 OAuthServer 中生成并保存 code_verifier

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
HMCLCore/src/main/java/org/jackhuang/hmcl/auth/OAuth.java	授权码流程增加 PKCE 参数；刷新流程移除 `client_secret`；新增 `generateCodeChallenge` 与 `Session#getCodeVerifier`
HMCL/src/main/java/org/jackhuang/hmcl/game/OAuthServer.java	生成并提供 PKCE `code_verifier`（通过 `OAuth.Session`）
HMCL/build.gradle.kts	删除微软授权 secret 的环境变量/属性注入

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-21T12:48:21Z

HMCLCore/src/main/java/org/jackhuang/hmcl/auth/OAuth.java

        options.callback.openBrowser(GrantFlow.AUTHORIZATION_CODE, NetworkUtils.withQuery(authorizationURL,
-                mapOf(pair("client_id", options.callback.getClientId()), pair("response_type", "code"),
-                        pair("redirect_uri", session.getRedirectURI()), pair("scope", options.scope),
-                        pair("prompt", "select_account"))));
+                mapOf(pair("client_id", options.callback.getClientId()),
+                        pair("response_type", "code"),
+                        pair("redirect_uri", session.getRedirectURI()),
+                        pair("scope", options.scope),
+                        pair("prompt", "select_account"),
+                        pair("code_challenge", codeChallenge),
+                        pair("code_challenge_method", "S256")
+                )));


Authorization code flow adds PKCE, but the request still omits the OAuth state parameter. Without generating and validating state, the localhost callback can be vulnerable to CSRF/login-swapping (accepting a code not initiated by this client). Consider generating a random state per auth attempt, include it in the authorize URL, and verify it in the callback handler before accepting the code.

Copilot · 2026-02-21T12:48:21Z

HMCL/src/main/java/org/jackhuang/hmcl/game/OAuthServer.java

@@ -52,6 +55,20 @@ private OAuthServer(int port) {
        super(port);

        this.port = port;
+        this.codeVerifier = generateCodeVerifier();
+    }
+
+    // https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+    private String generateCodeVerifier() {
+        SecureRandom sr = new SecureRandom();
+        byte[] code = new byte[64];
+        sr.nextBytes(code);
+        return Base64.getUrlEncoder().withoutPadding().encodeToString(code);
+    }
+
+    @Override
+    public String getCodeVerifier() {
+        return codeVerifier;
    }


PKCE verifier is generated and stored, but there is still no per-request state nonce stored on the session and validated in serve() before completing the future. Adding a state field here (and exposing it via OAuth.Session, e.g. getState()) would allow the authorize URL to include state and the callback to reject mismatches.

Glavo · 2026-02-21T13:33:40Z

HMCL/src/main/java/org/jackhuang/hmcl/game/OAuthServer.java

+
+    // https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+    private String generateCodeVerifier() {
+        SecureRandom sr = new SecureRandom();


为什么这里两个随机数用两种风格的写法？另外 generateState 和 generateCodeVerifier 是不是共享一个 SecureRandom 实例更好？

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

HMCL/src/main/java/org/jackhuang/hmcl/game/OAuthServer.java

HMCLCore/src/main/java/org/jackhuang/hmcl/auth/OAuth.java

Copilot · 2026-02-21T13:35:42Z

HMCLCore/src/main/java/org/jackhuang/hmcl/auth/OAuth.java

+        try {
+            byte[] bytes = codeVerifier.getBytes(StandardCharsets.US_ASCII);
+            MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
+            messageDigest.update(bytes, 0, bytes.length);
+            byte[] digest = messageDigest.digest();
+            return Base64.getUrlEncoder().withoutPadding().encodeToString(digest);
+        } catch (Exception e) {
+            LOG.warning("Failed to generate code challenge", e);
+            throw new RuntimeException(e);
+        }


generateCodeChallenge catches a broad Exception, logs, and then throws a generic RuntimeException. Since this is deterministic code (SHA-256 should always be available), consider narrowing the catch to NoSuchAlgorithmException (or treating it as an AssertionError/IllegalStateException) so unexpected runtime errors aren’t accidentally swallowed and rethrown with less context.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-21T13:58:10Z

HMCL/src/main/java/org/jackhuang/hmcl/game/OAuthServer.java

+        if (!this.state.equals(query.get("state")))
+            future.completeExceptionally(new AuthenticationException(
+                    query.containsKey("state") ? "invalid state" : "missing state"));


The code continues executing after state validation fails. When the state doesn't match, the code should return early instead of continuing to process the request. Currently, after calling future.completeExceptionally, the code continues to lines 130-136 which may call future.complete() or future.completeExceptionally() again, causing unpredictable behavior. Add a return statement after the state validation block to prevent further execution when validation fails.

Suggested change

if (!this.state.equals(query.get("state")))

future.completeExceptionally(new AuthenticationException(

query.containsKey("state") ? "invalid state" : "missing state"));

if (!this.state.equals(query.get("state"))) {

future.completeExceptionally(new AuthenticationException(

query.containsKey("state") ? "invalid state" : "missing state"));

return newFixedLengthResponse(Response.Status.BAD_REQUEST, MIME_PLAINTEXT,

query.containsKey("state") ? "invalid state" : "missing state");

}

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

HMCL/src/main/java/org/jackhuang/hmcl/game/OAuthServer.java

CiiLu added 2 commits February 19, 2026 22:21

update

1dfbb11

update

c0da4d3

CiiLu changed the title ~~迁移微软授权代码流到 PKCE~~ 迁移微软授权代码流 client_secret 到 PKCE Feb 19, 2026

CiiLu added 2 commits February 19, 2026 22:28

fix: Checkstyle

20a7580

update

3dac94a

CiiLu marked this pull request as ready for review February 19, 2026 14:38

update

8fd626c

修改 OAuth Server 端口

78c9241

还原端口

e247143

Glavo requested a review from Copilot February 21, 2026 12:44

Copilot started reviewing on behalf of Glavo February 21, 2026 12:45 View session

Copilot AI reviewed Feb 21, 2026

View reviewed changes

Glavo mentioned this pull request Feb 21, 2026

修复无法刷新微软账户的问题 #5567

Closed

state

6965e0c

huanghongxun self-requested a review February 21, 2026 13:30

Glavo requested a review from Copilot February 21, 2026 13:31

Copilot started reviewing on behalf of Glavo February 21, 2026 13:31 View session

huanghongxun approved these changes Feb 21, 2026

View reviewed changes

Glavo reviewed Feb 21, 2026

View reviewed changes

Copilot AI reviewed Feb 21, 2026

View reviewed changes

CiiLu and others added 4 commits February 21, 2026 21:42

state

1385ce9

state

3a27464

update

4606367

update

87111ba

Glavo requested a review from Copilot February 21, 2026 13:53

Copilot started reviewing on behalf of Glavo February 21, 2026 13:53 View session

Copilot AI reviewed Feb 21, 2026

View reviewed changes

Glavo added 4 commits February 21, 2026 22:08

update

a042318

update

e5264e2

update

def58f9

update

c7f3312

Glavo requested a review from Copilot February 21, 2026 14:13

Copilot started reviewing on behalf of Glavo February 21, 2026 14:14 View session

Copilot AI reviewed Feb 21, 2026

View reviewed changes

HMCL/src/main/java/org/jackhuang/hmcl/game/OAuthServer.java Outdated Show resolved Hide resolved

update

62e906b

Glavo approved these changes Feb 21, 2026

View reviewed changes

Glavo merged commit 917d110 into HMCL-dev:main Feb 21, 2026
2 checks passed

CiiLu deleted the pkce branch February 22, 2026 15:31

Comments

Conversation

CiiLu commented Feb 19, 2026

Uh oh!

huanghongxun commented Feb 19, 2026

Uh oh!

CiiLu commented Feb 19, 2026

Uh oh!

huanghongxun commented Feb 20, 2026

Uh oh!

CiiLu commented Feb 20, 2026

Uh oh!

huanghongxun commented Feb 20, 2026

Uh oh!

CiiLu commented Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Glavo Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

CiiLu commented Feb 21, 2026 •

edited

Loading