| 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} |
| |
| |