Added: websites/production/activemq/content/artemis/docs/1.5.4/security.html ============================================================================== --- websites/production/activemq/content/artemis/docs/1.5.4/security.html (added) +++ websites/production/activemq/content/artemis/docs/1.5.4/security.html Sun Mar 12 16:08:18 2017 @@ -0,0 +1,1684 @@ + +<!DOCTYPE HTML> +<html lang="" > + <head> + <title>Security · ActiveMQ Artemis Documentation</title> + <meta charset="UTF-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge" /> + <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> + <meta name="description" content=""> + <meta name="generator" content="GitBook 3.1.1"> + + + + + <link rel="stylesheet" href="gitbook/style.css"> + + + + + <link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css"> + + + + <link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css"> + + + + <link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css"> + + + + + + + + + + + + + + + + + + + + + + + + <meta name="HandheldFriendly" content="true"/> + <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no"> + <meta name="apple-mobile-web-app-capable" content="yes"> + <meta name="apple-mobile-web-app-status-bar-style" content="black"> + <link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png"> + <link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon"> + + + <link rel="next" href="resource-limits.html" /> + + + <link rel="prev" href="management.html" /> + + + </head> + <body> + +<div class="book"> + <div class="book-summary"> + + +<div id="book-search-input" role="search"> + <input type="text" placeholder="Type to search" /> +</div> + + + <nav role="navigation"> + + + +<ul class="summary"> + + + + + + + + + + <li class="chapter " data-level="1.1" data-path="./"> + + <a href="./"> + + + Introduction + + </a> + + + + </li> + + <li class="chapter " data-level="1.2" data-path="notice.html"> + + <a href="notice.html"> + + + Legal Notice + + </a> + + + + </li> + + <li class="chapter " data-level="1.3" data-path="preface.html"> + + <a href="preface.html"> + + + Preface + + </a> + + + + </li> + + <li class="chapter " data-level="1.4" data-path="project-info.html"> + + <a href="project-info.html"> + + + Project Info + + </a> + + + + </li> + + <li class="chapter " data-level="1.5" data-path="messaging-concepts.html"> + + <a href="messaging-concepts.html"> + + + Messaging Concepts + + </a> + + + + </li> + + <li class="chapter " data-level="1.6" data-path="architecture.html"> + + <a href="architecture.html"> + + + Architecture + + </a> + + + + </li> + + <li class="chapter " data-level="1.7" data-path="using-server.html"> + + <a href="using-server.html"> + + + Using the Server + + </a> + + + + </li> + + <li class="chapter " data-level="1.8" data-path="using-jms.html"> + + <a href="using-jms.html"> + + + Using JMS + + </a> + + + + </li> + + <li class="chapter " data-level="1.9" data-path="using-core.html"> + + <a href="using-core.html"> + + + Using Core + + </a> + + + + </li> + + <li class="chapter " data-level="1.10" data-path="jms-core-mapping.html"> + + <a href="jms-core-mapping.html"> + + + Mapping JMS Concepts to the Core API + + </a> + + + + </li> + + <li class="chapter " data-level="1.11" data-path="client-classpath.html"> + + <a href="client-classpath.html"> + + + The Client Classpath + + </a> + + + + </li> + + <li class="chapter " data-level="1.12" data-path="examples.html"> + + <a href="examples.html"> + + + Examples + + </a> + + + + </li> + + <li class="chapter " data-level="1.13" data-path="wildcard-routing.html"> + + <a href="wildcard-routing.html"> + + + Routing Messages With Wild Cards + + </a> + + + + </li> + + <li class="chapter " data-level="1.14" data-path="wildcard-syntax.html"> + + <a href="wildcard-syntax.html"> + + + Understanding the Apache ActiveMQ Artemis Wildcard Syntax + + </a> + + + + </li> + + <li class="chapter " data-level="1.15" data-path="filter-expressions.html"> + + <a href="filter-expressions.html"> + + + Filter Expressions + + </a> + + + + </li> + + <li class="chapter " data-level="1.16" data-path="persistence.html"> + + <a href="persistence.html"> + + + Persistence + + </a> + + + + </li> + + <li class="chapter " data-level="1.17" data-path="configuring-transports.html"> + + <a href="configuring-transports.html"> + + + Configuring Transports + + </a> + + + + </li> + + <li class="chapter " data-level="1.18" data-path="config-reload.html"> + + <a href="config-reload.html"> + + + Configuration Reload + + </a> + + + + </li> + + <li class="chapter " data-level="1.19" data-path="connection-ttl.html"> + + <a href="connection-ttl.html"> + + + Detecting Dead Connections + + </a> + + + + </li> + + <li class="chapter " data-level="1.20" data-path="slow-consumers.html"> + + <a href="slow-consumers.html"> + + + Detecting Slow Consumers + + </a> + + + + </li> + + <li class="chapter " data-level="1.21" data-path="transaction-config.html"> + + <a href="transaction-config.html"> + + + Resource Manager Configuration + + </a> + + + + </li> + + <li class="chapter " data-level="1.22" data-path="flow-control.html"> + + <a href="flow-control.html"> + + + Flow Control + + </a> + + + + </li> + + <li class="chapter " data-level="1.23" data-path="send-guarantees.html"> + + <a href="send-guarantees.html"> + + + Guarantees of sends and commits + + </a> + + + + </li> + + <li class="chapter " data-level="1.24" data-path="undelivered-messages.html"> + + <a href="undelivered-messages.html"> + + + Message Redelivery and Undelivered Messages + + </a> + + + + </li> + + <li class="chapter " data-level="1.25" data-path="message-expiry.html"> + + <a href="message-expiry.html"> + + + Message Expiry + + </a> + + + + </li> + + <li class="chapter " data-level="1.26" data-path="large-messages.html"> + + <a href="large-messages.html"> + + + Large Messages + + </a> + + + + </li> + + <li class="chapter " data-level="1.27" data-path="paging.html"> + + <a href="paging.html"> + + + Paging + + </a> + + + + </li> + + <li class="chapter " data-level="1.28" data-path="queue-attributes.html"> + + <a href="queue-attributes.html"> + + + Queue Attributes + + </a> + + + + </li> + + <li class="chapter " data-level="1.29" data-path="scheduled-messages.html"> + + <a href="scheduled-messages.html"> + + + Scheduled Messages + + </a> + + + + </li> + + <li class="chapter " data-level="1.30" data-path="last-value-queues.html"> + + <a href="last-value-queues.html"> + + + Last-Value Queues + + </a> + + + + </li> + + <li class="chapter " data-level="1.31" data-path="message-grouping.html"> + + <a href="message-grouping.html"> + + + Message Grouping + + </a> + + + + </li> + + <li class="chapter " data-level="1.32" data-path="pre-acknowledge.html"> + + <a href="pre-acknowledge.html"> + + + Extra Acknowledge Modes + + </a> + + + + </li> + + <li class="chapter " data-level="1.33" data-path="management.html"> + + <a href="management.html"> + + + Management + + </a> + + + + </li> + + <li class="chapter active" data-level="1.34" data-path="security.html"> + + <a href="security.html"> + + + Security + + </a> + + + + </li> + + <li class="chapter " data-level="1.35" data-path="resource-limits.html"> + + <a href="resource-limits.html"> + + + Resource Limits + + </a> + + + + </li> + + <li class="chapter " data-level="1.36" data-path="jms-bridge.html"> + + <a href="jms-bridge.html"> + + + The JMS Bridge + + </a> + + + + </li> + + <li class="chapter " data-level="1.37" data-path="client-reconnection.html"> + + <a href="client-reconnection.html"> + + + Client Reconnection and Session Reattachment + + </a> + + + + </li> + + <li class="chapter " data-level="1.38" data-path="diverts.html"> + + <a href="diverts.html"> + + + Diverting and Splitting Message Flows + + </a> + + + + </li> + + <li class="chapter " data-level="1.39" data-path="core-bridges.html"> + + <a href="core-bridges.html"> + + + Core Bridges + + </a> + + + + </li> + + <li class="chapter " data-level="1.40" data-path="duplicate-detection.html"> + + <a href="duplicate-detection.html"> + + + Duplicate Message Detection + + </a> + + + + </li> + + <li class="chapter " data-level="1.41" data-path="clusters.html"> + + <a href="clusters.html"> + + + Clusters + + </a> + + + + </li> + + <li class="chapter " data-level="1.42" data-path="ha.html"> + + <a href="ha.html"> + + + High Availability and Failover + + </a> + + + + </li> + + <li class="chapter " data-level="1.43" data-path="graceful-shutdown.html"> + + <a href="graceful-shutdown.html"> + + + Graceful Server Shutdown + + </a> + + + + </li> + + <li class="chapter " data-level="1.44" data-path="libaio.html"> + + <a href="libaio.html"> + + + Libaio Native Libraries + + </a> + + + + </li> + + <li class="chapter " data-level="1.45" data-path="thread-pooling.html"> + + <a href="thread-pooling.html"> + + + Thread management + + </a> + + + + </li> + + <li class="chapter " data-level="1.46" data-path="logging.html"> + + <a href="logging.html"> + + + Logging + + </a> + + + + </li> + + <li class="chapter " data-level="1.47" data-path="rest.html"> + + <a href="rest.html"> + + + REST Interface + + </a> + + + + </li> + + <li class="chapter " data-level="1.48" data-path="embedding-activemq.html"> + + <a href="embedding-activemq.html"> + + + Embedding Apache ActiveMQ Artemis + + </a> + + + + </li> + + <li class="chapter " data-level="1.49" data-path="karaf.html"> + + <a href="karaf.html"> + + + Apache Karaf + + </a> + + + + </li> + + <li class="chapter " data-level="1.50" data-path="spring-integration.html"> + + <a href="spring-integration.html"> + + + Spring Integration + + </a> + + + + </li> + + <li class="chapter " data-level="1.51" data-path="aerogear-integration.html"> + + <a href="aerogear-integration.html"> + + + AeroGear Integration + + </a> + + + + </li> + + <li class="chapter " data-level="1.52" data-path="vertx-integration.html"> + + <a href="vertx-integration.html"> + + + VertX Integration + + </a> + + + + </li> + + <li class="chapter " data-level="1.53" data-path="cdi-integration.html"> + + <a href="cdi-integration.html"> + + + CDI Integration + + </a> + + + + </li> + + <li class="chapter " data-level="1.54" data-path="intercepting-operations.html"> + + <a href="intercepting-operations.html"> + + + Intercepting Operations + + </a> + + + + </li> + + <li class="chapter " data-level="1.55" data-path="protocols-interoperability.html"> + + <a href="protocols-interoperability.html"> + + + Protocols and Interoperability + + </a> + + + + </li> + + <li class="chapter " data-level="1.56" data-path="tools.html"> + + <a href="tools.html"> + + + Tools + + </a> + + + + </li> + + <li class="chapter " data-level="1.57" data-path="maven-plugin.html"> + + <a href="maven-plugin.html"> + + + Maven Plugin + + </a> + + + + </li> + + <li class="chapter " data-level="1.58" data-path="unit-testing.html"> + + <a href="unit-testing.html"> + + + Unit Testing + + </a> + + + + </li> + + <li class="chapter " data-level="1.59" data-path="perf-tuning.html"> + + <a href="perf-tuning.html"> + + + Troubleshooting and Performance Tuning + + </a> + + + + </li> + + <li class="chapter " data-level="1.60" data-path="configuration-index.html"> + + <a href="configuration-index.html"> + + + Configuration Reference + + </a> + + + + </li> + + + + + <li class="divider"></li> + + <li> + <a href="https://www.gitbook.com"; target="blank" class="gitbook-link"> + Published with GitBook + </a> + </li> +</ul> + + + </nav> + + + </div> + + <div class="book-body"> + + <div class="body-inner"> + + + +<div class="book-header" role="navigation"> + + + <!-- Title --> + <h1> + <i class="fa fa-circle-o-notch fa-spin"></i> + <a href="." >Security</a> + </h1> +</div> + + + + + <div class="page-wrapper" tabindex="-1" role="main"> + <div class="page-inner"> + +<div id="book-search-results"> + <div class="search-noresults"> + + <section class="normal markdown-section"> + + <h1 id="security">Security</h1> +<p>This chapter describes how security works with Apache ActiveMQ Artemis and how you can +configure it. To disable security completely simply set the +<code>security-enabled</code> property to false in the <code>broker.xml</code> +file.</p> +<p>For performance reasons security is cached and invalidated every so +long. To change this period set the property +<code>security-invalidation-interval</code>, which is in milliseconds. The default +is <code>10000</code> ms.</p> +<p>To assist in security auditing the <code>populate-validated-user</code> option exists. If this is <code>true</code> then +the server will add the name of the validated user to the message using the key <code>_AMQ_VALIDATED_USER</code>. +For JMS and Stomp clients this is mapped to the key <code>JMSXUserID</code>. For users authenticated based on +their SSL certificate this name is the name to which their certificate's DN maps. If <code>security-enabled</code> +is <code>false</code> and <code>populate-validated-user</code> is <code>true</code> then the server will simply use whatever user name +(if any) the client provides. This option is <code>false</code> by default.</p> +<h2 id="role-based-security-for-addresses">Role based security for addresses</h2> +<p>Apache ActiveMQ Artemis contains a flexible role-based security model for applying +security to queues, based on their addresses.</p> +<p>As explained in <a href="using-core.html">Using Core</a>, Apache ActiveMQ Artemis core consists mainly of sets of queues bound +to addresses. A message is sent to an address and the server looks up +the set of queues that are bound to that address, the server then routes +the message to those set of queues.</p> +<p>Apache ActiveMQ Artemis allows sets of permissions to be defined against the queues +based on their address. An exact match on the address can be used or a +wildcard match can be used using the wildcard characters '<code>#</code>' and +'<code>*</code>'.</p> +<p>Seven different permissions can be given to the set of queues which +match the address. Those permissions are:</p> +<ul> +<li><p><code>createDurableQueue</code>. This permission allows the user to create a +durable queue under matching addresses.</p> +</li> +<li><p><code>deleteDurableQueue</code>. This permission allows the user to delete a +durable queue under matching addresses.</p> +</li> +<li><p><code>createNonDurableQueue</code>. This permission allows the user to create a +non-durable queue under matching addresses.</p> +</li> +<li><p><code>deleteNonDurableQueue</code>. This permission allows the user to delete a +non-durable queue under matching addresses.</p> +</li> +<li><p><code>send</code>. This permission allows the user to send a message to +matching addresses.</p> +</li> +<li><p><code>consume</code>. This permission allows the user to consume a message from +a queue bound to matching addresses.</p> +</li> +<li><p><code>browse</code>. This permission allows the user to browse a queue bound to +the matching address.</p> +</li> +<li><p><code>manage</code>. This permission allows the user to invoke management +operations by sending management messages to the management address.</p> +</li> +</ul> +<p>For each permission, a list of roles who are granted that permission is +specified. If the user has any of those roles, he/she will be granted +that permission for that set of addresses.</p> +<p>Let's take a simple example, here's a security block from +<code>broker.xml</code> file:</p> +<pre><code><security-setting match="globalqueues.europe.#"> + <permission type="createDurableQueue" roles="admin"/> + <permission type="deleteDurableQueue" roles="admin"/> + <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/> + <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/> + <permission type="send" roles="admin, europe-users"/> + <permission type="consume" roles="admin, europe-users"/> +</security-setting> +</code></pre><p>The '<code>#</code>' character signifies "any sequence of words". Words are +delimited by the '<code>.</code>' character. For a full description of the wildcard +syntax please see <a href="wildcard-syntax.html">Understanding the Wildcard Syntax</a>. +The above security block applies to any address +that starts with the string "globalqueues.europe.":</p> +<p>Only users who have the <code>admin</code> role can create or delete durable queues +bound to an address that starts with the string "globalqueues.europe."</p> +<p>Any users with the roles <code>admin</code>, <code>guest</code>, or <code>europe-users</code> can create +or delete temporary queues bound to an address that starts with the +string "globalqueues.europe."</p> +<p>Any users with the roles <code>admin</code> or <code>europe-users</code> can send messages to +these addresses or consume messages from queues bound to an address that +starts with the string "globalqueues.europe."</p> +<p>The mapping between a user and what roles they have is handled by the +security manager. Apache ActiveMQ Artemis ships with a user manager that reads user +credentials from a file on disk, and can also plug into JAAS or JBoss +Application Server security.</p> +<p>For more information on configuring the security manager, please see 'Changing the Security Manager'.</p> +<p>There can be zero or more <code>security-setting</code> elements in each xml file. +Where more than one match applies to a set of addresses the <em>more +specific</em> match takes precedence.</p> +<p>Let's look at an example of that, here's another <code>security-setting</code> +block:</p> +<pre><code><security-setting match="globalqueues.europe.orders.#"> + <permission type="send" roles="europe-users"/> + <permission type="consume" roles="europe-users"/> +</security-setting> +</code></pre><p>In this <code>security-setting</code> block the match +'globalqueues.europe.orders.#' is more specific than the previous match +'globalqueues.europe.#'. So any addresses which match +'globalqueues.europe.orders.#' will take their security settings <em>only</em> +from the latter security-setting block.</p> +<p>Note that settings are not inherited from the former block. All the +settings will be taken from the more specific matching block, so for the +address 'globalqueues.europe.orders.plastics' the only permissions that +exist are <code>send</code> and <code>consume</code> for the role europe-users. The +permissions <code>createDurableQueue</code>, <code>deleteDurableQueue</code>, +<code>createNonDurableQueue</code>, <code>deleteNonDurableQueue</code> are not inherited from +the other security-setting block.</p> +<p>By not inheriting permissions, it allows you to effectively deny +permissions in more specific security-setting blocks by simply not +specifying them. Otherwise it would not be possible to deny permissions +in sub-groups of addresses.</p> +<h2 id="security-setting-plugin">Security Setting Plugin</h2> +<p>Aside from configuring sets of permissions via XML these permissions can alternatively be +configured via a plugin which implements <code>org.apache.activemq.artemis.core.server.SecuritySettingPlugin</code> e.g.:</p> +<pre><code><security-settings> + <security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin"> + <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/> + <setting name="connectionURL" value="ldap://localhost:1024"/> + <setting name="connectionUsername" value="uid=admin,ou=system"/> + <setting name="connectionPassword" value="secret"/> + <setting name="connectionProtocol" value="s"/> + <setting name="authentication" value="simple"/> + </security-setting-plugin> +</security-settings> +</code></pre><p>Most of this configuration is specific to the plugin implementation. However, there are two configuration details that +will be specified for every implementation:</p> +<ul> +<li><p><code>class-name</code>. This attribute of <code>security-setting-plugin</code> indicates the name of the class which implements +<code>org.apache.activemq.artemis.core.server.SecuritySettingPlugin</code>.</p> +</li> +<li><p><code>setting</code>. Each of these elements represents a name/value pair that will be passed to the implementation for configuration +purposes.</p> +</li> +</ul> +<p>See the JavaDoc on <code>org.apache.activemq.artemis.core.server.SecuritySettingPlugin</code> for further details about the interface +and what each method is expected to do.</p> +<h3 id="available-plugins">Available plugins</h3> +<h4 id="legacyldapsecuritysettingplugin">LegacyLDAPSecuritySettingPlugin</h4> +<p>This plugin will read the security information that was previously handled by <a href="http://activemq.apache.org/security.html"; target="_blank"><code>LDAPAuthorizationMap</code></a> +and the <a href="http://activemq.apache.org/cached-ldap-authorization-module.html"; target="_blank"><code>cachedLDAPAuthorizationMap</code></a> in Apache ActiveMQ 5.x +and turn it into Artemis security settings where possible. The security implementations of ActiveMQ 5.x and Artemis don't +match perfectly so some translation must occur to achieve near equivalent functionality.</p> +<p>Here is an example of the plugin's configuration:</p> +<pre><code><security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin"> + <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/> + <setting name="connectionURL" value="ldap://localhost:1024"/> + <setting name="connectionUsername" value="uid=admin,ou=system"/> + <setting name="connectionPassword" value="secret"/> + <setting name="connectionProtocol" value="s"/> + <setting name="authentication" value="simple"/> +</security-setting-plugin> +</code></pre><ul> +<li><p><code>class-name</code>. The implementation is <code>org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin</code>.</p> +</li> +<li><p><code>initialContextFactory</code>. The initial context factory used to connect to LDAP. It must always be set to +<code>com.sun.jndi.ldap.LdapCtxFactory</code> (i.e. the default value).</p> +</li> +<li><p><code>connectionURL</code>. Specifies the location of the directory server using an ldap URL, <code>ldap://Host:Port</code>. You can +optionally qualify this URL, by adding a forward slash, <code>/</code>, followed by the DN of a particular node in the directory +tree. For example, <code>ldap://ldapserver:10389/ou=system</code>. The default is <code>ldap://localhost:1024</code>.</p> +</li> +<li><p><code>connectionUsername</code>. The DN of the user that opens the connection to the directory server. For example, <code>uid=admin,ou=system</code>. +Directory servers generally require clients to present username/password credentials in order to open a connection.</p> +</li> +<li><p><code>connectionPassword</code>. The password that matches the DN from <code>connectionUsername</code>. In the directory server, in the +DIT, the password is normally stored as a <code>userPassword</code> attribute in the corresponding directory entry.</p> +</li> +<li><p><code>connectionProtocol</code>. Currently the only supported value is a blank string. In future, this option will allow you to +select the Secure Socket Layer (SSL) for the connection to the directory server. Note: this option must be set +explicitly to an empty string, because it has no default value.</p> +</li> +<li><p><code>authentication</code>. Specifies the authentication method used when binding to the LDAP server. Can take either of the + values, <code>simple</code> (username and password, the default value) or <code>none</code> (anonymous). Note: Simple Authentication and + Security Layer (SASL) authentication is currently not supported.</p> +</li> +<li><p><code>destinationBase</code>. Specifies the DN of the node whose children provide the permissions for all destinations. In this +case the DN is a literal value (that is, no string substitution is performed on the property value). For example, a +typical value of this property is <code>ou=destinations,o=ActiveMQ,ou=system</code> (i.e. the default value).</p> +</li> +<li><p><code>filter</code>. Specifies an LDAP search filter, which is used when looking up the permissions for any kind of destination. +The search filter attempts to match one of the children or descendants of the queue or topic node. The default value +is <code>(cn=*)</code>.</p> +</li> +<li><p><code>roleAttribute</code>. Specifies an attribute of the node matched by <code>filter</code>, whose value is the DN of a role. Default +value is <code>uniqueMember</code>.</p> +</li> +<li><p><code>adminPermissionValue</code>. Specifies a value that matches the <code>admin</code> permission. The default value is <code>admin</code>.</p> +</li> +<li><p><code>readPermissionValue</code>. Specifies a value that matches the <code>read</code> permission. The default value is <code>read</code>.</p> +</li> +<li><p><code>writePermissionValue</code>. Specifies a value that matches the <code>write</code> permission. The default value is <code>write</code>.</p> +</li> +<li><p><code>enableListener</code>. Whether or not to enable a listener that will automatically receive updates made in the LDAP server +and update the broker's authorization configuration in real-time. The default value is <code>true</code>.</p> +</li> +</ul> +<p>The name of the queue or topic defined in LDAP will serve as the "match" for the security-setting, the permission value +will be mapped from the ActiveMQ 5.x type to the Artemis type, and the role will be mapped as-is. It's worth noting that +since the name of queue or topic coming from LDAP will server as the "match" for the security-setting the security-setting +may not be applied as expected to JMS destinations since Artemis always prefixes JMS destinations with "jms.queue." or +"jms.topic." as necessary.</p> +<p>ActiveMQ 5.x only has 3 permission types - <code>read</code>, <code>write</code>, and <code>admin</code>. These permission types are described on their +<a href="http://activemq.apache.org/security.html"; target="_blank">website</a>. However, as described previously, ActiveMQ Artemis has 7 permission +types - <code>createDurableQueue</code>, <code>deleteDurableQueue</code>, <code>createNonDurableQueue</code>, <code>deleteNonDurableQueue</code>, <code>send</code>, <code>consume</code>, +<code>browse</code>, and <code>manage</code>. Here's how the old types are mapped to the new types:</p> +<ul> +<li><code>read</code> - <code>consume</code>, <code>browse</code></li> +<li><code>write</code> - <code>send</code></li> +<li><code>admin</code> - <code>createDurableQueue</code>, <code>deleteDurableQueue</code>, <code>createNonDurableQueue</code>, <code>deleteNonDurableQueue</code></li> +</ul> +<p>As mentioned, there are a few places where a translation was performed to achieve some equivalence.:</p> +<ul> +<li><p>This mapping doesn't include the Artemis <code>manage</code> permission type since there is no type analogous for that in ActiveMQ +5.x.</p> +</li> +<li><p>The <code>admin</code> permission in ActiveMQ 5.x relates to whether or not the broker will auto-create a destination if +it doesn't exist and the user sends a message to it. Artemis automatically allows the automatic creation of a +destination if the user has permission to send message to it. Therefore, the plugin will map the <code>admin</code> permission +to the 4 aforementioned permissions in Artemis.</p> +</li> +</ul> +<h2 id="secure-sockets-layer-ssl-transport">Secure Sockets Layer (SSL) Transport</h2> +<p>When messaging clients are connected to servers, or servers are connected to other servers (e.g. via bridges) over an +untrusted network then Apache ActiveMQ Artemis allows that traffic to be encrypted using the Secure Sockets Layer (SSL) +transport.</p> +<p>For more information on configuring the SSL transport, please see <a href="configuring-transports.html">Configuring the Transport</a>.</p> +<h2 id="user-credentials">User credentials</h2> +<p>Apache ActiveMQ Artemis ships with two security manager implementations:</p> +<ul> +<li><p>The legacy, deprecated <code>ActiveMQSecurityManager</code> that reads user credentials, i.e. user names, passwords and role +information from properties files on the classpath called <code>artemis-users.properties</code> and <code>artemis-roles.properties</code>.</p> +</li> +<li><p>The flexible, pluggable <code>ActiveMQJAASSecurityManager</code> which supports any standard JAAS login module. Artemis ships +with several login modules which will be discussed further down. This is the default security manager.</p> +</li> +</ul> +<h3 id="jaas-security-manager">JAAS Security Manager</h3> +<p>When using JAAS much of the configuration depends on which login module is used. However, there are a few commonalities +for every case. The first place to look is in <code>bootstrap.xml</code>. Here is an example using the <code>PropertiesLogin</code> JAAS login +module which reads user, password, and role information from properties files:</p> +<pre><code><jaas-security domain="PropertiesLogin"/> +</code></pre><p>No matter what login module you're using, you'll need to specify it here in <code>bootstrap.xml</code>. The <code>domain</code> attribute +here refers to the relevant login module entry in <code>login.config</code>. For example:</p> +<pre><code>PropertiesLogin { + org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required + debug=true + org.apache.activemq.jaas.properties.user="artemis-users.properties" + org.apache.activemq.jaas.properties.role="artemis-roles.properties"; +}; +</code></pre><p>The <code>login.config</code> file is a standard JAAS configuration file. You can read more about this file on +<a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/LoginConfigFile.html"; target="_blank">Oracle's website</a>. +In short, the file defines:</p> +<ul> +<li><p>an alias for an entry (e.g. <code>PropertiesLogin</code>)</p> +</li> +<li><p>the implementation class for the login module (e.g. <code>org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule</code>)</p> +</li> +<li><p>a flag which indicates whether the success of the login module is <code>required</code>, <code>requisite</code>, <code>sufficient</code>, or <code>optional</code> +(see more details on these flags in the <a href="http://docs.oracle.com/javase/8/docs/api/javax/security/auth/login/Configuration.html"; target="_blank">JavaDoc</a></p> +</li> +<li><p>a list of configuration options specific to the login module implementation</p> +</li> +</ul> +<p>By default, the location and name of <code>login.config</code> is specified on the Artemis command-line which is set by +<code>etc/artemis.profile</code> on linux and <code>etc\artemis.profile.cmd</code> on Windows.</p> +<h4 id="dual-authentication">Dual Authentication</h4> +<p>The JAAS Security Manager also supports another configuration parameter - <code>certificate-domain</code>. This is useful when you +want to authenticate clients connecting with SSL connections based on their SSL certificates (e.g. using the <code>CertificateLoginModule</code> +discussed below) but you still want to authenticate clients connecting with non-SSL connections with, e.g., username and +password. Here's an example of what would go in <code>bootstrap.xml</code>:</p> +<pre><code><jaas-security domain="PropertiesLogin" certificate-domain="CertLogin"/> +</code></pre><p>And here's the corresponding <code>login.config</code>:</p> +<pre><code>PropertiesLogin { + org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required + debug=false + org.apache.activemq.jaas.properties.user="artemis-users.properties" + org.apache.activemq.jaas.properties.role="artemis-roles.properties"; +}; + +CertLogin { + org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule required + debug=true + org.apache.activemq.jaas.textfiledn.user="cert-users.properties" + org.apache.activemq.jaas.textfiledn.role="cert-roles.properties"; +}; +</code></pre><p>When the broker is configured this way then any client connecting with SSL and a client certificate will be authenticated +using <code>CertLogin</code> and any client connecting without SSL will be authenticated using <code>PropertiesLogin</code>.</p> +<h3 id="jaas-login-modules">JAAS Login Modules</h3> +<h4 id="guestloginmodule">GuestLoginModule</h4> +<p>Allows users without credentials (and, depending on how it is configured, possibly also users with invalid credentials) +to access the broker. Normally, the guest login module is chained with another login module, such as a properties login +module. It is implemented by <code>org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule</code>.</p> +<ul> +<li><p><code>org.apache.activemq.jaas.guest.user</code> - the user name to assign; default is "guest"</p> +</li> +<li><p><code>org.apache.activemq.jaas.guest.role</code> - the role name to assign; default is "guests"</p> +</li> +<li><p><code>credentialsInvalidate</code> - boolean flag; if <code>true</code>, reject login requests that include a password (i.e. guest login +succeeds only when the user does not provide a password); default is <code>false</code></p> +</li> +<li><p><code>debug</code> - boolean flag; if <code>true</code>, enable debugging; this is used only for testing or debugging; normally, it +should be set to <code>false</code>, or omitted; default is <code>false</code></p> +</li> +</ul> +<p>There are two basic use cases for the guest login module, as follows:</p> +<ul> +<li><p>Guests with no credentials or invalid credentials.</p> +</li> +<li><p>Guests with no credentials only.</p> +</li> +</ul> +<p>The following snippet shows how to configure a JAAS login entry for the use case where users with no credentials or +invalid credentials are logged in as guests. In this example, the guest login module is used in combination with the +properties login module.</p> +<pre><code>activemq-domain { + org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient + debug=true + org.apache.activemq.jaas.properties.user="artemis-users.properties" + org.apache.activemq.jaas.properties.role="artemis-roles.properties"; + + org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient + debug=true + org.apache.activemq.jaas.guest.user="anyone" + org.apache.activemq.jaas.guest.role="restricted"; +}; +</code></pre><p>Depending on the user login data, authentication proceeds as follows:</p> +<ul> +<li><p>User logs in with a valid password — the properties login module successfully authenticates the user and returns +immediately. The guest login module is not invoked.</p> +</li> +<li><p>User logs in with an invalid password — the properties login module fails to authenticate the user, and authentication +proceeds to the guest login module. The guest login module successfully authenticates the user and returns the guest principal.</p> +</li> +<li><p>User logs in with a blank password — the properties login module fails to authenticate the user, and authentication +proceeds to the guest login module. The guest login module successfully authenticates the user and returns the guest principal.</p> +</li> +</ul> +<p>The following snipped shows how to configure a JAAS login entry for the use case where only those users with no +credentials are logged in as guests. To support this use case, you must set the credentialsInvalidate option to true in +the configuration of the guest login module. You should also note that, compared with the preceding example, the order +of the login modules is reversed and the flag attached to the properties login module is changed to requisite.</p> +<pre><code>activemq-guest-when-no-creds-only-domain { + org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient + debug=true + credentialsInvalidate=true + org.apache.activemq.jaas.guest.user="guest" + org.apache.activemq.jaas.guest.role="guests"; + + org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule requisite + debug=true + org.apache.activemq.jaas.properties.user="artemis-users.properties" + org.apache.activemq.jaas.properties.role="artemis-roles.properties"; +}; +</code></pre><p>Depending on the user login data, authentication proceeds as follows:</p> +<ul> +<li><p>User logs in with a valid password — the guest login module fails to authenticate the user (because the user has +presented a password while the credentialsInvalidate option is enabled) and authentication proceeds to the properties +login module. The properties login module successfully authenticates the user and returns.</p> +</li> +<li><p>User logs in with an invalid password — the guest login module fails to authenticate the user and authentication proceeds +to the properties login module. The properties login module also fails to authenticate the user. The nett result is +authentication failure.</p> +</li> +<li><p>User logs in with a blank password — the guest login module successfully authenticates the user and returns immediately. +The properties login module is not invoked.</p> +</li> +</ul> +<h4 id="propertiesloginmodule">PropertiesLoginModule</h4> +<p>The JAAS properties login module provides a simple store of authentication data, where the relevant user data is stored +in a pair of flat files. This is convenient for demonstrations and testing, but for an enterprise system, the integration +with LDAP is preferable. It is implemented by <code>org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule</code>.</p> +<ul> +<li><p><code>org.apache.activemq.jaas.properties.user</code> - the path to the file which contains user and password properties</p> +</li> +<li><p><code>org.apache.activemq.jaas.properties.role</code> - the path to the file which contains user and role properties</p> +</li> +<li><p><code>reload</code> - boolean flag; whether or not to reload the properties files when a modification occurs; default is <code>false</code></p> +</li> +<li><p><code>debug</code> - boolean flag; if <code>true</code>, enable debugging; this is used only for testing or debugging; normally, it +should be set to <code>false</code>, or omitted; default is <code>false</code></p> +</li> +</ul> +<p>In the context of the properties login module, the <code>artemis-users.properties</code> file consists of a list of properties of the +form, <code>UserName=Password</code>. For example, to define the users <code>system</code>, <code>user</code>, and <code>guest</code>, you could create a file like +the following:</p> +<pre><code>system=manager +user=password +guest=password +</code></pre><p>The <code>artemis-roles.properties</code> file consists of a list of properties of the form, <code>Role=UserList</code>, where UserList is a +comma-separated list of users. For example, to define the roles <code>admins</code>, <code>users</code>, and <code>guests</code>, you could create a file +like the following:</p> +<pre><code>admins=system +users=system,user +guests=guest +</code></pre><h4 id="ldaploginmodule">LDAPLoginModule</h4> +<p>The LDAP login module enables you to perform authentication and authorization by checking the incoming credentials against +user data stored in a central X.500 directory server. For systems that already have an X.500 directory server in place, +this means that you can rapidly integrate ActiveMQ Artemis with the existing security database and user accounts can be +managed using the X.500 system. It is implemented by <code>org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule</code>.</p> +<ul> +<li><p><code>initialContextFactory</code> - must always be set to <code>com.sun.jndi.ldap.LdapCtxFactory</code></p> +</li> +<li><p><code>connectionURL</code> - specify the location of the directory server using an ldap URL, ldap://Host:Port. You can +optionally qualify this URL, by adding a forward slash, <code>/</code>, followed by the DN of a particular node in the directory +tree. For example, ldap://ldapserver:10389/ou=system.</p> +</li> +<li><p><code>authentication</code> - specifies the authentication method used when binding to the LDAP server. Can take either of +the values, <code>simple</code> (username and password) or <code>none</code> (anonymous).</p> +</li> +<li><p><code>connectionUsername</code> - the DN of the user that opens the connection to the directory server. For example, +<code>uid=admin,ou=system</code>. Directory servers generally require clients to present username/password credentials in order +to open a connection.</p> +</li> +<li><p><code>connectionPassword</code> - the password that matches the DN from <code>connectionUsername</code>. In the directory server, +in the DIT, the password is normally stored as a <code>userPassword</code> attribute in the corresponding directory entry.</p> +</li> +<li><p><code>connectionProtocol</code> - currently, the only supported value is a blank string. In future, this option will allow +you to select the Secure Socket Layer (SSL) for the connection to the directory server. This option must be set +explicitly to an empty string, because it has no default value.</p> +</li> +<li><p><code>userBase</code> - selects a particular subtree of the DIT to search for user entries. The subtree is specified by a +DN, which specifes the base node of the subtree. For example, by setting this option to <code>ou=User,ou=ActiveMQ,ou=system</code>, +the search for user entries is restricted to the subtree beneath the <code>ou=User,ou=ActiveMQ,ou=system</code> node.</p> +</li> +<li><p><code>userSearchMatching</code> - specifies an LDAP search filter, which is applied to the subtree selected by <code>userBase</code>. +Before passing to the LDAP search operation, the string value you provide here is subjected to string substitution, +as implemented by the <code>java.text.MessageFormat</code> class. Essentially, this means that the special string, <code>{0}</code>, is +substituted by the username, as extracted from the incoming client credentials.</p> +<p>After substitution, the string is interpreted as an LDAP search filter, where the LDAP search filter syntax is +defined by the IETF standard, RFC 2254. A short introduction to the search filter syntax is available from Oracle's +JNDI tutorial, <a href="http://download.oracle.com/javase/jndi/tutorial/basics/directory/filter.html"; target="_blank">Search Filters</a>.</p> +<p>For example, if this option is set to <code>(uid={0})</code> and the received username is <code>jdoe</code>, the search filter becomes +<code>(uid=jdoe)</code> after string substitution. If the resulting search filter is applied to the subtree selected by the +user base, <code>ou=User,ou=ActiveMQ,ou=system</code>, it would match the entry, <code>uid=jdoe,ou=User,ou=ActiveMQ,ou=system</code> +(and possibly more deeply nested entries, depending on the specified search depth—see the <code>userSearchSubtree</code> option).</p> +</li> +<li><p><code>userSearchSubtree</code> - specify the search depth for user entries, relative to the node specified by <code>userBase</code>. +This option is a boolean. <code>false</code> indicates it will try to match one of the child entries of the <code>userBase</code> node +(maps to <code>javax.naming.directory.SearchControls.ONELEVEL_SCOPE</code>). <code>true</code> indicates it will try to match any entry +belonging to the subtree of the <code>userBase</code> node (maps to <code>javax.naming.directory.SearchControls.SUBTREE_SCOPE</code>).</p> +</li> +<li><p><code>userRoleName</code> - specifies the name of the multi-valued attribute of the user entry that contains a list of +role names for the user (where the role names are interpreted as group names by the broker's authorization plug-in). +If you omit this option, no role names are extracted from the user entry.</p> +</li> +<li><p><code>roleBase</code> - if you want to store role data directly in the directory server, you can use a combination of role +options (<code>roleBase</code>, <code>roleSearchMatching</code>, <code>roleSearchSubtree</code>, and <code>roleName</code>) as an alternative to (or in addition +to) specifying the <code>userRoleName</code> option. This option selects a particular subtree of the DIT to search for role/group +entries. The subtree is specified by a DN, which specifes the base node of the subtree. For example, by setting this +option to <code>ou=Group,ou=ActiveMQ,ou=system</code>, the search for role/group entries is restricted to the subtree beneath +the <code>ou=Group,ou=ActiveMQ,ou=system</code> node.</p> +</li> +<li><p><code>roleName</code> - specifies the attribute type of the role entry that contains the name of the role/group (e.g. C, O, +OU, etc.). If you omit this option, the role search feature is effectively disabled.</p> +</li> +<li><p><code>roleSearchMatching</code> - specifies an LDAP search filter, which is applied to the subtree selected by <code>roleBase</code>. +This works in a similar manner to the <code>userSearchMatching</code> option, except that it supports two substitution strings, +as follows:</p> +<ul> +<li><p><code>{0}</code> - substitutes the full DN of the matched user entry (that is, the result of the user search). For +example, for the user, <code>jdoe</code>, the substituted string could be <code>uid=jdoe,ou=User,ou=ActiveMQ,ou=system</code>.</p> +</li> +<li><p><code>{1}</code> - substitutes the received username. For example, <code>jdoe</code>.</p> +</li> +</ul> +<p>For example, if this option is set to <code>(member=uid={1})</code> and the received username is <code>jdoe</code>, the search filter +becomes <code>(member=uid=jdoe)</code> after string substitution (assuming ApacheDS search filter syntax). If the resulting +search filter is applied to the subtree selected by the role base, <code>ou=Group,ou=ActiveMQ,ou=system</code>, it matches all +role entries that have a <code>member</code> attribute equal to <code>uid=jdoe</code> (the value of a <code>member</code> attribute is a DN).</p> +<p>This option must always be set, even if role searching is disabled, because it has no default value.</p> +<p>If you use OpenLDAP, the syntax of the search filter is <code>(member:=uid=jdoe)</code>.</p> +</li> +<li><p><code>roleSearchSubtree</code> - specify the search depth for role entries, relative to the node specified by <code>roleBase</code>. +This option can take boolean values, as follows:</p> +<ul> +<li><p><code>false</code> (default) - try to match one of the child entries of the roleBase node (maps to +<code>javax.naming.directory.SearchControls.ONELEVEL_SCOPE</code>).</p> +</li> +<li><p><code>true</code> — try to match any entry belonging to the subtree of the roleBase node (maps to +<code>javax.naming.directory.SearchControls.SUBTREE_SCOPE</code>).</p> +</li> +</ul> +</li> +<li><p><code>debug</code> - boolean flag; if <code>true</code>, enable debugging; this is used only for testing or debugging; normally, it +should be set to <code>false</code>, or omitted; default is <code>false</code></p> +</li> +</ul> +<p>Add user entries under the node specified by the <code>userBase</code> option. When creating a new user entry in the directory, +choose an object class that supports the <code>userPassword</code> attribute (for example, the <code>person</code> or <code>inetOrgPerson</code> object +classes are typically suitable). After creating the user entry, add the <code>userPassword</code> attribute, to hold the user's +password.</p> +<p>If you want to store role data in dedicated role entries (where each node represents a particular role), create a role +entry as follows. Create a new child of the <code>roleBase</code> node, where the <code>objectClass</code> of the child is <code>groupOfNames</code>. Set +the <code>cn</code> (or whatever attribute type is specified by <code>roleName</code>) of the new child node equal to the name of the +role/group. Define a <code>member</code> attribute for each member of the role/group, setting the <code>member</code> value to the DN of the +corresponding user (where the DN is specified either fully, <code>uid=jdoe,ou=User,ou=ActiveMQ,ou=system</code>, or partially, +<code>uid=jdoe</code>).</p> +<p>If you want to add roles to user entries, you would need to customize the directory schema, by adding a suitable +attribute type to the user entry's object class. The chosen attribute type must be capable of handling multiple values.</p> +<h4 id="certificateloginmodule">CertificateLoginModule</h4> +<p>The JAAS certificate authentication login module must be used in combination with SSL and the clients must be configured +with their own certificate. In this scenario, authentication is actually performed during the SSL/TLS handshake, not +directly by the JAAS certificate authentication plug-in. The role of the plug-in is as follows:</p> +<ul> +<li><p>To further constrain the set of acceptable users, because only the user DNs explicitly listed in the relevant +properties file are eligible to be authenticated.</p> +</li> +<li><p>To associate a list of groups with the received user identity, facilitating integration with the authorization feature.</p> +</li> +<li><p>To require the presence of an incoming certificate (by default, the SSL/TLS layer is configured to treat the +presence of a client certificate as optional).</p> +</li> +</ul> +<p>The JAAS certificate login module stores a collection of certificate DNs in a pair of flat files. The files associate a +username and a list of group IDs with each DN.</p> +<p>The certificate login module is implemented by the following class:</p> +<pre><code>org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule +</code></pre><p>The following <code>CertLogin</code> login entry shows how to configure certificate login module in the login.config file:</p> +<pre><code>CertLogin { + org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule + debug=true + org.apache.activemq.jaas.textfiledn.user="users.properties" + org.apache.activemq.jaas.textfiledn.role="roles.properties"; +}; +</code></pre><p>In the preceding example, the JAAS realm is configured to use a single <code>org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule</code> +login module. The options supported by this login module are as follows:</p> +<ul> +<li><p><code>debug</code> - boolean flag; if true, enable debugging; this is used only for testing or debugging; normally, +it should be set to <code>false</code>, or omitted; default is <code>false</code></p> +</li> +<li><p><code>org.apache.activemq.jaas.textfiledn.user</code> - specifies the location of the user properties file (relative to the + directory containing the login configuration file).</p> +</li> +<li><p><code>org.apache.activemq.jaas.textfiledn.role</code> - specifies the location of the role properties file (relative to the +directory containing the login configuration file).</p> +</li> +<li><p><code>reload</code> - boolean flag; whether or not to reload the properties files when a modification occurs; default is <code>false</code></p> +</li> +</ul> +<p>In the context of the certificate login module, the <code>users.properties</code> file consists of a list of properties of the form, +<code>UserName=StringifiedSubjectDN</code>. For example, to define the users, system, user, and guest, you could create a file like +the following:</p> +<pre><code>system=CN=system,O=Progress,C=US +user=CN=humble user,O=Progress,C=US +guest=CN=anon,O=Progress,C=DE +</code></pre><p>Each username is mapped to a subject DN, encoded as a string (where the string encoding is specified by RFC 2253). For +example, the system username is mapped to the <code>CN=system,O=Progress,C=US</code> subject DN. When performing authentication, +the plug-in extracts the subject DN from the received certificate, converts it to the standard string format, and +compares it with the subject DNs in the <code>users.properties</code> file by testing for string equality. Consequently, you must +be careful to ensure that the subject DNs appearing in the <code>users.properties</code> file are an exact match for the subject +DNs extracted from the user certificates.</p> +<p>Note: Technically, there is some residual ambiguity in the DN string format. For example, the <code>domainComponent</code> attribute +could be represented in a string either as the string, <code>DC</code>, or as the OID, <code>0.9.2342.19200300.100.1.25</code>. Normally, you do +not need to worry about this ambiguity. But it could potentially be a problem, if you changed the underlying +implementation of the Java security layer.</p> +<p>The easiest way to obtain the subject DNs from the user certificates is by invoking the <code>keytool</code> utility to print the +certificate contents. To print the contents of a certificate in a keystore, perform the following steps:</p> +<ol> +<li><p>Export the certificate from the keystore file into a temporary file. For example, to export the certificate with +alias <code>broker-localhost</code> from the <code>broker.ks</code> keystore file, enter the following command:</p> +<p> keytool -export -file broker.export -alias broker-localhost -keystore broker.ks -storepass password</p> +<p>After running this command, the exported certificate is in the file, <code>broker.export</code>.</p> +</li> +<li><p>Print out the contents of the exported certificate. For example, to print out the contents of <code>broker.export</code>, +enter the following command:</p> +<p> keytool -printcert -file broker.export</p> +<p>Which should produce output similar to that shown here:</p> +<p> Owner: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown + Issuer: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown + Serial number: 4537c82e + Valid from: Thu Oct 19 19:47:10 BST 2006 until: Wed Jan 17 18:47:10 GMT 2007 + Certificate fingerprints:</p> +<pre><code> MD5: 3F:6C:0C:89:A8:80:29:CC:F5:2D:DA:5C:D7:3F:AB:37 + SHA1: F0:79:0D:04:38:5A:46:CE:86:E1:8A:20:1F:7B:AB:3A:46:E4:34:5C +</code></pre><p>The string following <code>Owner:</code> gives the subject DN. The format used to enter the subject DN depends on your +platform. The <code>Owner:</code> string above could be represented as either <code>CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ ST=Unknown,\ C=Unknown</code> +or <code>CN=localhost,OU=broker,O=Unknown,L=Unknown,ST=Unknown,C=Unknown</code>.</p> +</li> +</ol> +<p>The <code>roles.properties</code> file consists of a list of properties of the form, <code>Role=UserList</code>, where <code>UserList</code> is a +comma-separated list of users. For example, to define the roles <code>admins</code>, <code>users</code>, and <code>guests</code>, you could create a file +like the following:</p> +<pre><code>admins=system +users=system,user +guests=guest +</code></pre><p>The simplest way to make the login configuration available to JAAS is to add the directory containing the file, +<code>login.config</code>, to your CLASSPATH.</p> +<h2 id="changing-the-usernamepassword-for-clustering">Changing the username/password for clustering</h2> +<p>In order for cluster connections to work correctly, each node in the +cluster must make connections to the other nodes. The username/password +they use for this should always be changed from the installation default +to prevent a security risk.</p> +<p>Please see <a href="management.html">Management</a> for instructions on how to do this.</p> +<h2 id="securing-the-console">Securing the console</h2> +<p>Artemis comes with a web console that allows user to browse Artemis documentation via an embedded server. By default the +web access is plain HTTP. It is configured in <code>bootstrap.xml</code>:</p> +<pre><code><web bind="http://localhost:8161" path="web"> + <app url="jolokia" war="jolokia-war-1.3.5.war"/> +</web> +</code></pre><p>Alternatively you can edit the above configuration to enable secure access using HTTPS protocol. e.g.:</p> +<pre><code><web bind="https://localhost:8443" + path="web" + keyStorePath="${artemis.instance}/etc/keystore.jks" + keyStorePassword="password"> + <app url="jolokia" war="jolokia-war-1.3.5.war"/> +</web> +</code></pre><p>As shown in the example, to enable https the first thing to do is config the <code>bind</code> to be an <code>https</code> url. In addition, +You will have to configure a few extra properties desribed as below.</p> +<ul> +<li><p><code>keyStorePath</code> - The path of the key store file.</p> +</li> +<li><p><code>keyStorePassword</code> - The key store's password.</p> +</li> +<li><p><code>clientAuth</code> - The boolean flag indicates whether or not client authentication is required. Default is <code>false</code>.</p> +</li> +<li><p><code>trustStorePath</code> - The path of the trust store file. This is needed only if <code>clientAuth</code> is <code>true</code>.</p> +</li> +<li><p><code>trustStorePassword</code> - The trust store's password.</p> +</li> +</ul> +<h2 id="controlling-jms-objectmessage-deserialization">Controlling JMS ObjectMessage deserialization</h2> +<p>Artemis provides a simple class filtering mechanism with which a user can specify which +packages are to be trusted and which are not. Objects whose classes are from trusted packages +can be deserialized without problem, whereas those from 'not trusted' packages will be denied +deserialization.</p> +<p>Artemis keeps a <code>black list</code> to keep track of packages that are not trusted and a <code>white list</code> +for trusted packages. By default both lists are empty, meaning any serializable object is +allowed to be deserialized. If an object whose class matches one of the packages in black list, +it is not allowed to be deserialized. If it matches one in the white list +the object can be deserialized. If a package appears in both black list and white list, +the one in black list takes precedence. If a class neither matches with <code>black list</code> +nor with the <code>white list</code>, the class deserialization will be denied +unless the white list is empty (meaning the user doesn't specify the white list at all).</p> +<p>A class is considered as a 'match' if</p> +<ul> +<li>its full name exactly matches one of the entries in the list.</li> +<li>its package matches one of the entries in the list or is a sub-package of one of the entries.</li> +</ul> +<p>For example, if a class full name is "org.apache.pkg1.Class1", some matching entries could be:</p> +<ul> +<li><code>org.apache.pkg1.Class1</code> - exact match.</li> +<li><code>org.apache.pkg1</code> - exact package match.</li> +<li><code>org.apache</code> -- sub package match.</li> +</ul> +<p>A <code>*</code> means 'match-all' in a black or white list.</p> +<h3 id="specifying-black-list-and-white-list-via-connection-factories">Specifying black list and white list via Connection Factories</h3> +<p>To specify the white and black lists one can append properties <code>deserializationBlackList</code> and <code>deserializationWhiteList</code> respectively +to a Connection Factory's url string. For example:</p> +<pre><code> ActiveMQConnectionFactory factory = new ActiveMQConnectionFactory("vm://0?deserializationBlackList=org.apache.pkg1,org.some.pkg2"); +</code></pre><p>The above statement creates a factory that has a black list contains two forbidden packages, "org.apache.pkg1" and "org.some.pkg2", +separated by a comma.</p> +<p>You can also set the values via ActiveMQConnectionFactory's API:</p> +<pre><code>public void setDeserializationBlackList(String blackList); +public void setDeserializationWhiteList(String whiteList); +</code></pre><p>Again the parameters are comma separated list of package/class names.</p> +<h3 id="specifying-black-list-and-white-list-via-system-properties">Specifying black list and white list via system properties</h3> +<p>There are two system properties available for specifying black list and white list:</p> +<ul> +<li><code>org.apache.activemq.artemis.jms.deserialization.whitelist</code> - comma separated list of entries for the white list.</li> +<li><code>org.apache.activemq.artemis.jms.deserialization.blacklist</code> - comma separated list of entries for the black list.</li> +</ul> +<p>Once defined, all JMS object message deserialization in the VM is subject to checks against the two lists. However if you create a ConnectionFactory +and set a new set of black/white lists on it, the new values will override the system properties.</p> +<h3 id="specifying-black-list-and-white-list-for-resource-adapters">Specifying black list and white list for resource adapters</h3> +<p>Message beans using a JMS resource adapter to receive messages can also control their object deserialization via properly configuring relevant +properties for their resource adapters. There are two properties that you can configure with connection factories in a resource adapter:</p> +<ul> +<li><code>deserializationBlackList</code> - comma separated values for black list</li> +<li><code>deserializationWhiteList</code> - comma separated values for white list</li> +</ul> +<p>These properties, once specified, are eventually set on the corresponding internal factories.</p> +<h3 id="specifying-black-list-and-white-list-for-rest-interface">Specifying black list and white list for REST interface</h3> +<p>Apache Artemis REST interface (<a href="rest.html">Rest</a>) allows interactions between jms client and rest clients. +It uses JMS ObjectMessage to wrap the actual user data between the 2 types of clients and deserialization +is needed during this process. If you want to control the deserialization for REST, you need to set the +black/white lists for it separately as Apache Artemis REST Interface is deployed as a web application. +You need to put the black/white lists in its web.xml, as context parameters, as follows</p> +<pre><code><web-app> + <context-param> + <param-name>org.apache.activemq.artemis.jms.deserialization.whitelist</param-name> + <param-value>some.allowed.class</param-value> + </context-param> + <context-param> + <param-name>org.apache.activemq.artemis.jms.deserialization.blacklist</param-name> + <param-value>some.forbidden.class</param-value> + </context-param> +... +</web-app> +</code></pre><p>The param-value for each list is a comma separated string value representing the list.</p> + + + </section> + + </div> + <div class="search-results"> + <div class="has-results"> + + <h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1> + <ul class="search-results-list"></ul> + + </div> + <div class="no-results"> + + <h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1> + + </div> + </div> +</div> + + </div> + </div> + + </div> + + + + <a href="management.html" class="navigation navigation-prev " aria-label="Previous page: Management"> + <i class="fa fa-angle-left"></i> + </a> + + + <a href="resource-limits.html" class="navigation navigation-next " aria-label="Next page: Resource Limits"> + <i class="fa fa-angle-right"></i> + </a> + + + + </div> + + <script> + var gitbook = gitbook || []; + gitbook.push(function() { + gitbook.page.hasChanged({"page":{"title":"Security","level":"1.34","depth":1,"next":{"title":"Resource Limits","level":"1.35","depth":1,"path":"resource-limits.md","ref":"resource-limits.md","articles":[]},"previous":{"title":"Management","level":"1.33","depth":1,"path":"management.md","ref":"management.md","articles":[]},"dir":"ltr"},"config":{"plugins":[],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","pr int":"styles/print.css"},"showLevel":false}},"github":"apache/activemq-artemis","theme":"default","githubHost":"https://github.com/","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"ActiveMQ Artemis Documentation","links":{"home":"http://activemq.apache.org/","issues":"http://activemq.apache.org/","contribute":"http://activemq.apache.org/contributing.html"},"gitbook":"3.x.x","description":"ActiveMQ Artemis User Guide and Reference Documentation"},"file":{"path":"security.md","mtime":"2016-10-24T23:37:36.000Z","type":"markdown"},"gitbook":{"version":"3.1.1","time":"2016-11-12T01:00:04.718Z"},"basePath":".","book":{"language":""}}); + }); + </script> +</div> + + + <script src="gitbook/gitbook.js"></script> + <script src="gitbook/theme.js"></script> + + + <script src="gitbook/gitbook-plugin-search/search-engine.js"></script> + + + + <script src="gitbook/gitbook-plugin-search/search.js"></script> + + + + <script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script> + + + + <script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script> + + + + <script src="gitbook/gitbook-plugin-sharing/buttons.js"></script> + + + + <script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script> + + + + </body> +</html> +
