You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2015/07/01 19:06:45 UTC
svn commit: r1688692 [19/30] - in
/karaf/site/production/manual/latest-3.0.x: ./ commands/ css/ css/scalate/
developers-guide/ images/ users-guide/
Added: karaf/site/production/manual/latest-3.0.x/developers-guide/scripting.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-3.0.x/developers-guide/scripting.html?rev=1688692&view=auto
==============================================================================
--- karaf/site/production/manual/latest-3.0.x/developers-guide/scripting.html (added)
+++ karaf/site/production/manual/latest-3.0.x/developers-guide/scripting.html Wed Jul 1 17:06:42 2015
@@ -0,0 +1,273 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
+<html lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <meta name="description" content="description goes here"/>
+ <meta name="keywords" content="keywords,goes,here"/>
+ <meta name="author" content="The Apache Karaf Team"/>
+ <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+ <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+ <title>
+ Apache Karaf 3.0.5-SNAPSHOT Guides
+ </title>
+ </head>
+ <body>
+ <table width="100%" cellpadding="0" cellspacing="0">
+ <tr width="100%">
+ <td id="cell-0-0" colspan="2">
+
+ </td>
+ <td id="cell-0-1">
+
+ </td>
+ <td id="cell-0-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-1-0">
+
+ </td>
+ <td id="cell-1-1">
+
+ </td>
+ <td id="cell-1-2">
+ <div style="padding: 5px;">
+ <div id="banner">
+ <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+ <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+ </td>
+ <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+ <img border="0" src="../images/asf-logo.png">
+</a>
+ </td>
+ </tr>
+ </table>
+
+ </div>
+ <div id="top-menu">
+ <table border="0" cellpadding="1" cellspacing="0" width="100%">
+ <tr>
+ <td>
+ <div align="left"></div>
+ </td>
+ <td>
+ <div align="right">
+ <p>
+<a href="../index.html" title="Home">Home</a>
+|
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+|
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+ </div>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ </td>
+ <td id="cell-1-3">
+
+ </td>
+ <td id="cell-1-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-2-0" colspan="2">
+
+ </td>
+ <td id="cell-2-1">
+ <table>
+ <tr height="100%" valign="top">
+ <td height="100%">
+ <div id="wrapper-menu-page-right">
+ <div id="wrapper-menu-page-top">
+ <div id="wrapper-menu-page-bottom">
+ <div id="menu-page">
+ <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installation</a></li><li><a href="../users-guide/directory-structure.html">Directory structure</a></li><li><a href="../users-guide/start-stop.html">Start, stop, restart, connect</a></li><li><a href="../users-guide/wrapper.html">Integration in the operating system: the Service Wrapper</a></li><li><a href="../users-guide/console.html">Console</a></li><li><a href="../users-guide/remote.html">Remote</a></li><li><a href="../users-guide/log.html">Log</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/urls.html">Artifacts repositories and URLs</a></li><li>
<a href="../users-guide/provisioning.html">Provisioning and features</a></li><li><a href="../users-guide/deployers.html">Deployers</a></li><li><a href="../users-guide/kar.html">KAR</a></li><li><a href="../users-guide/instances.html">Instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li><a href="../users-guide/obr.html">OBR</a></li><li><a href="../users-guide/enterprise.html">Enterprise</a><ul><li><a href="../users-guide/webcontainer.html">WebContainer (JSP/Servlet)</a></li><li><a href="../users-guide/jndi.html">Naming (JNDI)</a></li><li><a href="../users-guide/jta.html">Transaction (JTA)</a></li><li><a href="../users-guide/jdbc.html">DataSource (JDBC)</a></li><li><a href="../users-guide/jms.html">MOM (JMS)</a></li><li><a href="../users-guide/jpa.html">Persistence (JPA)</a></li><li><a href="../users-guide/ejb.html">EJB</a></li><li><a href="../users-guide/cdi.html">CDI</a></li><li><a href="../users-guide/failover.html">HA/failover and cluster</a></li></ul><
/li><li><a href="../users-guide/monitoring.html">Monitoring and Management using JMX</a></li><li><a href="../users-guide/webconsole.html">WebConsole</a></li><li><a href="../users-guide/tuning.html">Tuning</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="developer-commands.html">Developer commands</a></li><li><a href="scripting.html">Scripting</a></li><li><a href="connect.html">Programmatically connect</a></li><li><a href="branding.html">Branding</a></li><li><a href="extending.html">Extending</a></li><li><a href="karaf-maven-plugin.html">Karaf Maven plugin</a></li><li><a href="custom-distribution.html">Custom distribution</a></li><li><a href="services.html">OSGi services</a></li><li><a href="creating-bundles.html">Create OSGi bundle</a></li><li><a href="blueprint.html">Blueprint</a></li><li><a href="cdi.html">CDI</a></li><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href
="security-framework.html">Security Framework</a></li><li><a href="debugging.html">Troubleshooting, Debugging, Profiling</a></li><li><a href="writing-tests.html">Integration testing</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+ </div>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td height="100%" width="100%">
+ <div class="wiki-content">
+<h1 id="Scripting">Scripting</h1><p>In the console section of the users guide, we introduced the scripting support.</p><h2 id="Assignation">Assignation</h2><p>You already know the first usage of scripting: execution of command.</p><pre>
+karaf@root()> echo hello world
+hello world
+</pre><p>You can also assign value to session variables:</p><pre>
+karaf@root()> msg = "hello world"
+hello world
+</pre><p>Once you have assigned a value to a variable, you can display this value using the "resolved" variable name:</p><pre>
+karaf@root()> echo $msg
+hello world
+</pre><p>The () are execution quotes (like the backquotes when you use bash on Unix).</p><pre>
+karaf@root()> ($.context bundle 1) location
+mvn:org.apache.karaf.jaas/org.apache.karaf.jaas.modules/3.0.1-SNAPSHOT
+</pre><p>The <tt>$.context</tt> access the context variables in the current session.<br/>We access to the <tt>bundle</tt> variable (an array containing all bundles), and we want to display the bundle location for<br/>the bundle at the index 1 in the bundle array.</p><h2 id="Listmapspipesandclosures">List, maps, pipes and closures</h2><p>Using [], you can define array variable:</p><pre>
+karaf@root()> list = [1 2 a b]
+1
+2
+a
+b
+
+</pre><p>You can also create a map if you put variables assignation in the array:</p><pre>
+karaf@root()> map = [Jan=1 Feb=2 Mar=3]
+Jan 1
+Feb 2
+Mar 3
+</pre><p>Using the | character, you can pipe output from a command as an input to another one.</p><p>For instance, you can access to the bundles context variables and send it as input to the grep command:</p><pre>
+karaf@root()> ($.context bundles) | grep -i felix
+ 0|Active | 0|org.apache.felix.framework (4.2.1)
+ 21|Active | 11|org.apache.felix.fileinstall (3.2.6)
+ 43|Active | 10|org.apache.felix.configadmin (1.6.0)
+ 51|Active | 30|org.apache.felix.gogo.runtime (0.10.0)
+</pre><p>You can assign name to script execution. It's what we use for alias:</p><pre>
+karaf@root()> echo2 = { echo xxx $args yyy }
+echo xxx $args yyy
+karaf@root()> echo2 hello world
+xxx hello world yyy
+</pre><h2 id="Startup">Startup</h2><p>The <tt>etc/shell.init.script</tt> file is executed at startup in each shell session, allowing the definition of additional<br/>variables or aliases or even complex functions. It's like the bashrc or profile on Unix.</p><h2 id="Constantsandvariables">Constants and variables</h2><p>Apache Karaf console provides a set of implicit constants and variables that you can use in your script.</p><ul><li><tt>$.context</tt> to access a bundle context</li><li><tt>$.variables</tt> to access the list of defined variables</li><li><tt>$.commands</tt> to access the list of defined commands</li></ul><p>The variables starting with a # that are defined as Function (such as closures) will be executed automatically:</p><pre>
+karaf@root> \#inc = { var = "${var}i" ; $var }
+var = "${var}i" ; $var
+karaf@root> echo $inc
+i
+karaf@root> echo $inc
+ii
+karaf@root>
+</pre><h2 id="Builtinvariablesandcommands">Built-in variables and commands</h2><p>Apache Karaf console provides built-in variable very useful for scripting:</p><ul><li><tt>$args</tt> retrieves the list of script parameters, given to the closure being executed</li><li><tt>$1 .. $999</tt> retrieves the nth argument of the closure</li><li><tt>$it</tt> (same as <tt>$1</tt>) is used in a loop to access the current iterator value</li></ul><p>Apache Karaf console provides commands for scripting:</p><ul><li><tt>shell:if</tt></li><li><tt>shell:new</tt></li><li><tt>shell:each</tt></li><li>...</li></ul><h2 id="LeveragingexistingJavacapabilitiesviareflection">Leveraging existing Java capabilities (via reflection)</h2><p>Apache Karaf console supports loading and execution of Java classes.</p><p>The <tt>$karaf.lastException</tt> implicit variable contains the latest Exception thrown.</p><pre>
+karaf@root()> ($.context bundle) loadClass foo
+Error executing command: foo not found by org.apache.karaf.shell.console [17]
+karaf@root()> $karaf.lastException printStackTrace
+java.lang.ClassNotFoundException: foo not found by org.apache.karaf.shell.console [17]
+ at org.apache.felix.framework.BundleWiringImpl.findClassOrResourceByDelegation(BundleWiringImpl.java:1460)
+ at org.apache.felix.framework.BundleWiringImpl.access$400(BundleWiringImpl.java:72)
+ at org.apache.felix.framework.BundleWiringImpl$BundleClassLoader.loadClass(BundleWiringImpl.java:1843)
+ at java.lang.ClassLoader.loadClass(ClassLoader.java:247)
+ at org.apache.felix.framework.Felix.loadBundleClass(Felix.java:1723)
+ at org.apache.felix.framework.BundleImpl.loadClass(BundleImpl.java:926)
+ at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
+ at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
+ at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
+ at java.lang.reflect.Method.invoke(Method.java:597)
+ at org.apache.felix.gogo.runtime.Reflective.invoke(Reflective.java:137)
+ at org.apache.felix.gogo.runtime.Closure.executeMethod(Closure.java:527)
+ at org.apache.felix.gogo.runtime.Closure.executeStatement(Closure.java:403)
+ at org.apache.felix.gogo.runtime.Pipe.run(Pipe.java:108)
+ at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:183)
+ at org.apache.felix.gogo.runtime.Closure.execute(Closure.java:120)
+ at org.apache.felix.gogo.runtime.CommandSessionImpl.execute(CommandSessionImpl.java:89)
+ at org.apache.karaf.shell.console.jline.Console.run(Console.java:166)
+ at java.lang.Thread.run(Thread.java:680)
+</pre><p>It's possible to create objects to create commands "on the fly":</p><pre>
+karaf@root()> addcommand system (($.context bundle) loadClass java.lang.System)
+karaf@root()> system:getproperty karaf.name
+root
+</pre><p>It means that you can create object using the <tt>new</tt> directive, and call methods on the objects:</p><pre>
+karaf@root> map = (new java.util.HashMap)
+karaf@root> $map put 0 0
+karaf@root> $map
+0 0
+</pre><h2 id="Examples">Examples</h2><p>The following examples show some scripts defined in <tt>etc/shell.init.script</tt>.</p><p>The first example show a script to add a value into a configuration list:</p><pre>
+#
+# Add a value at the end of a property in the given OSGi configuration
+#
+# For example:
+# > config-add-to-list org.ops4j.pax.url.mvn org.ops4j.pax.url.mvn.repositories http://scala-tools.org/repo-releases
+#
+config-add-to-list = {
+ config:edit $1 ;
+ a = (config:property-list | grep --color never $2 | tac) ;
+ b = (echo $a | grep --color never "\b$3\b" | tac) ;
+ if { ($b trim) isEmpty } {
+ if { $a isEmpty } {
+ config:property-set $2 $3
+ } {
+ config:property-append $2 ", $3"
+ } ;
+ config:update
+ } {
+ config:cancel
+ }
+}
+</pre><p>This second example shows a script to wait for an OSGi service, up to a given timeout, and combine this script in<br/>other scripts:</p><pre>
+#
+# Wait for the given OSGi service to be available
+#
+wait-for-service-timeout = {
+ _filter = $.context createFilter $1 ;
+ _tracker = shell:new org.osgi.util.tracker.ServiceTracker $.context $_filter null ;
+ $_tracker open ;
+ _service = $_tracker waitForService $2 ;
+ $_tracker close
+}
+#
+# Wait for the given OSGi service to be available with a timeout of 10 seconds
+#
+wait-for-service = {
+ wait-for-service-timeout $1 10000
+}
+#
+# Wait for the given command to be available with a timeout of 10 seconds
+# For example:
+# > wait-for-command dev watch
+#
+wait-for-command = {
+ wait-for-service "(&(objectClass=org.apache.felix.service.command.Function)(osgi.command.scope=$1)(osgi.command.function=$2))"
+}
+</pre>
+ </div>
+ </td>
+ </tr>
+ </table>
+ </td>
+ <td id="cell-2-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-3-0">
+
+ </td>
+ <td id="cell-3-1">
+
+ </td>
+ <td id="cell-3-2">
+ <div id="footer">
+ <div id="site-footer">
+ © 2008-2011 The Apache Software Foundation
+ <br/>
+ Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
+ </div>
+ </div>
+ </td>
+ <td id="cell-3-3">
+
+ </td>
+ <td id="cell-3-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-4-0" colspan="2">
+
+ </td>
+ <td id="cell-4-1">
+
+ </td>
+ <td id="cell-4-2" colspan="2">
+
+ </td>
+ </tr>
+ </table>
+ </body>
+</html>
\ No newline at end of file
Added: karaf/site/production/manual/latest-3.0.x/developers-guide/security-framework.html
URL: http://svn.apache.org/viewvc/karaf/site/production/manual/latest-3.0.x/developers-guide/security-framework.html?rev=1688692&view=auto
==============================================================================
--- karaf/site/production/manual/latest-3.0.x/developers-guide/security-framework.html (added)
+++ karaf/site/production/manual/latest-3.0.x/developers-guide/security-framework.html Wed Jul 1 17:06:42 2015
@@ -0,0 +1,210 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN" "http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
+<html lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <meta name="description" content="description goes here"/>
+ <meta name="keywords" content="keywords,goes,here"/>
+ <meta name="author" content="The Apache Karaf Team"/>
+ <link href="../css/style.css" rel="stylesheet" type="text/css"/>
+ <link href="../css/pygmentize.css" rel="stylesheet" type="text/css"/>
+ <title>
+ Apache Karaf 3.0.5-SNAPSHOT Guides
+ </title>
+ </head>
+ <body>
+ <table width="100%" cellpadding="0" cellspacing="0">
+ <tr width="100%">
+ <td id="cell-0-0" colspan="2">
+
+ </td>
+ <td id="cell-0-1">
+
+ </td>
+ <td id="cell-0-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-1-0">
+
+ </td>
+ <td id="cell-1-1">
+
+ </td>
+ <td id="cell-1-2">
+ <div style="padding: 5px;">
+ <div id="banner">
+ <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td align="left" class="topbardiv" nowrap="">
+<a href="http://karaf.apache.org/" title="A server side OSGi distribution">
+ <img border="0" src="../images/karaf-logo.png" width="400px"></img>
+</a>
+ </td>
+ <td align="right" nowrap="">
+<a href="http://www.apache.org/" title="The Apache Sofware Foundation">
+ <img border="0" src="../images/asf-logo.png">
+</a>
+ </td>
+ </tr>
+ </table>
+
+ </div>
+ <div id="top-menu">
+ <table border="0" cellpadding="1" cellspacing="0" width="100%">
+ <tr>
+ <td>
+ <div align="left"></div>
+ </td>
+ <td>
+ <div align="right">
+ <p>
+<a href="../index.html" title="Home">Home</a>
+|
+<a href="../users-guide/index.html" title="Users Guide">Users Guide</a>
+|
+<a href="index.html" title="Developers Guide">Developers Guide</a>
+</p>
+
+
+ </div>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ </td>
+ <td id="cell-1-3">
+
+ </td>
+ <td id="cell-1-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-2-0" colspan="2">
+
+ </td>
+ <td id="cell-2-1">
+ <table>
+ <tr height="100%" valign="top">
+ <td height="100%">
+ <div id="wrapper-menu-page-right">
+ <div id="wrapper-menu-page-top">
+ <div id="wrapper-menu-page-bottom">
+ <div id="menu-page">
+ <h3 id="Homeindex"><a href="../index.html">Home</a></h3><ul style="list-style: square"><li><a href="../overview.html">Overview</a></li><li><a href="../quick-start.html">Quick Start</a></li></ul><h3 id="UsersGuideusersguideindex"><a href="../users-guide/index.html">Users Guide</a></h3><ul style="list-style: square"><li><a href="../users-guide/installation.html">Installation</a></li><li><a href="../users-guide/directory-structure.html">Directory structure</a></li><li><a href="../users-guide/start-stop.html">Start, stop, restart, connect</a></li><li><a href="../users-guide/wrapper.html">Integration in the operating system: the Service Wrapper</a></li><li><a href="../users-guide/console.html">Console</a></li><li><a href="../users-guide/remote.html">Remote</a></li><li><a href="../users-guide/log.html">Log</a></li><li><a href="../users-guide/configuration.html">Configuration</a></li><li><a href="../users-guide/urls.html">Artifacts repositories and URLs</a></li><li>
<a href="../users-guide/provisioning.html">Provisioning and features</a></li><li><a href="../users-guide/deployers.html">Deployers</a></li><li><a href="../users-guide/kar.html">KAR</a></li><li><a href="../users-guide/instances.html">Instances</a></li><li><a href="../users-guide/security.html">Security</a></li><li><a href="../users-guide/obr.html">OBR</a></li><li><a href="../users-guide/enterprise.html">Enterprise</a><ul><li><a href="../users-guide/webcontainer.html">WebContainer (JSP/Servlet)</a></li><li><a href="../users-guide/jndi.html">Naming (JNDI)</a></li><li><a href="../users-guide/jta.html">Transaction (JTA)</a></li><li><a href="../users-guide/jdbc.html">DataSource (JDBC)</a></li><li><a href="../users-guide/jms.html">MOM (JMS)</a></li><li><a href="../users-guide/jpa.html">Persistence (JPA)</a></li><li><a href="../users-guide/ejb.html">EJB</a></li><li><a href="../users-guide/cdi.html">CDI</a></li><li><a href="../users-guide/failover.html">HA/failover and cluster</a></li></ul><
/li><li><a href="../users-guide/monitoring.html">Monitoring and Management using JMX</a></li><li><a href="../users-guide/webconsole.html">WebConsole</a></li><li><a href="../users-guide/tuning.html">Tuning</a></li></ul><h3 id="DevelopersGuidedevelopersguideindex"><a href="index.html">Developers Guide</a></h3><ul style="list-style: square"><li><a href="developer-commands.html">Developer commands</a></li><li><a href="scripting.html">Scripting</a></li><li><a href="connect.html">Programmatically connect</a></li><li><a href="branding.html">Branding</a></li><li><a href="extending.html">Extending</a></li><li><a href="karaf-maven-plugin.html">Karaf Maven plugin</a></li><li><a href="custom-distribution.html">Custom distribution</a></li><li><a href="services.html">OSGi services</a></li><li><a href="creating-bundles.html">Create OSGi bundle</a></li><li><a href="blueprint.html">Blueprint</a></li><li><a href="cdi.html">CDI</a></li><li><a href="archetypes.html">Maven Archetypes</a></li><li><a href
="security-framework.html">Security Framework</a></li><li><a href="debugging.html">Troubleshooting, Debugging, Profiling</a></li><li><a href="writing-tests.html">Integration testing</a></li><li><a href="github-contributions.html">Github Contributions</a></li></ul><h3 id="Commandscommandscommands"><a href="../commands/commands.html">Commands</a></h3>
+ </div>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td height="100%" width="100%">
+ <div class="wiki-content">
+<h1 id="Securityframework">Security framework</h1><p>Karaf supports <a href="http://download.oracle.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html">JAAS</a> with some enhancements to allow JAAS to work nicely in an OSGi environment. This framework also features an OSGi keystore manager with the ability to deploy new keystores or truststores at runtime. </p><h2 id="Overview">Overview</h2><p>This feature allows runtime deployment of JAAS based configuration for use in various parts of the application. This<br/>includes the remote console login, which uses the <tt>karaf</tt> realm, but which is configured with a dummy login module<br/>by default. These realms can also be used by the NMR, JBI components or the JMX server to authenticate users logging in<br/>or sending messages into the bus.</p><p>In addition to JAAS realms, you can also deploy keystores and truststores to secure the remote shell console, setting up HTTPS connectors or using certificates for WS-Secu
rity.</p><p>A very simple XML schema for spring has been defined, allowing the deployment of a new realm or a new keystore very easily.</p><h2 id="Schema">Schema</h2><p>To override or deploy a new realm, you can use the following XSD which is supported by a Spring namespace handler and can thus be defined in a Spring xml configuration file.</p><p>Following is the XML Schema to use when defining Karaf realms:</p><div class="syntax"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="c"><!--</span>

