Security

Managing authentication by users and passwords

The default security configuration uses a property file located at 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 authentication by key

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

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

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

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

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

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

bin/client -k ~/karaf.id_dsa

or to ssh

ssh -p 8101 -i ~/karaf.id_dsa karaf@localhost

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:

Layer PID Value
SSH org.apache.karaf.shell sshRole
JMX org.apache.karaf.management jmxRole
Web org.apache.karaf.webconsole role

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 lib/ext
  • modify the 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*