keycloak-http-header-condition-plugin

Keycloak conditional authenticator that evaluates incoming HTTP headers against a Java regex.

Features

• regex check for incoming HTTP headers in authentication flows
• optional boolean negation of the final condition
• supports multi-value headers (condition is true if any value matches)

Configuration options

• HTTP header name — header name to inspect
• Header regex — Java regex. The full header value must match because the authenticator uses Matcher.matches(). Invalid regex fails closed and returns false regardless of Negate result.
• Negate result — invert match result

Examples

Example 1

• Header name: X-Env
• Regex: prod|stage
• Negate result: false

Condition returns true when the incoming X-Env header equals prod or stage.

Example 2

• Header name: X-Forwarded-Host
• Regex: ^admin\\.example\\.com$
• Negate result: true

Condition returns true when the incoming host does not match admin.example.com.

Build

mvn clean package

Deploy to Keycloak

Copy the resulting JAR to the Keycloak providers directory:

cp target/http-header-condition-plugin-*.jar /opt/keycloak/providers/

Then rebuild or restart Keycloak depending on your distribution, for example:

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

Usage in authentication flow

1. Open Authentication in the Keycloak Admin Console.
2. Create or edit a flow/subflow with requirement Conditional.
3. Add execution Condition - HTTP Header Regex to that conditional subflow.
4. Keep the execution requirement as Required unless you want to disable the condition.
5. Configure HTTP header name and other settings.