<span class="c"> Licensed to the Apache Software Foundation (ASF) under one or more</span>
<span class="c"> contributor license agreements. See the NOTICE file distributed with</span>
<span class="c"> this work for additional information regarding copyright ownership.</span>
<span class="c"> The ASF licenses this file to You under the Apache License, Versi
on 2.0</span>
<span class="c"> (the "License"); you may not use this file except in compliance with</span>
<span class="c"> the License. You may obtain a copy of the License at</span>

<span class="c"> http://www.apache.org/licenses/LICENSE-2.0</span>

<span class="c"> Unless required by applicable law or agreed to in writing, software</span>
<span class="c"> distributed under the License is distributed on an "AS IS" BASIS,</span>
<span class="c"> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span>
<span class="c"> See the License for the specific language governing permissions and</span>
<span class="c"> limitations under the License.</span>

<span class="c">--></span>
<span class="nt"><xs:schema</span> <span class="na">elementFormDefault=</span><span class="s">'qualified'</span>
 <span
class="na">targetNamespace=</span><span class="s">'http://karaf.apache.org/xmlns/jaas/v1.1.0'</span>
 <span class="na">xmlns:xs=</span><span class="s">'http://www.w3.org/2001/XMLSchema'</span>
 <span class="na">xmlns:bp=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:tns=</span><span class="s">'http://karaf.apache.org/xmlns/jaas/v1.1.0'</span><span class="nt">></span>

 <span class="nt"><xs:import</span> <span class="na">namespace=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span><span class="nt">/></span>

 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"config"</span><span class="nt">></span>
 <span class="nt"><xs:complexType></span>
 <span class="nt"><xs:sequence></span>

