karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject git commit: [KARAF-3164] Update security documentation with the backend engine
Date Tue, 19 Aug 2014 08:17:11 GMT
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é <jbonofre@apache.org>
Authored: Tue Aug 19 10:15:30 2014 +0200
Committer: Jean-Baptiste Onofré <jbonofre@apache.org>
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}


Mime
View raw message