Repository: karaf Updated Branches: refs/heads/karaf-2.3.x 54e7493cd -> 037147aa3
[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/037147aa Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/037147aa Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/037147aa Branch: refs/heads/karaf-2.3.x Commit: 037147aa3211a3b1e5ad543a2c091ead6d20587c Parents: 54e7493 Author: Jean-Baptiste Onofré <[email protected]> Authored: Tue Aug 19 10:15:30 2014 +0200 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Tue Aug 19 10:16:50 2014 +0200 ---------------------------------------------------------------------- .../developers-guide/security-framework.conf | 124 ++++++++++++++++++- 1 file changed, 119 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/037147aa/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 57352db..e08b081 100644 --- a/manual/src/main/webapp/developers-guide/security-framework.conf +++ b/manual/src/main/webapp/developers-guide/security-framework.conf @@ -103,9 +103,18 @@ Due to constraints in the JAAS specification, one class has to be available for The xml schema defined above allows the use of a simple xml (leveraging spring xml extensibility) to configure and register a JAAS configuration for a given realm. This configuration will be made available into the OSGi registry as a [JaasRealm|http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java] and the OSGi specific Configuration will look for such services. 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 @@ -134,17 +143,77 @@ user=password[,role][,role]... 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 | LoginModule | org.apache.karaf.jaas.modules.osgi.OsgiConfigLoginModule | -| BackingEngineFactory | | +| BackingEngineFactory | N/A | The OsgiConfigLoginModule uses the OSGi ConfigurationAdmin service to provide the users, passwords and roles. || 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 @@ -189,10 +258,45 @@ To use an JNDI name, the prefix jndi: needs to be provided. The example below as </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 | LoginModule | org.apache.karaf.jaas.modules.ldap.LDAPLoginModule | -| BackingEngineFactory | | +| BackingEngineFactory | N/A | The LDAPLoginModule uses LDAP to load the users and roles and bind the users on the LDAP to check passwords. @@ -270,8 +374,14 @@ The LDAPLoginModule supports the following patterns that you can use in the filt * {{%fqdn}} is replaced by the user full qualified DN ({{userDN,userBaseDN}}). * {{%nsdn}} is replaced by the userDNNamespace (interesting especially for ActiveDirectory). +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 +| LoginModule | org.apache.karaf.jaas.modules.syncope.SyncopeLoginModule | +| BackingEngineFactory | org.apache.karaf.jaas.modules.syncope.SyncopeBackingEngineFactory | + The Syncope login module uses the Syncope REST API to authenticate users and retrieve the roles. The Syncope login module just requires one parameter: @@ -295,6 +405,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}
