MaxKey puts five SSO protocols and nine sign-in methods in one Java product

Two separate protocol tables describe what MaxKey speaks and how users log in

MaxKey's README organises its reach into two tables that are easy to conflate. The first is application facing: OAuth 2.x/OpenID Connect, SAML 2.0, JWT, CAS and SCIM 2.0 are each marked HIGH, while FormBased and TokenBased(Post/Cookie) are marked MIDDLE, and ExtendApi and EXT are marked LOW.

Those ratings are the project's own assessment and they are worth taking at face value when you scope a migration. A HIGH entry is the path the team considers solid; a LOW entry is an escape hatch. If your application can only do form posts back to a central login page, you are on a MIDDLE path and should test it early rather than discovering the rough edge during cutover.

The second table is user facing, listing nine sign-in methods: captcha in letter, number or arithmetic form; two factor authentication over SMS, TOTP or mail; SMS through Tencent, Alibaba or NetEaseYunXin; TOTP with Google Authenticator, Microsoft Authenticator, FreeOTP, plus TOTP or HOTP support; domain integration via Kerberos, SPNEGO or Active Directory; LDAP against OpenLDAP, Active Directory or a standard LDAP server; social accounts covering WeChat, QQ, Weibo, DingTalk, Google, Facebook and others; QR code scanning through WeCom, DingTalk and FeiShu; and passwordless sign-in using WebAuthn FIDO2 and passkey.

That breadth is the product. MaxKey is positioned as an identity provider for enterprises rather than a library, and the wide sign-in table is the reason a team would look at it at all.

The build is a set of Gradle modules split by protocol, persistence and UI

The repository root is a Gradle multi-project build with gradlew, gradlew.bat, settings.gradle, build.gradle, build_cnf.gradle and gradle.properties. The module names map onto the product's internal structure:

maxkey-authentications/  maxkey-commons/  maxkey-entity/
maxkey-lib/  maxkey-persistence/  maxkey-protocols/
maxkey-starter/  maxkey-synchronizers/  maxkey-web-apis/
maxkey-web-frontend/  maxkey-webs/

maxkey-protocols is where the federation protocol implementations sit, separated from maxkey-authentications, which is where the sign-in methods sit. maxkey-persistence and maxkey-entity cover storage, maxkey-web-apis and maxkey-webs cover the HTTP surface, and maxkey-web-frontend is the bundled frontend. maxkey-starter is the assembled application, and maxkey-synchronizers is the directory-side provisioning side that pairs with SCIM.

Three supporting directories matter for operators. sql/ holds the database schema, deployment/ holds packaging, and integrations/ is separate from both. Release is script driven: release.bat, release_docker.bat, release_docker_push.bat, release_frontend.bat and release_frontend_docker_push.bat sit at the root next to setEnvVars.bat and gradle-version.bat.

JDK 21 and MySQL 8.4 are the stated floor, Spring and Redis the stated stack

The README badges state the requirements plainly: JDK v21+ and MySQL 8.4+. Those two numbers decide whether you can evaluate MaxKey at all, and they are stricter than a great many Java identity products still running on JDK 8 or 11 baselines.

The install section does not give shell commands in the README itself. It lists four targets, Windows, Linux, Docker and a panel installer, each pointing at the same document page at https://www.maxkey.top/zh/about/download.html. The download section does pin a version: v 4.1.12, dated 2026/06/30, with a download link on the project's own site.

For the underlying stack, feature point 9 states that MaxKey is based on the Java EE platform with a microservice architecture and uses Spring, MySQL, Tomcat and Redis among other open source components. Redis is named there but no cache or session configuration is documented in the README, so if you are sizing an HA deployment, treat the Redis role as something to confirm with the maintainers rather than something you can read off.

Multi-tenancy and RBAC are the two features a group company would ask about first

Feature 6 describes MaxKey as an IDaaS multi-tenancy authentication platform supporting independent management of multiple enterprises under a group company, or data isolation between departments inside one enterprise, with the stated goal of reducing operations cost. That is a tenancy model with two levels rather than one, which matters if you are consolidating subsidiaries onto one identity server and need either separate brands or separate departmental boundaries.

Feature 1 of the overview describes the base SSO model in two sentences: users log in to the authentication centre once and then reach all trusted application systems without logging in again, and each application can identify and extract the ticket.

Feature 4 ties SCIM 2.0 to identity lifecycle management and states that the out of the box connector handles identity supply synchronisation. Combined with the LDAP and Active Directory rows in the sign-in table, that means the directory story is two sided: users authenticate against an existing directory, and accounts can be provisioned into one.

Audit and geo lookup lean on external IP databases

Feature 8 covers the policy and audit surface: configurable password and access policies, precise IP location using either the Ip2region or GeoLite2 geographic database, security auditing, full lifecycle auditing of users, traceability of access behaviour records, compliance audit, and risk warning.

Ip2region and GeoLite2 are named as alternatives you supply, not data bundled with the project. The README does not explain the licensing or distribution terms for these geographic databases. Nothing in the README explains what happens when a lookup misses, such as a VPN address or an unassigned block, and that is a real question to answer before you make geography part of an access rule.

The audit side is the part most likely to matter for the compliance use cases the project names. Whether audit records can be exported in a form your SIEM ingests is not documented.

Where the README stops short, and what that means for an evaluation

Several gaps are visible. There is no clustering or high availability documentation in the README, no statement about which databases other than MySQL are supported, no HA story for Redis, and no upgrade path between versions. There are no GitHub releases for the project; the version history is instead carried by ReleaseNotes.txt in the repository root and by the download table.

The repository does carry the governance files an Apache-licensed project is expected to have: LICENSE, NOTICE, SECURITY.md, CONTRIBUTING.md and CODE_OF_CONDUCT-style material, plus 3rdpartylicenses.txt for bundled dependencies and a.circleci directory for CI. Release numbering follows a 4.1.x line, with 4.1.12 published on 2026-06-30, 4.1.11 on 2026-02-02 and 4.1.10 on 2025-12-13. The last push to the repository was on 2026-10-16.

Support channels are also worth noting before you commit. Issues are tracked on Gitee rather than on the GitHub mirror, alongside GitHub, Gitee and GitCode as the three hosting mirrors, with an online demo, a WeChat account, a QQ group and a support email listed in the README. That shape suits a team already working in that ecosystem and is worth weighing if your engineering organisation is not.

Editorial conclusion

MaxKey fits organisations whose existing applications already speak one of the mainstream federation protocols and which want to self-host an identity provider under Apache-2.0 rather than rent one. It is the wrong choice if you want a library to embed, or if your environment cannot supply JDK 21 and MySQL 8.4. Before deploying, read the install documentation at https://www.maxkey.top/zh/about/download.html for your platform and confirm which of the nine sign-in methods in its table you actually need, since the ones marked MIDDLE and LOW in the protocol table are the ones to test first.

Frequently asked questions

Official sources

1. dromara/MaxKey on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases