keycloak接入微信登录

约 9855 字大约 33 分钟

Keycloak SSO 微信登录

2026-10-29

📋 项目概述

本项目是一个 Keycloak SPI 扩展，用于实现微信 OAuth 登录功能。用户可以通过微信账号登录 Keycloak 管理的应用系统。

核心功能

✅ 微信 OAuth 2.0 授权登录
✅ 自动创建/关联 Keycloak 用户
✅ 支持微信用户信息同步
✅ 支持手机号绑定与短信验证码
✅ 支持开发环境 Mock 模式
✅ 环境变量配置管理
✅ Redis 缓存支持（可选）

技术栈

Java: 17
Keycloak: 26.4
构建工具: Maven
部署方式: Docker
数据库: MySQL
缓存: Redis（可选）

🏗️ 架构设计

1. 项目结构

keycloak-wx-authenticator/
├── pom.xml                                    # Maven 配置
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/vectorstory/keycloak/wechat/
│   │   │       ├── authenticator/            # 认证器实现
│   │   │       │   ├── WeChatAuthenticator.java
│   │   │       │   └── WeChatAuthenticatorFactory.java
│   │   │       ├── service/                  # 微信 API 服务
│   │   │       │   ├── WeChatOAuthService.java
│   │   │       │   ├── WeChatOAuthServiceImpl.java
│   │   │       │   └── MockWeChatOAuthService.java
│   │   │       ├── model/                    # 数据模型
│   │   │       │   ├── WeChatAccessToken.java
│   │   │       │   ├── WeChatUserInfo.java
│   │   │       │   └── VerificationCode.java
│   │   │       ├── cache/                    # 缓存层
│   │   │       │   ├── CodeCache.java
│   │   │       │   ├── StateCache.java
│   │   │       │   ├── MemoryCodeCache.java
│   │   │       │   ├── MemoryStateCache.java
│   │   │       │   ├── RedisCodeCache.java
│   │   │       │   └── RedisStateCache.java
│   │   │       ├── sms/                      # 短信服务
│   │   │       │   ├── SmsService.java
│   │   │       │   ├── MockSmsService.java
│   │   │       │   └── AliyunSmsService.java
│   │   │       └── config/                   # 配置管理
│   │   │           └── WeChatConfig.java
│   │   └── resources/
│   │       ├── META-INF/
│   │       │   └── services/
│   │       │       └── org.keycloak.authentication.AuthenticatorFactory
│   │       └── theme-resources/              # 主题资源
│   │           ├── messages/
│   │           │   ├── messages_zh_CN.properties
│   │           │   └── messages_en.properties
│   │           └── templates/
│   │               ├── wechat-login-button.ftl
│   │               ├── wechat-bind-phone.ftl
│   │               └── wechat-bind-code.ftl
│   └── test/
│       └── java/
└── target/                                    # 构建输出
    └── keycloak-wx-authenticator-1.0.0.jar

2. 核心组件说明

2.1 WeChatAuthenticator（认证器）

实现 org.keycloak.authentication.Authenticator 接口
处理微信 OAuth 授权流程
管理用户创建和关联逻辑
首次登录引导手机号绑定与短信校验

2.2 WeChatAuthenticatorFactory（工厂类）

实现 org.keycloak.authentication.AuthenticatorFactory 接口
向 Keycloak 注册认证器
提供元数据和配置信息

2.3 WeChatOAuthService（微信 API 服务）

封装微信 OAuth API 调用
支持多种微信平台（开放平台/公众平台/企业微信）
提供 Mock 实现用于开发测试

2.4 StateCache（状态缓存）

存储 OAuth state 参数（防 CSRF）
提供内存和 Redis 两种实现
支持过期时间管理

2.5 CodeCache（短信验证码缓存）

存储短信验证码与发送频率
支持内存与 Redis 实现
支持验证码过期与重试次数限制

2.6 SmsService（短信服务）

发送手机号验证码
提供 Mock 与阿里云实现

🔧 开发环境准备

1. 前置要求

必需软件

# Java 17
java -version
# 输出应包含: openjdk version "17.x.x"

# Maven 3.6+
mvn -version

# Docker 和 Docker Compose
docker --version
docker compose --version

外部服务

# MySQL 容器（需要先启动）
# 确保创建了 mysql_mysql-network 网络
docker network ls | grep mysql_mysql-network

# Redis 容器（可选，推荐用于生产环境）
# 确保创建了 redis_redis-network 网络
docker network ls | grep redis_redis-network

2. 微信平台配置

选择微信平台类型

根据您的应用场景，选择合适的微信平台：

2.1 微信开放平台（推荐用于网页应用）

适用场景: 网站、H5 页面、移动 App

注册步骤:

访问微信开放平台
注册开发者账号（需要企业认证，¥300/年）
创建网站应用
填写应用信息：
- 应用名称：您的应用名称
- 应用简介：应用描述
- 应用官网：https://your-domain.com
- 授权回调域：your-domain.com（重要！）
等待审核（1-3 个工作日）
审核通过后获取：
- AppID: wx1234567890abcdef
- AppSecret: your_app_secret_32_chars

回调 URL 格式:

https://your-domain.com/realms/{realm-name}/login-actions/authenticate

2.2 微信公众平台（用于公众号内）

适用场景: 微信公众号内的网页

注册步骤:

访问微信公众平台
注册公众号（服务号支持网页授权）
开发 → 接口权限 → 网页授权
设置网页授权域名：your-domain.com
获取：
- AppID: 在开发 → 基本配置中查看
- AppSecret: 在开发 → 基本配置中生成

2.3 企业微信（用于企业内部应用）

适用场景: 企业内部 OA 系统

注册步骤:

访问企业微信
注册企业
应用管理 → 创建应用
获取：
- CorpID: 企业 ID
- AgentID: 应用 ID
- Secret: 应用密钥

2.4 开发环境配置（Mock 模式）

如果暂时没有微信平台账号，可以使用 Mock 模式进行开发：

WECHAT_SERVICE_MOCK=true
WECHAT_APP_ID=mock_app_id
WECHAT_APP_SECRET=mock_app_secret
SMS_SERVICE_MOCK=true

Mock 模式下：

不会真实调用微信 API
会模拟返回固定的用户信息
首次登录进入手机号绑定，验证码会打印到日志
所有操作日志会打印到 Keycloak 日志中

3. 本地环境配置

3.1 创建环境变量文件

在项目根目录（keycloak-groups/）的 .env 文件中添加微信相关配置：

# ========================================
# 微信 OAuth 配置
# ========================================

# Mock 模式（开发环境：true，生产环境：false）
# true: 不调用真实微信 API，使用模拟数据
# false: 调用真实微信 OAuth API
WECHAT_SERVICE_MOCK=true

# 微信平台类型
# 可选值：open（开放平台）, official（公众平台）, work（企业微信）
WECHAT_PLATFORM_TYPE=open

# 微信应用凭证（从微信平台获取）
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=your_app_secret_here

# 微信授权回调 URL
# 当前实现默认使用 Keycloak action URL
# 如需兼容旧版本或自定义逻辑可保留
WECHAT_REDIRECT_URI=http://localhost:8081/realms/vectorstory-test/login-actions/authenticate

# 微信 OAuth 作用域
# snsapi_login: 静默授权（开放平台）
# snsapi_userinfo: 获取用户信息（需用户同意）
WECHAT_SCOPE=snsapi_login

# State 参数过期时间（秒）
WECHAT_STATE_EXPIRE_TIME=300

# ========================================
# 短信服务配置
# ========================================
# true: Mock 短信（验证码打印到日志）
# false: 使用阿里云短信
SMS_SERVICE_MOCK=true

# 阿里云短信（SMS_SERVICE_MOCK=false 时必填）
ALIYUN_ACCESS_KEY_ID=your_key_id
ALIYUN_ACCESS_KEY_SECRET=your_key_secret
ALIYUN_SMS_SIGN_NAME=your_sign_name
ALIYUN_SMS_TEMPLATE_CODE=your_template_code

# 可选：手机号/验证码规则
PHONE_NUMBER_REGEX=^1[3-9]\d{9}$
VERIFICATION_CODE_LENGTH=6

# ========================================
# Redis 缓存配置（state + 短信验证码）
# ========================================
# USE_REDIS_CACHE=true 时启用
USE_REDIS_CACHE=false
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DATABASE=0

3.2 本地调试 HTTPS 回调（重要！）

问题: 微信 OAuth 要求回调地址必须是 HTTPS 协议，但本地开发环境通常使用 HTTP。

解决方案: 我们提供了多种本地调试方案，请参考详细指南：

📖 本地调试完整指南(LOCAL_DEBUG_GUIDE.md,内部资料未随博客发布)

快速方案选择：

开发阶段	推荐方案	说明
初期开发	Mock 模式	无需真实微信账号，快速迭代
OAuth 测试	ngrok	免费，真实微信 OAuth 流程
稳定开发	Cloudflare Tunnel	免费，固定域名，团队共享

快速开始 - ngrok 示例:

# 1. 安装 ngrok
brew install ngrok  # macOS

# 2. 注册并配置（一次性）
ngrok config add-authtoken YOUR_AUTHTOKEN

# 3. 启动隧道
ngrok http 8081

# 4. 获得 HTTPS URL
# Forwarding https://abc123.ngrok-free.app -> http://localhost:8081

# 5. 更新环境变量（可选）
WECHAT_REDIRECT_URI=https://abc123.ngrok-free.app/realms/vectorstory-test/login-actions/authenticate
#
# 说明：回调地址默认由 Keycloak action URL 生成，WECHAT_REDIRECT_URI 仅用于兼容或自定义逻辑

# 6. 在微信平台配置授权回调域
# 填入: abc123.ngrok-free.app （不含 https://）

详细步骤、其他方案和常见问题请查看: LOCAL_DEBUG_GUIDE.md(内部资料,未随博客发布)

💻 开发步骤

步骤 1: 配置 pom.xml

