• User's Guide
  • Installation
  • Directory structure
  • Starting and stopping Karaf
  • Using the console
  • Web console
  • Remote console
  • Child instances
  • Security
  • Failover deployments
  • Logging system
  • Deployer
  • Configuration

Security

Managing users and passwords

The default security configuration uses a property file located at karaf-install-dir/etc/users.properties to store authorized users and their passwords.

The default user name is karaf and the associated password is karaf too. We strongly encourage you to change the default password by editing the above file before moving Karaf into production.

The users are currently used in three different places in Karaf:

• access to the SSH console

• access to the JMX management layer

• access to the Web console
  Those three ways all delegate to the same JAAS based security authentication.

The users.properties file contains one or more lines, each line defining a user, its password and the associated roles.

user=password[,role][,role]...

Managing roles

JAAS roles can be used by various components. The three management layers (SSH, JMX and WebConsole) all use a global role based authorization system. The default role name is configured in the etc/system.properties using the karaf.admin.role system property and the default value is admin. All users authenticating for the management layer must have this role defined.

The syntax for this value is the following:

[classname:]principal

where classname is the class name of the principal object (defaults to org.apache.karaf.jaas.modules.RolePrincipal) and principal is the name of the principal of that class (defaults to admin).

Note that roles can be changed for a given layer using ConfigAdmin in the following configurations:

Enabling password encryption

In order to not keep the passwords in plain text, the passwords can be stored encrypted in the configuration file.
This can be easily enabled using the following commands:

# edit config
config:edit org.apache.karaf.jaas
config:propset encryption.enabled true
config:update 
# force a restart
dev:restart

The passwords will be encrypted automatically in the etc/users.properties configuration file the first time the user logs in.
Encrypted passwords are prepended with {CRYPT} so that are easy to recognize.

Managing realms

More information about modifying the default realm or deploying new realms is provided in the developers guide.

Deploying security providers

Some applications require specific security providers to be available, such as BouncyCastle. The JVM impose 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.

Karaf offers a simple way to configure additional security providers:

• put your provider jar in karaf-install-dir/lib/ext

• modify the karaf-install-dir/etc/config.properties configuration file to add the following property

org.apache.karaf.security.providers = xxx,yyy

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

org.apache.karaf.security.providers = org.bouncycastle.jce.provider.BouncyCastleProvider

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*