[KARAF-3105] Readd the security page in the users-guide
Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/b3adef18 Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/b3adef18 Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/b3adef18 Branch: refs/heads/karaf-2.3.x Commit: b3adef182e14f3c8bf29751a56039e1768056ce0 Parents: 5cdaa4d Author: Jean-Baptiste Onofré <jbono...@apache.org> Authored: Sat Jul 12 14:39:45 2014 +0200 Committer: Jean-Baptiste Onofré <jbono...@apache.org> Committed: Sat Jul 12 14:39:45 2014 +0200 ---------------------------------------------------------------------- .../src/main/webapp/users-guide/security.conf | 83 ++++++++++++++++++++ 1 file changed, 83 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/b3adef18/manual/src/main/webapp/users-guide/security.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/users-guide/security.conf b/manual/src/main/webapp/users-guide/security.conf new file mode 100644 index 0000000..482f633 --- /dev/null +++ b/manual/src/main/webapp/users-guide/security.conf @@ -0,0 +1,83 @@ +h1. Security + +h2. Managing 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. + +{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 {{lib/ext}} +* modify the {{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} + +