更新 pom.xml 文件，添加必要的依赖：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.vectorstory</groupId>
    <artifactId>keycloak-wx-authenticator</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <name>Keycloak WeChat Authenticator</name>
    <description>Keycloak SPI for WeChat OAuth authentication</description>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <keycloak.version>26.0.4</keycloak.version>
        <jedis.version>5.1.0</jedis.version>
        <slf4j.version>2.0.9</slf4j.version>
    </properties>

    <dependencies>
        <!-- Keycloak SPI 依赖 -->
        <dependency>
            <groupId>org.keycloak</groupId>
            <artifactId>keycloak-core</artifactId>
            <version>${keycloak.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.keycloak</groupId>
            <artifactId>keycloak-server-spi</artifactId>
            <version>${keycloak.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.keycloak</groupId>
            <artifactId>keycloak-server-spi-private</artifactId>
            <version>${keycloak.version}</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.keycloak</groupId>
            <artifactId>keycloak-services</artifactId>
            <version>${keycloak.version}</version>
            <scope>provided</scope>
        </dependency>

        <!-- HTTP 客户端（用于调用微信 API） -->
        <dependency>
            <groupId>com.squareup.okhttp3</groupId>
            <artifactId>okhttp</artifactId>
            <version>4.12.0</version>
        </dependency>

        <!-- JSON 处理 -->
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.10.1</version>
        </dependency>

        <!-- Redis 客户端（可选，用于生产环境缓存） -->
        <dependency>
            <groupId>redis.clients</groupId>
            <artifactId>jedis</artifactId>
            <version>${jedis.version}</version>
        </dependency>

        <!-- 日志 -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>${slf4j.version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <finalName>${project.artifactId}-${project.version}</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                </configuration>
            </plugin>

            <!-- Maven Shade Plugin - 打包依赖到 JAR -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.5.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <artifactSet>
                                <includes>
                                    <include>com.squareup.okhttp3:*</include>
                                    <include>com.squareup.okio:*</include>
                                    <include>com.google.code.gson:*</include>
                                    <include>redis.clients:*</include>
                                    <include>org.apache.commons:*</include>
                                </includes>
                            </artifactSet>
                            <filters>
                                <filter>
                                    <artifact>*:*</artifact>
                                    <excludes>
                                        <exclude>META-INF/*.SF</exclude>
                                        <exclude>META-INF/*.DSA</exclude>
                                        <exclude>META-INF/*.RSA</exclude>
                                    </excludes>
                                </filter>
                            </filters>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

步骤 2: 创建配置管理类

创建 src/main/java/com/vectorstory/keycloak/wechat/config/WeChatConfig.java:

package com.vectorstory.keycloak.wechat.config;

/**
 * 微信 OAuth 配置管理
 * 从环境变量读取配置
 */
public class WeChatConfig {

    // 微信平台类型
    public enum PlatformType {
        OPEN,       // 开放平台
        OFFICIAL,   // 公众平台
        WORK        // 企业微信
    }

    private final boolean mock;
    private final PlatformType platformType;
    private final String appId;
    private final String appSecret;
    private final String redirectUri;
    private final String scope;
    private final int stateExpireTime;

    public WeChatConfig() {
        this.mock = "true".equalsIgnoreCase(getEnv("WECHAT_SERVICE_MOCK", "true"));
        this.platformType = parsePlatformType(getEnv("WECHAT_PLATFORM_TYPE", "open"));
        this.appId = getEnv("WECHAT_APP_ID", "");
        this.appSecret = getEnv("WECHAT_APP_SECRET", "");
        this.redirectUri = getEnv("WECHAT_REDIRECT_URI", "");
        this.scope = getEnv("WECHAT_SCOPE", "snsapi_login");
        this.stateExpireTime = Integer.parseInt(getEnv("WECHAT_STATE_EXPIRE_TIME", "300"));
    }

    private String getEnv(String key, String defaultValue) {
        String value = System.getenv(key);
        return (value != null && !value.isEmpty()) ? value : defaultValue;
    }

    private PlatformType parsePlatformType(String type) {
        try {
            return PlatformType.valueOf(type.toUpperCase());
        } catch (IllegalArgumentException e) {
            return PlatformType.OPEN;
        }
    }

    // Getters
    public boolean isMock() { return mock; }
    public PlatformType getPlatformType() { return platformType; }
    public String getAppId() { return appId; }
    public String getAppSecret() { return appSecret; }
    public String getRedirectUri() { return redirectUri; }
    public String getScope() { return scope; }
    public int getStateExpireTime() { return stateExpireTime; }

    /**
     * 获取微信授权 URL
     */
    public String getAuthorizationUrl() {
        switch (platformType) {
            case OPEN:
                return "https://open.weixin.qq.com/connect/qrconnect";
            case OFFICIAL:
                return "https://open.weixin.qq.com/connect/oauth2/authorize";
            case WORK:
                return "https://open.work.weixin.qq.com/wwopen/sso/qrConnect";
            default:
                return "https://open.weixin.qq.com/connect/qrconnect";
        }
    }

    /**
     * 获取 Access Token URL
     */
    public String getAccessTokenUrl() {
        switch (platformType) {
            case WORK:
                return "https://qyapi.weixin.qq.com/cgi-bin/gettoken";
            default:
                return "https://api.weixin.qq.com/sns/oauth2/access_token";
        }
    }

    /**
     * 获取用户信息 URL
     */
    public String getUserInfoUrl() {
        switch (platformType) {
            case WORK:
                return "https://qyapi.weixin.qq.com/cgi-bin/user/getuserinfo";
            default:
                return "https://api.weixin.qq.com/sns/userinfo";
        }
    }
}

步骤 3: 创建数据模型

3.1 创建 `WeChatAccessToken.java`

package com.vectorstory.keycloak.wechat.model;

/**
 * 微信 Access Token 模型
 */
public class WeChatAccessToken {
    private String accessToken;
    private int expiresIn;
    private String refreshToken;
    private String openid;
    private String scope;
    private String unionid;

    // Getters and Setters
    public String getAccessToken() { return accessToken; }
    public void setAccessToken(String accessToken) { this.accessToken = accessToken; }

    public int getExpiresIn() { return expiresIn; }
    public void setExpiresIn(int expiresIn) { this.expiresIn = expiresIn; }

    public String getRefreshToken() { return refreshToken; }
    public void setRefreshToken(String refreshToken) { this.refreshToken = refreshToken; }

    public String getOpenid() { return openid; }
    public void setOpenid(String openid) { this.openid = openid; }

    public String getScope() { return scope; }
    public void setScope(String scope) { this.scope = scope; }

    public String getUnionid() { return unionid; }
    public void setUnionid(String unionid) { this.unionid = unionid; }
}

3.2 创建 `WeChatUserInfo.java`

package com.vectorstory.keycloak.wechat.model;

/**
 * 微信用户信息模型
 */
public class WeChatUserInfo {
    private String openid;        // 用户唯一标识
    private String unionid;       // 开放平台唯一标识
    private String nickname;      // 用户昵称
    private String headimgurl;    // 头像 URL
    private int sex;              // 性别：0-未知，1-男，2-女
    private String province;      // 省份
    private String city;          // 城市
    private String country;       // 国家

    // Getters and Setters
    public String getOpenid() { return openid; }
    public void setOpenid(String openid) { this.openid = openid; }

    public String getUnionid() { return unionid; }
    public void setUnionid(String unionid) { this.unionid = unionid; }

    public String getNickname() { return nickname; }
    public void setNickname(String nickname) { this.nickname = nickname; }

    public String getHeadimgurl() { return headimgurl; }
    public void setHeadimgurl(String headimgurl) { this.headimgurl = headimgurl; }

    public int getSex() { return sex; }
    public void setSex(int sex) { this.sex = sex; }

    public String getProvince() { return province; }
    public void setProvince(String province) { this.province = province; }

    public String getCity() { return city; }
    public void setCity(String city) { this.city = city; }

    public String getCountry() { return country; }
    public void setCountry(String country) { this.country = country; }

    /**
     * 获取性别文本
     */
    public String getSexText() {
        switch (sex) {
            case 1: return "男";
            case 2: return "女";
            default: return "未知";
        }
    }
}

3.3 创建 `VerificationCode.java`

package com.vectorstory.keycloak.wechat.model;

/**
 * 短信验证码模型
 */
public class VerificationCode {
    private final String code;
    private final long timestamp;
    private int attempts;

    public VerificationCode(String code, long timestamp) {
        this.code = code;
        this.timestamp = timestamp;
        this.attempts = 0;
    }

    public String getCode() {
        return code;
    }

    public long getTimestamp() {
        return timestamp;
    }

    public int getAttempts() {
        return attempts;
    }

    public void incrementAttempts() {
        this.attempts++;
    }

    public boolean isExpired(int expiryMinutes) {
        long currentTime = System.currentTimeMillis();
        long elapsedMinutes = (currentTime - timestamp) / (1000 * 60);
        return elapsedMinutes >= expiryMinutes;
    }

    public boolean isMaxAttemptsExceeded(int maxAttempts) {
        return attempts >= maxAttempts;
    }
}

步骤 4: 创建缓存层

4.1 创建缓存接口 `StateCache.java`

package com.vectorstory.keycloak.wechat.cache;

/**
 * State 参数缓存接口
 * 用于存储 OAuth state 参数，防止 CSRF 攻击
 */
public interface StateCache {

    /**
     * 保存 state
     * @param state state 参数
     * @param expireSeconds 过期时间（秒）
     */
    void saveState(String state, int expireSeconds);

    /**
     * 验证并删除 state
     * @param state state 参数
     * @return true 如果 state 有效，false 如果 state 无效或已过期
     */
    boolean validateAndRemoveState(String state);
}

4.2 创建内存缓存实现 `MemoryStateCache.java`

package com.vectorstory.keycloak.wechat.cache;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

/**
 * 基于内存的 State 缓存实现
 * 适用于单机开发环境
 */
public class MemoryStateCache implements StateCache {

    private static final Map<String, Long> stateMap = new ConcurrentHashMap<>();

    @Override
    public void saveState(String state, int expireSeconds) {
        long expireTime = System.currentTimeMillis() + (expireSeconds * 1000L);
        stateMap.put(state, expireTime);

        // 清理过期的 state
        cleanExpiredStates();
    }

    @Override
    public boolean validateAndRemoveState(String state) {
        Long expireTime = stateMap.remove(state);
        if (expireTime == null) {
            return false;
        }
        return System.currentTimeMillis() <= expireTime;
    }

    private void cleanExpiredStates() {
        long now = System.currentTimeMillis();
        stateMap.entrySet().removeIf(entry -> entry.getValue() < now);
    }
}

4.3 创建 Redis 缓存实现 `RedisStateCache.java`

package com.vectorstory.keycloak.wechat.cache;

import org.jboss.logging.Logger;
import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisPool;
import redis.clients.jedis.JedisPoolConfig;

/**
 * 基于 Redis 的 State 缓存实现
 * 适用于生产环境（支持分布式部署）
 */
public class RedisStateCache implements StateCache {

    private static final Logger logger = Logger.getLogger(RedisStateCache.class);
    private static final String KEY_PREFIX = "wechat:state:";

    private final JedisPool jedisPool;

    public RedisStateCache() {
        String host = System.getenv().getOrDefault("REDIS_HOST", "localhost");
        int port = Integer.parseInt(System.getenv().getOrDefault("REDIS_PORT", "6379"));
        String password = System.getenv("REDIS_PASSWORD");
        int database = Integer.parseInt(System.getenv().getOrDefault("REDIS_DATABASE", "0"));
        int timeout = Integer.parseInt(System.getenv().getOrDefault("REDIS_TIMEOUT", "3000"));

        JedisPoolConfig poolConfig = new JedisPoolConfig();
        poolConfig.setMaxTotal(20);
        poolConfig.setMaxIdle(10);
        poolConfig.setMinIdle(5);

        if (password != null && !password.isEmpty()) {
            this.jedisPool = new JedisPool(poolConfig, host, port, timeout, password, database);
        } else {
            this.jedisPool = new JedisPool(poolConfig, host, port, timeout, null, database);
        }

        logger.infof("Redis State Cache 初始化: %s:%d (database=%d)", host, port, database);
    }

    @Override
    public void saveState(String state, int expireSeconds) {
        try (Jedis jedis = jedisPool.getResource()) {
            String key = KEY_PREFIX + state;
            jedis.setex(key, expireSeconds, "1");
            logger.debugf("State 已保存: %s (过期时间: %d 秒)", state, expireSeconds);
        } catch (Exception e) {
            logger.errorf(e, "保存 State 失败: %s", state);
        }
    }

    @Override
    public boolean validateAndRemoveState(String state) {
        try (Jedis jedis = jedisPool.getResource()) {
            String key = KEY_PREFIX + state;
            Long result = jedis.del(key);
            boolean valid = result != null && result > 0;
            logger.debugf("State 验证: %s -> %s", state, valid ? "有效" : "无效");
            return valid;
        } catch (Exception e) {
            logger.errorf(e, "验证 State 失败: %s", state);
            return false;
        }
    }
}

4.4 创建短信验证码缓存接口 `CodeCache.java`

package com.vectorstory.keycloak.wechat.cache;

/**
 * 短信验证码缓存接口
 */
public interface CodeCache {

    void store(String phone, String code);

    boolean verify(String phone, String inputCode);

    boolean canSendSms(String phone);

    void recordSmsSent(String phone);

    void remove(String phone);
}

4.5 创建内存验证码缓存 `MemoryCodeCache.java`

package com.vectorstory.keycloak.wechat.cache;

import com.vectorstory.keycloak.wechat.model.VerificationCode;
import org.jboss.logging.Logger;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

/**
 * 基于内存的短信验证码缓存
 */
public class MemoryCodeCache implements CodeCache {

    private static final Logger logger = Logger.getLogger(MemoryCodeCache.class);

    private static final int CODE_EXPIRY_MINUTES = 5;
    private static final int MAX_ATTEMPTS = 5;
    private static final int SEND_INTERVAL_SECONDS = 60;

    private final Map<String, VerificationCode> codeMap = new ConcurrentHashMap<>();
    private final Map<String, Long> sendTimestamps = new ConcurrentHashMap<>();

    @Override
    public void store(String phone, String code) {
        VerificationCode verificationCode = new VerificationCode(code, System.currentTimeMillis());
        codeMap.put(phone, verificationCode);
        logger.infof("验证码已存储: phone=%s", phone);
    }

    @Override
    public boolean verify(String phone, String inputCode) {
        VerificationCode storedCode = codeMap.get(phone);

        if (storedCode == null) {
            logger.warnf("验证码不存在: phone=%s", phone);
            return false;
        }

        if (storedCode.isExpired(CODE_EXPIRY_MINUTES)) {
            logger.warnf("验证码已过期: phone=%s", phone);
            codeMap.remove(phone);
            return false;
        }

        if (storedCode.isMaxAttemptsExceeded(MAX_ATTEMPTS)) {
            logger.warnf("超过最大尝试次数: phone=%s", phone);
            return false;
        }

        storedCode.incrementAttempts();

        boolean isValid = storedCode.getCode().equals(inputCode);

        if (isValid) {
            logger.infof("验证码验证成功: phone=%s", phone);
            codeMap.remove(phone);
        } else {
            logger.warnf("验证码验证失败: phone=%s, attempts=%d", phone, storedCode.getAttempts());
        }

        return isValid;
    }

    @Override
    public boolean canSendSms(String phone) {
        Long lastSendTime = sendTimestamps.get(phone);

        if (lastSendTime == null) {
            return true;
        }

        long elapsedSeconds = (System.currentTimeMillis() - lastSendTime) / 1000;
        boolean canSend = elapsedSeconds >= SEND_INTERVAL_SECONDS;

        if (!canSend) {
            logger.warnf("发送频率限制: phone=%s, 需等待 %d 秒", phone, SEND_INTERVAL_SECONDS - elapsedSeconds);
        }

        return canSend;
    }

    @Override
    public void recordSmsSent(String phone) {
        sendTimestamps.put(phone, System.currentTimeMillis());
        logger.infof("记录短信发送时间: phone=%s", phone);
    }

    @Override
    public void remove(String phone) {
        codeMap.remove(phone);
        logger.infof("验证码已删除: phone=%s", phone);
    }
}

4.6 创建 Redis 验证码缓存 `RedisCodeCache.java`

package com.vectorstory.keycloak.wechat.cache;

import org.jboss.logging.Logger;
import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisPool;
import redis.clients.jedis.JedisPoolConfig;

/**
 * 基于 Redis 的短信验证码缓存
 */
public class RedisCodeCache implements CodeCache {

    private static final Logger logger = Logger.getLogger(RedisCodeCache.class);

    private static final int CODE_EXPIRY_SECONDS = 300;
    private static final int SEND_INTERVAL_SECONDS = 60;
    private static final int MAX_ATTEMPTS = 5;

    private static final String CODE_PREFIX = "sms:code:";
    private static final String SEND_PREFIX = "sms:send:";
    private static final String ATTEMPTS_PREFIX = "sms:attempts:";

    private final JedisPool jedisPool;

    public RedisCodeCache() {
        String host = getEnv("REDIS_HOST", "localhost");
        int port = Integer.parseInt(getEnv("REDIS_PORT", "6379"));
        String password = getEnv("REDIS_PASSWORD", null);
        int database = Integer.parseInt(getEnv("REDIS_DATABASE", "0"));

        JedisPoolConfig poolConfig = new JedisPoolConfig();
        poolConfig.setMaxTotal(20);
        poolConfig.setMaxIdle(10);
        poolConfig.setMinIdle(5);
        poolConfig.setTestOnBorrow(true);

        if (password != null && !password.isEmpty()) {
            this.jedisPool = new JedisPool(poolConfig, host, port, 2000, password, database);
        } else {
            this.jedisPool = new JedisPool(poolConfig, host, port, 2000);
        }

        logger.infof("Redis 连接池已初始化: %s:%d, database=%d", host, port, database);
    }

    @Override
    public void store(String phone, String code) {
        try (Jedis jedis = jedisPool.getResource()) {
            String key = CODE_PREFIX + phone;
            jedis.setex(key, CODE_EXPIRY_SECONDS, code);

            String attemptsKey = ATTEMPTS_PREFIX + phone;
            jedis.setex(attemptsKey, CODE_EXPIRY_SECONDS, "0");

            logger.infof("验证码已存储到 Redis: phone=%s", phone);
        } catch (Exception e) {
            logger.errorf(e, "存储验证码到 Redis 失败: phone=%s", phone);
            throw new RuntimeException("Redis 操作失败", e);
        }
    }

    @Override
    public boolean verify(String phone, String inputCode) {
        try (Jedis jedis = jedisPool.getResource()) {
            String key = CODE_PREFIX + phone;
            String storedCode = jedis.get(key);

            if (storedCode == null) {
                logger.warnf("验证码不存在或已过期: phone=%s", phone);
                return false;
            }

            String attemptsKey = ATTEMPTS_PREFIX + phone;
            String attemptsStr = jedis.get(attemptsKey);
            int attempts = attemptsStr != null ? Integer.parseInt(attemptsStr) : 0;

            if (attempts >= MAX_ATTEMPTS) {
                logger.warnf("超过最大尝试次数: phone=%s, attempts=%d", phone, attempts);
                return false;
            }

            jedis.incr(attemptsKey);

            boolean isValid = storedCode.equals(inputCode);

            if (isValid) {
                logger.infof("验证码验证成功: phone=%s", phone);
                jedis.del(key);
                jedis.del(attemptsKey);
            } else {
                logger.warnf("验证码验证失败: phone=%s, attempts=%d", phone, attempts + 1);
            }

            return isValid;
        } catch (Exception e) {
            logger.errorf(e, "验证验证码失败: phone=%s", phone);
            throw new RuntimeException("Redis 操作失败", e);
        }
    }

    @Override
    public boolean canSendSms(String phone) {
        try (Jedis jedis = jedisPool.getResource()) {
            String key = SEND_PREFIX + phone;
            String lastSendTime = jedis.get(key);

            if (lastSendTime == null) {
                return true;
            }

            long lastSend = Long.parseLong(lastSendTime);
            long elapsedSeconds = (System.currentTimeMillis() - lastSend) / 1000;
            boolean canSend = elapsedSeconds >= SEND_INTERVAL_SECONDS;

            if (!canSend) {
                logger.warnf("发送频率限制: phone=%s, 需等待 %d 秒", phone, SEND_INTERVAL_SECONDS - elapsedSeconds);
            }

            return canSend;
        } catch (Exception e) {
            logger.errorf(e, "检查发送频率失败: phone=%s", phone);
            return true;
        }
    }

    @Override
    public void recordSmsSent(String phone) {
        try (Jedis jedis = jedisPool.getResource()) {
            String key = SEND_PREFIX + phone;
            jedis.setex(key, SEND_INTERVAL_SECONDS, String.valueOf(System.currentTimeMillis()));
            logger.infof("记录短信发送时间到 Redis: phone=%s", phone);
        } catch (Exception e) {
            logger.errorf(e, "记录短信发送时间失败: phone=%s", phone);
        }
    }

    @Override
    public void remove(String phone) {
        try (Jedis jedis = jedisPool.getResource()) {
            jedis.del(CODE_PREFIX + phone);
            jedis.del(ATTEMPTS_PREFIX + phone);
            logger.infof("验证码已从 Redis 删除: phone=%s", phone);
        } catch (Exception e) {
            logger.errorf(e, "删除验证码失败: phone=%s", phone);
        }
    }

    private String getEnv(String key, String defaultValue) {
        String value = System.getenv(key);
        return (value != null && !value.isEmpty()) ? value : defaultValue;
    }
}

步骤 5: 创建微信 OAuth 服务

5.1 创建服务接口 `WeChatOAuthService.java`

package com.vectorstory.keycloak.wechat.service;

import com.vectorstory.keycloak.wechat.model.WeChatAccessToken;
import com.vectorstory.keycloak.wechat.model.WeChatUserInfo;

/**
 * 微信 OAuth 服务接口
 */
public interface WeChatOAuthService {

    /**
     * 构建微信授权 URL
     * @param state CSRF 防护参数
     * @param redirectUri 回调地址（可为空，使用配置默认值）
     * @return 授权 URL
     */
    String buildAuthorizationUrl(String state, String redirectUri);

    /**
     * 使用授权码获取 Access Token
     * @param code 授权码
     * @return Access Token 信息
     */
    WeChatAccessToken getAccessToken(String code) throws Exception;

    /**
     * 获取微信用户信息
     * @param accessToken Access Token
     * @param openid 用户 OpenID
     * @return 用户信息
     */
    WeChatUserInfo getUserInfo(String accessToken, String openid) throws Exception;
}

5.2 创建真实实现 `WeChatOAuthServiceImpl.java`

package com.vectorstory.keycloak.wechat.service;

import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.vectorstory.keycloak.wechat.config.WeChatConfig;
import com.vectorstory.keycloak.wechat.model.WeChatAccessToken;
import com.vectorstory.keycloak.wechat.model.WeChatUserInfo;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import org.jboss.logging.Logger;

import java.io.IOException;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.concurrent.TimeUnit;

/**
 * 微信 OAuth 服务实现（真实 API 调用）
 */
public class WeChatOAuthServiceImpl implements WeChatOAuthService {

    private static final Logger logger = Logger.getLogger(WeChatOAuthServiceImpl.class);

    private final WeChatConfig config;
    private final OkHttpClient httpClient;
    private final Gson gson;

    public WeChatOAuthServiceImpl() {
        this.config = new WeChatConfig();
        this.httpClient = new OkHttpClient.Builder()
                .connectTimeout(10, TimeUnit.SECONDS)
                .readTimeout(10, TimeUnit.SECONDS)
                .build();
        this.gson = new Gson();

        logger.infof("微信 OAuth 服务初始化: 平台类型=%s, AppID=%s",
                config.getPlatformType(), config.getAppId());
    }

    @Override
    public String buildAuthorizationUrl(String state, String redirectUri) {
        try {
            String baseUrl = config.getAuthorizationUrl();
            String resolvedRedirectUri = resolveRedirectUri(redirectUri);
            String encodedRedirectUri = URLEncoder.encode(resolvedRedirectUri, "UTF-8");

            return String.format("%s?appid=%s&redirect_uri=%s&response_type=code&scope=%s&state=%s#wechat_redirect",
                    baseUrl,
                    config.getAppId(),
                    encodedRedirectUri,
                    config.getScope(),
                    state);
        } catch (UnsupportedEncodingException e) {
            logger.error("构建授权 URL 失败", e);
            throw new RuntimeException("构建授权 URL 失败", e);
        }
    }

    private String resolveRedirectUri(String redirectUri) {
        if (redirectUri != null && !redirectUri.isBlank()) {
            return redirectUri;
        }
        return config.getRedirectUri();
    }

    @Override
    public WeChatAccessToken getAccessToken(String code) throws Exception {
        String url = String.format("%s?appid=%s&secret=%s&code=%s&grant_type=authorization_code",
                config.getAccessTokenUrl(),
                config.getAppId(),
                config.getAppSecret(),
                code);

        logger.debugf("获取 Access Token: code=%s", code);

        Request request = new Request.Builder()
                .url(url)
                .get()
                .build();

        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IOException("获取 Access Token 失败: HTTP " + response.code());
            }

            String body = response.body().string();
            logger.debugf("Access Token 响应: %s", body);

            JsonObject json = gson.fromJson(body, JsonObject.class);

            // 检查错误
            if (json.has("errcode")) {
                int errcode = json.get("errcode").getAsInt();
                String errmsg = json.get("errmsg").getAsString();
                throw new Exception(String.format("微信 API 错误: errcode=%d, errmsg=%s", errcode, errmsg));
            }

            WeChatAccessToken token = new WeChatAccessToken();
            token.setAccessToken(json.get("access_token").getAsString());
            token.setExpiresIn(json.get("expires_in").getAsInt());
            token.setRefreshToken(json.get("refresh_token").getAsString());
            token.setOpenid(json.get("openid").getAsString());
            token.setScope(json.get("scope").getAsString());

            if (json.has("unionid")) {
                token.setUnionid(json.get("unionid").getAsString());
            }

            return token;
        }
    }

    @Override
    public WeChatUserInfo getUserInfo(String accessToken, String openid) throws Exception {
        String url = String.format("%s?access_token=%s&openid=%s&lang=zh_CN",
                config.getUserInfoUrl(),
                accessToken,
                openid);

        logger.debugf("获取用户信息: openid=%s", openid);

        Request request = new Request.Builder()
                .url(url)
                .get()
                .build();

        try (Response response = httpClient.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new IOException("获取用户信息失败: HTTP " + response.code());
            }

            String body = response.body().string();
            logger.debugf("用户信息响应: %s", body);

            JsonObject json = gson.fromJson(body, JsonObject.class);

            // 检查错误
            if (json.has("errcode")) {
                int errcode = json.get("errcode").getAsInt();
                String errmsg = json.get("errmsg").getAsString();
                throw new Exception(String.format("微信 API 错误: errcode=%d, errmsg=%s", errcode, errmsg));
            }

            return gson.fromJson(json, WeChatUserInfo.class);
        }
    }
}

