[2/2] git commit: [KARAF-3105] Readd the security page in the users-guide

[jb...@apache.org]

[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/92578b03
Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/92578b03
Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/92578b03

Branch: refs/heads/karaf-2.x
Commit: 92578b03c00b08ca44b482fdadb8a4d4331749cb
Parents: 2b6a181
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Sat Jul 12 14:33:46 2014 +0200
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Sat Jul 12 14:33:46 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/92578b03/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}
+
+