Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cevheri/keycloak-custom-event-listener
Keycloak Extension - Custom Event Listener. User create and register events, listen and Call Rest API with Java
https://github.com/cevheri/keycloak-custom-event-listener
docker docker-compose java keycloak keycloak-extension keycloak-spi mockapi
Last synced: 3 months ago
JSON representation
Keycloak Extension - Custom Event Listener. User create and register events, listen and Call Rest API with Java
- Host: GitHub
- URL: https://github.com/cevheri/keycloak-custom-event-listener
- Owner: cevheri
- License: apache-2.0
- Created: 2021-09-10T06:18:22.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-02T19:47:58.000Z (4 months ago)
- Last Synced: 2024-11-02T20:26:00.957Z (4 months ago)
- Topics: docker, docker-compose, java, keycloak, keycloak-extension, keycloak-spi, mockapi
- Language: Java
- Homepage:
- Size: 183 KB
- Stars: 31
- Watchers: 3
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Keycloak Custom Event Listener and API Publisher
## TLDR
A Keycloak extension that listens for user events (create/register) and forwards them to your webhook.## Quick Start
```bash
# Clone the repository
git clone https://github.com/cevher/keycloak-custom-event-listener.git
cd keycloak-custom-event-listener# Set up environment variables
cp .env.example .env
# Edit .env and set your WEBHOOK_URL# Build the extension
mvn clean package# Copy JAR to Keycloak providers
cp target/custom-event-listener.jar providers/# or
### Attach keycloak dockerVolume (already in docker-compose file)
```yaml
volumes:
- ../../../target/custom-event-listener.jar://opt/jboss/keycloak/standalone/deployments/custom-event-listener.jar
```# Start Keycloak and Postgres
docker-compose up -d

### 2. Configuration
#### Set Up Environment Variables
```bash
# Copy example environment file
cp .env.example .env# Edit .env file and update the WEBHOOK_URL
# Example:
# WEBHOOK_URL=https://your-webhook-url.com/endpoint
```### 3. Build and Deploy
#### Build the Extension
```bash
mvn clean package
```#### Deploy to Keycloak (Normal installation without Docker)
```bash
# Create providers directory if it doesn't exist
mkdir -p keycloak/providers# Copy JAR to providers directory
cp target/custom-event-listener.jar keycloak/providers/
```### 4. Run Keycloak
#### Start Docker Container
```bash
docker-compose up -d
```### 5. Configure Keycloak
#### Enable Event Listener
1. Access Keycloak Admin Console (default: http://localhost:8080)
2. Login as admin (default credentials: admin/admin)
3. Navigate to:
- Events
- Event configs
- Events
4. Add "custom-event-listener"
5. Save

### 6. Configure Webhook
#### Set Up Webhook
1. **Ensure your webhook endpoint is publicly accessible.**2. **Configure the `WEBHOOK_URL` in the `docker-compose.yaml` file:**
```yaml:docker-compose.yaml
services:
keycloak:
image: quay.io/keycloak/keycloak:latest
environment:
- WEBHOOK_URL=https://your-webhook-url.com/endpoint
ports:
- "8080:8080"
volumes:
- ./providers:/opt/keycloak/providers
```3. **Test the webhook by sending a sample event from Keycloak or using a tool like Postman to ensure it receives the data correctly.**
4. **Monitor your webhook endpoint for incoming requests to verify that events are being forwarded successfully.**

## Usage
### Testing the Integration
#### Method 1: Admin Console
1. Users
2. Add User
3. Fill in the required fields:
- Username (required)
- First Name
- Last Name
4. Click "Create" to save the new user
5. Check your webhook endpoint for the notification

#### Method 2: Self-Registration
1. Go to http://localhost:8080/realms/master/account/#/
2. Click "Register" or navigate to the registration page
3. Fill out the registration form and submit


## Architecture
```mermaid
sequenceDiagram
participant User
participant Keycloak
participant EventListener
participant WebhookEndpointUser->>Keycloak: Registers or Creates an Account
Keycloak-->>EventListener: Emits User Registration Event
EventListener->>WebhookEndpoint: Sends Event Data
WebhookEndpoint-->>EventListener: Acknowledgement
```## Development
### Local Testing
You can use services like webhook.site or RequestBin to test the webhook integration:
1. Get a temporary webhook URL from webhook.site
2. Add it to your .env file
3. Create a user in Keycloak
4. Check the webhook.site dashboard for the event data### Cleanup
```bash
# Stop and remove containers
docker-compose down# Remove volumes (optional)
docker-compose down -v
docker volume ls | grep keycloak | awk '{print $2}' | xargs docker volume rm
```## Troubleshooting
### Common Issues
1. **Webhook not receiving events**
- Check if the WEBHOOK_URL in .env is correct
- Verify the event listener is enabled in Keycloak
- Check Keycloak logs for any errors2. **Build failures**
- Ensure Maven is installed
- Check Java version (requires Java 11+)### Logs
```bash
# View Keycloak logs
docker-compose logs -f keycloak
```## Contributing
Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.## License
[Apache-2.0 license](LICENSE)