<span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"module"</span> <span class="na">minOccurs=</span><span class="s">"0"</span> <span class="na">maxOccurs=</span><span class="s">"unbounded"</span><span class="nt">></span>
 <span class="nt"><xs:complexType</span> <span class="na">mixed=</span><span class="s">"true"</span><span class="nt">></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"className"</span> <span class="na">use=</span><span class="s">"required"
;</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"flags"</span> <span class="na">default=</span><span class="s">"required"</span><span class="nt">></span>
 <span class="nt"><xs:simpleType></span>
 <span class="nt"><xs:restriction</span> <span class="na">base=</span><span class="s">"xs:NMTOKEN"</span><span class="nt">></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"required"</span><span class="nt">/></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"requisite"</span><span class="nt">/></
span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"sufficient"</span><span class="nt">/></span>
 <span class="nt"><xs:enumeration</span> <span class="na">value=</span><span class="s">"optional"</span><span class="nt">/></span>
 <span class="nt"></xs:restriction></span>
 <span class="nt"></xs:simpleType></span>
 <span class="nt"></xs:attribute></span>
 <span class="nt"></xs:complexType></span>
 <span class="nt"></xs:element></span>
 <span class="nt"></xs:sequence></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span class="na">use=</span><s
pan class="s">"required"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"rank"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">default=</span><span class="s">"0"</span> <span class="na">type=</span><span class="s">"xs:int"</span><span class="nt">/></span>
 <span class="nt"></xs:complexType></span>
 <span class="nt"></xs:element></span>

 <span class="nt"><xs:element</span> <span class="na">name=</span><span class="s">"keystore"</span><span class="nt">></span>
 <span class="nt"><xs:complexType></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"name"</span> <span class="n
