You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by cl...@apache.org on 2017/09/14 19:48:13 UTC
svn commit: r1018163 [37/45] - in
/websites/production/activemq/content/artemis/docs: 2.2.0/ latest/
latest/diagrams/ latest/gitbook/ latest/gitbook/fonts/
latest/gitbook/fonts/fontawesome/
latest/gitbook/gitbook-plugin-fontsettings/ latest/gitbook/git...
Added: websites/production/activemq/content/artemis/docs/latest/security.html
==============================================================================
--- websites/production/activemq/content/artemis/docs/latest/security.html (added)
+++ websites/production/activemq/content/artemis/docs/latest/security.html Thu Sep 14 19:48:11 2017
@@ -0,0 +1,1781 @@
+
+<!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="broker-plugins.html" />
+
+
+ <link rel="prev" href="management-console.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="address-model.html">
+
+ <a href="address-model.html">
+
+
+ Address Model
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.9" data-path="using-jms.html">
+
+ <a href="using-jms.html">
+
+
+ Using JMS
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.10" data-path="using-core.html">
+
+ <a href="using-core.html">
+
+
+ Using Core
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.11" data-path="using-AMQP.html">
+
+ <a href="using-AMQP.html">
+
+
+ Using AMQP
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.12" 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.13" data-path="client-classpath.html">
+
+ <a href="client-classpath.html">
+
+
+ The Client Classpath
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.14" data-path="examples.html">
+
+ <a href="examples.html">
+
+
+ Examples
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.15" data-path="wildcard-routing.html">
+
+ <a href="wildcard-routing.html">
+
+
+ Routing Messages With Wild Cards
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.16" 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.17" data-path="filter-expressions.html">
+
+ <a href="filter-expressions.html">
+
+
+ Filter Expressions
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.18" data-path="persistence.html">
+
+ <a href="persistence.html">
+
+
+ Persistence
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.19" data-path="configuring-transports.html">
+
+ <a href="configuring-transports.html">
+
+
+ Configuring Transports
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.20" data-path="config-reload.html">
+
+ <a href="config-reload.html">
+
+
+ Configuration Reload
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.21" data-path="connection-ttl.html">
+
+ <a href="connection-ttl.html">
+
+
+ Detecting Dead Connections
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.22" data-path="slow-consumers.html">
+
+ <a href="slow-consumers.html">
+
+
+ Detecting Slow Consumers
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.23" data-path="network-isolation.html">
+
+ <a href="network-isolation.html">
+
+
+ Avoiding Network Isolation
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.24" data-path="critical-analysis.html">
+
+ <a href="critical-analysis.html">
+
+
+ Detecting Broker Issues (Critical Analysis)
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.25" data-path="transaction-config.html">
+
+ <a href="transaction-config.html">
+
+
+ Resource Manager Configuration
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.26" data-path="flow-control.html">
+
+ <a href="flow-control.html">
+
+
+ Flow Control
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.27" data-path="send-guarantees.html">
+
+ <a href="send-guarantees.html">
+
+
+ Guarantees of sends and commits
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.28" data-path="undelivered-messages.html">
+
+ <a href="undelivered-messages.html">
+
+
+ Message Redelivery and Undelivered Messages
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.29" data-path="message-expiry.html">
+
+ <a href="message-expiry.html">
+
+
+ Message Expiry
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.30" data-path="large-messages.html">
+
+ <a href="large-messages.html">
+
+
+ Large Messages
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.31" data-path="paging.html">
+
+ <a href="paging.html">
+
+
+ Paging
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.32" data-path="queue-attributes.html">
+
+ <a href="queue-attributes.html">
+
+
+ Queue Attributes
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.33" data-path="scheduled-messages.html">
+
+ <a href="scheduled-messages.html">
+
+
+ Scheduled Messages
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.34" data-path="last-value-queues.html">
+
+ <a href="last-value-queues.html">
+
+
+ Last-Value Queues
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.35" data-path="message-grouping.html">
+
+ <a href="message-grouping.html">
+
+
+ Message Grouping
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.36" data-path="pre-acknowledge.html">
+
+ <a href="pre-acknowledge.html">
+
+
+ Extra Acknowledge Modes
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.37" data-path="management.html">
+
+ <a href="management.html">
+
+
+ Management
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.38" data-path="management-console.html">
+
+ <a href="management-console.html">
+
+
+ Management Console
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter active" data-level="1.39" data-path="security.html">
+
+ <a href="security.html">
+
+
+ Security
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.40" data-path="broker-plugins.html">
+
+ <a href="broker-plugins.html">
+
+
+ Broker Plugins
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.41" data-path="resource-limits.html">
+
+ <a href="resource-limits.html">
+
+
+ Resource Limits
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.42" data-path="jms-bridge.html">
+
+ <a href="jms-bridge.html">
+
+
+ The JMS Bridge
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.43" data-path="client-reconnection.html">
+
+ <a href="client-reconnection.html">
+
+
+ Client Reconnection and Session Reattachment
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.44" data-path="diverts.html">
+
+ <a href="diverts.html">
+
+
+ Diverting and Splitting Message Flows
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.45" data-path="core-bridges.html">
+
+ <a href="core-bridges.html">
+
+
+ Core Bridges
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.46" data-path="duplicate-detection.html">
+
+ <a href="duplicate-detection.html">
+
+
+ Duplicate Message Detection
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.47" data-path="clusters.html">
+
+ <a href="clusters.html">
+
+
+ Clusters
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.48" data-path="ha.html">
+
+ <a href="ha.html">
+
+
+ High Availability and Failover
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.49" data-path="graceful-shutdown.html">
+
+ <a href="graceful-shutdown.html">
+
+
+ Graceful Server Shutdown
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.50" data-path="libaio.html">
+
+ <a href="libaio.html">
+
+
+ Libaio Native Libraries
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.51" data-path="thread-pooling.html">
+
+ <a href="thread-pooling.html">
+
+
+ Thread management
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.52" data-path="logging.html">
+
+ <a href="logging.html">
+
+
+ Logging
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.53" data-path="rest.html">
+
+ <a href="rest.html">
+
+
+ REST Interface
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.54" data-path="embedding-activemq.html">
+
+ <a href="embedding-activemq.html">
+
+
+ Embedding Apache ActiveMQ Artemis
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.55" data-path="karaf.html">
+
+ <a href="karaf.html">
+
+
+ Apache Karaf
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.56" data-path="spring-integration.html">
+
+ <a href="spring-integration.html">
+
+
+ Spring Integration
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.57" data-path="cdi-integration.html">
+
+ <a href="cdi-integration.html">
+
+
+ CDI Integration
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.58" data-path="intercepting-operations.html">
+
+ <a href="intercepting-operations.html">
+
+
+ Intercepting Operations
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.59" data-path="protocols-interoperability.html">
+
+ <a href="protocols-interoperability.html">
+
+
+ Protocols and Interoperability
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.60" data-path="tools.html">
+
+ <a href="tools.html">
+
+
+ Tools
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.61" data-path="maven-plugin.html">
+
+ <a href="maven-plugin.html">
+
+
+ Maven Plugin
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.62" data-path="unit-testing.html">
+
+ <a href="unit-testing.html">
+
+
+ Unit Testing
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.63" data-path="perf-tuning.html">
+
+ <a href="perf-tuning.html">
+
+
+ Troubleshooting and Performance Tuning
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.64" data-path="configuration-index.html">
+
+ <a href="configuration-index.html">
+
+
+ Configuration Reference
+
+ </a>
+
+
+
+ </li>
+
+ <li class="chapter " data-level="1.65" data-path="updating-artemis.html">
+
+ <a href="updating-artemis.html">
+
+
+ Updating Artemis
+
+ </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>Eight 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.</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 the Java Authentication and Authorization Service (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>
+<h3 id="kerberos-authentication">Kerberos Authentication</h3>
+<p>You must have the Kerberos infrastructure set up in your deployment environment before the server can accept Kerberos credentials.
+The server can acquire its Kerberos acceptor credentials by using JAAS and a Kerberos login module. The JDK provides the
+<a href="https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html" target="_blank">Krb5LoginModule</a>
+which executes the necessary Kerberos protocol steps to authenticate and obtain Kerberos credentials.</p>
+<h4 id="gssapi-sasl-mechanism">GSSAPI SASL Mechanism</h4>
+<p>Using SASL over <a href="using-AMQP.html">AMQP</a>, Kerberos authentication is supported using the <code>GSSAPI</code> SASL mechanism.
+With SASL doing Kerberos authentication, TLS can be used to provide integrity and confidentially to the communications
+channel in the normal way.
+The <code>GSSAPI</code> SASL mechanism must be enabled on the AMQP acceptor in <code>broker.xml</code> by adding it to the <code>saslMechanisms</code> list url parameter:
+<code>saslMechanisms="GSSAPI<,PLAIN, etc></code>.</p>
+<pre><code><acceptor name="amqp">tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI</acceptor>
+</code></pre><p>The GSSAPI mechanism implementation on the server will use a JAAS configuration scope named <code>amqp-sasl-gssapi</code> to
+obtain it's Kerberos acceptor credentials. An alternative configuration scope can be specified on the AMQP acceptor
+using the url parameter: <code>saslLoginConfigScope=<some other scope></code>.</p>
+<p>An example configuration scope for <code>login.config</code> that will pick up a Kerberos keyTab for the Kerberos acceptor Principal
+<code>amqp/localhost</code> is as follows:</p>
+<pre><code>amqp-sasl-gssapi {
+ com.sun.security.auth.module.Krb5LoginModule required
+ isInitiator=false
+ storeKey=true
+ useKeyTab=true
+ principal="amqp/localhost"
+ debug=true;
+};
+</code></pre><h4 id="role-mapping">Role Mapping</h4>
+<p>On the server, the Kerberos authenticated Peer Principal can be added to the Subject's principal set as an Apache ActiveMQ Artemis UserPrincipal
+using the Apache ActiveMQ Artemis <code>Krb5LoginModule</code> login module. The <a href="#propertiesloginmodule">PropertiesLoginModule</a> can then be used to map
+the authenticated Kerberos Peer Principal to a <a href="#role-based-security-for-addresses">Role</a>.</p>
+<p>Note: the Kerberos Peer Principal does not exist as an Apache ActiveMQ Artemis user.</p>
+<pre><code>org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule optional;
+</code></pre><h4 id="tls-kerberos-cipher-suites">TLS Kerberos Cipher Suites</h4>
+<p>The legacy <a href="http://www.ietf.org/rfc/rfc2712.txt" target="_blank">rfc2712</a> defines TLS Kerberos cipher suites that can be used by TLS to negotiate
+Kerberos authentication. The cypher suites offered by rfc2712 are dated and insecure and rfc2712 has been superseded by
+SASL GSSAPI. However, for clients that don't support SASL (core client), using TLS can provide Kerberos authentication
+over an <em>unsecure</em> channel.</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 use the URL parameters
+<code>deserializationBlackList</code> and <code>deserializationWhiteList</code>. For example,
+using JMS:</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>
+<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-console.html" class="navigation navigation-prev " aria-label="Previous page: Management Console">
+ <i class="fa fa-angle-left"></i>
+ </a>
+
+
+ <a href="broker-plugins.html" class="navigation navigation-next " aria-label="Next page: Broker Plugins">
+ <i class="fa fa-angle-right"></i>
+ </a>
+
+
+
+ </div>
+
+ <script>
+ var gitbook = gitbook || [];
+ gitbook.push(function() {
+ gitbook.page.hasChanged({"page":{"title":"Security","level":"1.39","depth":1,"next":{"title":"Broker Plugins","level":"1.40","depth":1,"path":"broker-plugins.md","ref":"broker-plugins.md","articles":[]},"previous":{"title":"Management Console","level":"1.38","depth":1,"path":"management-console.md","ref":"management-console.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","print":"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/artemis","issues":"https://issues.apache.org/jira/browse/ARTEMIS","contribute":"http://activemq.apache.org/contributing.html"},"gitbook":"3.x.x","description":"ActiveMQ Artemis User Guide and Reference Documentation"},"file":{"path":"security.md","mtime":"2017-09-14T19:42:03.000Z","type":"markdown"},"gitbook":{"version":"3.1.1","time":"2017-09-14T19:42:32.953Z"},"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>
+