5.3 创建 Mock 实现 `MockWeChatOAuthService.java`

package com.vectorstory.keycloak.wechat.service;

import com.vectorstory.keycloak.wechat.config.WeChatConfig;
import com.vectorstory.keycloak.wechat.model.WeChatAccessToken;
import com.vectorstory.keycloak.wechat.model.WeChatUserInfo;
import org.jboss.logging.Logger;

import java.util.UUID;

/**
 * 微信 OAuth 服务 Mock 实现（用于开发测试）
 */
public class MockWeChatOAuthService implements WeChatOAuthService {

    private static final Logger logger = Logger.getLogger(MockWeChatOAuthService.class);

    private final WeChatConfig config;

    public MockWeChatOAuthService() {
        this.config = new WeChatConfig();
        logger.info("=== 微信 OAuth Mock 模式已启用 ===");
    }

    @Override
    public String buildAuthorizationUrl(String state, String redirectUri) {
        String mockCode = "mock_code_" + UUID.randomUUID().toString().replace("-", "");
        String resolvedRedirectUri = resolveRedirectUri(redirectUri);
        String separator = resolvedRedirectUri.contains("?") ? "&" : "?";
        String url = String.format("%s%scode=%s&state=%s&mock=true",
                resolvedRedirectUri,
                separator,
                mockCode,
                state);

        logger.infof("[Mock] 构建授权 URL: %s", url);
        return url;
    }