a">use=</span><span class="s">"required"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"rank"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">default=</span><span class="s">"0"</span> <span class="na">type=</span><span class="s">"xs:int"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"path"</span> <span class="na">use=</span><span class="s">"required"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"keystorePassword"</span> <span class="na">use=
</span><span class="s">"optional"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"><xs:attribute</span> <span class="na">name=</span><span class="s">"keyPasswords"</span> <span class="na">use=</span><span class="s">"optional"</span> <span class="na">type=</span><span class="s">"xs:string"</span><span class="nt">/></span>
 <span class="nt"></xs:complexType></span>
 <span class="nt"></xs:element></span>

<span class="nt"></xs:schema></span>
</pre></div>
</div><p>You can find the schema at the following <a href="http://karaf.apache.org/xmlns/jaas/v1.1.0">location</a>.</p><p>Here are two examples using this schema:</p><div class="syntax"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> 
<span class="nt">
<blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.0.0"</span>
 <span class="na">xmlns:ext=</span><span class="s">"http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"</span><span class="nt">></span>

 <span class="c"><!-- Bean to allow the $[karaf.base] property to be correctly resolved --></span>
 <span class="nt"><ext:property-placeholder</span> <span class="na">placeholder-prefix=</span><span class="s">"$["</span> <span class="na">placeholder-suffix=</span><span class="s">"]"</span><span class="nt">/></span>

 <span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"myrealm"</span><span class="nt">></span>
 <span class
="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 <span class="nt"></jaas:module></span>
 <span class="nt"></jaas:config></span>

<span class="nt"></blueprint></span>
</pre></div>
</div><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:keystore</span> <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.1.0"</span>
 <span class="na">name=</span><span class="s">"ks"</span>
 <span class="na">rank=</span><span class="s">"1"</span>
 <span class="na">path=</span><span
class="s">"classpath:privatestore.jks"</span>
 <span class="na">keystorePassword=</span><span class="s">"keyStorePassword"</span>
 <span class="na">keyPasswords=</span><span class="s">"myalias=myAliasPassword"</span><span class="nt">></span>
<span class="nt"></jaas:keystore></span>
</pre></div>
</div><p>The <tt>id</tt> attribute is the blueprint id of the bean, but it will be used by default as the name of the realm if no<br/><tt>name</tt> attribute is specified. Additional attributes on the <tt>config</tt> elements are a <tt>rank</tt>, which is an integer.<br/>When the LoginContext looks for a realm for authenticating a given user, the realms registered in the OSGi registry are<br/>matched against the required name. If more than one realm is found, the one with the highest rank will be used, thus<br/>allowing the override of some realms with new values. The last attribute is <tt>p
ublish</tt> which can be set to false to<br/>not publish the realm in the OSGi registry, thereby disabling the use of this realm.</p><p>Each realm can contain one or more module definitions. Each module identifies a LoginModule and the <tt>className</tt><br/>attribute must be set to the class name of the login module to use. Note that this login module must be available from<br/>the bundle classloader, so either it has to be defined in the bundle itself, or the needed package needs to be correctly<br/>imported. The <tt>flags</tt> attribute can take one of four values that are explained on the <a href="http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/boot/src/main/java/org/apache/karaf/jaas/boot/ProxyLoginModule.java">JAAS documentation</a>.<br/>The content of the <tt>module</tt> element is parsed as a properties file and will be used to further configure the login module.</p><p>Deploying such a code will lead to a <a href="http://svn.apache.org/repos/asf/karaf/tags/karaf-
2.0.0/jaas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java">JaasRealm</a> object in the OSGi registry, which will then be used when using the JAAS login module.</p><h3 id="Configurationoverrideanduseoftherankattribute">Configuration override and use of the <tt>rank</tt> attribute</h3><p>The <tt>rank</tt> attribute on the <tt>config</tt> element is tied to the ranking of the underlying OSGi service. When the JAAS<br/>framework performs an authentication, it will use the realm name to find a matching JAAS configuration. If multiple<br/>configurations are used, the one with the highest <tt>rank</tt> attribute will be used.<br/>So if you want to override the default security configuration in Karaf (which is used by the ssh shell, web console and<br/>JMX layer), you need to deploy a JAAS configuration with the name <tt>name="karaf"</tt> and <tt>rank="1"</tt>.</p><div class="syntax"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding=&
quot;UTF-8"?></span>
<span class="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.1.0"</span>
 <span class="na">xmlns:ext=</span><span class="s">"http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"</span><span class="nt">></span>

 <span class="c"><!-- Bean to allow the $[karaf.base] property to be correctly resolved --></span>
 <span class="nt"><ext:property-placeholder</span> <span class="na">placeholder-prefix=</span><span class="s">"$["</span> <span class="na">placeholder-suffix=</span><span class="s">"]"</span><span class="nt">/></span>

 <span class="nt"><type-converters></span>
 <span class="nt"><bean</span> <span class="na">
class=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesConverter"</span><span class="nt">/></span>
 <span class="nt"></type-converters></span> 

 <span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span> <span class="na">rank=</span><span class="s">"1"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span>
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 ...
 <span class="nt"></jaas:module></span>
 <span class="nt"></jaas:config></span>

<span class="nt"></blueprint></span>

</pre></div>
</div><h2 id="Architecture">Architecture</h2><p>Due to constraints in the JAAS specification, one class has to be available for all bundles.<br/>This class is called <a href="http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/jaas/boot/src/main/java/org/apache/karaf/jaas/boot/ProxyLoginModule.java">ProxyLoginModule</a> and is a LoginModule that acts as a proxy for an OSGi defines LoginModule. If you plan to integrate this feature into another OSGi runtime, this class must be made available from the system classloader and the related package be part of the boot delegation classpath (or be deployed as a fragment attached to the system bundle).</p><p>The xml schema defined above allows the use of a simple xml (leveraging spring xml extensibility) to configure and<br/>register a JAAS configuration for a given realm. This configuration will be made available into the OSGi registry as a<br/><a href="http://svn.apache.org/repos/asf/karaf/tags/karaf-2.0.0/j
aas/config/src/main/java/org/apache/karaf/jaas/config/JaasRealm.java">JaasRealm</a> and the OSGi specific Configuration will look for such services.<br/>Then the proxy login module will be able to use the information provided by the realm to actually load the class from<br/>the bundle containing the real login module.</p><p>Karaf itself provides a set of login modules ready to use, depending of the authentication backend that you need.</p><p>In addition of the login modules, Karaf also support backend engine. The backend engine is coupled to a login module and<br/>allows you to manipulate users and roles directly from Karaf (adding a new user, delete an existing user, etc).<br/>The backend engine is constructed by a backend engine factory, registered as an OSGi service.<br/>Some login modules (for security reason for instance) don't provide backend engine.</p><h2 id="Availablerealmandloginmodules">Available realm and login modules</h2><p>Karaf comes with a default realm named "karaf
" using login modules.</p><p>Karaf also provides a set of login modules and backend engines to handle authentication needs for your environment.</p><h3 id="PropertiesLoginModule">PropertiesLoginModule</h3><div class="table-wrap"><table class="confluenceTable"><tr><td class="confluenceTd"> LoginModule </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.properties.PropertiesLoginModule </td></tr><tr><td class="confluenceTd"> BackendEngineFactory </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.properties.PropertiesBackendEngineFactory </td></tr></table></div><p>This login module is the one configured by default. It uses a properties text file to load the users, passwords and roles.</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>users</tt> </td><td class="confluenceTd"> location of the prop
erties file </td></tr></table></div><p>This file uses the <a href="http://download.oracle.com/javase/6/docs/api/java/util/Properties.html#load(java.io.Reader)">properties file format</a>.<br/>The format of the properties is as follows, with each line defining a user, its password and associated roles:</p><pre>
+user=password[,role][,role]...
+</pre><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = ${karaf.etc}/users.properties
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</div><p>The PropertiesLoginModule provides a backend engine allowing:</p><ul><li>add a new user</li><li>delete an existing user</li><li>list the users, groups, and roles</li><li>add a new role to an user</li><li>delete a role from an user</li><li>add an user into a group</li><li>remove an user from a grou
p</li><li>add a role to a group</li><li>delete a role from a group</li></ul><p>To enable the backend engine, you have to register the corresponding OSGi service. For instance, the following blueprint<br/>shows how to register the PropertiesLoginModule and the corresponding backend engine:</p><div class="syntax"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.1.0"</span>
 <span class="na">xmlns:ext=</span><span class="s">"http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0"</span><span class="nt">></span>

 <span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">&quo
