Modified: websites/production/activemq/content/shiro.html ============================================================================== --- websites/production/activemq/content/shiro.html (original) +++ websites/production/activemq/content/shiro.html Sat Jun 27 21:23:55 2015 @@ -32,15 +32,6 @@ </style> <![endif]--> - <link href='http://activemq.apache.org/styles/highlighter/styles/shCore.css' rel='stylesheet' type='text/css' /> - <link href='http://activemq.apache.org/styles/highlighter/styles/shThemeEclipse.css' rel='stylesheet' type='text/css' /> - <script src='http://activemq.apache.org/styles/highlighter/scripts/shCore.js' type='text/javascript'></script> - <script src='http://activemq.apache.org/styles/highlighter/scripts/shBrushJava.js' type='text/javascript'></script> - - <script type="text/javascript"> - SyntaxHighlighter.defaults['toolbar'] = false; - SyntaxHighlighter.all(); - </script> <title> Apache ActiveMQ ™ -- Shiro @@ -82,7 +73,7 @@ <tr> <td valign="top" width="100%"> <div class="wiki-content maincontent"><p> </p><p>ActiveMQ 5.10 and later provides a fully customizable security experience using <a shape="rect" class="external-link" href="http://shiro.apache.org">Apache Shiro</a>.</p><p>The ActiveMQ Shiro plugin can secure the ActiveMQ broker, from authenticating transport connections to authorizing behavior with topics and queues and everything in between.</p><h2 id="Shiro-Quickstart">Quickstart</h2><p>The fastest/simplest way to enable the ShiroPlugin is to define it as a Spring bean in the <code>broker</code> <code>plugins</code> section and embed <a shape="rect" class="external-link" href="http://shiro.apache.org/configuration.html">Shiro ini configuration</a>:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans" +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans" xmlns:amq="http://activemq.apache.org/schema/core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" @@ -150,7 +141,7 @@ </beans> ]]></script> </div></div><p>This config assumes you have a simple/small set of static users that access your ActiveMQ broker. We'll cover enabling more advanced user repositories later.</p><h4 id="Shiro-EncryptedPasswords">Encrypted Passwords</h4><p>The above example uses plaintext passwords, which is simple to set up and easy to use for testing, but not really secure. Most production deployments will likely want to use encrypted passwords. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<bean id="shiroPlugin" class="org.apache.activemq.shiro.ShiroPlugin" xmlns="http://www.springframework.org/schema/beans"> +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<bean id="shiroPlugin" class="org.apache.activemq.shiro.ShiroPlugin" xmlns="http://www.springframework.org/schema/beans"> <!-- enabled by default. To disable, uncomment: <property name="iniConfig"><value> @@ -170,22 +161,22 @@ </bean> ]]></script> </div></div><p>As you can see, two things are different than the simpler/default configuration:</p><ol><li>The <code>[main]</code> section configured a <code>PasswordMatcher</code> on the implicit <code>iniRealm</code>. This indicates that all <code>.ini</code>-configured users are expected to have proper hashed/secure passwords.</li><li>The <code>[users]</code> lines now have hash values in the <code>password</code> location instead of plaintext values.</li></ol><p>To get the hashed password text values, you will want to <a shape="rect" class="external-link" href="http://search.maven.org/remotecontent?filepath=org/apache/shiro/tools/shiro-tools-hasher/1.2.2/shiro-tools-hasher-1.2.2-cli.jar" rel="nofollow">Download Shiro's Command Line Hasher</a> from Maven Central. Once downloaded, you can use it to create secure password hashes that you can safely copy-and-paste in to the <code>[users]</code> section:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeConten t panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[$ java -jar shiro-tools-hasher-X.X.X-cli.jar -p +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[$ java -jar shiro-tools-hasher-X.X.X-cli.jar -p ]]></script> </div></div><p>It will then ask you to enter the password and then confirm it:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[Password to hash: +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[Password to hash: Password to hash (confirm): ]]></script> </div></div><p>When this command executes, it will print out the securely-salted-iterated-and-hashed password. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[$shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM= +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[$shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM= ]]></script> </div></div><p>Take this value and place it as the password in the user definition line (followed by any desired roles, such as the <code>advisory</code> role). For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[[users] +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[[users] scott = $shiro1$SHA-256$500000$eWpVX2tGX7WCP2J+jMCNqw==$it/NRclMOHrfOvhAEFZ0mxIZRdbcfqIBdwdwdDXW2dM=, advisory system = $shiro1$SHA-256$500000$eUyGwMGr9GYzB/gg/MoNgw==$WGc0yWFWv8+hLqjzVLgW7Hat2FQTywDXBl5izpqaLSY=, system ]]></script> </div></div><h2 id="Shiro-Configuration">Configuration</h2><p>The ActiveMQ Shiro plugin can be configured in a number of ways. For example, with Java:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[BrokerService brokerService = new BrokerService(); +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[BrokerService brokerService = new BrokerService(); ShiroPlugin shiroPlugin = new ShiroPlugin(); //configure shiroPlugin via getters/setters here @@ -194,7 +185,7 @@ broker.setPlugins(new BrokerPlugin[]{shi //continue configuring the brokerService as necessary ... ]]></script> </div></div><p>Or, if using traditional ActiveMQ xml, as a Spring bean in the <code>broker</code> <code>plugins</code> section. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans" +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans" xmlns:amq="http://activemq.apache.org/schema/core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" @@ -215,13 +206,13 @@ broker.setPlugins(new BrokerPlugin[]{shi </beans> ]]></script> </div></div><p>The remaining configuration examples on this page will be shown as bean XML, but know that the same configuration can be done in Java as standard JavaBeans-compatible getter and setter methods.</p><h3 id="Shiro-Enabling/Disabling">Enabling/Disabling</h3><p>You can enable or disable the ShiroPlugin entirely without having to remove it from your configuration. This is convenient when testing, or when you want to enable or disable it based on a configuration parameter at startup.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<bean id="shiroPlugin" class="org.apache.activemq.shiro.ShiroPlugin" xmlns="http://www.springframework.org/schema/beans"> +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<bean id="shiroPlugin" class="org.apache.activemq.shiro.ShiroPlugin" xmlns="http://www.springframework.org/schema/beans"> <!-- enabled by default. To disable, uncomment: <property name="enabled" value="false"/> --> </bean> ]]></script> </div></div><p>A nice technique is to use Spring's <a shape="rect" class="external-link" href="http://static.springsource.org/spring/docs/3.2.x/javadoc-api/org/springframework/context/support/PropertySourcesPlaceholderConfigurer.html" rel="nofollow">PropertySourcesPlaceholderConfigurer</a> and placeholder tokens (set <code>shiro.enabled = true</code> in one of your placeholder property files):</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<beans ...> +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<beans ...> <bean class="org.springframework.context.support.PropertySourcesPlaceholderConfigurer"> ... @@ -239,7 +230,7 @@ broker.setPlugins(new BrokerPlugin[]{shi </beans> ]]></script> </div></div><p>This allows you to enable or disable the Shiro plugin by simply setting a property in a <code>.properties</code> file without having to change your XML config.</p><h3 id="Shiro-ShiroEnvironment">Shiro Environment</h3><p>The <code>shiroPlugin</code> requires a Shiro <a shape="rect" class="external-link" href="http://shiro.apache.org/static/current/apidocs/org/apache/shiro/env/Environment.html">Environment</a> to function. You must either configure the plugin with:</p><ul><li>an <code>Environment</code> instance (or a Shiro <code>SecurityManager</code> instance) that you instantiate and configure elsewhere - e.g. in Java code or elsewhere in the Spring XML config, or</li><li>specify some Shiro <a shape="rect" class="external-link" href="http://shiro.apache.org/configuration.html">.ini configuration</a>, either as a direct String, an <a shape="rect" class="external-link" href="http://shiro.apache.org/static/current/apidocs/org/apache/shiro/config/Ini.html">Ini</a> instan ce, or a <a shape="rect" class="external-link" href="http://shiro.apache.org/static/current/apidocs/org/apache/shiro/io/ResourceUtils.html#getInputStreamForPath(java.lang.String)">resource path</a> where your <code>shiro.ini</code> file is located. The plugin will load the ini config and create an <code>Environment</code> automatically.</li></ul><h4 id="Shiro-CustomEnvironment">Custom Environment</h4><p>A Shiro <code>Environment</code> object contains everything that Shiro needs to operate, and this encapsulates the Shiro <code>SecurityManager</code> as well. If you want to construct and configure an Environment instance yourself:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<beans ...> +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<beans ...> <broker ...> <plugins> @@ -258,7 +249,7 @@ broker.setPlugins(new BrokerPlugin[]{shi </beans> ]]></script> </div></div><h4 id="Shiro-CustomSecurityManager">Custom SecurityManager</h4><p>Instead of configuring an <code>Environment</code> instance, you can construct a <code>SecurityManager</code> instead:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<beans ...> +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<beans ...> <broker ...> <plugins> @@ -284,7 +275,7 @@ broker.setPlugins(new BrokerPlugin[]{shi </beans> ]]></script> </div></div><p>If specifying a <code>SecurityManager</code> instead of the <code>Environment</code> property, an <code>Environment</code> will be created automatically that wraps the configured <code>SecurityManager</code>.</p><h4 id="Shiro-shiro.iniFile">shiro.ini File</h4><p>If you don't want to construct a <code>SecurityManager</code> or <code>Environment</code> in code or xml, you can easily specify a <a shape="rect" class="external-link" href="http://shiro.apache.org/configuration.html">shiro.ini</a> file instead and an Environment/SecurityManager will automatically be created based on that:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<beans ...> +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<beans ...> <broker ...> <plugins> @@ -297,7 +288,7 @@ broker.setPlugins(new BrokerPlugin[]{shi </beans> ]]></script> </div></div><p>This allows you to keep your Shiro config separate from your ActiveMQ broker configuration if you prefer.</p><h4 id="Shiro-shiro.iniEmbedded">shiro.ini Embedded</h4><p>If you want to use ini configuration and you would prefer to have all configuration in one place, you can embed the ini config instead:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<beans ...> +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<beans ...> <broker ...> <plugins ...> @@ -323,14 +314,14 @@ broker.setPlugins(new BrokerPlugin[]{shi </beans> ]]></script> </div></div><h2 id="Shiro-Design">Design</h2><p>The Shiro plugin is a <a shape="rect" class="external-link" href="http://activemq.apache.org/maven/apidocs/org/apache/activemq/broker/BrokerPlugin.html">BrokerPlugin</a> that inserts 3 <a shape="rect" class="external-link" href="http://activemq.apache.org/maven/apidocs/org/apache/activemq/broker/BrokerFilter.html">BrokerFilter</a>s in the broker filter chain: the <code>SubjectFilter</code>, the <code>AuthenticationFilter</code> and the <code>AuthorizationFilter</code></p><p><strong>SubjectFilter</strong></p><p>The <code>SubjectFilter</code> exists before all other Shiro-related broker filters in the broker filter chain. It constructs a Shiro <a shape="rect" class="external-link" href="http://shiro.apache.org/subject.html">Subject</a> instance reflecting the broker client and ensures the <code>Subject</code> instance is available for all downstream broker filters that may need to use the <code>Subject</code> to perform security operatio ns.</p><p><strong>AuthenticationFilter</strong></p><p>The <code>AuthenticationFilter</code> exists immediately after the <code>SubjectFilter</code> in the broker filter chain. It ensures that the broker client <code>Subject</code> is authenticated if necessary before allowing the chain to continue. If authentication is required and the <code>Subject</code> is not authenticated, the broker filter chain will not be executed, ensuring only verified identities may perform further behavior.</p><p><strong>AuthorizationFilter</strong></p><p>The <code>AuthorizationFilter</code> exists immediately after the <code>AuthenticationFilter</code> in the broker filter chain. It ensures that the <code>Subject</code> associated with the filter chain is authorized (permitted) to perform the action being attempted before allowing the action to execute.</p><p>For example, it would ensure that the <code>Subject</code> is allowed to send a message to a particular topic before allowing the send operation t o execute. If authorization is enabled and the <code>Subject</code> is not authorized to perform the desired action, the broker filter chain will not be executed.</p><h2 id="Shiro-SubjectFilter">SubjectFilter</h2><p>The ShiroPlugin installs and executes the <code>SubjectFilter</code> before all other Shiro-related broker filters in the broker filter chain. The <code>SubjectFilter</code> constructs a Shiro <a shape="rect" class="external-link" href="http://shiro.apache.org/subject.html">Subject</a> instance reflecting the broker client and ensures the <code>Subject</code> instance is available for all downstream broker filters that may need to use the <code>Subject</code> to perform security operations.</p><p>The <code>SubjectFilter</code> is mostly a 'behind the scenes' component of the SubjectFilter, but it does offer some customization for advanced use cases:</p><ul><li>the ability to customize exactly how broker clients' <code>Subject</code> instances are created via a <code>Conn ectionSubjectFactory</code> and</li><li>the ability to customize how the ActiveMQ ConnectionContext's <a shape="rect" class="external-link" href="http://activemq.apache.org/maven/apidocs/org/apache/activemq/security/SecurityContext.html">SecurityContext</a> is constructed.</li></ul><p>Unless you're deeply familiar with ActiveMQ's security model, you can safely skip to <strong>Authentication</strong> below.</p><h3 id="Shiro-ConnectionSubjectFactory">ConnectionSubjectFactory</h3><p>A <code>ConnectionSubjectFactory</code> creates a <code>Subject</code> instance that represents the broker client's identity. The <code>SubjectFilter</code>'s default instance is a <code>DefaultConnectionSubjectFactory</code></p><p>Most <code>ConnectionSubjectFactory</code> implementations will simply use Shiro's <code>Subject.Builder</code> to create an anonymous Subject instance and let the downstream <code>AuthenticationFilter</code> authenticate the Subject based on any credentials associated with the c onnection. After authentication, the Subject will have an identity, and this is the expected flow for most connection clients.</p><p>However, if there is some other data associated with the connection that can be inspected to create a Subject instance beyond what the <code>DefaultConnectionSubjectFactory</code>, you can implement the <code>ConnectionSubjectFactory</code> interface and plug it in to the <code>SubjectFilter</code>:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<bean id="shiroPlugin" class="org.apache.activemq.shiro.ShiroPlugin" xmlns="http://www.springframework.org/schema/beans"> +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<bean id="shiroPlugin" class="org.apache.activemq.shiro.ShiroPlugin" xmlns="http://www.springframework.org/schema/beans"> <property name="subjectFilter.connectionSubjectFactory"> <bean class="com.my.ConnectionSubjectFactory" .../> </property> </bean> ]]></script> </div></div><h3 id="Shiro-SecurityContextFactory">SecurityContextFactory</h3><p>The ActiveMQ <code>ConnectionContext</code> associated with broker client connections utilizes a <code>SecurityContext</code> object. When the <code>SubjectFilter</code> executes, it needs to create a Shiro-specific <code>SecurityContext</code> and associate it with the <code>ConnectionContext</code> so the Subject may be accessed downstream for all subsequent security operations.</p><p>The <code>SubjectFilter</code> delegates <code>SecurityContext</code> creation to a <code>SecurityContextFactory</code> instance. The <code>DefaultSecurityContextFactory</code> implementation returns <code>SubjectSecurityContext</code> instances based on the connection's associated <code>Subject</code>. It should be an extremely rare thing to change, but if you must configure a custom <code>SecurityContextFactory</code>, you can do as follows:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeConte nt panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[<bean id="shiroPlugin" class="org.apache.activemq.shiro.ShiroPlugin" xmlns="http://www.springframework.org/schema/beans"> +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<bean id="shiroPlugin" class="org.apache.activemq.shiro.ShiroPlugin" xmlns="http://www.springframework.org/schema/beans"> <property name="subjectFilter.securityContextFactory"> <bean class="com.my.SecurityContextFactory" .../> </property>
Modified: websites/production/activemq/content/should-i-use-xa.html ============================================================================== --- websites/production/activemq/content/should-i-use-xa.html (original) +++ websites/production/activemq/content/should-i-use-xa.html Sat Jun 27 21:23:55 2015 @@ -32,15 +32,6 @@ </style> <![endif]--> - <link href='http://activemq.apache.org/styles/highlighter/styles/shCore.css' rel='stylesheet' type='text/css' /> - <link href='http://activemq.apache.org/styles/highlighter/styles/shThemeEclipse.css' rel='stylesheet' type='text/css' /> - <script src='http://activemq.apache.org/styles/highlighter/scripts/shCore.js' type='text/javascript'></script> - <script src='http://activemq.apache.org/styles/highlighter/scripts/shBrushJava.js' type='text/javascript'></script> - - <script type="text/javascript"> - SyntaxHighlighter.defaults['toolbar'] = false; - SyntaxHighlighter.all(); - </script> <title> Apache ActiveMQ ™ -- Should I use XA @@ -87,17 +78,10 @@ <p>If you are using more than one resource; e.g. reading a JMS message and writing to a database, you really should use XA - its purpose is to provide atomic transactions for multiple transactional resources. For example there is a small window from when you complete updating the database and your changes are committed up to the point at which you commit/acknowledge the message; if there is a network/hardware/process failure inside that window, the message will be redelivered and you may end up processing duplicates.</p> -<p>The problem with XA is it can be a bit slow; as the XA protocol requires multiple syncs to disk to ensure it can always recover properly under every possible failure scenario. This adds significant cost (in terms of latency, performance, resources and complexity). Also quite a few EJB servers and databases don't actually properly support XA! <img class="emoticon emoticon-smile" src="https://cwiki.apache.org/confluence/s/en_GB-1988229788/4109/76e0dbb30bc8580e459c201f3535d84f9283a9ac.1/_/images/icons/emoticons/smile.png" data-emoticon-name="smile" alt="(smile)"></p> +<p>The problem with XA is it can be a bit slow; as the XA protocol requires multiple syncs to disk to ensure it can always recover properly under every possible failure scenario. This adds significant cost (in terms of latency, performance, resources and complexity). Also quite a few EJB servers and databases don't actually properly support XA! <img class="emoticon emoticon-smile" src="https://cwiki.apache.org/confluence/s/en_GB/5982/f2b47fb3d636c8bc9fd0b11c0ec6d0ae18646be7.1/_/images/icons/emoticons/smile.png" data-emoticon-name="smile" alt="(smile)"></p> - <div class="aui-message hint shadowed information-macro"> - <p class="title">Be Careful</p> - <span class="aui-icon icon-hint">Icon</span> - <div class="message-content"> - -<p>ActiveMQ does not currently support XA Transaction suspend / resume semantics. </p> - </div> - </div> - +<div class="confluence-information-macro confluence-information-macro-information"><p class="title">Be Careful</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"> +<p>ActiveMQ does not currently support XA Transaction suspend / resume semantics. </p></div></div> <h3 id="ShouldIuseXA-AnalternativetoXA">An alternative to XA</h3> @@ -107,7 +91,7 @@ <p>Or in pseudocode you could use something like the following...</p> <div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> -<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ +<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ onMessage try { if I have not processed this message successfully before {