    private String resolveRedirectUri(String redirectUri) {
        if (redirectUri != null && !redirectUri.isBlank()) {
            return redirectUri;
        }
        return config.getRedirectUri();
    }

    @Override
    public WeChatAccessToken getAccessToken(String code) {
        logger.infof("[Mock] 获取 Access Token: code=%s", code);

        WeChatAccessToken token = new WeChatAccessToken();
        token.setAccessToken("mock_access_token_" + UUID.randomUUID().toString());
        token.setExpiresIn(7200);
        token.setRefreshToken("mock_refresh_token_" + UUID.randomUUID().toString());
        token.setOpenid("mock_openid_" + System.currentTimeMillis());
        token.setScope("snsapi_login");
        token.setUnionid("mock_unionid_" + System.currentTimeMillis());

        logger.infof("[Mock] Access Token: %s, OpenID: %s", token.getAccessToken(), token.getOpenid());
        return token;
    }

    @Override
    public WeChatUserInfo getUserInfo(String accessToken, String openid) {
        logger.infof("[Mock] 获取用户信息: openid=%s", openid);

        WeChatUserInfo userInfo = new WeChatUserInfo();
        userInfo.setOpenid(openid);
        userInfo.setUnionid("mock_unionid_" + System.currentTimeMillis());
        userInfo.setNickname("测试用户_" + openid.substring(openid.length() - 6));
        userInfo.setHeadimgurl("https://thirdwx.qlogo.cn/mmopen/mock_avatar.jpg");
        userInfo.setSex(1);
        userInfo.setProvince("广东");
        userInfo.setCity("深圳");
        userInfo.setCountry("中国");

        logger.infof("[Mock] 用户信息: nickname=%s, openid=%s", userInfo.getNickname(), userInfo.getOpenid());
        return userInfo;
    }
}

5.4 创建短信服务接口 `SmsService.java`

package com.vectorstory.keycloak.wechat.sms;

/**
 * 短信服务接口
 */
public interface SmsService {

    boolean sendVerificationCode(String phoneNumber, String code);

    default String generateCode(int length) {
        StringBuilder code = new StringBuilder();
        for (int i = 0; i < length; i++) {
            code.append((int) (Math.random() * 10));
        }
        return code.toString();
    }
}

5.5 创建 Mock 短信服务 `MockSmsService.java`

package com.vectorstory.keycloak.wechat.sms;

import org.jboss.logging.Logger;

/**
 * Mock 短信服务（验证码打印到日志）
 */
public class MockSmsService implements SmsService {

    private static final Logger logger = Logger.getLogger(MockSmsService.class);

    public MockSmsService() {
        logger.warn("=".repeat(60));
        logger.warn("警告：正在使用 Mock 短信服务，验证码将打印在日志中");
        logger.warn("生产环境请设置 SMS_SERVICE_MOCK=false");
        logger.warn("=".repeat(60));
    }

    @Override
    public boolean sendVerificationCode(String phoneNumber, String code) {
        logger.info("=".repeat(60));
        logger.infof("【Mock 短信】手机号: %s", phoneNumber);
        logger.infof("【Mock 短信】验证码: %s", code);
        logger.infof("【Mock 短信】有效期: 5分钟");
        logger.info("=".repeat(60));
        return true;
    }
}

5.6 创建阿里云短信服务 `AliyunSmsService.java`

package com.vectorstory.keycloak.wechat.sms;

import com.aliyun.dysmsapi20170525.Client;
import com.aliyun.dysmsapi20170525.models.SendSmsRequest;
import com.aliyun.dysmsapi20170525.models.SendSmsResponse;
import com.aliyun.teaopenapi.models.Config;
import org.jboss.logging.Logger;

/**
 * 阿里云短信服务实现
 */
public class AliyunSmsService implements SmsService {

    private static final Logger logger = Logger.getLogger(AliyunSmsService.class);

    private final Client client;
    private final String signName;
    private final String templateCode;

    public AliyunSmsService() {
        try {
            String accessKeyId = getRequiredEnv("ALIYUN_ACCESS_KEY_ID");
            String accessKeySecret = getRequiredEnv("ALIYUN_ACCESS_KEY_SECRET");
            this.signName = getRequiredEnv("ALIYUN_SMS_SIGN_NAME");
            this.templateCode = getRequiredEnv("ALIYUN_SMS_TEMPLATE_CODE");

            Config config = new Config()
                    .setAccessKeyId(accessKeyId)
                    .setAccessKeySecret(accessKeySecret)
                    .setEndpoint("dysmsapi.aliyuncs.com");

            this.client = new Client(config);

            logger.infof("阿里云短信服务初始化成功: signName=%s, templateCode=%s", signName, templateCode);
        } catch (Exception e) {
            logger.error("阿里云短信服务初始化失败", e);
            throw new RuntimeException("Failed to initialize Aliyun SMS service", e);
        }
    }

