Introduction: KumuluzEE Security extension for easy integration with OAuth2/OpenID identity and access management providers.
More: Author   ReportBugs   OfficialWebsite   

Build Status

KumuluzEE Security extension for the Kumuluz EE microservice framework.

KumuluzEE Security is a security project for the KumuluzEE microservice framework. It provides support for OpenID authentication through standard Java EE security annotations for roles. It is specifically targeted towards securing REST services. Roles are mapped to the selected OpenID provider. KumuluzEE Security has been designed to work with different OpenID providers. Currently only Keycloak is supported. Contributions for other OpenID providers are welcome.


You can enable the KumuluzEE Security authentication with Keycloak by adding the following dependencies:


The keycloak.version property should match the version of keycloak that is used.

Security configuration

To protect a REST service using KumuluzEE Security authentication you have to annotate the REST application class with the @DeclareRoles annotation. When using the @DeclareRoles annotation the Keycloak configuration (keycloak.json) has to be provided with configuration key kumuluzee.security.keycloak.json. The configuration key can be defined as an environment variable, file property or config server entry (if using the KumuluzEE Config project with support for etcd/Consul). Please refer to KumuluzEE Config for more information. Optionally you can also provide the configuration in code using the @Keycloak annotation.

Example of security configuration with configuration override:

@DeclareRoles({"user", "admin"})
@Keycloak(json =
        "{" +
        "  \"realm\": \"customers\"," +
        "  \"bearer-only\": true," +
        "  \"auth-server-url\": \"https://localhost:8082/auth\"," +
        "  \"ssl-required\": \"external\"," +
        "  \"resource\": \"customers-api\"" +
public class CustomerApplication extends Application {

It is possible to specify security constraints for JAX-RS resources using the standard @DenyAll, @PermitAll and @RolesAllowed Java annotations.

Example of security constraints:

public class CustomerResource {

    public Response getCustomer(@PathParam("customerId") String customerId) {

    public Response addNewCustomer(Customer customer) {

NOTE: When using the non CDI security constraint annotations, note that these constraints behave as if they were declared in the web.xml descriptor, i.e. the url patterns do not support path parameters.

The security extension also supports CDI based security, which means that security constraints are checked and resolved during method invocation. To enable CDI based security just add @Secure annotation to the CDI bean and use the standard Java security annotations as before.

Example of CDI based security:

public class CustomerResource {

    public Customer getCustomer(String customerId) {

    public void addNewCustomer(Customer customer) {

When using the CDI based security it is also possible to provide application role mappings. The specified role mappings transform Keycloak roles into internal application roles. Role mappings are defined using the kumuluzee.security.roles key.

Example role mapping configuration:

      user: role_user
      admin: role_admin

You may also disable Jetty servlet security, which is enabled by default, by setting key kumuluzee.security.disable-jetty-auth to true.

You can set a custom config resolver class (see here) to be able to tweak Keycloak configuration at runtime for each request (for multitenant or purposes). Note that this class must implement org.keycloak.adapters.KeycloakConfigResolver.

Example custom config resolver configuration:

      config-resolver: foo.bar.MyKeycloakConfigResolver


Recent changes can be viewed on Github on the Releases Page


See the contributing docs

When submitting an issue, please follow the guidelines.

When submitting a bugfix, write a test that exposes the bug and fails before applying your fix. Submit the test alongside the fix.

When submitting a new feature, add tests that cover the feature.



About Me
GitHub: Trinea
Facebook: Dev Tools