Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 21. Security

Apache Karaf provides an advanced and flexible security system, powered by JAAS (Java Authentication and Authorization Service) in an OSGi compliant way.

It provides a dynamic security system.

The Apache Karaf security framework is used internally to control the access to:

  • the OSGi services (described in the developer guide)
  • the console commands
  • the JMX layer
  • the WebConsole

Your applications can also use the security framework (see the developer guide for details).

21.1. Realms
Copy link

Apache Karaf is able to manage multiple realms. A realm contains the definition of the login modules to use for the authentication and/or authorization on this realm. The login modules define the authentication and authorization for the realm.

The jaas:realm-list command list the current defined realms: 

karaf@root()> jaas:realm-list
Index | Realm Name | Login Module Class Name
-----------------------------------------------------------------------------------
1     | karaf      | org.apache.karaf.jaas.modules.properties.PropertiesLoginModule
2     | karaf      | org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule
Copy to Clipboard Toggle word wrap

You can see that the Apache Karaf provides a default realm named karaf.

This realm has two login modules:

  • the PropertiesLoginModule uses the etc/users.properties file as backend for users, groups, roles and password. This login module authenticates the users and returns the users' roles.
  • the PublickeyLoginModule is especially used by the SSHd. It uses the etc/keys.properties file. This file contains the users and a public key associated to each user.

Apache Karaf provides additional login modules (see the developer guide for details):

  • JDBCLoginModule uses a database as backend
  • LDAPLoginModule uses a LDAP server as backend
  • SyncopeLoginModule uses Apache Syncope as backend
  • OsgiConfigLoginModule uses a configuration as backend
  • Krb5LoginModule uses a Kerberos Server as backend
  • GSSAPILdapLoginModule uses a LDAP server as backend but delegate LDAP server authentication to an other backend (typically Krb5LoginModule)

You can manage an existing realm, login module, or create your own realm using the jaas:realm-manage command.

21.1.1. Users, groups, roles, and passwords
Copy link

As we saw, by default, Apache Karaf uses a PropertiesLoginModule.

This login module uses the etc/users.properties file as storage for the users, groups, roles and passwords.

The initial etc/users.properties file contains: 

################################################################################
#
#    Licensed to the Apache Software Foundation (ASF) under one or more
#    contributor license agreements.  See the NOTICE file distributed with
#    this work for additional information regarding copyright ownership.
#    The ASF licenses this file to You under the Apache License, Version 2.0
#    (the "License"); you may not use this file except in compliance with
#    the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
#
################################################################################

#
# This file contains the users, groups, and roles.
# Each line has to be of the format:
#
# USER=PASSWORD,ROLE1,ROLE2,...
# USER=PASSWORD,_g_:GROUP,...
# _g_\:GROUP=ROLE1,ROLE2,...
#
# All users, grousp, and roles entered in this file are available after Karaf startup
# and modifiable via the JAAS command group. These users reside in a JAAS domain
# with the name "karaf".
#
karaf = karaf,_g_:admingroup
_g_\:admingroup = group,admin,manager,viewer
Copy to Clipboard Toggle word wrap

We can see in this file, that we have one user by default: karaf. The default password is karaf.

The karaf user is member of one group: the admingroup.

A group is always prefixed by g:. An entry without this prefix is an user.

A group defines a set of roles. By default, the admingroup defines group, admin, manager, and viewer roles.

It means that the karaf user will have the roles defined by the admingroup.

21.1.1.1. Commands
Copy link

The jaas:* commands manage the realms, users, groups, roles in the console.

21.1.1.1.1. jaas:realm-list
Copy link

We already used the jaas:realm-list previously in this section.

The jaas:realm-list command list the realm and the login modules for each realm: 

karaf@root()> jaas:realm-list
Index | Realm Name | Login Module Class Name
-----------------------------------------------------------------------------------
1     | karaf      | org.apache.karaf.jaas.modules.properties.PropertiesLoginModule
2     | karaf      | org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule
Copy to Clipboard Toggle word wrap