    @Override
    public boolean sendVerificationCode(String phoneNumber, String code) {
        try {
            SendSmsRequest request = new SendSmsRequest()
                    .setPhoneNumbers(phoneNumber)
                    .setSignName(signName)
                    .setTemplateCode(templateCode)
                    .setTemplateParam("{\"code\":\"" + code + "\"}");

            SendSmsResponse response = client.sendSms(request);

            String resultCode = response.getBody().getCode();
            boolean success = "OK".equals(resultCode);

            if (success) {
                logger.infof("短信发送成功: phone=%s, code=%s, requestId=%s",
                        phoneNumber, code, response.getBody().getRequestId());
            } else {
                logger.errorf("短信发送失败: phone=%s, code=%s, message=%s",
                        phoneNumber, resultCode, response.getBody().getMessage());
            }

            return success;

        } catch (Exception e) {
            logger.errorf(e, "短信发送异常: phone=%s", phoneNumber);
            return false;
        }
    }

    private String getRequiredEnv(String key) {
        String value = System.getenv(key);
        if (value == null || value.trim().isEmpty()) {
            throw new IllegalStateException("Required environment variable not set: " + key);
        }
        return value.trim();
    }
}

步骤 6: 创建认证器核心类

6.1 创建 `WeChatAuthenticator.java`

这是认证器的核心实现，处理完整的 OAuth 流程与手机号绑定逻辑：

package com.vectorstory.keycloak.wechat.authenticator;

import com.vectorstory.keycloak.wechat.cache.CodeCache;
import com.vectorstory.keycloak.wechat.cache.MemoryCodeCache;
import com.vectorstory.keycloak.wechat.cache.RedisCodeCache;
import com.vectorstory.keycloak.wechat.cache.StateCache;
import com.vectorstory.keycloak.wechat.cache.MemoryStateCache;
import com.vectorstory.keycloak.wechat.cache.RedisStateCache;
import com.vectorstory.keycloak.wechat.config.WeChatConfig;
import com.vectorstory.keycloak.wechat.model.WeChatAccessToken;
import com.vectorstory.keycloak.wechat.model.WeChatUserInfo;
import com.vectorstory.keycloak.wechat.service.MockWeChatOAuthService;
import com.vectorstory.keycloak.wechat.service.WeChatOAuthService;
import com.vectorstory.keycloak.wechat.service.WeChatOAuthServiceImpl;
import com.vectorstory.keycloak.wechat.sms.AliyunSmsService;
import com.vectorstory.keycloak.wechat.sms.MockSmsService;
import com.vectorstory.keycloak.wechat.sms.SmsService;
import jakarta.ws.rs.core.MultivaluedMap;
import jakarta.ws.rs.core.Response;
import jakarta.ws.rs.core.UriBuilder;
import org.jboss.logging.Logger;
import org.keycloak.authentication.AuthenticationFlowContext;
import org.keycloak.authentication.AuthenticationFlowError;
import org.keycloak.authentication.Authenticator;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.models.UserModel;
import org.keycloak.sessions.AuthenticationSessionModel;

import java.util.UUID;

public class WeChatAuthenticator implements Authenticator {

    private static final Logger logger = Logger.getLogger(WeChatAuthenticator.class);

    private static final String TEMPLATE_LOGIN_BUTTON = "wechat-login-button.ftl";
    private static final String TEMPLATE_PHONE_FORM = "wechat-bind-phone.ftl";
    private static final String TEMPLATE_CODE_FORM = "wechat-bind-code.ftl";

    private static final String FORM_ACTION = "wechatAction";
    private static final String ACTION_LOGIN = "login";
    private static final String ACTION_SEND_CODE = "sendCode";
    private static final String ACTION_VERIFY_CODE = "verifyCode";

    private static final String FORM_PHONE = "phone";
    private static final String FORM_CODE = "code";

    private static final String PARAM_CODE = "code";
    private static final String PARAM_STATE = "state";
    private static final String PARAM_SESSION_CODE = "session_code";
    private static final String PARAM_EXECUTION = "execution";
    private static final String PARAM_CLIENT_ID = "client_id";
    private static final String PARAM_TAB_ID = "tab_id";
    private static final String PARAM_CLIENT_DATA = "client_data";

    private static final String NOTE_WECHAT_OPENID = "WECHAT_OPENID";
    private static final String NOTE_WECHAT_UNIONID = "WECHAT_UNIONID";
    private static final String NOTE_WECHAT_NICKNAME = "WECHAT_NICKNAME";
    private static final String NOTE_WECHAT_AVATAR = "WECHAT_AVATAR";
    private static final String NOTE_WECHAT_GENDER = "WECHAT_GENDER";
    private static final String NOTE_BIND_PHONE = "WECHAT_BIND_PHONE";

    private final WeChatOAuthService oauthService;
    private final StateCache stateCache;
    private final WeChatConfig config;
    private final SmsService smsService;
    private final CodeCache codeCache;
    private final String phoneRegex;
    private final int codeLength;

    public WeChatAuthenticator() {
        this.config = new WeChatConfig();

        this.oauthService = config.isMock()
                ? new MockWeChatOAuthService()
                : new WeChatOAuthServiceImpl();

        boolean useRedis = "true".equalsIgnoreCase(System.getenv("USE_REDIS_CACHE"));
        this.stateCache = useRedis ? new RedisStateCache() : new MemoryStateCache();

        boolean useMockSms = "true".equalsIgnoreCase(System.getenv("SMS_SERVICE_MOCK"));
        this.smsService = useMockSms ? new MockSmsService() : new AliyunSmsService();
        this.codeCache = useRedis ? new RedisCodeCache() : new MemoryCodeCache();

        this.phoneRegex = System.getenv().getOrDefault("PHONE_NUMBER_REGEX", "^1[3-9]\\d{9}$");
        this.codeLength = parseIntEnv("VERIFICATION_CODE_LENGTH", 6);

        logger.infof("微信认证器初始化: mock=%s, stateCache=%s, smsService=%s",
                config.isMock(),
                stateCache.getClass().getSimpleName(),
                smsService.getClass().getSimpleName());
    }

    @Override
    public void authenticate(AuthenticationFlowContext context) {
        Response response = context.form().createForm(TEMPLATE_LOGIN_BUTTON);
        context.challenge(response);
    }