t;karaf"</span> <span class="na">rank=</span><span class="s">"-1"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span>
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = ${karaf.etc}/users.properties
 <span class="nt"></jaas:module></span>
 <span class="nt"></jaas:config></span>

 <span class="nt"><service</span> <span class="na">interface=</span><span class="s">"org.apache.karaf.jaas.modules.BackingEngineFactory"</span><span class="nt">></span>
 <span class="nt"><bean</span> <span class="na">class=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesBackingEngineFactory"</span><spa
n class="nt">/></span>
 <span class="nt"></service></span>

<span class="nt"></blueprint></span>
</pre></div>
</div><h3 id="OsgiConfigLoginModule">OsgiConfigLoginModule</h3><div class="table-wrap"><table class="confluenceTable"><tr><td class="confluenceTd"> LoginModule </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.osgi.OsgiConfigLoginModule </td></tr><tr><td class="confluenceTd"> BackendEngineFactory </td><td class="confluenceTd"> N/A </td></tr></table></div><p>The OsgiConfigLoginModule uses the OSGi ConfigurationAdmin service to provide the users, passwords and roles.</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>pid</tt> </td><td class="confluenceTd"> the PID of the configuration containing user def
initions </td></tr></table></div><p>The format of the configuration is the same than for the <tt>PropertiesLoginModule</tt> with properties prefixed with <tt>user.</tt>.</p><p>For instance, in the Karaf etc folder, we create a file <tt>org.apache.karaf.authentication.cfg</tt> containing:</p><pre>
+user.karaf=karaf,admin
+user.user=password,role
+</pre><p>The following blueprint shows how to use this configuration:</p><div class="syntax"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.1.0"</span><span class="nt">></span>

 <span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span> <span class="na">rank=</span><span class="s">"-1"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.osgi.OsgiConfigLoginModule"</span>
 <span class="na">flags=</span><span class="
s">"required"</span><span class="nt">></span>
 pid = org.apache.karaf.authentication
 <span class="nt"></jaas:module></span>
 <span class="nt"></jaas:config></span>

<span class="nt"></blueprint></span>
</pre></div>
</div><p>NB: the OsgiConfigLoginModule doesn't provide a backend engine.</p><h3 id="JDBCLoginModule">JDBCLoginModule</h3><div class="table-wrap"><table class="confluenceTable"><tr><td class="confluenceTd"> LoginModule </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule </td></tr><tr><td class="confluenceTd"> BackendEngineFactory </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.jdbc.JDBCBackendEngineFactory </td></tr></table></div><p>The JDBCLoginModule uses a database to load the users, passwords and roles from a provided data source <em>(normal or XA)</em>.<br/>The data source and the queries for password
and role retrieval are configurable using the following parameters.</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>datasource</tt> </td><td class="confluenceTd"> The datasource as on OSGi ldap filter or as JDNI name</td></tr><tr><td class="confluenceTd"> <tt>query.password</tt> </td><td class="confluenceTd"> The SQL query that retries the password of the user </td></tr><tr><td class="confluenceTd"> <tt>query.role</tt> </td><td class="confluenceTd"> The SQL query that retries the roles of the user </td></tr></table></div><p><u>Passing a data source as an OSGi ldap filter</u></p><p>To use an OSGi ldap filter, the prefix osgi: needs to be provided, as shown below:</p><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf&qu
ot;</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 datasource = osgi: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=?
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</div><p><u>Passing a data source as a JNDI name</u></p><p>To use an JNDI name, the prefix jndi: needs to be provided. The example below assumes the use of Aries jndi to expose<br/>services via JNDI.</p><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:config</span
> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 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=?
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</div><p>The JDBCLoginModule provides a backend engine allowing:</p><ul><li>add a new user</li><li>delete an user</li><li>list users, roles</li><li>add a new role to an user</li><li>remove a role from an user</li>
</ul><p>NB: the groups are not fully supported by the JDBCBackingEngine.</p><p>The following blueprint shows how to define the JDBCLoginModule with the corresponding backend engine:</p><div class="syntax"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:jaas=</span><span class="s">"http://karaf.apache.org/xmlns/jaas/v1.1.0"</span><span class="nt">></span>

 <span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule"</span>
 <span cl
ass="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 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=?
 <span class="nt"></jaas:module></span>
 <span class="nt"></jaas:config></span>

 <span class="nt"><service</span> <span class="na">interface=</span><span class="s">"org.apache.karaf.jaas.modules.BackingEngineFactory"</span><span class="nt">></span>
 <span class="nt"><bean</span> <span class="na">class=</span><span class="s"
>"org.apache.karaf.jaas.modules.jdbc.JDBCBackingEngineFactory"</span><span class="nt">/></span>
 <span class="nt"></service></span>

<span class="nt"></blueprint></span>
</pre></div>
</div><h3 id="LDAPLoginModule">LDAPLoginModule</h3><div class="table-wrap"><table class="confluenceTable"><tr><td class="confluenceTd"> LoginModule </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.ldap.LDAPLoginModule </td></tr><tr><td class="confluenceTd"> BackendEngineFactory </td><td class="confluenceTd"> N/A </td></tr></table></div><p>The LDAPLoginModule uses LDAP to load the users and roles and bind the users on the LDAP to check passwords.</p><p>The LDAPLoginModule supports the following parameters:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Des
cription </th></tr><tr><td class="confluenceTd"> <tt>connection.url</tt> </td><td class="confluenceTd"> The LDAP connection URL, e.g. ldap://hostname </td></tr><tr><td class="confluenceTd"> <tt>connection.username</tt> </td><td class="confluenceTd"> Admin username to connect to the LDAP. This parameter is optional, if it's not provided, the LDAP connection will be anonymous. </td></tr><tr><td class="confluenceTd"> <tt>connection.password</tt> </td><td class="confluenceTd"> Admin password to connect to the LDAP. Only used if the <tt>connection.username</tt> is specified. </td></tr><tr><td class="confluenceTd"> <tt>user.base.dn</tt> </td><td class="confluenceTd"> The LDAP base DN used to looking for user, e.g. ou=user,dc=apache,dc=org </td></tr><tr><td class="confluenceTd"> <tt>user.filter</tt> </td><td class="confluenceTd"> The LDAP filter used to looking for user, e.g. (uid=%u) where %u will be replaced by the username. </td></tr><tr><td class
="confluenceTd"> <tt>user.search.subtree</tt> </td><td class="confluenceTd"> If "true", the user lookup will be recursive (SUBTREE). If "false", the user lookup will be performed only at the first level (ONELEVEL). </td></tr><tr><td class="confluenceTd"> <tt>role.base.dn</tt> </td><td class="confluenceTd"> The LDAP base DN used to looking for roles, e.g. ou=role,dc=apache,dc=org </td></tr><tr><td class="confluenceTd"> <tt>role.filter</tt> </td><td class="confluenceTd"> The LDAP filter used to looking for user's role, e.g. (member:=uid=%u) </td></tr><tr><td class="confluenceTd"> <tt>role.name.attribute</tt> </td><td class="confluenceTd"> The LDAP role attribute containing the role string used by Karaf, e.g. cn </td></tr><tr><td class="confluenceTd"> <tt>role.search.subtree</tt> </td><td class="confluenceTd"> If "true", the role lookup will be recursive (SUBTREE). If "false", the role lookup will be performed only at the first level (ONELEVEL). </td>
</tr><tr><td class="confluenceTd"> <tt>role.mapping</tt> </td><td class="confluenceTd"> Define a mapping between roles defined in the LDAP directory for the user, and corresponding roles in Karaf. The format is ldapRole1=karafRole1,karafRole2;ldapRole2=karafRole3,karafRole4. </td></tr><tr><td class="confluenceTd"> <tt>authentication</tt> </td><td class="confluenceTd"> Define the authentication backend used on the LDAP server. The default is simple. </td></tr><tr><td class="confluenceTd"> <tt>initial.context.factory</tt> </td><td class="confluenceTd"> Define the initial context factory used to connect to the LDAP server. The default is com.sun.jndi.ldap.LdapCtxFactory </td></tr><tr><td class="confluenceTd"> <tt>ssl</tt> </td><td class="confluenceTd"> If "true" or if the protocol on the <tt>connection.url</tt> is <tt>ldaps</tt>, an SSL connection will be used </td></tr><tr><td class="confluenceTd"> <tt>ssl.provider</tt> </td><td class
="confluenceTd"> The provider name to use for SSL </td></tr><tr><td class="confluenceTd"> <tt>ssl.protocol</tt> </td><td class="confluenceTd"> The protocol name to use for SSL (SSL for example)</td></tr><tr><td class="confluenceTd"> <tt>ssl.algorithm</tt> </td><td class="confluenceTd"> The algorithm to use for the KeyManagerFactory and TrustManagerFactory (PKIX for example) </td></tr><tr><td class="confluenceTd"> <tt>ssl.keystore</tt> </td><td class="confluenceTd"> The key store name to use for SSL. The key store must be deployed using a <tt>jaas:keystore</tt> configuration. </td></tr><tr><td class="confluenceTd"> <tt>ssl.keyalias</tt> </td><td class="confluenceTd"> The key alias to use for SSL </td></tr><tr><td class="confluenceTd"> <tt>ssl.truststore</tt> </td><td class="confluenceTd"> The trust store name to use for SSL. The trust store must be deployed using a <tt>jaas:keystore</tt> configuration. </td></tr></table></div><
p>A example of LDAPLoginModule usage follows:</p><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.ldap.LDAPLoginModule"</span> <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 connection.url = ldap://localhost:389
 user.base.dn = ou=user,dc=apache,dc=org
 user.filter = (cn=%u)
 user.search.subtree = true
 role.base.dn = ou=group,dc=apache,dc=org
 role.filter = (member:=uid=%u)
 role.name.attribute = cn
 role.search.subtree = true
 authentication = simple
 <span class="nt"></jaas:module></span>
