h1. Security

h2. 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.

{code}
user=password[,role][,role]...
{code}

h2. 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:
{code}
[classname:]principal
{code}
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    |

h2. 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:

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

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.

h2. Managing realms

More information about modifying the default realm or deploying new realms is provided in the [developers guide|/developers-guide/security-framework].

h2. Deploying security providers

Some applications require specific security providers to be available, such as [BouncyCastle|http://www.bouncycastle.org].  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

{code}
org.apache.karaf.security.providers = xxx,yyy
{code}

The value of this property is a comma separated list of the provider class names to register.
For example:
{code}
org.apache.karaf.security.providers = org.bouncycastle.jce.provider.BouncyCastleProvider
{code}

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:
{code}
org.osgi.framework.bootdelegation = ...,org.bouncycastle*
{code}