    @Override
    public void action(AuthenticationFlowContext context) {
        MultivaluedMap<String, String> queryParams = context.getHttpRequest().getUri().getQueryParameters();
        String code = queryParams.getFirst(PARAM_CODE);
        String state = queryParams.getFirst(PARAM_STATE);

        if (code != null || state != null) {
            handleCallback(context, code, state);
            return;
        }

        MultivaluedMap<String, String> formData = context.getHttpRequest().getDecodedFormParameters();
        String action = formData.getFirst(FORM_ACTION);

        if (ACTION_LOGIN.equals(action)) {
            if (config.isMock()) {
                handleMockLogin(context);
            } else {
                redirectToWeChat(context);
            }
            return;
        }

        if (ACTION_SEND_CODE.equals(action)) {
            handleSendCode(context, formData);
            return;
        }

        if (ACTION_VERIFY_CODE.equals(action)) {
            handleVerifyCode(context, formData);
            return;
        }

        logger.warnf("未知的操作: %s", action);
        context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS,
                context.form().setError("微信登录失败：请求无效").createForm(TEMPLATE_LOGIN_BUTTON));
    }

    private void redirectToWeChat(AuthenticationFlowContext context) {
        String state = UUID.randomUUID().toString();
        stateCache.saveState(state, config.getStateExpireTime());

        // 使用 Keycloak 提供的 Action URL,它会自动生成正确的 session_code
        // getActionUrl() 返回当前认证流程的 action URL
        String callbackUrl = context.getActionUrl(context.generateAccessCode()).toString();
        String authUrl = oauthService.buildAuthorizationUrl(state, callbackUrl);
        logger.infof("重定向到微信授权页面: %s", authUrl);
        logger.infof("回调地址: %s", callbackUrl);

        Response response = Response.status(302)
                .header("Location", authUrl)
                .build();
        context.challenge(response);
    }

    private String buildCallbackUrl(AuthenticationFlowContext context) {
        return context.getUriInfo().getRequestUriBuilder()
                .replaceQueryParam(PARAM_CODE)
                .replaceQueryParam(PARAM_STATE)
                .build()
                .toString();
    }

    private String resolveRedirectUri(AuthenticationFlowContext context) {
        String configuredRedirect = config.getRedirectUri();
        if (configuredRedirect != null && !configuredRedirect.isBlank()) {
            return mergeLoginParams(configuredRedirect, context.getHttpRequest().getUri().getQueryParameters());
        }
        return buildCallbackUrl(context);
    }

    private String mergeLoginParams(String baseRedirect, MultivaluedMap<String, String> params) {
        UriBuilder builder = UriBuilder.fromUri(baseRedirect);
        copyParam(builder, params, PARAM_SESSION_CODE);
        copyParam(builder, params, PARAM_EXECUTION);
        copyParam(builder, params, PARAM_CLIENT_ID);
        copyParam(builder, params, PARAM_TAB_ID);
        copyParam(builder, params, PARAM_CLIENT_DATA);
        return builder.build().toString();
    }

    private void copyParam(UriBuilder builder, MultivaluedMap<String, String> params, String name) {
        String value = params.getFirst(name);
        if (value != null && !value.isBlank()) {
            builder.replaceQueryParam(name, value);
        }
    }

    private void handleMockLogin(AuthenticationFlowContext context) {
        try {
            WeChatAccessToken token = oauthService.getAccessToken("mock_code");
            WeChatUserInfo userInfo = oauthService.getUserInfo(token.getAccessToken(), token.getOpenid());
            processWeChatUser(context, userInfo);
        } catch (Exception e) {
            logger.error("Mock 微信登录失败", e);
            context.failureChallenge(AuthenticationFlowError.INTERNAL_ERROR,
                    context.form().setError("微信登录失败：" + e.getMessage())
                            .createErrorPage(Response.Status.INTERNAL_SERVER_ERROR));
        }
    }

    private void handleCallback(AuthenticationFlowContext context, String code, String state) {
        logger.infof("微信回调: code=%s, state=%s", code, state);

        if (state == null || !stateCache.validateAndRemoveState(state)) {
            logger.error("State 参数验证失败");
            context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS,
                    context.form().setError("微信登录失败：state 参数无效")
                            .createErrorPage(Response.Status.BAD_REQUEST));
            return;
        }

        if (code == null || code.isEmpty()) {
            logger.error("授权码为空");
            context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS,
                    context.form().setError("微信登录失败：授权码无效")
                            .createErrorPage(Response.Status.BAD_REQUEST));
            return;
        }

        try {
            WeChatAccessToken token = oauthService.getAccessToken(code);
            logger.infof("获取 Access Token 成功: openid=%s", token.getOpenid());

            WeChatUserInfo userInfo = oauthService.getUserInfo(token.getAccessToken(), token.getOpenid());
            logger.infof("获取用户信息成功: nickname=%s, openid=%s", userInfo.getNickname(), userInfo.getOpenid());

            processWeChatUser(context, userInfo);
        } catch (Exception e) {
            logger.error("微信登录失败", e);
            context.failureChallenge(AuthenticationFlowError.INTERNAL_ERROR,
                    context.form().setError("微信登录失败：" + e.getMessage())
                            .createErrorPage(Response.Status.INTERNAL_SERVER_ERROR));
        }
    }

    private void processWeChatUser(AuthenticationFlowContext context, WeChatUserInfo userInfo) {
        UserModel user = findUserByUnionId(context, userInfo.getUnionid());

        if (user != null) {
            bindWeChatToUser(user, userInfo);
            context.setUser(user);
            context.success();
            clearWeChatNotes(context.getAuthenticationSession());
            logger.infof("微信登录成功: username=%s, unionid=%s", user.getUsername(), userInfo.getUnionid());
            return;
        }

        storeWeChatNotes(context.getAuthenticationSession(), userInfo);
        Response response = context.form().createForm(TEMPLATE_PHONE_FORM);
        context.challenge(response);
    }

    private void handleSendCode(AuthenticationFlowContext context, MultivaluedMap<String, String> formData) {
        if (!hasWeChatNotes(context.getAuthenticationSession())) {
            context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS,
                    context.form().setError("微信登录信息已失效，请重新登录")
                            .createForm(TEMPLATE_LOGIN_BUTTON));
            return;
        }

        String phone = formData.getFirst(FORM_PHONE);
        if (!isValidPhone(phone)) {
            Response response = context.form()
                    .setError("手机号格式不正确，请输入正确的手机号")
                    .createForm(TEMPLATE_PHONE_FORM);
            context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS, response);
            return;
        }

        if (!codeCache.canSendSms(phone)) {
            Response response = context.form()
                    .setError("发送频率过快，请稍后再试")
                    .createForm(TEMPLATE_PHONE_FORM);
            context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS, response);
            return;
        }

        String code = smsService.generateCode(codeLength);
        boolean sent = smsService.sendVerificationCode(phone, code);

        if (!sent) {
            Response response = context.form()
                    .setError("验证码发送失败，请稍后重试")
                    .createForm(TEMPLATE_PHONE_FORM);
            context.failureChallenge(AuthenticationFlowError.INTERNAL_ERROR, response);
            return;
        }

        codeCache.store(phone, code);
        codeCache.recordSmsSent(phone);
        context.getAuthenticationSession().setAuthNote(NOTE_BIND_PHONE, phone);

        Response response = context.form()
                .setAttribute(FORM_PHONE, phone)
                .createForm(TEMPLATE_CODE_FORM);
        context.challenge(response);
    }

    private void handleVerifyCode(AuthenticationFlowContext context, MultivaluedMap<String, String> formData) {
        AuthenticationSessionModel authSession = context.getAuthenticationSession();
        if (!hasWeChatNotes(authSession)) {
            context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS,
                    context.form().setError("微信登录信息已失效，请重新登录")
                            .createForm(TEMPLATE_LOGIN_BUTTON));
            return;
        }

        String phone = formData.getFirst(FORM_PHONE);
        if (phone == null || phone.isBlank()) {
            phone = authSession.getAuthNote(NOTE_BIND_PHONE);
        }

        String inputCode = formData.getFirst(FORM_CODE);

        if (phone == null || phone.isBlank() || inputCode == null || inputCode.isBlank()) {
            Response response = context.form()
                    .setAttribute(FORM_PHONE, phone)
                    .setError("验证码不能为空，请重新输入")
                    .createForm(TEMPLATE_CODE_FORM);
            context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS, response);
            return;
        }

        if (!codeCache.verify(phone, inputCode)) {
            Response response = context.form()
                    .setAttribute(FORM_PHONE, phone)
                    .setError("验证码错误或已过期，请重新获取")
                    .createForm(TEMPLATE_CODE_FORM);
            context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS, response);
            return;
        }

        WeChatUserInfo userInfo = loadWeChatInfoFromNotes(authSession);
        if (userInfo == null) {
            context.failureChallenge(AuthenticationFlowError.INVALID_CREDENTIALS,
                    context.form().setError("微信登录信息已失效，请重新登录")
                            .createForm(TEMPLATE_LOGIN_BUTTON));
            return;
        }

        UserModel user = findUserByPhone(context, phone);
        if (user == null) {
            user = createUserForPhone(context, phone);
        }

        if (user == null) {
            context.failureChallenge(AuthenticationFlowError.INTERNAL_ERROR,
                    context.form().setError("系统错误，请联系管理员")
                            .createForm(TEMPLATE_PHONE_FORM));
            return;
        }

        bindWeChatToUser(user, userInfo);
        user.setSingleAttribute("phone", phone);
        user.setSingleAttribute("phoneVerified", "true");

        context.setUser(user);
        context.success();
        clearWeChatNotes(authSession);

        logger.infof("手机号绑定成功: username=%s, phone=%s", user.getUsername(), phone);
    }

    private UserModel findUserByUnionId(AuthenticationFlowContext context, String unionid) {
        if (unionid == null || unionid.isBlank()) {
            return null;
        }

        KeycloakSession session = context.getSession();
        RealmModel realm = context.getRealm();
        return session.users().searchForUserByUserAttributeStream(realm, "wechatUnionId", unionid)
                .findFirst()
                .orElse(null);
    }

    private UserModel findUserByPhone(AuthenticationFlowContext context, String phone) {
        KeycloakSession session = context.getSession();
        RealmModel realm = context.getRealm();

        UserModel user = session.users().searchForUserByUserAttributeStream(realm, "phone", phone)
                .findFirst()
                .orElse(null);
        if (user != null) {
            return user;
        }

        return session.users().getUserByUsername(realm, phone);
    }

    private UserModel createUserForPhone(AuthenticationFlowContext context, String phone) {
        KeycloakSession session = context.getSession();
        RealmModel realm = context.getRealm();

        String username = buildUniqueUsername(session, realm, phone);
        try {
            UserModel user = session.users().addUser(realm, username);
            user.setEnabled(true);
            user.setSingleAttribute("phone", phone);
            user.setSingleAttribute("phoneVerified", "true");

            user.addRequiredAction(UserModel.RequiredAction.UPDATE_PROFILE);
            user.addRequiredAction(UserModel.RequiredAction.UPDATE_PASSWORD);

            logger.infof("创建新用户成功: username=%s, phone=%s", user.getUsername(), phone);
            return user;
        } catch (Exception e) {
            logger.errorf(e, "创建用户失败: phone=%s", phone);
            return null;
        }
    }

    private void bindWeChatToUser(UserModel user, WeChatUserInfo userInfo) {
        user.setSingleAttribute("wechatOpenId", userInfo.getOpenid());
        if (userInfo.getUnionid() != null) {
            user.setSingleAttribute("wechatUnionId", userInfo.getUnionid());
        }
        if (userInfo.getNickname() != null) {
            user.setSingleAttribute("wechatNickname", userInfo.getNickname());
        }
        if (userInfo.getHeadimgurl() != null) {
            user.setSingleAttribute("wechatAvatar", userInfo.getHeadimgurl());
        }
        user.setSingleAttribute("wechatGender", userInfo.getSexText());

        if (user.getFirstName() == null || user.getFirstName().isBlank()) {
            user.setFirstName(userInfo.getNickname());
        }
    }

    private void storeWeChatNotes(AuthenticationSessionModel authSession, WeChatUserInfo userInfo) {
        authSession.setAuthNote(NOTE_WECHAT_OPENID, userInfo.getOpenid());
        if (userInfo.getUnionid() != null) {
            authSession.setAuthNote(NOTE_WECHAT_UNIONID, userInfo.getUnionid());
        }
        if (userInfo.getNickname() != null) {
            authSession.setAuthNote(NOTE_WECHAT_NICKNAME, userInfo.getNickname());
        }
        if (userInfo.getHeadimgurl() != null) {
            authSession.setAuthNote(NOTE_WECHAT_AVATAR, userInfo.getHeadimgurl());
        }
        authSession.setAuthNote(NOTE_WECHAT_GENDER, String.valueOf(userInfo.getSex()));
    }

    private boolean hasWeChatNotes(AuthenticationSessionModel authSession) {
        return authSession.getAuthNote(NOTE_WECHAT_OPENID) != null;
    }

    private WeChatUserInfo loadWeChatInfoFromNotes(AuthenticationSessionModel authSession) {
        String openid = authSession.getAuthNote(NOTE_WECHAT_OPENID);
        if (openid == null || openid.isBlank()) {
            return null;
        }

        WeChatUserInfo userInfo = new WeChatUserInfo();
        userInfo.setOpenid(openid);
        userInfo.setUnionid(authSession.getAuthNote(NOTE_WECHAT_UNIONID));
        userInfo.setNickname(authSession.getAuthNote(NOTE_WECHAT_NICKNAME));
        userInfo.setHeadimgurl(authSession.getAuthNote(NOTE_WECHAT_AVATAR));

        String gender = authSession.getAuthNote(NOTE_WECHAT_GENDER);
        if (gender != null && !gender.isBlank()) {
            try {
                userInfo.setSex(Integer.parseInt(gender));
            } catch (NumberFormatException ignored) {
                userInfo.setSex(0);
            }
        }

        return userInfo;
    }

    private void clearWeChatNotes(AuthenticationSessionModel authSession) {
        authSession.removeAuthNote(NOTE_WECHAT_OPENID);
        authSession.removeAuthNote(NOTE_WECHAT_UNIONID);
        authSession.removeAuthNote(NOTE_WECHAT_NICKNAME);
        authSession.removeAuthNote(NOTE_WECHAT_AVATAR);
        authSession.removeAuthNote(NOTE_WECHAT_GENDER);
        authSession.removeAuthNote(NOTE_BIND_PHONE);
    }

    private boolean isValidPhone(String phone) {
        if (phone == null || phone.trim().isEmpty()) {
            return false;
        }
        return phone.trim().matches(phoneRegex);
    }

    private int parseIntEnv(String key, int defaultValue) {
        String value = System.getenv(key);
        if (value == null || value.trim().isEmpty()) {
            return defaultValue;
        }
        try {
            return Integer.parseInt(value.trim());
        } catch (NumberFormatException e) {
            return defaultValue;
        }
    }

    private String buildUniqueUsername(KeycloakSession session, RealmModel realm, String baseUsername) {
        String username = baseUsername;
        int suffix = 1;
        while (session.users().getUserByUsername(realm, username) != null) {
            username = baseUsername + "_" + suffix++;
        }
        return username;
    }

    @Override
    public boolean requiresUser() {
        return false;
    }

    @Override
    public boolean configuredFor(KeycloakSession session, RealmModel realm, UserModel user) {
        return true;
    }

    @Override
    public void setRequiredActions(KeycloakSession session, RealmModel realm, UserModel user) {
    }

    @Override
    public void close() {
    }
}