<span class="nt"><
;/jaas:config></span>
</pre></div>
</div><p>If you wish to use an SSL connection, the following configuration can be used as an example:</p><div class="syntax"><div class="highlight"><pre><span class="nt"><ext:property-placeholder</span> <span class="nt">/></span>

<span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span> <span class="na">rank=</span><span class="s">"1"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.ldap.LDAPLoginModule"</span> <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 connection.url = ldaps://localhost:10636
 user.base.dn = ou=users,ou=system
 user.filter = (uid=%u)
 user.search.subtree = true
 role.base.dn = ou
=groups,ou=system
 role.filter = (uniqueMember=uid=%u)
 role.name.attribute = cn
 role.search.subtree = true
 authentication = simple
 ssl.protocol=SSL
 ssl.truststore=ks
 ssl.algorithm=PKIX
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>

<span class="nt"><jaas:keystore</span> <span class="na">name=</span><span class="s">"ks"</span>
 <span class="na">path=</span><span class="s">"file:///${karaf.home}/etc/trusted.ks"</span>
 <span class="na">keystorePassword=</span><span class="s">"secret"</span> <span class="nt">/></span>
</pre></div>
</div><p>The LDAPLoginModule supports the following patterns that you can use in the filter (user and role filters):</p><ul><li><tt>%u</tt> is replaced by the user</li><li><tt>%dn</tt> is rep
laced by the user DN</li><li><tt>%fqdn</tt> is replaced by the user full qualified DN (<tt>userDNNamespace</tt>).</li></ul><p>For instance, the following configuration will work properly with ActiveDirectory (adding the ActiveDirectory to the<br/>default <tt>karaf</tt> realm):</p><pre>
+<jaas:config name="karaf" rank="2">
+ <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule" flags="required">
+ initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
+ connection.username=admin
+ connection.password=xxxxxxx
+ connection.protocol=
+ connection.url=ldap://activedirectory_host:389
+ user.base.dn=ou=Users,ou=there,DC=local
+ user.filter=(sAMAccountName=%u)
+ user.search.subtree=true
+ role.base.dn=ou=Groups,ou=there,DC=local
+ role.name.attribute=cn
+ role.filter=(member=%nsdn)
+ role.search.subtree=true
+ authentication=simple
+ </jaas:module>
+</jaas:config>
+</pre><p>NB: the LDAPLoginModule doesn't provide backend engine. It means that the administration of the users and roles should be<br/>performed directly on the LDAP backend.</p><h3 id="SyncopeLoginModule">SyncopeLoginModule</h3><div class="table-wrap"><table class="confluenceTable"><tr><td class="confluenceTd"> LoginModule </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.syncope.SyncopeLoginModule </td></tr><tr><td class="confluenceTd"> BackendEngineFactory </td><td class="confluenceTd"> org.apache.karaf.jaas.modules.syncope.SyncopeBackendEngineFactory </td></tr></table></div><p>The Syncope login module uses the Syncope REST API to authenticate users and retrieve the roles.</p><p>The Syncope login module just requires one parameter:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>address</tt>
</td><td class="confluenceTd"> Location of the Syncope REST API </td></tr><tr><td class="confluenceTd"> <tt>admin.user</tt> </td><td class="confluenceTd"> Admin username to administrate Syncope (only required by the backend engine) </td></tr><tr><td class="confluenceTd"> <tt>admin.password</tt> </td><td class="confluenceTd"> Admin password to administrate Syncope (only required by the backend engine) </td></tr></table></div><p>The following snippet shows how to use Syncope with the karaf realm:</p><pre>
+<jaas:config name="karaf" rank="2">
+ <jaas:module className="org.apache.karaf.jaas.modules.syncope.SyncopeLoginModule" flags="required">
+ address=http://localhost:9080/syncope/cxf
+ admin.user=admin
+ admin.password=password
+ </jaas:module>
+</jaas:config>
+</pre><p>SyncopeLoginModule comes with a backend engine allowing to manipulate users and roles. You have to register the<br/>SyncopeBackendEngineFactory service.</p><p>For security reason, the SyncopeLoginModule backend engine allows only to list users and roles. You can't create or delete<br/>users and roles directly from Karaf. To do it, you have to use the Syncope web console.</p><p>For instance, the following blueprint descriptor enables the SyncopeLoginModule and the backend engine factory:</p><pre>
+<?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="2">
+ <jaas:module className="org.apache.karaf.jaas.modules.syncope.SyncopeLoginModule"
+ flags="required">
+ address=http://localhost:9080/syncope/cxf
+ admin.user=admin
+ admin.password=password
+ </jaas:module>
+ </jaas:config>
+
+ <service interface="org.apache.karaf.jaas.modules.BackingEngineFactory">
+ <bean class="org.apache.karaf.jaas.modules.syncope.SyncopeBackingEngineFactory"/>
+ </service>
+
+</blueprint>
+</pre><h2 id="Encryptionservice">Encryption service</h2><p>The <a href="http://svn.apache.org/repos/asf/karaf/trunk/jaas/modules/src/main/java/org/apache/karaf/jaas/modules/EncryptionService.java">EncryptionService</a> is a service registered in the OSGi registry providing means to encrypt and check encrypted passwords. This service acts as a factory for <a href="http://svn.apache.org/repos/asf/karaf/trunk/jaas/modules/src/main/java/org/apache/karaf/jaas/modules/Encryption.java">Encryption</a> objects actually performing the encryption.</p><p>This service is used in all Karaf login modules to support encrypted passwords.</p><h3 id="Configuringproperties">Configuring properties</h3><p>Each login module supports the following additional set of properties:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>encryption.name</tt> </td><td
class="confluenceTd"> Name of the encryption service registered in OSGi (cf. paragraph <a href="#Jasypt.html">below</a>) </td></tr><tr><td class="confluenceTd"> <tt>encryption.enabled</tt> </td><td class="confluenceTd"> Boolean used to turn on encryption </td></tr><tr><td class="confluenceTd"> <tt>encryption.prefix</tt> </td><td class="confluenceTd"> Prefix for encrypted passwords </td></tr><tr><td class="confluenceTd"> <tt>encryption.suffix</tt> </td><td class="confluenceTd"> Suffix for encrypted passwords </td></tr><tr><td class="confluenceTd"> <tt>encryption.algorithm</tt> </td><td class="confluenceTd"> Name of an algorithm to be used for hashing, like "MD5" or "SHA-1" </td></tr><tr><td class="confluenceTd"> <tt>encryption.encoding</tt> </td><td class="confluenceTd"> Encrypted passwords encoding (can be <tt>hexadecimal</tt> or <tt>base64</tt>) </td></tr><tr><td class="confluenceTd"> <tt>role.policy</tt> </td><td class="confluenceTd"> A policy for identifying ro
les (can be <tt>prefix</tt> or <tt>group</tt>) <a href="#Rolediscoverypolicies.html">below</a>) </td></tr><tr><td class="confluenceTd"> <tt>role.discriminator</tt> </td><td class="confluenceTd"> A discriminator value to be used by the role policy </td></tr></table></div><p>A simple example follows:</p><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 encryption.enabled = true
 encryption.algorithm = MD5
 encryption.encoding = hexadecimal

