Repository: karaf Updated Branches: refs/heads/master 3de1efc46 -> e2f9652c1
[KARAF-3164] Update security documentation with the backend engine Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/e2f9652c Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/e2f9652c Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/e2f9652c Branch: refs/heads/master Commit: e2f9652c1b5f3acf4237e02fffd564ab5982a86f Parents: 3de1efc Author: Jean-Baptiste Onofré <[email protected]> Authored: Tue Aug 19 09:58:25 2014 +0200 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Tue Aug 19 09:58:25 2014 +0200 ---------------------------------------------------------------------- .../developers-guide/security-framework.conf | 119 ++++++++++++++++++- 1 file changed, 114 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/e2f9652c/manual/src/main/webapp/developers-guide/security-framework.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/developers-guide/security-framework.conf b/manual/src/main/webapp/developers-guide/security-framework.conf index e75df3b..6185ef3 100644 --- a/manual/src/main/webapp/developers-guide/security-framework.conf +++ b/manual/src/main/webapp/developers-guide/security-framework.conf @@ -110,9 +110,18 @@ register a JAAS configuration for a given realm. This configuration will be mad Then the proxy login module will be able to use the information provided by the realm to actually load the class from the bundle containing the real login module. -h2. Available realms +Karaf itself provides a set of login modules ready to use, depending of the authentication backend that you need. -Karaf comes with several login modules to handle authentication needs for your environment. +In addition of the login modules, Karaf also support backend engine. The backend engine is coupled to a login module and +allows you to manipulate users and roles directly from Karaf (adding a new user, delete an existing user, etc). +The backend engine is constructed by a backend engine factory, registered as an OSGi service. +Some login modules (for security reason for instance) don't provide backend engine. + +h2. Available realm and login modules + +Karaf comes with a default realm named "karaf" using login modules. + +Karaf also provides a set of login modules and backend engines to handle authentication needs for your environment. h3. PropertiesLoginModule @@ -131,12 +140,44 @@ user=password[,role][,role]... <jaas:config name="karaf"> <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule" flags="required"> - users = $[karaf.base]/etc/users.properties + users = ${karaf.etc}/users.properties </jaas:module> </jaas:config> {pygmentize} -Note for windows users: Do not forget the typeconverter from the first config snippet. It makes sure that windows paths are handled correctly. +The PropertiesLoginModule provides a backend engine allowing: +* add a new user +* delete an existing user +* list the users, groups, and roles +* add a new role to an user +* delete a role from an user +* add an user into a group +* remove an user from a group +* add a role to a group +* delete a role from a group + +To enable the backend engine, you have to register the corresponding OSGi service. For instance, the following blueprint +shows how to register the PropertiesLoginModule and the corresponding backend engine: + +{pygmentize:xml} +<?xml version="1.0" encoding="UTF-8"?> +<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"; + xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.1.0"; + xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0";> + + <jaas:config name="karaf" rank="-1"> + <jaas:module className="org.apache.karaf.jaas.modules.properties.PropertiesLoginModule" + flags="required"> + users = ${karaf.etc}/users.properties + </jaas:module> + </jaas:config> + + <service interface="org.apache.karaf.jaas.modules.BackingEngineFactory"> + <bean class="org.apache.karaf.jaas.modules.properties.PropertiesBackingEngineFactory"/> + </service> + +</blueprint> +{pygmentize} h3. OsgiConfigLoginModule @@ -145,7 +186,33 @@ The OsgiConfigLoginModule uses the OSGi ConfigurationAdmin service to provide th || Name || Description | | {{pid}} | the PID of the configuration containing user definitions | -The format of the configuration is the same than for the {{PropertiesLoginModule}}. +The format of the configuration is the same than for the {{PropertiesLoginModule}} with properties prefixed with {{user.}}. + +For instance, in the Karaf etc folder, we create a file {{org.apache.karaf.authentication.cfg}} containing: + +{code} +user.karaf=karaf,admin +user.user=password,role +{code} + +The following blueprint shows how to use this configuration: + +{pygmentize:xml} +<?xml version="1.0" encoding="UTF-8"?> +<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"; + xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.1.0";> + + <jaas:config name="karaf" rank="-1"> + <jaas:module className="org.apache.karaf.jaas.modules.osgi.OsgiConfigLoginModule" + flags="required"> + pid = org.apache.karaf.authentication + </jaas:module> + </jaas:config> + +</blueprint> +{pygmentize} + +NB: the OsgiConfigLoginModule doesn't provide a backend engine. h3. JDBCLoginModule @@ -188,6 +255,41 @@ services via JNDI. </jaas:config> {pygmentize} +The JDBCLoginModule provides a backend engine allowing: +* add a new user +* delete an user +* list users, roles +* add a new role to an user +* remove a role from an user + +NB: the groups are not fully supported by the JDBCBackingEngine. + +The following blueprint shows how to define the JDBCLoginModule with the corresponding backend engine: + +{pygmentize:xml} +<?xml version="1.0" encoding="UTF-8"?> +<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"; + xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.1.0";> + + <jaas:config name="karaf"> + <jaas:module className="org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule" + flags="required"> + datasource = jndi:aries:services/javax.sql.DataSource/(osgi.jndi.service.name=jdbc/karafdb) + query.password = SELECT PASSWORD FROM USERS WHERE USERNAME=? + query.role = SELECT ROLE FROM ROLES WHERE USERNAME=? + insert.user = INSERT INTO USERS(USERNAME,PASSWORD) VALUES(?,?) + insert.role = INSERT INTO ROLES(ROLE,USERNAME) VALUES(?,?) + delete.user = DELETE FROM USERS WHERE USERNAME=? + </jaas:module> + </jaas:config> + + <service interface="org.apache.karaf.jaas.modules.BackingEngineFactory"> + <bean class="org.apache.karaf.jaas.modules.jdbc.JDBCBackingEngineFactory"/> + </service> + +</blueprint> +{pygmentize} + h3. LDAPLoginModule The LDAPLoginModule uses LDAP to load the users and roles and bind the users on the LDAP to check passwords. @@ -289,6 +391,9 @@ default {{karaf}} realm): </jaas:config> {code} +NB: the LDAPLoginModule doesn't provide backend engine. It means that the administration of the users and roles should be +performed directly on the LDAP backend. + h3. SyncopeLoginModule The Syncope login module uses the Syncope REST API to authenticate users and retrieve the roles. @@ -314,6 +419,10 @@ The following snippet shows how to use Syncope with the karaf realm: SyncopeLoginModule comes with a backend engine allowing to manipulate users and roles. You have to register the SyncopeBackendEngineFactory service. + +For security reason, the SyncopeLoginModule backend engine allows only to list users and roles. You can't create or delete +users and roles directly from Karaf. To do it, you have to use the Syncope web console. + For instance, the following blueprint descriptor enables the SyncopeLoginModule and the backend engine factory: {code}
