https://github.com/dsb-norge/keycloak-friendly-captcha
Custom keycloak provider which adds the ability to use FriendlyCaptcha in a authentication flow
https://github.com/dsb-norge/keycloak-friendly-captcha
captcha dsb-library friendly-captcha keycloak
Last synced: 2 months ago
JSON representation
Custom keycloak provider which adds the ability to use FriendlyCaptcha in a authentication flow
- Host: GitHub
- URL: https://github.com/dsb-norge/keycloak-friendly-captcha
- Owner: dsb-norge
- License: isc
- Created: 2025-01-16T12:19:05.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-03-31T01:00:10.000Z (3 months ago)
- Last Synced: 2025-03-31T02:19:49.142Z (3 months ago)
- Topics: captcha, dsb-library, friendly-captcha, keycloak
- Language: Kotlin
- Homepage: https://www.dsb.no
- Size: 120 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Keycloak Friendly Captcha
[](https://sonarcloud.io/summary/new_code?id=dsb-norge_keycloak-friendly-captcha)
A Keycloak authentication plugin that integrates [Friendly Captcha](https://friendlycaptcha.com/) into the registration flow. Friendly Captcha is a privacy-friendly, GDPR-compliant alternative to reCAPTCHA that respects user privacy while effectively preventing spam and abuse.
## Features
- Easy integration with Keycloak registration flow
- Privacy-focused CAPTCHA solution
- Configurable API endpoint
- Customizable form field names
- Optional failure handling for API errors
## Prerequisites
- Keycloak 26.1.0 or later (will most likely work with earlier versions)
- Java 17 or later
- A Friendly Captcha account with site key and secret key
## Installation
1. Build the plugin:
```bash
mvn clean package
```
2. Copy the generated JAR file from `target/keycloak-friendly-captcha-1.0-SNAPSHOT.jar` to Keycloak's `providers` directory.
3. Restart Keycloak to load the plugin.
## Configuration
### 1. Add Authentication Execution
1. In the Keycloak admin console, go to Authentication
2. Select the "Registration flow" (You probably need to duplicate it, if its the built in one)
3. Click "+" button next to the "Registration form" step
4. On the popup click "Add step"
5. Select "Friendly Captcha" from the list
6. Configure all the values for the plugin (See below)
7. Set the requirement to "Required"
8. Make sure that the flow you have modified is bound to the "Registration flow"
9. The Friendly Captcha should now show up in the registration form (Provided you have added the necessary HTML to the registration form)
**Note:** if you are using the v2 version you need to tweak the Content-Security-Policy inside the realm settings under the "Security Defenses" tab.
Writing: `frame-src 'self' https://global.frcapi.com; frame-ancestors 'self'; object-src 'none';` should be enough. (Or the domain you are using)
### 2. Configure the Execution
Click the gear icon next to the Friendly Captcha execution and configure:
- **Site Key**: Your Friendly Captcha site key
- **Secret Key**: Your Friendly Captcha secret key (API Key)
- **API Domain**: The Friendly Captcha API domain (default: https://api.friendlycaptcha.com)
- **Form field name**: The name of the form field for the captcha solution (default: frc-captcha-solution)
- **Fail on HTTP status error**: Whether to fail on API errors (default: false)
### 3. Add to template file `register.ftl`
Add the following code to the `register.ftl` file in your theme to render the Friendly Captcha widget:
```html
<#if friendlyCaptchaRequired??>
lang="${friendlyCaptchaLang}"
data-api-endpoint="${friendlyCaptchaApiDomain}/api/v2/captcha"
data-form-field-name="${friendlyCaptchaFormAttribute}"
data-theme="auto"
<#else>
data-lang="${friendlyCaptchaLang}"
data-puzzle-endpoint="${friendlyCaptchaApiDomain}/api/v1/puzzle"
data-solution-field-name="${friendlyCaptchaFormAttribute}"
#if>
>
#if>
```
**Note:** `data-theme="auto"` uses the theme of the client. If you want to use a specific theme, you can set it to `light` or `dark`.
#### Note about *Fail on HTTP status error*:
See Friendly Captcha [Best Practices](https://developer.friendlycaptcha.com/docs/v1/getting-started/verify#verification-best-practices)
So if this value is false, the user will be allowed to continue even if the API returns an error. If it is true, the user will be blocked from continuing.
## Development
For local development, you can use the provided Docker Compose file:
```bash
mvn clean package
docker-compose up
```
This will start Keycloak with the plugin pre-installed at http://localhost:8080.
### Update included javascript scripts
The plugin includes the Friendly Captcha javascript scripts in [Resources](src/main/resources/theme/base/login/resources/js) directory. To update these scripts, download the latest version from a CDN and replace the existing files.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.