MaxKey 4.2.0

• In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration.
• Select MaxKey 4.2.0 on Ubuntu 24.04 as the software version, choose your Region, then choose Launch through EC2.
• Choose m5.large, your key pair and a security group as described in Prerequisites.

First boot takes about a minute and a half. It creates the database, the keys and the administrator, then starts MaxKey.

Connect over SSH with your EC2 key pair. The SSH user for Ubuntu 24.04 is ubuntu.

Operating system SSH user

Ubuntu 24.04 ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

systemctl is-active maxkey maxkey-mgt mysql nginx maxkey-guard
sudo ss -tln | awk 'NR>1 {print $4}' | sort -u

active active active active active 0.0.0.0:22 0.0.0.0:443 0.0.0.0:80 127.0.0.1:3306 127.0.0.53%lo:53 127.0.0.54:53 [::]:22 [::]:443 [::]:80 [::ffff:127.0.0.1]:9526 [::ffff:127.0.0.1]:9527

Only SSH, HTTP and HTTPS listen on the network. The MaxKey portal (9527), the console API (9526) and MySQL (3306) listen on 127.0.0.1 only. In the socket list, [::ffff:127.0.0.1] is how Java shows 127.0.0.1, and port 53 is Ubuntu's local DNS resolver.

First boot writes everything that is unique to your instance to a file that only root can read. Read it with sudo. The file contains the following values:

sudo cat /root/maxkey-credentials.txt

# MaxKey 4.2.0 - written on first boot by maxkey-firstboot.service. Unique to this instance. Keep it secret. MAXKEY_PORTAL_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/maxkey/ MAXKEY_CONSOLE_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/maxkey-mgt/ MAXKEY_OIDC_ISSUER=https://ec2-203-0-113-10.compute-1.amazonaws.com/sign MAXKEY_TLS_SHA256=8A:3C:... MAXKEY_ADMIN_USER=admin MAXKEY_ADMIN_PASSWORD=<20 random characters> ...

• MAXKEY_PORTAL_URL and MAXKEY_CONSOLE_URL are where your users and your administrators sign in.
• MAXKEY_OIDC_ISSUER is the issuer that OpenID Connect clients on this instance put in their tokens (Step 8).
• MAXKEY_TLS_SHA256 is the fingerprint of the instance's own certificate.

Your browser warns that the certificate is not trusted. Compare the fingerprint it shows with this one before you continue.

Do not add the certificate to a trust store. Instead, replace it with a certificate from a certificate authority for your own name (Step 12).

The image includes an end-to-end test. It signs in as the administrator and creates a throwaway user, group, OpenID Connect client and CAS client. It then exercises the following:

• The OpenID Connect sign-in
• The CAS sign-in
• Enrolment of an authenticator app for two-factor sign-in
• Every refusal listed in Step 13

When it finishes, the test deletes everything it created. Run it:

sudo maxkey-selftest