; <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</div><h3 id="Prefixandsuffix">Prefix and suffix</h3><p>The login modules have the ability to support both encrypted and plain passwords at the same time. In some cases, some login modules may be able to encrypt the passwords on the fly and save them back in an encrypted form.</p><h3 id="Jasypt">Jasypt</h3><p>Karaf default installation comes with a simple encryption service which usually fullfill simple needs. However, in some<br/>cases, you may want to install the <a href="http://www.jasypt.org/">Jasypt</a> library which provides stronger encryption algorithms<br/>and more control over them.</p><p>To install the Jasypt library, the easiest way is to install the available feature:</p><pre>
+karaf@root> features:install jasypt-encryption
+</pre><p>It will download and install the required bundles and also register an <tt>EncryptionService</tt> for Jasypt in the OSGi registry.</p><p>When configuring a login module to use Jasypt, you need to specify the <tt>encryption.name</tt> property and set it to a value of <tt>jasypt</tt> to make sure the Jasypt encryption service will be used. </p><p>In addition to the standard properties above, the Jasypt service provides the following parameters:</p><div class="table-wrap"><table class="confluenceTable"><tr><th class="confluenceTh"> Name </th><th class="confluenceTh"> Description </th></tr><tr><td class="confluenceTd"> <tt>providerName</tt> </td><td class="confluenceTd"> Name of the <tt>java.security.Provider</tt> name to use for obtaining the digest algorithm </td></tr><tr><td class="confluenceTd"> <tt>providerClassName</tt> </td><td class="confluenceTd"> Class name for the security provider to be used for obtaining the digest algorithm </td>
</tr><tr><td class="confluenceTd"> <tt>iterations</tt> </td><td class="confluenceTd"> Number of times the hash function will be applied recursively </td></tr><tr><td class="confluenceTd"> <tt>saltSizeBytes</tt> </td><td class="confluenceTd"> Size of the salt to be used to compute the digest </td></tr><tr><td class="confluenceTd"> <tt>saltGeneratorClassName</tt> </td><td class="confluenceTd"> Class name of the salt generator </td></tr></table></div><p>A typical realm definition using Jasypt encryption service would look like:</p><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span> 
 <span class="na">flags=</span><span class="s">&q
uot;required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 encryption.enabled = true
 encryption.name = jasypt
 encryption.algorithm = SHA-256
 encryption.encoding = base64
 encryption.iterations = 100000
 encryption.saltSizeBytes = 16
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</div><h3 id="Usingencryptedpropertyplaceholders">Using encrypted property placeholders</h3><p>When using blueprint framework for OSGi for configuring devices that requires passwords like JDBC datasources,<br/>it is undesirable to use plain text passwords in configuration files. To avoid this problem it is good to store database<br/>passwords in encrypted format and use encrypted property placeholders when ever possible.</p><p>Encrypted properties can be stored in plain properties fi
les. The encrypted content is wrapped by an ENC() function.</p><pre>
+#db.cfg / db.properties
+db.url=localhost:9999
+db.username=admin
+db.password=ENC(zRM7Pb/NiKyCalroBz8CKw==)
+</pre><p>The encrypted property placeholders can be used either by defining Apache Aries ConfigAdmin <tt>property-placeholder</tt><br/>or by directly using the Apache Karaf <tt>property-placeholder</tt>. It has one child element <tt>encryptor</tt> that contains<br/>the actual Jasypt configuration. For detailed information on how to configure the different Jasypt encryptors, see the<br/><a href="http://www.jasypt.org/general-usage.html">Jasypt documentation</a>.</p><p>A typical definition using Jasypt encryption would look like:</p><div class="syntax"><div class="highlight"><pre><span class="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span>
 <span class="na">xmlns:cm=</span><span class="s">"http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0"</span>
 <span class="na">xmlns:ext=</span><span class="s">"http://aries.apache.org/blueprint/xmlns/bluepr