We have here one realm (karaf) containing two login modules (PropertiesLoginModule and PublickeyLoginModule).

The index is used by the jaas:realm-manage command to easily identify the realm/login module that we want to manage.

21.1.1.1.2. jaas:realm-manage
Copy link

The jaas:realm-manage command switch in realm/login module edit mode, where you can manage the users, groups, and roles in the login module.

To identify the realm and login module that you want to manage, you can use the --index option. The indexes are displayed by the jaas:realm-list command: 

karaf@root()> jaas:realm-manage --index 1
Copy to Clipboard Toggle word wrap

Another way is to use the --realm and --module options. The --realm option expects the realm name, and the --module option expects the login module class name: 

karaf@root()> jaas:realm-manage --realm karaf --module org.apache.karaf.jaas.modules.properties.PropertiesLoginModule
Copy to Clipboard Toggle word wrap
21.1.1.1.3. jaas:user-list
Copy link

When you are in edit mode, you can list the users in the login module using the jaas:user-list: 

karaf@root()> jaas:user-list
User Name | Group      | Role
--------------------------------
karaf     | admingroup | admin
karaf     | admingroup | manager
karaf     | admingroup | viewer
Copy to Clipboard Toggle word wrap

You can see the user name and the group by role.

21.1.1.1.4. jaas:user-add
Copy link

The jaas:user-add command adds a new user (and the password) in the currently edited login module: 

karaf@root()> jaas:user-add foo bar
Copy to Clipboard Toggle word wrap

To "commit" your change (here the user addition), you have to execute the jaas:update command: 

karaf@root()> jaas:update
karaf@root()> jaas:realm-manage --index 1
karaf@root()> jaas:user-list
User Name | Group      | Role
--------------------------------
karaf     | admingroup | admin
karaf     | admingroup | manager
karaf     | admingroup | viewer
foo       |            |
Copy to Clipboard Toggle word wrap

On the other hand, if you want to rollback the user addition, you can use the jaas:cancel command.

21.1.1.1.5. jaas:user-delete
Copy link

The jaas:user-delete command deletes an user from the currently edited login module: 

karaf@root()> jaas:user-delete foo
Copy to Clipboard Toggle word wrap

Like for the jaas:user-add command, you have to use the jaas:update to commit your change (or jaas:cancel to rollback): 

karaf@root()> jaas:update
karaf@root()> jaas:realm-manage --index 1
karaf@root()> jaas:user-list
User Name | Group      | Role
--------------------------------
karaf     | admingroup | admin
karaf     | admingroup | manager
karaf     | admingroup | viewer
Copy to Clipboard Toggle word wrap
21.1.1.1.6. jaas:group-add
Copy link

The jaas:group-add command assigns a group (and eventually creates the group) to an user in the currently edited login module: 

karaf@root()> jaas:group-add karaf mygroup
Copy to Clipboard Toggle word wrap
21.1.1.1.7. jaas:group-delete
Copy link

The jaas:group-delete command removes an user from a group in the currently edited login module: 

karaf@root()> jaas:group-delete karaf mygroup
Copy to Clipboard Toggle word wrap
21.1.1.1.8. jaas:group-role-add
Copy link

The jaas:group-role-add command adds a role in a group in the currently edited login module: 

karaf@root()> jaas:group-role-add mygroup myrole
Copy to Clipboard Toggle word wrap
21.1.1.1.9. jaas:group-role-delete
Copy link

The jaas:group-role-delete command removes a role from a group in the currently edited login module: 

karaf@root()> jaas:group-role-delete mygroup myrole
Copy to Clipboard Toggle word wrap
21.1.1.1.10. jaas:update
Copy link

The jaas:update command commits your changes in the login module backend. For instance, in the case of the PropertiesLoginModule, the etc/users.properties will be updated only after the execution of the jaas:update command.

21.1.1.1.11. jaas:cancel
Copy link