6.2 创建 `WeChatAuthenticatorFactory.java`

package com.vectorstory.keycloak.wechat.authenticator;

import org.keycloak.Config;
import org.keycloak.authentication.Authenticator;
import org.keycloak.authentication.AuthenticatorFactory;
import org.keycloak.models.AuthenticationExecutionModel;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.KeycloakSessionFactory;
import org.keycloak.provider.ProviderConfigProperty;

import java.util.Collections;
import java.util.List;

/**
 * 微信登录认证器工厂
 */
public class WeChatAuthenticatorFactory implements AuthenticatorFactory {

    public static final String PROVIDER_ID = "wechat-authenticator";

    private static final WeChatAuthenticator SINGLETON = new WeChatAuthenticator();

    @Override
    public String getId() {
        return PROVIDER_ID;
    }

    @Override
    public String getDisplayType() {
        return "wechat-authenticator-display-name";
    }

    @Override
    public String getReferenceCategory() {
        return "WeChat";
    }

    @Override
    public String getHelpText() {
        return "wechat-authenticator-help-text";
    }

    @Override
    public boolean isConfigurable() {
        return false;
    }

    @Override
    public boolean isUserSetupAllowed() {
        return false;
    }

    @Override
    public AuthenticationExecutionModel.Requirement[] getRequirementChoices() {
        return new AuthenticationExecutionModel.Requirement[]{
                AuthenticationExecutionModel.Requirement.REQUIRED,
                AuthenticationExecutionModel.Requirement.ALTERNATIVE,
                AuthenticationExecutionModel.Requirement.DISABLED
        };
    }

    @Override
    public List<ProviderConfigProperty> getConfigProperties() {
        return Collections.emptyList();
    }

    @Override
    public Authenticator create(KeycloakSession session) {
        return SINGLETON;
    }

    @Override
    public void init(Config.Scope config) {
        // 初始化配置
    }

    @Override
    public void postInit(KeycloakSessionFactory factory) {
        // 初始化后处理
    }

    @Override
    public void close() {
        // 清理资源
    }
}

步骤 7: 创建 SPI 注册文件

创建 src/main/resources/META-INF/services/org.keycloak.authentication.AuthenticatorFactory:

com.vectorstory.keycloak.wechat.authenticator.WeChatAuthenticatorFactory

步骤 8: 创建国际化资源文件

8.1 创建中文资源 `src/main/resources/theme-resources/messages/messages_zh_CN.properties`

# 微信登录认证器
wechat-authenticator-display-name=微信登录
wechat-authenticator-help-text=允许用户使用微信账号登录

# 按钮文本
wechat.button.login=微信登录
wechat.button.back=返回

# 绑定手机号
wechat.bind.phone.title=绑定手机号
wechat.bind.phone.label=手机号
wechat.bind.phone.placeholder=请输入手机号
wechat.bind.code.title=验证码
wechat.bind.code.label=验证码
wechat.bind.code.placeholder=请输入验证码
wechat.bind.code.sent=验证码已发送至手机号
wechat.bind.button.sendCode=发送验证码
wechat.bind.button.verify=验证并绑定

# 错误消息
wechat.error.invalid-state=State 参数无效，请重新登录
wechat.error.invalid-code=授权码无效，请重新登录
wechat.error.api-failed=微信服务暂时不可用，请稍后重试

8.2 创建英文资源 `src/main/resources/theme-resources/messages/messages_en.properties`

# WeChat Authenticator
wechat-authenticator-display-name=WeChat Login
wechat-authenticator-help-text=Allows users to log in with WeChat account

# Button text
wechat.button.login=WeChat Login
wechat.button.back=Back

# Bind phone
wechat.bind.phone.title=Bind Phone
wechat.bind.phone.label=Phone Number
wechat.bind.phone.placeholder=Enter your phone number
wechat.bind.code.title=Verification Code
wechat.bind.code.label=Verification Code
wechat.bind.code.placeholder=Enter verification code
wechat.bind.code.sent=Verification code sent to
wechat.bind.button.sendCode=Send Code
wechat.bind.button.verify=Verify and Bind

# Error messages
wechat.error.invalid-state=Invalid state parameter, please try again
wechat.error.invalid-code=Invalid authorization code, please try again
wechat.error.api-failed=WeChat service is temporarily unavailable, please try again later

8.3 创建模板文件

创建 src/main/resources/theme-resources/templates/wechat-login-button.ftl:

<#import "template.ftl" as layout>
<@layout.registrationLayout displayMessage=true; section>
    <#if section = "header">
        ${msg("wechat-authenticator-display-name")}
    <#elseif section = "form">
        <div id="kc-form">
            <div id="kc-form-wrapper">
                <form id="kc-wechat-login-form" class="${properties.kcFormClass!}" action="${url.loginAction}" method="post">
                    <input type="hidden" name="wechatAction" value="login"/>

                    <div class="${properties.kcFormGroupClass!}">
                        <div id="kc-form-buttons" class="${properties.kcFormButtonsClass!}">
                            <button
                                type="submit"
                                class="${properties.kcButtonClass!} ${properties.kcButtonPrimaryClass!} ${properties.kcButtonBlockClass!} ${properties.kcButtonLargeClass!}"
                                name="submit"
                                id="kc-wechat-login-button"
                            >
                                ${msg("wechat.button.login")}
                            </button>
                        </div>
                    </div>
                </form>

                <div style="margin-top: 20px; display: flex; justify-content: space-between; align-items: center;">
                    <div>
                        <a href="${url.loginUrl}">${msg("wechat.button.back")}</a>
                    </div>
                    <#if realm.password && realm.registrationAllowed && !registrationDisabled??>
                        <div>
                            <span>${msg("noAccount")} <a tabindex="6" href="${url.registrationUrl}">${msg("doRegister")}</a></span>
                        </div>
                    </#if>
                </div>
            </div>
        </div>
    </#if>
</@layout.registrationLayout>

创建 src/main/resources/theme-resources/templates/wechat-bind-phone.ftl:

<#import "template.ftl" as layout>
<@layout.registrationLayout displayMessage=true; section>
    <#if section = "header">
        ${msg("wechat.bind.phone.title")}
    <#elseif section = "form">
        <div id="kc-form">
            <div id="kc-form-wrapper">
                <form id="kc-wechat-phone-form" class="${properties.kcFormClass!}" action="${url.loginAction}" method="post">
                    <input type="hidden" name="wechatAction" value="sendCode"/>

                    <div class="${properties.kcFormGroupClass!}">
                        <label for="phone" class="${properties.kcLabelClass!}">${msg("wechat.bind.phone.label")}</label>
                        <input
                            type="tel"
                            id="phone"
                            name="phone"
                            class="${properties.kcInputClass!}"
                            placeholder="${msg("wechat.bind.phone.placeholder")}"
                            pattern="[0-9]{11}"
                            maxlength="11"
                            autocomplete="tel"
                            required
                            autofocus
                        />
                    </div>

                    <div class="${properties.kcFormGroupClass!}">
                        <div id="kc-form-buttons" class="${properties.kcFormButtonsClass!}">
                            <button
                                type="submit"
                                class="${properties.kcButtonClass!} ${properties.kcButtonPrimaryClass!} ${properties.kcButtonBlockClass!} ${properties.kcButtonLargeClass!}"
                                name="submit"
                                id="kc-submit-button"
                            >
                                ${msg("wechat.bind.button.sendCode")}
                            </button>
                        </div>
                    </div>
                </form>

                <div style="margin-top: 20px; display: flex; justify-content: space-between; align-items: center;">
                    <div>
                        <a href="${url.loginUrl}">${msg("wechat.button.back")}</a>
                    </div>
                    <#if realm.password && realm.registrationAllowed && !registrationDisabled??>
                        <div>
                            <span>${msg("noAccount")} <a tabindex="6" href="${url.registrationUrl}">${msg("doRegister")}</a></span>
                        </div>
                    </#if>
                </div>
            </div>
        </div>
    </#if>
</@layout.registrationLayout>

创建 src/main/resources/theme-resources/templates/wechat-bind-code.ftl:

<#import "template.ftl" as layout>
<@layout.registrationLayout displayMessage=true; section>
    <#if section = "header">
        ${msg("wechat.bind.code.title")}
    <#elseif section = "form">
        <div id="kc-form">
            <div id="kc-form-wrapper">
                <div class="${properties.kcFormGroupClass!}" style="margin-bottom: 20px;">
                    <div class="alert alert-info" style="padding: 10px; background-color: #d1ecf1; border: 1px solid #bee5eb; border-radius: 4px; color: #0c5460;">
                        <i class="pficon pficon-info" style="margin-right: 8px;"></i>
                        ${msg("wechat.bind.code.sent")} ${phone!""}
                    </div>
                </div>

                <form id="kc-wechat-code-form" class="${properties.kcFormClass!}" action="${url.loginAction}" method="post">
                    <input type="hidden" name="wechatAction" value="verifyCode"/>
                    <input type="hidden" name="phone" value="${phone!""}"/>

                    <div class="${properties.kcFormGroupClass!}">
                        <label for="code" class="${properties.kcLabelClass!}">${msg("wechat.bind.code.label")}</label>
                        <input
                            type="text"
                            id="code"
                            name="code"
                            class="${properties.kcInputClass!}"
                            placeholder="${msg("wechat.bind.code.placeholder")}"
                            pattern="[0-9]{6}"
                            maxlength="6"
                            inputmode="numeric"
                            autocomplete="off"
                            required
                            autofocus
                        />
                    </div>

                    <div class="${properties.kcFormGroupClass!}">
                        <div id="kc-form-buttons" class="${properties.kcFormButtonsClass!}">
                            <button
                                type="submit"
                                class="${properties.kcButtonClass!} ${properties.kcButtonPrimaryClass!} ${properties.kcButtonBlockClass!} ${properties.kcButtonLargeClass!}"
                                name="submit"
                                id="kc-submit-button"
                            >
                                ${msg("wechat.bind.button.verify")}
                            </button>
                        </div>
                    </div>
                </form>
            </div>
        </div>
    </#if>
</@layout.registrationLayout>

🔨 构建和部署

1. 编译项目

# 进入项目目录
cd keycloak-wx-authenticator

# 清理并编译
mvn clean package

# 编译成功后，JAR 文件位于：
# target/keycloak-wx-authenticator-1.0.0.jar

2. 更新 Docker Compose 配置

编辑父目录的 docker-compose.yml，添加微信认证器的挂载：

