Keycloak Event Listener Slack

Project description

This project is an extension for Keycloak that allows to forward events to specified Slack channel. It's build for Keycloak X (quarkus), so it won't work with legacy Wildfly based Keycloak distributions.

Set up with Keycloak

Minimal Dockerfile for bundling this extension together with Keycloak could look like following:

FROM quay.io/keycloak/keycloak:18.0.2

ARG SLACK_LISTENER_VERSION=0.3.0

RUN curl -s -L -o /opt/keycloak/providers/keycloak-event-listener-slack--$SLACK_LISTENER_VERSION.jar \
    https://github.com/kilmajster/keycloak-event-listener-slack/releases/download/$SLACK_LISTENER_VERSION/keycloak-event-listener-slack-$SLACK_LISTENER_VERSION.jar

RUN /opt/keycloak/bin/kc.sh build

ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start"]

Configuration

Creating and configuring Slack app

Go to https://api.slack.com/apps and click Create New App, choose option From scratch and provide App Name e.g. Keycloak then choose app installation workspace.

After creating an app, go to its features and choose Activate Incoming Webhooks and then click Add New Webhook to Workspace, choose which channel Keycloak should send messages to and click Allow.

When Incoming Webhooks are active, go to OAuth & Permissions and in Scopes add chat:write (you could need to reinstall app into workspace at this point)

After that, copy Bot User OAuth Token (xoxb-123123123...) - you will need to add it as env variable for Keycloak.

Last step is to add app you just created to specific channel, to do that simply mention app by name at the desired channel, for e.g. @Keycloak, Slack will ask if you want to add app to channel, click accept button.

👏 Done! From now Slack is ready to receiving messages from Keycloak.

In case of missing configuration WARN with error code will be logged. All error codes are described here.

Configuring Keycloak

Keycloak configuration is done based on environment variables. All their names and descriptions are listed below:

• SLACK_TOKEN - Slack Bot User OAuth Token. E.g. "xoxb-123123123..."

• SLACK_CHANNEL- channel used for forwarding events to. Can be channel name with # (#general) or channel ID (C03V7AT6DHS)

• SLACK_INCLUDE_EVENTS - comma-separated list of event types that should be forward to Slack. When present, other event related env variables are ignored. E.g. "LOGIN, LOGIN_ERROR, LOGOUT, LOGOUT_ERROR"

• SLACK_INCLUDE_ALL_EVENTS - for forwarding all possible events, good for testing purposes, not recommended for production. Available values are "true" / "false".

• SLACK_INCLUDE_ALL_EVENTS_EXCEPT - comma-separated list of event types exceptions, all other will be forwarded to Slack. E.g. "LOGIN, LOGIN_ERROR"

• SLACK_INCLUDE_ALL_ERRORS - for forwarding all possible error events. Available values are "true" / "false".

• SLACK_INCLUDE_ALL_ERRORS_EXCEPT - comma-separated list of error events exceptions, all other errors will be sent to Slack. E.g. "LOGIN_ERROR, LOGOUT_ERROR, UPDATE_PASSWORD_ERROR"

• SLACK_INCLUDE_ADMIN_EVENTS - comma-separated list of admin operations (such as users creation, clients changes etc.). Available values are CREATE, UPDATE, DELETE, ACTION

• SLACK_INCLUDE_ALL_ADMIN_EVENTS - for forwarding all events done by admin. Available values are "true" / "false".

Configuring message format

By default, events json representation will be attached to the message. It can be disabled by:

• SLACK_INCLUDE_EVENT_REPRESENTATION="false" - for normal event types

• SLACK_INCLUDE_ADMIN_EVENT_REPRESENTATION="false"" - for admin events

Enabling listener in Keycloak

In the Keycloak admin console, choose realm and under manage section go to Events. Switch to the Config tab and add slack to the Event Listeners then click Save button.

🕶 Done, Keycloak is ready to send messages with events to your Slack.

Development & testing

To build a project, do following:

$ mvn clean install

You will need Slack workspace and app configured same as in Configuration section, update SLACK_TOKEN and SLACK_CHANNEL in docker-compose.yml file and run:

$ docker-compose up

Enable listener, just like it is described in Enabling listener in Keycloak section.

Running automation tests locally

Build a project with mvn clean install, and run:

$  mvn verify -P automation-tests -D slack.token=<your Slack token> -D slack.channel=<your Slack channel>