The jaas:cancel command rollback your changes and doesn’t update the login module backend.

21.1.2. Passwords encryption
Copy link

By default, the passwords are stored in clear form in the etc/users.properties file.

It’s possible to enable encryption in the etc/org.apache.karaf.jaas.cfg configuration file: 

################################################################################
#
#    Licensed to the Apache Software Foundation (ASF) under one or more
#    contributor license agreements.  See the NOTICE file distributed with
#    this work for additional information regarding copyright ownership.
#    The ASF licenses this file to You under the Apache License, Version 2.0
#    (the "License"); you may not use this file except in compliance with
#    the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS,
#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#    See the License for the specific language governing permissions and
#    limitations under the License.
#
################################################################################

#
# Boolean enabling / disabling encrypted passwords
#
encryption.enabled = false

#
# Encryption Service name
#   the default one is 'basic'
#   a more powerful one named 'jasypt' is available
#       when installing the encryption feature
#
encryption.name =

#
# Encryption prefix
#
encryption.prefix = {CRYPT}

#
# Encryption suffix
#
encryption.suffix = {CRYPT}

#
# Set the encryption algorithm to use in Karaf JAAS login module
# Supported encryption algorithms follow:
#   MD2
#   MD5
#   SHA-1
#   SHA-256
#   SHA-384
#   SHA-512
#
encryption.algorithm = MD5

#
# Encoding of the encrypted password.
# Can be:
#   hexadecimal
#   base64
#
encryption.encoding = hexadecimal
Copy to Clipboard Toggle word wrap

If the encryption.enabled y is set to true, the password encryption is enabled.

With encryption enabled, the password are encrypted at the first time an user logs in. The encrypted passwords are prefixed and suffixed with \{CRYPT\}. To re-encrypt the password, you can reset the password in clear (in etc/users.properties file), without the \{CRYPT\} prefix and suffix. Apache Karaf will detect that this password is in clear (because it’s not prefixed and suffixed with \{CRYPT\}) and encrypt it again.

The etc/org.apache.karaf.jaas.cfg configuration file allows you to define advanced encryption behaviours:

  • the encryption.prefix property defines the prefix to "flag" a password as encrypted. The default is \{CRYPT\}.
  • the encryption.suffix property defines the suffix to "flag" a password as encrypted. The default is \{CRYPT\}.
  • the encryption.algorithm property defines the algorithm to use for encryption (digest). The possible values are MD2, MD5, SHA-1, SHA-256, SHA-384, SHA-512. The default is MD5.
  • the encryption.encoding property defines the encoding of the encrypted password. The possible values are hexadecimal or base64. The default value is hexadecimal.

21.1.3. Managing authentication by key
Copy link

For the SSH layer, Karaf supports the authentication by key, allowing to login without providing the password.

The SSH client (so bin/client provided by Karaf itself, or any ssh client like OpenSSH) uses a public/private keys pair that will identify himself on Karaf SSHD (server side).

The keys allowed to connect are stored in etc/keys.properties file, following the format: 

user=key,role
Copy to Clipboard Toggle word wrap

By default, Karaf allows a key for the karaf user: 

# karaf=AAAAB3NzaC1kc3MAAACBAP1/U4EddRIpUt9KnC7s5Of2EbdSPO9EAMMeP4C2USZpRV1AIlH7WT2NWPq/xfW6MPbLm1Vs14E7gB00b/JmYLdrmVClpJ+f6AR7ECLCT7up1/63xhv4O1fnxqimFQ8E+4P208UewwI1VBNaFpEy9nXzrith1yrv8iIDGZ3RSAHHAAAAFQCXYFCPFSMLzLKSuYKi64QL8Fgc9QAAAIEA9+GghdabPd7LvKtcNrhXuXmUr7v6OuqC+VdMCz0HgmdRWVeOutRZT+ZxBxCBgLRJFnEj6EwoFhO3zwkyjMim4TwWeotUfI0o4KOuHiuzpnWRbqN/C/ohNWLx+2J6ASQ7zKTxvqhRkImog9/hWuWfBpKLZl6Ae1UlZAFMO/7PSSoAAACBAKKSU2PFl/qOLxIwmBZPPIcJshVe7bVUpFvyl3BbJDow8rXfskl8wO63OzP/qLmcJM0+JbcRU/53JjTuyk31drV2qxhIOsLDC9dGCWj47Y7TyhPdXh/0dthTRBy6bqGtRPxGa7gJov1xm/UuYYXPIUR/3x9MAZvZ5xvE0kYXO+rx,admin
Copy to Clipboard Toggle word wrap
Note