ok console: the administrator signs in ok portal: the administrator signs in ok portal refuses upstream's default admin/maxkey ok portal refuses upstream demo user sunsx ok portal refuses a wrong password ok portal refuses the mobile-login bypass (any SMS code, GHSA-gfj2/923q) ok console refuses upstream's default admin/maxkey ok console refuses upstream demo user sunsx ok console refuses a wrong password ok console refuses the mobile-login bypass (any SMS code, GHSA-gfj2/923q) ok the administrator's failed-sign-in counter is back to its value before the self-test ok console API refuses an anonymous call ok console: throwaway user created ok console: group created ok console: user added to the group ok console: MaxKey generated an RS256 signing key for the client ok console: OIDC client created ok console: CAS client created ok console: group granted both clients ok portal: the throwaway user signs in ok OIDC: authorization code issued to the registered redirect URI ok OIDC: code exchanged for an access token + id_token (MaxKey 4.2.0 shape: value / additionalInformation.id_token) ok OIDC: the client's JWKS publishes the public key only ok OIDC: the id_token's RS256 signature verifies against the instance JWKS ok OIDC: id_token iss == this instance's issuer (https://ec2-203-0-113-10.compute-1.amazonaws.com/sign) ok OIDC: aud / sub / nonce are the client, the user and the request's nonce ok OIDC: a tampered id_token (sub=admin) fails verification ok OIDC: discovery names this instance's issuer and https://ec2-203-0-113-10.compute-1.amazonaws.com/ endpoints ok MFA: the portal generated a TOTP secret for the user (6 digits, 30 s) ok MFA: the user enrolled the authenticator (the server accepted a code computed from the secret) ok MFA: a current code verifies, a wrong code is refused ok CAS: a service ticket is issued for the registered service ok CAS: p3/serviceValidate succeeds for the user and its own service ok CAS: the same ticket is refused on replay ok CAS: a ticket is refused for another service (GHSA-rc95) ok CAS: a proxy-callback (pgtUrl) validation is refused by nginx ok cleanup: the throwaway clients are deleted ok cleanup: the throwaway user is deleted MAXKEY_SELFTEST_OK

• Open MAXKEY_PORTAL_URL from Step 4 in your browser and check the certificate fingerprint.
• Sign in as admin with the password from Step 4.

MaxKey refuses a wrong password, and it refuses upstream's default admin / maxkey.

Open MAXKEY_CONSOLE_URL and sign in as admin. The console's sign-in form has a field for the code shown in the picture beside it, and the form will not submit while that field is empty. Type the code you see. The captcha check is off on this image, so the server does not verify the code. The MaxKey 4.2.0 console form always asks for one.

The sign-in page may reload once as it opens. MaxKey is replacing a random sign-in token that its own request filter rejected. The page then loads normally.

Change the administrator's password first. Choose the user menu (top right), then Change Password. MaxKey's default password policy applies: 6 to 20 characters, with upper and lower case letters, digits and a special character.

Then create your own users and organisations under Identity (users, organisations, groups).

Signing in to the console. The console signs administrators in with a username and password. Its server-side MFA switch (maxkey.login.mfa) is on in this image and must stay on (Step 13). The switch does not ask an administrator for a second factor at password sign-in. It makes the console check the SMS code on mobile-number sign-in. No SMS provider is configured, so mobile sign-in is refused.

In the console, open Applications, select Add, then choose OpenID Connect 1.0 (or OAuth 2.0). Then complete these steps:

• Enter the application's sign-in URL and its redirect URI.
• Choose the scopes (openid, profile, email) and the grant type authorization_code.
• Under signing, choose RS256 and select Generate to create the client's own signing key.
• Save, then grant a group access to the application (Access, then Groups).

The issuer of every client on this instance defaults to MAXKEY_OIDC_ISSUER (https://<your name>/sign). If you leave the field empty, the instance fills it in, so the id_token carries iss. Your application uses these endpoints:

Purpose URL

Discovery https://<your name>/sign/authz/oauth/v20/.well-known/openid-configuration?client_id=<client id>

Authorization https://<your name>/sign/authz/oauth/v20/authorize

Token https://<your name>/sign/authz/oauth/v20/token

Keys (JWKS) https://<your name>/sign/authz/oauth/v20/jwks?client_id=<client id>

User info https://<your name>/sign/api/connect/userinfo

Important: MaxKey 4.2.0 token response layout. The token endpoint answers in MaxKey's own JSON layout, not with the field names of RFC 6749 / OpenID Connect. This is upstream behaviour in 4.2.0. Its move to Spring Boot 4 / Jackson 3 left the token serializer unused, and the unmodified upstream build answers the same way.

Many off-the-shelf OAuth 2.0 / OpenID Connect client libraries therefore cannot read the response directly. If you write the client yourself, map the fields as follows:

MaxKey 4.2.0 field Standard name

value access_token

tokenType token_type

expiresIn expires_in

refreshToken.value refresh_token

scope (a list) scope (space-separated)

additionalInformation.id_token id_token

The id_token itself is a standard RS256 JWT. It verifies against the client's JWKS, which publishes only the public key, and it carries iss, aud, sub and your nonce. The self-test (Step 5) runs this whole flow and verifies the signature.

For applications that expect a standard protocol, use CAS or SAML 2.0 (Step 9). They work with off-the-shelf clients on this version.

CAS. Add a CAS application, then complete these steps:

• Set the application's service URL, where users are sent back.
• Choose the CasDefaultAdapter adapter.
• Grant a group access.

Your application uses https://<your name>/sign/authz/cas as its CAS server. For example, the CAS 3.0 validation URL is https://<your name>/sign/authz/cas/p3/serviceValidate. A ticket validates only for the service it was issued to, and only once. This image refuses CAS proxy tickets and proxy callbacks (pgtUrl) (Step 13).

SAML 2.0. Add a SAML v2.0 application with your service provider's entity ID and assertion consumer URL. Then download MaxKey's IdP metadata from the application's page.

MaxKey signs with this instance's own IdP key. First boot creates the key, and the IdP keystore is /etc/maxkey/saml/saml-idp.jks.

Users can enrol an authenticator app (TOTP: Google Authenticator, Microsoft Authenticator, FreeOTP and similar) in the portal, under their profile's one-time password settings. MaxKey generates the secret and shows a QR code, and the user confirms with a current code.

The self-test enrols an authenticator this way. It checks that a current code verifies and that a wrong one is refused.

Limitation in 4.2.0. MaxKey 4.2.0 does not enforce a user's enrolled second factor when that user signs in with a password (GHSA-g4rp-w5gg-cwjw). Upstream fixed this on its main branch after 4.2.0. Until a MaxKey release with the fix is available, treat per-user two-factor sign-in as providing no protection. Rely on strong passwords and the console access list (Step 11).

You can limit the console (/maxkey-mgt/) and its API (/maxkey-mgt-api/) to your own networks in one file. Open it:

sudo cat /etc/nginx/sac/maxkey-console-access.conf

• Replace allow all; with your addresses and a final deny all;. For example, use allow 203.0.113.0/24; followed by deny all;.
• Run sudo nginx -t && sudo systemctl reload nginx.

The portal stays reachable for your users. The restriction covers every spelling of the console paths: upper case, %-encoded, //, dot segments and ; parameters.

Point a DNS name at the instance (for example sso.example.com), then run:

sudo maxkey-set-hostname sso.example.com

This command does the following:

• Renders nginx and MaxKey for the new name
• Mints a new self-signed end-entity certificate
• Updates the institution's domains
• Moves every OpenID Connect client that still uses the old default issuer to https://sso.example.com/sign

Update the applications that trust tokens from this server to the new issuer.

To use a certificate from a certificate authority, replace /etc/ssl/maxkey/maxkey.crt and /etc/ssl/maxkey/maxkey.key (key mode 0600), then run sudo systemctl reload nginx.

H=$(cat /etc/sac/maxkey-host);
IP=$(hostname -I | awk '{print $1}') for p in /sign/passkey/registration/begin /SIGN/PASSKEY/registration/begin /sign/passkey%2Fregistration/begin \
  /maxkey-mgt-api/passkey/registration/begin /sign/login/jwt /sign/access/session/terminate \
  /sign/authz/cas/p3/proxyValidate /sign/v3/api-docs /sign/actuator/health; do printf '%-45s %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' --cacert /etc/ssl/maxkey/maxkey.crt --resolve "$H:443:$IP" -X POST "https://$H$p")" done for u in ubuntu nobody; do printf '%s -> 127.0.0.1:9527: %s\n' "$u" "$(sudo -u $u curl -s -m 3 -o /dev/null -w '%{http_code}' http://127.0.0.1:9527/sign/login/get)"; done
sudo grep -h -E '^maxkey\.(login\.mfa|passkey\.enabled|login\.jwt)=' /etc/maxkey/mgt/application-maxkey-mgt.properties /etc/maxkey/portal/application-maxkey.properties | sort | uniq -c

/sign/passkey/registration/begin 403 /SIGN/PASSKEY/registration/begin 403 /sign/passkey%2Fregistration/begin 400 /maxkey-mgt-api/passkey/registration/begin 403 /sign/login/jwt 403 /sign/access/session/terminate 403 /sign/authz/cas/p3/proxyValidate 403 /sign/v3/api-docs 404 /sign/actuator/health 404 ubuntu -> 127.0.0.1:9527: 000 nobody -> 127.0.0.1:9527: 000 2 maxkey.login.jwt=false 2 maxkey.login.mfa=true 2 maxkey.passkey.enabled=false

The output shows the settings below. Keep them as shipped:

• Console MFA switch on (maxkey.login.mfa=true in /etc/maxkey/mgt/application-maxkey-mgt.properties), for GHSA-gfj2-7r3v-jfjg. With the switch off (upstream's console default), the MaxKey 4.2.0 console signs anyone in by mobile number or username without checking the SMS code, including as the administrator. Keep it on until a MaxKey release fixes the issue.
• Passkeys off and denied, for GHSA-q2xr-792r-2r22 (maxkey.passkey.enabled=false; nginx answers 403, or 400 for encoded and ; forms, on every /sign/passkey/ and /maxkey-mgt-api/passkey/ path). MaxKey 4.2.0 lets a signed-in user bind a passkey to someone else's account. With passkeys off, the SecureAnyCloud build does not register MaxKey's passkey endpoints at all (Step 16). Keep passkeys off until a MaxKey release fixes the issue.
• JWT login off and /sign/login/jwt denied (GHSA-98j5-7h45-7gj9). The JWT-login key is also unique to your instance.
• Session termination by a user denied (/sign/access/session/terminate, GHSA-6vx4-gvc8-5hfw: 4.2.0 has no ownership check). Administrators can still end sessions in the console.
• CAS proxy tickets and proxy callbacks refused. The API documentation and actuator paths are not exposed.
• The nftables owner guard is part of the security model. It stops other local accounts (here ubuntu and nobody, refused with 000) from talking to MaxKey without nginx in front. Do not disable it, flush it or stop nftables. MaxKey stops if the guard is removed.

• The administrator password is in /root/maxkey-credentials.txt. Change it in the console (Step 7), then delete it from that file.
• The database password, the JWT session secrets, the SAML keystore password and the Kerberos crypto key are in /etc/maxkey/secrets/ (root only). Only root and MaxKey can read the rendered configuration in /etc/maxkey/portal/ and /etc/maxkey/mgt/.
• First boot generated the JWK key sets (/etc/maxkey/classpath/config/) and the SAML keystores (/etc/maxkey/saml/) on your instance. The console generates each OpenID Connect client's signing key when you create the client.
• No secret appears on any command line, in a systemd unit or in a log. MaxKey logs to the journal at INFO level only.

MaxKey stores everything (users, organisations, applications and their keys, access rights, history) in the MySQL database maxkey. Back it up to a file that only root can read:

sudo sh -c 'umask 077; mysqldump --single-transaction --routines --triggers maxkey > /var/backups/maxkey-$(date +%F).sql'
sudo ls -l /var/backups/ | grep maxkey

-rw------- 1 root root 74907 Oct 31 21:41 maxkey-2026-10-31.sql

The dump holds password hashes and application signing keys, so store it encrypted and off the instance. Keep a copy of /etc/maxkey/ (root only) with it, because the JWK sets, SAML keystores and secrets there belong with the database. EBS snapshots are a simple way to keep point-in-time copies of the whole server.

ls /usr/share/doc/sac-maxkey/ sed -n '1,3p;/^patch (d-725)/,/^removed:/p' /usr/share/doc/sac-maxkey/BUILD-INFO

3rdpartylicenses-mgt.txt 3rdpartylicenses-portal.txt BUILD-INFO LICENSE-maxkey-Apache-2.0.txt NOTICE-maxkey.txt SOURCE.txt passkey-endpoints-conditional.patch MaxKey 4.2.0 - sac build of the pinned upstream tag (one coordinator-ruled minimal patch, d-725; nothing else changed) source: https://github.com/dromara/MaxKey.git tag 4.2.0 commit e147ade6a3c5f2e11a202b3e66c4522605bc4c6d (Apache-2.0, LICENSE sha256 9bab590ff9e938c73b25eb45a3edb01e81ae573982ab9cdf08448f6ddfff4896) toolchain: openjdk version "21.0.12.1" 2026-08-18; Gradle 9.1.0 (sha256 a17ddd85a26b6a7f5ddb71ff8b05fc5104c0202c6e64782429790c933686c806); node v24.22.2; pnpm 12.6.0 patch (d-725): passkey-endpoints-conditional.patch sha256 c6cfd28eb82ec3fafbee7f67a69847f4cb858984022691cc748d357c6d344831 (sac-authored, Apache-2.0, 10 added lines in maxkey-starter/maxkey-starter-passkey/src/main/java/org/dromara/maxkey/passkey/endpoint/Passkey{Registration,Authentication}Endpoint.java: @ConditionalOnProperty(prefix="maxkey.passkey", name="enabled", havingValue="true", matchIfMissing=true), so with passkeys off the endpoints are not registered; GHSA-q2xr-792r-2r22. The diff ships in /usr/share/doc/sac-maxkey/.) removed: taobao-sdk-java-auto_1479188381469-20210326.jar (sha256 b57882f9fc4e0845a29e3eee285b1866b54b72f7f89c349438d19d77bae99121; DingTalk SDK, no licence) from both boot jars, and

MaxKey is licensed under the Apache License 2.0. The front-end libraries and their licences are listed in 3rdpartylicenses-portal.txt and 3rdpartylicenses-mgt.txt.

The one source change. SecureAnyCloud adds one annotation to each of MaxKey's two passkey endpoint classes (passkey-endpoints-conditional.patch, 10 added lines, Apache-2.0, shipped in this directory). The endpoints are then registered only when passkeys are enabled (maxkey.passkey.enabled), the same condition that MaxKey's own passkey configuration uses. Upstream 4.2.0 registers them even with passkeys switched off (GHSA-q2xr-792r-2r22). Nothing else in MaxKey is modified.

What is not shipped, for licence reasons:

• The DingTalk open-platform SDK, which is distributed without a licence. DingTalk directory synchronisation is not available. LDAP, Active Directory, WeCom, Feishu and JDBC synchronizers are available.
• The MaxMind GeoLite2 database (GeoLite2 EULA). Sign-in location lookup uses the bundled ip2region database only. The GeoIP2 provider option is not available.

• Advisories. MaxKey 4.2.0 is the current release. This image closes the advisories that are still open in it through configuration (Step 13) and the source change described in Step 16. The exception is GHSA-g4rp (Step 10).
• Bundled libraries. The bundled Java libraries were raised to versions without known issues where a fix exists in their release line. Six findings remain, and none is reachable in this configuration:
  • The captcha library kaptcha 2.3.2 has predictable captcha text (CVE-2018-18531). The captcha check is off on this image. The console's sign-in form still shows a picture, but the server does not check its code.
  • velocity 1.7 (CVE-2020-13936) is exploitable only by editing templates. MaxKey uses its own built-in SAML POST template.
  • commons-httpclient 3.1 and not-yet-commons-ssl 0.3.9 (CVE-2012-5783, CVE-2014-3604) perform no host-name check on TLS. Only the legacy SAML library uses them, to fetch remote metadata over HTTPS. Upload SP metadata instead of pointing MaxKey at a URL.
  • commons-lang 2.6 (CVE-2025-48924) can overflow the stack on very long class names. No user input reaches it.
  • The OGNL copy inside MyBatis 3.5.19 (CVE-2026-113730) evaluates only MaxKey's own SQL mapping expressions.
  • In the console's front end, the rich-text editor Quill 2.0.3 has a low-severity issue with no fix (CVE-2025-15056). Only signed-in administrators can reach it.
• Outbound requests. MaxKey connects to URLs that administrators configure: LDAP directories, synchronizers, SAML and OpenID Connect metadata. Those connections cannot reach the EC2 metadata service.
• Disabled features. Captcha, self-registration, social sign-in and "remember me" are off. Configure an SMTP server and SMS provider in the console if you need password-reset mail or SMS codes.
• One server. MaxKey keeps sessions in memory, so restarting it signs everyone out. Use a single instance, or put Redis behind it for a cluster (maxkey.server.persistence=2).