keycloak-services-social-weixin

KO | EN

gitlite — search

#javascript #python #ai #typescript #llm #deep-learning #java #windows #cli #kubernetes #awesome-list #pytorch #ios #open-source

keycloak-services-social-weixin

(★ 12)

Keycloak 微信登录插件，支持 PC 端扫码登录、关注公众号即登录、手机微信等登录方式。

keycloak-services-social-weixin Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# keycloak-services-social-weixin

[🇺🇸 English](README_en-US.md) | **[🇨🇳 简体中文](README.md)**

> 感谢原作者Jeff-Tian的开源项目，本项目是在原项目的基础上进行了一些修改，主要是适配了quay.io/keycloak 26.0版本。
> Keycloak 的微信登录插件，尝试在 Keycloak 里打通整个微信生态。相关文章：《[对接微信登录的三种方式 - Jeff Tian的文章 - 知乎](https://zhuanlan.zhihu.com/p/659232648)》

![Java CI with Maven](https://github.com/Jeff-Tian/keycloak-services-social-weixin/workflows/Java%20CI%20with%20Maven/badge.svg)
[![Maven Package](https://github.com/Jeff-Tian/keycloak-services-social-weixin/workflows/Maven%20Package/badge.svg)](https://github.com/Jeff-Tian/keycloak-services-social-weixin/packages)

## 在线体验

- [点击我，右上角点击登录，然后选择使用微信登录](https://keycloak.jiwai.win/realms/Brickverse/account/#/ )

## 如何使用

本项目是一个 Keycloak 的插件，所以你需要先有一个 Keycloak 实例，然后把本项目打包成 jar 包，放到 Keycloak 的 providers 目录下，然后重启 Keycloak 即可。即：

* Add the jar to the Keycloak server:
    * `cp target/keycloak-services-social-weixin-*.jar _KEYCLOAK_HOME_/providers/`

* 在生产环境下的keycloak，需要执行kc.sh build 注册provider

## 👨‍💻 本地开发

需要 JDK 17 或者以上。

```shell script
mvn install
```

::: tip

如果在本地碰到比如编译出错等问题，最简单的办法就是使用 GitHub CodeSpace，绕过环境问题。

![](https://raw.githubusercontent.com/z5882852/keycloak-services-social-weixin/main/assets/dev-container.jpg)

以上就是我在 CodeSpace 里开发本项目的截图，其开发容器配置在[这里](./.devcontainer/devcontainer.json)。

:::

### 如何调试？

我一般都是通过添加日志，然后重启 Keycloak 服务，然后查看日志来排查问题。

原因是这并不是一个独立的程序，无法通过 IDE 直接运行或者调试（找不到 Main class）。它是嵌入在 Keycloak 里，通过 Keycloak 的 SPI 机制来运行的。我一般都是通过 Docker 方式启动 Keycloak 或者直接将该包加载到服务器上的 Keycloak 实例，然后观察本地或者服务器端的日志输出来排查问题的。

如果有人知道如何在 IDE 中本地调试 Keycloak 的 SPI 插件，欢迎提供帮助！

## 跑测试

```shell script
mvn clean test
```

## Maven 包

[![](https://go.inversify.cn/api/dynamicimage?url=https://resume.jijiyy.me/zh-CN/jeff-tian/linked-in&width=332&height=242&version=v2)](https://www.linkedin.com/in/jeff~tian/)

我本是一名 JavaScript 程序员，使用 NodeJs 两年之后，就在 npm 上发布了 20 多个包。当开始折腾 Java 之后，也想在 Maven Central 中发布包，但折腾了很久之后，我放弃了——没想到这么复杂！发布到 Maven Central 的好处是可以方便其他项目在 pom.xml 中引用此包，所以还是有价值的，如果有谁知道怎么发布到 Maven Central，**请提供帮助**！

> 你也可以直接 fork 本仓库，并将它发布到 Maven Central，善莫大焉。

目前我在 GitHub 上发布了，在 GitHub 发布后，如果要在 pom.xml 中引用，不仅需要在 pom.xml 中配置 GitHub Packages 的仓库地址，还需要一个访问令牌，有一些麻烦。

当然，你也可以直接下载 jar 包：

- 支持 jboss/keycloak 16，你可以使用我打的包：https://github.com/Jeff-Tian/keycloak-services-social-weixin/packages/225091
- 支持 quay.io/keycloak 18.0.2 的代码版本：https://github.com/Jeff-Tian/keycloak-services-social-weixin/tree/8069d7b32cb225742d7566d61e7ca0d0e0e389a5
- 支持 quay.io/keycloak 21.1 的版本：https://github.com/Jeff-Tian/keycloak-services-social-weixin/tree/dev-keycloak-21
- 支持 quay.io/keycloak 22 的版本： https://github.com/Jeff-Tian/keycloak-services-social-weixin/tree/dev-keycloak-22
- 支持 quay.io/keycloak 26 的版本：

## 获取 jar 包

### 直接下载

你可以从 https://github.com/Jeff-Tian/keycloak-services-social-weixin/packages 获取已经打好的 jar 包，可以省去打包的步骤。

### 手动打包

如果需要自己手动打包，可以在本地命令行执行：

```shell
mvn package
ls target
```

### 自动打包

本项目使用 GitHub Actions 自动打包，只需要在 master 分支上提交代码，即可自动打包。但是注意，需要修改 pom.xml 中的版本号，否则打包出来的 jar 包版本号和已经打好的 jar 包版本号冲突，从而不能上传到 GitHub Packages。

## 发版

本项目使用 GitHub Actions 自动发版，只需要在 master 分支上打一个 tag，然后在 GitHub 上发布一个 release 即可。不过，一般来说，也不需要手动打 tag。每次提交代码到 master 分支，GitHub Actions 都会检测是否有版本号的变化。如果版本号发生了变化，就会自动将该版本号做为新的 tag，并基于此来发布一个 release。详见： [这个 yml 文件](.github/workflows/release.yml) 。

## 版本更新

当需要更新本项目的版本时，需要修改 pom.xml 中的版本号。或者使用如下命令，比如将版本号改为 0.5.14：

```shell
mvn versions:set -DnewVersion=0.5.14
```

## 配置截图

### Keycloak 16

![image](https://user-images.githubusercontent.com/3367820/82117152-fdfd0300-97a0-11ea-8e10-02c9d9838a0a.png)

### Keycloak 22

![](https://raw.githubusercontent.com/z5882852/keycloak-services-social-weixin/main/assets/config.png)

Client ID 和 公众号 App Id；Client Secret 和 公众号 App Secret 都可以是一样的，即通过手机或者 PC 的微信登录时，都使用同一个公众号。但是以上截图用了两个不同的，其中公众号 App Id 使用了我的个人测试公众号，在关注人数在 100 以内时可以使用。而手机端，则必须使用经过认证的企业公众号（特别感谢知友 [hhhnnn](https://www.zhihu.com/people/hhhnnn-78) 帮我提供，没有该服务号我没法调通手机端）。

## Docker 镜像

我也打包了一个包含[微信 idp 的 keycloak server docker 镜像](https://hub.docker.com/repository/docker/jefftian/keycloak-heroku)：
我补充了一个包含[微信 idp 的 keycloak server docker 镜像](https://hub.docker.com/r/monsterlin2024/keycloak-heroku)：

```shell script
docker pull jefftian/keycloak-heroku:latest

docker pull monsterlin2024/keycloak-heroku:26.0-wx0.6
```

## 一键部署

### 部署到 Heroku

点击这个按钮，可以部署一个包含微信登录的 Keycloak 到你自己的 Heroku：

[![Deploy to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://dashboard.heroku.com/new?button-url=https%3A%2F%2Fgithub.com%2FJeff-Tian%2Fkeycloak-heroku&template=https%3A%2F%2Fgithub.com%2FJeff-Tian%2Fkeycloak-heroku)

::: warning 注意
Heroku 不再提供免费的 Dyno，部署到 Heroku 可能会产生费用。

![](https://raw.githubusercontent.com/z5882852/keycloak-services-social-weixin/main/assets/heroku-bill.png)
:::

### 部署到 Okteto

[【免费架构】Heroku 不免费了，何去何从之 Keycloak 的容器化部署之路 - Jeff Tian的文章 - 知乎](https://zhuanlan.zhihu.com/p/611823061)

## 谁在使用

| URL                        | 说明                                           | 源码                                           |
|----------------------------|----------------------------------------------|----------------------------------------------|
| https://keycloak.jiwai.win | 我部署在 heroku 上的 Keycloak 实例                   | https://github.com/jeff-tian/keycloak-heroku |
| https://www.da-yi-jia.com  | 感谢[答疑家](https://www.da-yi-jia.com)对本项目的大力支持！ |

## 💵 欢迎问我！

有任何相关问题，欢迎来知乎咨询：

## Release Notes

* 2022090
    - 适配 quay.io/keycloak 18.0.2

* 20180730
    - 增加自适应微信登录功能。
    - 账号关联默认使用微信unionid，如unionid不存在则使用openId
    - pc和wechat使用同一套账号则必须绑定同一个开放平台，否则会绑定不同账号
    - wechat信息非必填,默认使用pc方式登录

* 20200514
    - 增加 customizedLoginUrlForPc 功能。

* 20230820
    - 适配 quay.io/keycloak 21.1 的版本（由于 21 既不支持老的配置页，又没有新的方式增加自定义配置页，所以只能通过导入老的 Keycloak 版本中的 微信 identity provider 配置）

* 20230823
    - 适配 quay.io/keycloak 22.0.1 的版本，可以正常显示所有的配置了！[【重磅更新】关注微信公众号即登录插件升级支持 Keycloak 22！ - Jeff Tian的文章 - 知乎](https://zhuanlan.zhihu.com/p/652167012) ![](https://raw.githubusercontent.com/z5882852/keycloak-services-social-weixin/main/assets/config.png)
* 20230827
    - 新增对微信开放平台的支持。 [【继续更新】尝试在 Keycloak 里打通整个微信生态 - Jeff Tian的文章 - 知乎](https://zhuanlan.zhihu.com/p/652566471)

* 20240129（[0.5.13](https://github.com/Jeff-Tian/keycloak-services-social-weixin/releases/tag/0.5.13)）
    - 优化关注公众号即登录方案的微信后台配置。 详见《[基于 Keycloak 的关注微信公众号即登录方案再次升级：有意思的成长 - Jeff Tian的文章 - 知乎](https://zhuanlan.zhihu.com/p/680356153)》

* 20250227（[0.6.0]
    - 适配 quay.io/keycloak 26.0版本。由于keycloak 对类库org.keycloak.services.HttpRequestImpl进行修订，转而使用类库org.keycloak.quarkus.runtime.integration.resteasy.QuarkusHttpRequest。

## Star History

感谢大家的支持！

[![Star History Chart](https://api.star-history.com/svg?repos=Jeff-Tian/keycloak-services-social-weixin,jyqq163/keycloak-services-social-weixin&type=Date)](https://star-history.com/#Jeff-Tian/keycloak-services-social-weixin&jyqq163/keycloak-services-social-weixin&Date)

## 致谢

- 感谢 [jyqq163/keycloak-services-social-weixin](https://github.com/jyqq163/keycloak-services-social-weixin) 提供的基础代码，本仓库从该仓库 fork 而来。
- 感谢 [hhhnnn](https://www.zhihu.com/people/hhhnnn-78) 提供的企业公众号，没有该服务号我没法调通手机端。
- 感谢[各位](https://github.com/Jeff-Tian/keycloak-services-social-weixin/graphs/contributors)发的 pull request 和 issue，让本项目越来越好！

## 原理

其实任何一个 OAuth2/OIDC 的登录插件都是一样的，都是通过一个授权链接，然后通过 code 换取 access_token，再通过 access_token 换取用户信息。详见《[三步开发社交账号登录（以钉钉登录举例） - Jeff Tian的文章 - 知乎](https://zhuanlan.zhihu.com/p/666423994) 》

### 以开放平台微信登录举例

#### 先构建授权链接

链接如下：

```
https://open.weixin.qq.com/connect/qrconnect?scope=snsapi_login&state=d3Yvfou3pdgp-UNVZ-i7DTDEbv4rZTWx6Wh7lmxzyvk.98VO-haMdj4.c0L0bnybTEatKpqInU02nQ&response_type=code&appid=wxc09e145146844e43&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Frealms%2Fmaster%2Fbroker%2Fweixin%2Fendpoint
```

用户使用微信扫描以上链接中展示的二维码后，会跳转到微信的授权页面，用户点击同意后，会跳转到我们的回调地址，并且带上 code 和 state 参数，如下：

```
https://keycloak.jiwai.win/realms/master/broker/weixin/endpoint?code=011er8000zwPzQ1Fvw200DTBCP1er80K&state=d3Yvfou3pdgp-UNVZ-i7DTDEbv4rZTWx6Wh7lmxzyvk.98VO-haMdj4.c0L0bnybTEatKpqInU02nQ
```

#### 通过 code 换取 access_token

#### 通过 access_token 换取用户信息

## 🧧 [其他 Keycloak 社交登录插件](https://afdian.net/album/1270bba089c511eebb825254001e7c00)

- [钉钉登录](https://github.com/Jeff-Tian/keycloak-services-social-dingding)
- [企业微信](https://github.com/Jeff-Tian/keycloak-services-social-wechatwork)

keycloak-services-social-weixin

keycloak-services-social-weixin Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

keycloak-services-social-weixin

keycloak-services-social-weixin Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README