For security reason, this key is disabled. We encourage to create the keys pair per client and update the etc/keys.properties file.

The easiest way to create key pair is to use OpenSSH.

You can create a key pair using: 

ssh-keygen -t dsa -f karaf.id_dsa -N karaf
Copy to Clipboard Toggle word wrap

You have now the public and private keys: 

-rw-------  1 jbonofre jbonofre    771 Jul 25 22:05 karaf.id_dsa
-rw-r--r--  1 jbonofre jbonofre    607 Jul 25 22:05 karaf.id_dsa.pub
Copy to Clipboard Toggle word wrap

You can copy in the content of the karaf.id_dsa.pub file in the etc/keys.properties: 

karaf=AAAAB3NzaC1kc3MAAACBAJLj9vnEhu3/Q9Cvym2jRDaNWkATgQiHZxmErCmiLRuD5Klfv+HT/+8WoYdnvj0YaXFP80phYhzZ7fbIO2LRFhYhPmGLa9nSeOsQlFuX5A9kY1120yB2kxSIZI0fU2hy1UCgmTxdTQPSYtdWBJyvO/vczoX/8I3FziEfss07Hj1NAAAAFQD1dKEzkt4e7rBPDokPOMZigBh4kwAAAIEAiLnpbGNbKm8SNLUEc/fJFswg4G4VjjngjbPZAjhkYe4+H2uYmynry6V+GOTS2kaFQGZRf9XhSpSwfdxKtx7vCCaoH9bZ6S5Pe0voWmeBhJXi/Sww8f2stpitW2Oq7V7lDdDG81+N/D7/rKDD5PjUyMsVqc1n9wCTmfqmi6XPEw8AAACAHAGwPn/Mv7P9Q9+JZRWtGq+i4pL1zs1OluiStCN9e/Ok96t3gRVKPheQ6IwLacNjC9KkSKrLtsVyepGA+V5j/N+Cmsl6csZilnLvMUTvL/cmHDEEhTIQnPNrDDv+tED2BFqkajQqYLgMWeGVqXsBU6IT66itZlYtrq4v6uDQG/o=,admin
Copy to Clipboard Toggle word wrap

and specify to the client to use the karaf.id_dsa private key: 

bin/client -k ~/karaf.id_dsa
Copy to Clipboard Toggle word wrap

or to ssh 

ssh -p 8101 -i ~/karaf.id_dsa karaf@localhost
Copy to Clipboard Toggle word wrap

21.1.4. RBAC
Copy link

Apache Karaf uses the roles to control the access to the resources: it’s a RBAC (Role Based Access Control) system.

The roles are used to control:

  • access to OSGi services
  • access to the console (control the execution of the commands)
  • access to JMX (MBeans and/or operations)
  • access to the WebConsole

21.1.4.1. OSGi services
Copy link

The details about OSGi services RBAC support is explained in the developer guide.

21.1.4.2. Console
Copy link

Console RBAC supports is a specialization of the OSGi service RBAC. Actually, in Apache Karaf, all console commands are defined as OSGi services.

The console command name follows the scope:name format.

The ACL (Access Lists) are defined in etc/org.apache.karaf.command.acl.<scope>.cfg configuration files, where <scope> is the commands scope.

