AusWeis — Cloudflare Turnstile Verification

AusWeis is a lightweight Bukkit/Paper plugin that integrates Cloudflare Turnstile to provide frictionless human verification before players enter your server. It effectively stops bot attacks while offering a smooth experience for real players.

I am not a native English speaker, so corrections are welcome if there are any mistakes.

Features

• Simple workflow – Players are kicked once with a verification URL; after completing the Turnstile challenge on your website, they can rejoin normally.
• Real‑time API check – Every login queries your backend API for the player's verification status (no local cache, always up‑to‑date).
• Bypass permission – Grant ausweis.bypass to trusted players (or yourself) to skip verification entirely.
• Highly customisable – Kick message, API URL, timeout and more can be changed in config.yml. Supports Minecraft colour codes and multi‑line messages.
• Multi‑language ready – Choose the language in config (en, zh, or add your own .yml files in the lang folder). Built‑in English and Chinese translations.
• Command reload – Use /ausweis reload to apply configuration changes without restarting the server.
• Wide compatibility – Works on Spigot/Paper from 1.8 to latest (tested on 1.12.2, 1.16.5, 1.21+).

Installation

1. Download the latest AusWeis-*.jar from the Releases page.
2. Place the JAR file into your server's plugins/ folder.
3. Restart your server (or use /reload – restart is recommended).
4. The plugin will generate a default config.yml and a lang/ folder with language files.
5. Edit plugins/AusWeis/config.yml to set your own backend API URL and verification page URL.
6. Run /ausweis reload to apply the changes.

Config

# Language file to use (e.g., en, zh). Must correspond to a messages_<lang>.yml file in the lang folder.
language: "en"
# API URL to check player verification status
api-url: "https://your-server.com/api/check?user={player}"
# Verification page URL to show in kick message
verify-url: "https://your-server.com/verify?user={player}"
# HTTP request timeout in milliseconds
timeout: 5000
# Debug mode, enables more detailed logs
debug: false

Commands

Command	Description	Permission	Default
/ausweis reload	Reload the plugin configuration	ausweis.reload	op
/ausw reload	Alias for the above	same	op

Permission	Description	Default
ausweis.reload	Allows reloading config	op
ausweis.bypass	Bypass verification and always join	false

API Specification

Your website must provide two endpoints:

1. Verification Status Query

• URL: GET {api-url}?user={player}
• Response format: JSON

  {
    "verified": true,
    "user": "Steve",
    "timestamp": 1709123456.789
  }
  

• Description: Return "verified": true if the player has already passed the Turnstile challenge, otherwise false.

2. Verification Page

• URL: {verify-url}?user={player}
• Function: Display the Cloudflare Turnstile widget. After successful verification, your backend should mark the player as verified (e.g., update a database) so that subsequent API calls return true.

Reference implementation: The companion web backend is open‑sourced by @ChineseLiyao – ChineseLiyao/AusWeis. You can deploy it directly or use it as an example.

Languages

1. Create a new file messages_<code>.yml in the plugins/AusWeis/lang/ folder (e.g., messages_fr.yml for French).
2. Use the same keys as in the built‑in language files (kick-title, kick-message).
3. Set language: "<code>" in config.yml and reload.

Building

If you prefer to compile the plugin yourself:

git clone https://github.com/Nskawa/AusWeisPlugin.git
cd AusWeis
mvn clean package

The compiled JAR will be in the target/ directory.

License

This project is licensed under the MIT License – see the LICENSE file for details.

Support

• GitHub Issues: Report bugs / suggest features
• Discussion: Feel free to open a discussion on GitHub or leave a comment below.

Happy Gaming!