int-ext/v1.0.0"</span>
 <span class="na">xmlns:enc=</span><span class="s">"http://karaf.apache.org/xmlns/jasypt/v1.0.0"</span><span class="nt">></span>

 <span class="c"><!-- Configuration via ConfigAdmin property-placeholder --></span>
 <span class="c"><!-- the etc/*.cfg can contain encrypted values with ENC() function --></span>
 <span class="nt"><cm:property-placeholder</span> <span class="na">persistent-id=</span><span class="s">"db"</span> <span class="na">update-strategy=</span><span class="s">"reload"</span><span class="nt">></span>
 <span class="nt"><cm:default-properties></span>
 <span class="nt"><cm:property</span> <span class="na">name=</span><span class="s">"encoded"</span> <span class="na">value=</span><span class="s">"ENC(${foo})"</span><span class="nt">/></span>
 <span class="nt"></cm:default-propert
ies></span>
 <span class="nt"></cm:property-placeholder></span>

 <span class="c"><!-- Configuration via properties file --></span>
 <span class="c"><!-- Instead of ConfigAdmin, we can load "regular" properties file from a location --></span>
 <span class="c"><!-- Again, the db.properties file can contain encrypted values with ENC() function --></span>
 <span class="nt"><ext:property-placeholder></span>
 <span class="nt"><ext:location></span>file:etc/db.properties<span class="nt"></ext:location></span>
 <span class="nt"></ext:property-placeholder></span>

 <span class="nt"><enc:property-placeholder></span>
 <span class="nt"><enc:encryptor</span> <span class="na">class=</span><span class="s">"org.jasypt.encryption.pbe.StandardPBEStringEncryptor"</span><span class="nt">></span>
 <span class="nt"><pro
perty</span> <span class="na">name=</span><span class="s">"config"</span><span class="nt">></span>
 <span class="nt"><bean</span> <span class="na">class=</span><span class="s">"org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig"</span><span class="nt">></span>
 <span class="nt"><property</span> <span class="na">name=</span><span class="s">"algorithm"</span> <span class="na">value=</span><span class="s">"PBEWithMD5AndDES"</span><span class="nt">/></span>
 <span class="nt"><property</span> <span class="na">name=</span><span class="s">"passwordEnvName"</span> <span class="na">value=</span><span class="s">"ENCRYPTION_PASSWORD"</span><span class="nt">/></span>
 <span class="nt"></bean></span>
 <span class="nt"></property></span>
 <span class="nt"></enc:encryptor></span>
 <span class="nt"></
enc:property-placeholder></span>

 <span class="c"><!-- ... --></span>

<span class="nt"></blueprint></span>
</pre></div>
</div><p>Don't forget to install the jasypt feature to add the support of the enc namespace:</p><pre>
+karaf@root()> feature:install jasypt-encryption
+</pre><h2 id="Rolediscoverypolicies">Role discovery policies</h2><p>The JAAS specification does not provide means to distinguish between User and Role Principals without referring to the<br/>specification classes. In order to provide means to the application developer to decouple the application from Karaf<br/>JAAS implementation role policies have been created.</p><p>A role policy is a convention that can be adopted by the application in order to identify Roles, without depending from the implementation. Each role policy can be cofigured by setting a "role.policy" and "role.discriminator" property to the login module configuration. Currently, Karaf provides two policies that can be applied to all Karaf Login Modules.</p><ol><li>Prefixed Roles</li><li>Grouped Roles</li></ol><p><u>Prefixed Roles</u><br/>When the prefixed role policy is used the login module applies a configurable prefix <em>(property role.discriminator)</em> to<br/>the role, so that the application can identify the r
ole's principals by its prefix. Example:</p><div class="syntax"><div class="highlight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 role.policy = prefix
 role.discriminator = ROLE_
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</div><p>The application can identify the role principals using a snippet like this:</p><div class="syntax"><div class="highlight"><pre><span class="n">LoginContext</span> <span class="n
">ctx</span> <span class="o">=</span> <span class="k">new</span> <span class="n">LoginContext</span><span class="o">(</span><span class="s">"karaf"</span><span class="o">,</span> <span class="n">handler</span><span class="o">);</span>
<span class="n">ctx</span><span class="o">.</span><span class="na">login</span><span class="o">();</span>
<span class="n">authenticated</span> <span class="o">=</span> <span class="kc">true</span><span class="o">;</span>
<span class="n">subject</span> <span class="o">=</span> <span class="n">ctx</span><span class="o">.</span><span class="na">getSubject</span><span class="o">();</span>
<span class="k">for</span> <span class="o">(</span><span class="n">Principal</span> <span class="n">p</span> <span class="o">:</span> <span class="n">subject</span><span class="o">.</span><span class="na">getPrincipals</span><span class="o">())</span> <span class="o">{</span>
 <span class="k">if</span> <span class="o">(</spa
n><span class="n">p</span><span class="o">.</span><span class="na">getName</span><span class="o">().</span><span class="na">startsWith</span><span class="o">(</span><span class="s">"ROLE_"</span><span class="o">))</span> <span class="o">{</span>
 <span class="n">roles</span><span class="o">.</span><span class="na">add</span><span class="o">((</span><span class="n">p</span><span class="o">.</span><span class="na">getName</span><span class="o">().</span><span class="na">substring</span><span class="o">(</span><span class="s">"ROLE_"</span><span class="o">.</span><span class="na">length</span><span class="o">())));</span>
 <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div><p><u>Grouped Roles</u><br/>When the group role policy is used the login module provides all roles as members of a group with a configurable name <em>(property role.discriminator)</em>. Example:</p><div class="syntax"><div class="highl
ight"><pre><span class="nt"><jaas:config</span> <span class="na">name=</span><span class="s">"karaf"</span><span class="nt">></span>
 <span class="nt"><jaas:module</span> <span class="na">className=</span><span class="s">"org.apache.karaf.jaas.modules.properties.PropertiesLoginModule"</span> 
 <span class="na">flags=</span><span class="s">"required"</span><span class="nt">></span>
 users = $[karaf.base]/etc/users.properties
 role.policy = group
 role.discriminator = ROLES
 <span class="nt"></jaas:module></span>
<span class="nt"></jaas:config></span>
</pre></div>
</div><div class="syntax"><div class="highlight"><pre><span class="n">LoginContext</span> <span class="n">ctx</span> <span class="o">=</span> <span class="k">new</span> <span class="n">LoginContext</span><span class="o">(</span><span class="s">"karaf"</span>
<span class="o">,</span> <span class="n">handler</span><span class="o">);</span>
<span class="n">ctx</span><span class="o">.</span><span class="na">login</span><span class="o">();</span>
<span class="n">authenticated</span> <span class="o">=</span> <span class="kc">true</span><span class="o">;</span>
<span class="n">subject</span> <span class="o">=</span> <span class="n">ctx</span><span class="o">.</span><span class="na">getSubject</span><span class="o">();</span>
<span class="k">for</span> <span class="o">(</span><span class="n">Principal</span> <span class="n">p</span> <span class="o">:</span> <span class="n">subject</span><span class="o">.</span><span class="na">getPrincipals</span><span class="o">())</span> <span class="o">{</span>
 <span class="k">if</span> <span class="o">((</span><span class="n">p</span> <span class="k">instanceof</span> <span class="n">Group</span><span class="o">)</span> <span class="o">&&</span> <span class="o"
>(</span><span class="s">"ROLES"</span><span class="o">.</span><span class="na">equalsIgnoreCase</span><span class="o">(</span><span class="n">p</span><span class="o">.</span><span class="na">getName</span><span class="o">())))</span> <span class="o">{</span>
 <span class="n">Group</span> <span class="n">g</span> <span class="o">=</span> <span class="o">(</span><span class="n">Group</span><span class="o">)</span> <span class="n">p</span><span class="o">;</span>
 <span class="n">Enumeration</span><span class="o"><?</span> <span class="kd">extends</span> <span class="n">Principal</span><span class="o">></span> <span class="n">members</span> <span class="o">=</span> <span class="n">g</span><span class="o">.</span><span class="na">members</span><span class="o">();</span>
 <span class="k">while</span> <span class="o">(</span><span class="n">members</span><span class="o">.</span><span class="na">hasMoreElements</span><span class="o
">())</span> <span class="o">{</span>
 <span class="n">Principal</span> <span class="n">member</span> <span class="o">=</span> <span class="n">members</span><span class="o">.</span><span class="na">nextElement</span><span class="o">();</span>
 <span class="n">roles</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">member</span><span class="o">.</span><span class="na">getName</span><span class="o">());</span>
 <span class="o">}</span>
 <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div><h2 id="Defaultrolepolicies">Default role policies</h2><p>The previous section describes how to leverage role policies. However, Karaf provides a default role policy, based on the following class names:</p><ul><li>org.apache.karaf.jaas.modules.UserPrincipal</li><li>org.apache.karaf.jaas.modules.RolePrincipal</li><li>org.apache.karaf.jaas.modules.GroupPrincipa
l</li></ul><p>It allows you to directly handling the role class:</p><div class="syntax"><div class="highlight"><pre><span class="n">String</span> <span class="n">rolePrincipalClass</span> <span class="o">=</span> <span class="s">"org.apache.karaf.jaas.modules.RolePrincipal"</span><span class="o">;</span>

<span class="k">for</span> <span class="o">(</span><span class="n">Principal</span> <span class="n">p</span> <span class="o">:</span> <span class="n">subject</span><span class="o">.</span><span class="na">getPrincipals</span><span class="o">())</span> <span class="o">{</span>
 <span class="k">if</span> <span class="o">(</span><span class="n">p</span><span class="o">.</span><span class="na">getClass</span><span class="o">().</span><span class="na">getName</span><span class="o">().</span><span class="na">equals</span><span class="o">(</span><span class="n">rolePrincipalClass</span><span class="o">))</span> <span class="o">{</span>
 <span class="
n">roles</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">p</span><span class="o">.</span><span class="na">getName</span><span class="o">());</span>
 <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
+ </div>
+ </td>
+ </tr>
+ </table>
+ </td>
+ <td id="cell-2-2" colspan="2">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-3-0">
+
+ </td>
+ <td id="cell-3-1">
+
+ </td>
+ <td id="cell-3-2">
+ <div id="footer">
+ <div id="site-footer">
+ © 2008-2011 The Apache Software Foundation
+ <br/>
+ Apache Karaf, Karaf, Apache, the Apache feather logo, and the Apache Karaf project logo are trademarks of The Apache Software Foundation.
+ </div>
+ </div>
+ </td>
+ <td id="cell-3-3">
+
+ </td>
+ <td id="cell-3-4">
+
+ </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-4-0" colspan="2">
+
+ </td>
+ <td id="cell-4-1">
+
+ </td>
+ <td id="cell-4-2" colspan="2">
+
+ </td>
+ </tr>
+ </table>
+ </body>
+</html>
\ No newline at end of file