For instance, we can define the ACL to the feature:* commands by creating a etc/org.apache.karaf.command.acl.feature.cfg configuration file. In this etc/org.apache.karaf.command.acl.feature.cfg configuration file, we can set: 

list = viewer
info = viewer
install = admin
uninstall = admin
Copy to Clipboard Toggle word wrap

Here, we define that feature:list and feature:info commands can be executed by users with viewer role, whereas the feature:install and feature:uninstall commands can only be executed by users with admin role. Note that users in the admin group will also have viewer role, so will be able to do everything.

Apache Karaf command ACLs can control access using (inside a given command scope):

  • the command name regex (e.g. name = role)
  • the command name and options or arguments values regex (e.g. name[/.[0-9][0-9][0-9]+./] = role to execute name only with argument value above 100)

Both command name and options/arguments support exact matching or regex matching.

By default, Apache Karaf defines the following commands ACLs:

  • etc/org.apache.karaf.command.acl.bundle.cfg configuration file defines the ACL for bundle:* commands. This ACL limits the execution of bundle:* commands for system bundles only to the users with admin role, whereas bundle:* commands for non-system bundles can be executed by the users with manager role.
  • etc/org.apache.karaf.command.acl.config.cfg configuration file defines the ACL for config:* commands. This ACL limits the execution of config:* commands with jmx.acl.*, org.apache.karaf.command.acl.*, and org.apache.karaf.service.acl.* configuration PID to the users with admin role. For the other configuration PID, the users with the manager role can execute config:* commands.
  • etc/org.apache.karaf.command.acl.feature.cfg configuration file defines the ACL for feature:* commands. Only the users with admin role can execute feature:install and feature:uninstall commands. The other feature:* commands can be executed by any user.
  • etc/org.apache.karaf.command.acl.jaas.cfg configuration file defines the ACL for jaas:* commands. Only the users with admin role can execute jaas:update command. The other jaas:* commands can be executed by any user.
  • etc/org.apache.karaf.command.acl.kar.cfg configuration file defines the ACL for kar:* commands. Only the users with admin role can execute kar:install and kar:uninstall commands. The other kar:* commands can be executed by any user.
  • etc/org.apache.karaf.command.acl.shell.cfg configuration file defines the ACL for shell:* and "direct" commands. Only the users with admin role can execute shell:edit, shell:exec, shell:new, and shell:java commands. The other shell:* commands can be executed by any user.

You can change these default ACLs, and add your own ACLs for additional command scopes (for instance etc/org.apache.karaf.command.acl.cluster.cfg for Apache Karaf Cellar, etc/org.apache.karaf.command.acl.camel.cfg from Apache Camel, …​).

You can fine tuned the command RBAC support by editing the karaf.secured.services property in etc/system.properties: 

#
# By default, only Karaf shell commands are secured, but additional services can be
# secured by expanding this filter
#
karaf.secured.services = (&(osgi.command.scope=*)(osgi.command.function=*))
Copy to Clipboard Toggle word wrap

21.1.4.3. JMX
Copy link

Like for the console commands, you can define ACL (AccessLists) to the JMX layer.

The JMX ACL are defined in etc/jmx.acl<ObjectName>.cfg configuration file, where <ObjectName> is a MBean object name (for instance org.apache.karaf.bundle represents org.apache.karaf;type=Bundle MBean).

The etc/jmx.acl.cfg is the most generic configuration file and is used when no specific ones are found. It contains the "global" ACL definition.

JMX ACLs can control access using (inside a JMX MBean):

  • the operation name regex (e.g. operation* = role)
  • the operation arguments value regex (e.g. operation(java.lang.String, int)[/([1-4])?[0-9]/,/.*/] = role)