services:
  keycloak:
    # ... 其他配置 ...

    environment:
      # ... 其他环境变量 ...

      # ========================================
      # 微信 OAuth 配置
      # ========================================
      WECHAT_SERVICE_MOCK: ${WECHAT_SERVICE_MOCK:-true}
      WECHAT_PLATFORM_TYPE: ${WECHAT_PLATFORM_TYPE:-open}
      WECHAT_APP_ID: ${WECHAT_APP_ID:-}
      WECHAT_APP_SECRET: ${WECHAT_APP_SECRET:-}
      WECHAT_REDIRECT_URI: ${WECHAT_REDIRECT_URI:-}
      WECHAT_SCOPE: ${WECHAT_SCOPE:-snsapi_login}
      WECHAT_STATE_EXPIRE_TIME: ${WECHAT_STATE_EXPIRE_TIME:-300}
      SMS_SERVICE_MOCK: ${SMS_SERVICE_MOCK:-true}
      ALIYUN_ACCESS_KEY_ID: ${ALIYUN_ACCESS_KEY_ID:-}
      ALIYUN_ACCESS_KEY_SECRET: ${ALIYUN_ACCESS_KEY_SECRET:-}
      ALIYUN_SMS_SIGN_NAME: ${ALIYUN_SMS_SIGN_NAME:-}
      ALIYUN_SMS_TEMPLATE_CODE: ${ALIYUN_SMS_TEMPLATE_CODE:-}
      PHONE_NUMBER_REGEX: ${PHONE_NUMBER_REGEX:-^1[3-9]\d{9}$}
      VERIFICATION_CODE_LENGTH: ${VERIFICATION_CODE_LENGTH:-6}
      USE_REDIS_CACHE: ${USE_REDIS_CACHE:-false}
      REDIS_HOST: ${REDIS_HOST:-localhost}
      REDIS_PORT: ${REDIS_PORT:-6379}
      REDIS_PASSWORD: ${REDIS_PASSWORD:-}
      REDIS_DATABASE: ${REDIS_DATABASE:-0}

    volumes:
      # ... 其他挂载 ...

      # 4. 微信登录扩展
      - ./keycloak-wx-authenticator/target/keycloak-wx-authenticator-1.0.0.jar:/opt/keycloak/providers/keycloak-wx-authenticator.jar:ro

3. 启动 Keycloak

# 回到父目录
cd ..

# 重建 Keycloak 容器
docker compose up -d --force-recreate keycloak

# 验证环境变量（确保 .env 生效）
docker compose exec keycloak env | grep WECHAT

# 查看日志，确认扩展加载成功
docker compose logs -f keycloak | grep -i wechat

# 应该看到类似输出：
# keycloak  | ... INFO  [org.keycloak.services] KC-SERVICES0001: Loading providers
# keycloak  | ... INFO  [WeChatAuthenticator] 微信认证器初始化: mock=true, stateCache=MemoryStateCache, smsService=MockSmsService

说明：docker compose restart 不会重新读取 .env。

⚙️ Keycloak 配置

1. 创建 Realm

访问 Keycloak 管理控制台：http://localhost:8081
登录（admin / 你的密码）
点击左上角下拉菜单 → Create Realm
Realm name: vectorstory-test
点击 Create

2. 配置用户属性

在 Realm Settings → User Profile → Attributes：

添加以下属性：

Attribute name	Display name	Required	Permissions: User can edit
phone	手机号	❌ No	❌ No
phoneVerified	手机号已验证	❌ No	❌ No
wechatOpenId	微信 OpenID	❌ No	❌ No
wechatUnionId	微信 UnionID	❌ No	❌ No
wechatNickname	微信昵称	❌ No	❌ No
wechatAvatar	微信头像	❌ No	❌ No
wechatGender	性别	❌ No	❌ No

3. 配置认证流程

3.1 创建微信登录流程

Authentication → Flows
点击右上角 Create flow
Name: Browser with WeChat
Flow type: Basic flow
点击 Create

3.2 添加认证步骤

在新创建的流程中：

点击 Add execution
搜索 WeChat Login（或 微信登录）
点击 Add
设置 Requirement 为 ALTERNATIVE

3.3 添加其他认证方式（可选）

为了支持多种登录方式：

添加 Username Password Form → 设置为 ALTERNATIVE
添加 Phone SMS Authenticator（如果已配置）→ 设置为 ALTERNATIVE

3.4 绑定认证流程

Authentication → Bindings 选项卡
Browser Flow 下拉选择 Browser with WeChat
点击 Save

4. 测试登录

打开浏览器隐私模式/无痕模式
访问：http://localhost:8081/realms/vectorstory-test/account
应该会重定向到登录页面
开发模式（Mock）: 首次登录进入手机号绑定，验证后完成登录
生产模式: 会重定向到微信授权页面，回调后进入手机号绑定

🧪 测试和调试

1. 查看日志

# 实时查看 Keycloak 日志
docker compose logs -f keycloak

# 过滤微信相关日志
docker compose logs -f keycloak | grep -i wechat

# 过滤认证相关日志
docker compose logs -f keycloak | grep -E "WeChatAuthenticator|OAuth|State"

2. Mock 模式调试

开发环境设置：

WECHAT_SERVICE_MOCK=true
SMS_SERVICE_MOCK=true

Mock 模式特点：

✅ 不需要真实微信平台账号
✅ 所有操作打印到日志
✅ 验证码会打印到日志（需手机号绑定）
✅ 快速迭代开发

查看 Mock 日志：

docker compose logs keycloak | grep "Mock"

# 示例输出：
# [Mock] 获取 Access Token: code=mock_code
# [Mock] Access Token: mock_access_token_..., OpenID: mock_openid_...
# [Mock] 获取用户信息: openid=mock_openid_...
# [Mock] 用户信息: nickname=测试用户_123456, openid=mock_openid_...
# 【Mock 短信】验证码: 123456

3. 验证 SPI 加载

# 检查扩展是否加载
docker compose exec keycloak ls -la /opt/keycloak/providers/

# 应该看到：
# keycloak-wx-authenticator.jar

# 检查日志确认加载
docker compose logs keycloak | grep "Added provider.*wechat"

# 应该看到：
# Added provider 'singleton' (WeChatAuthenticatorFactory)

4. 用户数据验证

登录后，在 Keycloak 管理控制台：

Users → 搜索手机号（如 13800138000）
查看用户属性，应该包含：
- phone
- phoneVerified
- wechatOpenId
- wechatNickname
- wechatAvatar
- 等

🚀 生产环境部署

1. 配置真实微信凭证

在 .env 文件中：

# 禁用 Mock 模式
WECHAT_SERVICE_MOCK=false

# 配置真实微信平台信息
WECHAT_PLATFORM_TYPE=open
WECHAT_APP_ID=wx1234567890abcdef
WECHAT_APP_SECRET=your_real_app_secret

# 回调地址默认由 Keycloak action URL 生成
# 如需兼容旧版本或自定义逻辑可保留
WECHAT_REDIRECT_URI=https://your-domain.com/realms/your-realm/login-actions/authenticate

# 短信服务（生产环境建议真实短信）
SMS_SERVICE_MOCK=false
ALIYUN_ACCESS_KEY_ID=your_key_id
ALIYUN_ACCESS_KEY_SECRET=your_key_secret
ALIYUN_SMS_SIGN_NAME=your_sign_name
ALIYUN_SMS_TEMPLATE_CODE=your_template_code

# 启用 Redis 缓存（推荐）
USE_REDIS_CACHE=true

2. HTTPS 配置

微信 OAuth 要求回调 URL 必须是 HTTPS（本地测试除外）。

方案 1: 使用 Nginx 反向代理

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

方案 2: Keycloak 原生 HTTPS

修改 docker-compose.yml:

environment:
  KC_HTTPS_ENABLED: true
  KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/conf/cert.pem
  KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/conf/key.pem

volumes:
  - ./certs/cert.pem:/opt/keycloak/conf/cert.pem:ro
  - ./certs/key.pem:/opt/keycloak/conf/key.pem:ro

3. 微信平台回调域名配置

在微信开放平台/公众平台：

应用管理 → 你的应用
网站应用：设置授权回调域 = your-domain.com
公众号：设置网页授权域名 = your-domain.com
上传验证文件（微信会提供）

4. 安全检查清单

生产部署前确认：

🐛 常见问题

Q1: 扩展未加载，Keycloak 日志没有微信相关信息

排查步骤:

# 1. 检查 JAR 文件是否存在
ls -la keycloak-wx-authenticator/target/keycloak-wx-authenticator-1.0.0.jar

# 2. 检查容器内挂载
docker compose exec keycloak ls -la /opt/keycloak/providers/

# 3. 检查 SPI 注册文件
unzip -l target/keycloak-wx-authenticator-1.0.0.jar | grep AuthenticatorFactory

# 应该看到：
# META-INF/services/org.keycloak.authentication.AuthenticatorFactory

解决方案:

确保 mvn clean package 编译成功
确保 docker-compose.yml 正确挂载了 JAR 文件
重建容器：docker compose up -d --force-recreate keycloak

Q2: 微信授权后报错 "State 参数无效"

原因: State 缓存失效或不一致

解决方案:

开发环境（单机）：

USE_REDIS_CACHE=false  # 使用内存缓存

生产环境（分布式）：

USE_REDIS_CACHE=true   # 必须使用 Redis

Q3: 获取 Access Token 失败，errcode=40029

错误信息: invalid code

原因: 授权码已被使用或过期

解决方案:

授权码只能使用一次
不要刷新回调页面
检查是否有重复的请求

Q4: 获取用户信息失败，errcode=40001

错误信息: invalid credential, access_token is invalid or not latest

原因: Access Token 无效

解决方案:

检查 AppID 和 AppSecret 是否正确
确认微信平台应用状态正常
检查作用域 scope 是否正确

Q5: 回调 URL 不匹配

错误信息: redirect_uri 参数错误

原因: 回调 URL 未在微信平台配置

解决方案:

确保域名与微信平台配置一致
检查 Keycloak KC_HOSTNAME/KC_PROXY（action URL 生成的域名必须正确）
如使用自定义回调逻辑，再检查 WECHAT_REDIRECT_URI
微信平台只需要配置域名，不需要完整 URL
- ✅ 配置: your-domain.com
- ❌ 不要配置: https://your-domain.com/realms/...

Q6: 本地开发无法测试真实微信登录

解决方案: 使用 ngrok 暴露本地端口

# 启动 ngrok
ngrok http 8081

# 获取公网 URL，例如：https://abc123.ngrok.io

# 如需兼容旧版本可保留
WECHAT_REDIRECT_URI=https://abc123.ngrok.io/realms/vectorstory-test/login-actions/authenticate

# 推荐：让 Keycloak action URL 使用公网域名
KC_HOSTNAME=abc123.ngrok.io

# 在微信平台配置授权回调域
# 域名: abc123.ngrok.io