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

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!