By default, Apache Karaf defines the following JMX ACLs:

  • etc/jmx.acl.org.apache.karaf.bundle.cfg configuration file defines the ACL for the org.apache.karaf:type=bundle MBean. This ACL limits the setStartLevel(), start(), stop(), and update() operations for system bundles for only users with admin role. The other operations can be performed by users with the manager role.
  • etc/jmx.acl.org.apache.karaf.config.cfg configuration file defines the ACL for the org.apache.karaf:type=config MBean. This ACL limits the change on jmx.acl*, org.apache.karaf.command.acl*, and org.apache.karaf.service.acl* configuration PIDs for only users with admin role. The other operations can be performed by users with the manager role.
  • etc/jmx.acl.org.apache.karaf.security.jmx.cfg configuration file defines the ACL for the org.apache.karaf:type=security,area=jmx MBean. This ACL limits the invocation of the canInvoke() operation for the users with viewer role.
  • etc/jmx.acl.osgi.compendium.cm.cfg configuration file defines the ACL for the osgi.compendium:type=cm MBean. This ACL limits the changes on jmx.acl*, org.apache.karaf.command.acl*, and org.apache.karaf.service.acl* configuration PIDs for only users with admin role. The other operations can be performed by users with the manager role.
  • etc/jmx.acl.java.lang.Memory.cfg configuration file defines the ACL for the core JVM Memory MBean. This ACL limits the invocation of the gc operation for only users with the manager role.
  • etc/jmx.acl.cfg configuration file is the most generic file. The ACLs defined here are used when no other specific ACLs match (by specific ACL, it’s an ACL defined in another MBean specific etc/jmx.acl.*.cfg configuration file). The list*(), get*(), is*() operations can be performed by users with the viewer role. The set*() and all other *() operations can be performed by users with the admin role.

21.1.4.4. WebConsole
Copy link

The Apache Karaf WebConsole is not available by default. To enable it, you have to install the webconsole feature: 

karaf@root()> feature:install webconsole
Copy to Clipboard Toggle word wrap

The WebConsole doesn’t support fine grained RBAC like console or JMX for now.

All users with the admin role can logon the WebConsole and perform any operations.

21.1.5. SecurityMBean
Copy link

Apache Karaf provides a JMX MBean to check if the current user can invoke a given MBean and/or operation.

The canInvoke() operation gets the roles of the current user, and check if one the roles can invoke the MBean and/or the operation, eventually with a given argument value.

21.1.5.1. Operations
Copy link

  • canInvoke(objectName) returns true if the current user can invoke the MBean with the objectName, false else.
  • canInvoke(objectName, methodName) returns true if the current user can invoke the operation methodName on the MBean with the objectName, false else.
  • canInvoke(objectName, methodName, argumentTypes) returns true if the current user can invoke the operation methodName with the array of arguments types argumentTypes on the MBean with objectName, false else.
  • canInvoke(bulkQuery) returns a tabular data containing for each operation in the bulkQuery tabular data if canInvoke is true or false.

21.1.6. Security providers
Copy link

Some applications require specific security providers to be available, such as [BouncyCastle|http://www.bouncycastle.org].

The JVM imposes some restrictions about the use of such jars: they have to be signed and be available on the boot classpath.

One way to deploy those providers is to put them in the JRE folder at $JAVA_HOME/jre/lib/ext and modify the security policy configuration ($JAVA_HOME/jre/lib/security/java.security) in order to register such providers.

While this approach works fine, it has a global effect and requires you to configure all your servers accordingly.

Apache Karaf offers a simple way to configure additional security providers: * put your provider jar in lib/ext * modify the etc/config.properties configuration file to add the following property 

org.apache.karaf.security.providers = xxx,yyy
Copy to Clipboard Toggle word wrap

The value of this property is a comma separated list of the provider class names to register.

For instance, to add the bouncycastle security provider, you define: 

org.apache.karaf.security.providers = org.bouncycastle.jce.provider.BouncyCastleProvider
Copy to Clipboard Toggle word wrap

In addition, you may want to provide access to the classes from those providers from the system bundle so that all bundles can access those.

It can be done by modifying the org.osgi.framework.bootdelegation property in the same configuration file: 

org.osgi.framework.bootdelegation = ...,org.bouncycastle*
Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat