http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/security.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md index 2f70701..dfd1a41 100644 --- a/docs/user-manual/en/security.md +++ b/docs/user-manual/en/security.md @@ -1,606 +1,755 @@ # Security -This chapter describes how security works with Apache ActiveMQ Artemis and how you can -configure it. To disable security completely simply set the -`security-enabled` property to false in the `broker.xml` -file. - -For performance reasons security is cached and invalidated every so -long. To change this period set the property -`security-invalidation-interval`, which is in milliseconds. The default -is `10000` ms. - -To assist in security auditing the `populate-validated-user` option exists. If this is `true` then -the server will add the name of the validated user to the message using the key `_AMQ_VALIDATED_USER`. -For JMS and Stomp clients this is mapped to the key `JMSXUserID`. For users authenticated based on -their SSL certificate this name is the name to which their certificate's DN maps. If `security-enabled` -is `false` and `populate-validated-user` is `true` then the server will simply use whatever user name -(if any) the client provides. This option is `false` by default. +This chapter describes how security works with Apache ActiveMQ Artemis and how +you can configure it. To disable security completely simply set the +`security-enabled` property to false in the `broker.xml` file. + +For performance reasons security is cached and invalidated every so long. To +change this period set the property `security-invalidation-interval`, which is +in milliseconds. The default is `10000` ms. + +## Tracking the Validated User + +To assist in security auditing the `populate-validated-user` option exists. If +this is `true` then the server will add the name of the validated user to the +message using the key `_AMQ_VALIDATED_USER`. For JMS and Stomp clients this is +mapped to the key `JMSXUserID`. For users authenticated based on their SSL +certificate this name is the name to which their certificate's DN maps. If +`security-enabled` is `false` and `populate-validated-user` is `true` then the +server will simply use whatever user name (if any) the client provides. This +option is `false` by default. ## Role based security for addresses -Apache ActiveMQ Artemis contains a flexible role-based security model for applying -security to queues, based on their addresses. +Apache ActiveMQ Artemis contains a flexible role-based security model for +applying security to queues, based on their addresses. -As explained in [Using Core](using-core.md), 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. +As explained in [Using Core](core.md), 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. -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 '`#`' and -'`*`'. +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](wildcard-syntax.md) can be used. -Eight different permissions can be given to the set of queues which -match the address. Those permissions are: +Eight different permissions can be given to the set of queues which match the +address. Those permissions are: -- `createAddress`. This permission allows the user to create an - address fitting the `match`. +- `createAddress`. This permission allows the user to create an address fitting + the `match`. -- `deleteAddress`. This permission allows the user to delete an - address fitting the `match`. +- `deleteAddress`. This permission allows the user to delete an address fitting + the `match`. -- `createDurableQueue`. This permission allows the user to create a - durable queue under matching addresses. +- `createDurableQueue`. This permission allows the user to create a durable + queue under matching addresses. -- `deleteDurableQueue`. This permission allows the user to delete a - durable queue under matching addresses. +- `deleteDurableQueue`. This permission allows the user to delete a durable + queue under matching addresses. -- `createNonDurableQueue`. This permission allows the user to create a - non-durable queue under matching addresses. +- `createNonDurableQueue`. This permission allows the user to create a + non-durable queue under matching addresses. -- `deleteNonDurableQueue`. This permission allows the user to delete a - non-durable queue under matching addresses. +- `deleteNonDurableQueue`. This permission allows the user to delete a + non-durable queue under matching addresses. -- `send`. This permission allows the user to send a message to - matching addresses. +- `send`. This permission allows the user to send a message to matching + addresses. -- `consume`. This permission allows the user to consume a message from - a queue bound to matching addresses. +- `consume`. This permission allows the user to consume a message from a queue + bound to matching addresses. -- `browse`. This permission allows the user to browse a queue bound to - the matching address. +- `browse`. This permission allows the user to browse a queue bound to the + matching address. -- `manage`. This permission allows the user to invoke management - operations by sending management messages to the management address. +- `manage`. This permission allows the user to invoke management operations by + sending management messages to the management address. 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. - -Let's take a simple example, here's a security block from -`broker.xml` file: - - <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> - -The '`#`' character signifies "any sequence of words". Words are -delimited by the '`.`' character. For a full description of the wildcard -syntax please see [Understanding the Wildcard Syntax](wildcard-syntax.md). -The above security block applies to any address -that starts with the string "globalqueues.europe.": - -Only users who have the `admin` role can create or delete durable queues -bound to an address that starts with the string "globalqueues.europe." - -Any users with the roles `admin`, `guest`, or `europe-users` can create -or delete temporary queues bound to an address that starts with the -string "globalqueues.europe." - -Any users with the roles `admin` or `europe-users` can send messages to -these addresses or consume messages from queues bound to an address that -starts with the string "globalqueues.europe." - -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 +specified. If the user has any of those roles, he/she will be granted that +permission for that set of addresses. + +Let's take a simple example, here's a security block from `broker.xml` file: + +```xml +<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> +``` + +Using the default [wildcard syntax](wildcard-syntax.md) the `#` character +signifies "any sequence of words". Words are delimited by the `.` character. +Therefore, the above security block applies to any address that starts with the +string "globalqueues.europe.". + +Only users who have the `admin` role can create or delete durable queues bound +to an address that starts with the string "globalqueues.europe." + +Any users with the roles `admin`, `guest`, or `europe-users` can create or +delete temporary queues bound to an address that starts with the string +"globalqueues.europe." + +Any users with the roles `admin` or `europe-users` can send messages to these +addresses or consume messages from queues bound to an address that starts with +the string "globalqueues.europe." + +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. -For more information on configuring the security manager, please see 'Changing the Security Manager'. +For more information on configuring the security manager, please see 'Changing +the Security Manager'. -There can be zero or more `security-setting` elements in each xml file. -Where more than one match applies to a set of addresses the *more -specific* match takes precedence. +There can be zero or more `security-setting` elements in each xml file. Where +more than one match applies to a set of addresses the *more specific* match +takes precedence. -Let's look at an example of that, here's another `security-setting` -block: +Let's look at an example of that, here's another `security-setting` block: - <security-setting match="globalqueues.europe.orders.#"> - <permission type="send" roles="europe-users"/> - <permission type="consume" roles="europe-users"/> - </security-setting> +```xml +<security-setting match="globalqueues.europe.orders.#"> + <permission type="send" roles="europe-users"/> + <permission type="consume" roles="europe-users"/> +</security-setting> +``` -In this `security-setting` 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 *only* -from the latter security-setting block. +In this `security-setting` 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 *only* from the latter security-setting block. -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 `send` and `consume` for the role europe-users. The -permissions `createDurableQueue`, `deleteDurableQueue`, -`createNonDurableQueue`, `deleteNonDurableQueue` are not inherited from -the other security-setting block. +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 +`send` and `consume` for the role europe-users. The permissions +`createDurableQueue`, `deleteDurableQueue`, `createNonDurableQueue`, +`deleteNonDurableQueue` are not inherited from the other security-setting +block. -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. +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. ## Security Setting Plugin -Aside from configuring sets of permissions via XML these permissions can alternatively be -configured via a plugin which implements `org.apache.activemq.artemis.core.server.SecuritySettingPlugin` e.g.: - - <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> +Aside from configuring sets of permissions via XML these permissions can +alternatively be configured via a plugin which implements +`org.apache.activemq.artemis.core.server.SecuritySettingPlugin` e.g.: + +```xml +<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> +``` -Most of this configuration is specific to the plugin implementation. However, there are two configuration details that -will be specified for every implementation: +Most of this configuration is specific to the plugin implementation. However, +there are two configuration details that will be specified for every +implementation: -- `class-name`. This attribute of `security-setting-plugin` indicates the name of the class which implements - `org.apache.activemq.artemis.core.server.SecuritySettingPlugin`. +- `class-name`. This attribute of `security-setting-plugin` indicates the name + of the class which implements + `org.apache.activemq.artemis.core.server.SecuritySettingPlugin`. -- `setting`. Each of these elements represents a name/value pair that will be passed to the implementation for configuration - purposes. +- `setting`. Each of these elements represents a name/value pair that will be + passed to the implementation for configuration purposes. -See the JavaDoc on `org.apache.activemq.artemis.core.server.SecuritySettingPlugin` for further details about the interface -and what each method is expected to do. +See the JavaDoc on +`org.apache.activemq.artemis.core.server.SecuritySettingPlugin` for further +details about the interface and what each method is expected to do. ### Available plugins #### LegacyLDAPSecuritySettingPlugin -This plugin will read the security information that was previously handled by [`LDAPAuthorizationMap`](http://activemq.apache.org/security.html) -and the [`cachedLDAPAuthorizationMap`](http://activemq.apache.org/cached-ldap-authorization-module.html) 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. +This plugin will read the security information that was previously handled by +[`LDAPAuthorizationMap`](http://activemq.apache.org/security.html) and the +[`cachedLDAPAuthorizationMap`](http://activemq.apache.org/cached-ldap-authorization-module.html) +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. Here is an example of the plugin's configuration: - <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> - -- `class-name`. The implementation is `org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin`. - -- `initialContextFactory`. The initial context factory used to connect to LDAP. It must always be set to - `com.sun.jndi.ldap.LdapCtxFactory` (i.e. the default value). - -- `connectionURL`. Specifies the location of the directory server using an ldap URL, `ldap://Host:Port`. You can - optionally qualify this URL, by adding a forward slash, `/`, followed by the DN of a particular node in the directory - tree. For example, `ldap://ldapserver:10389/ou=system`. The default is `ldap://localhost:1024`. - -- `connectionUsername`. The DN of the user that opens the connection to the directory server. For example, `uid=admin,ou=system`. - Directory servers generally require clients to present username/password credentials in order to open a connection. - -- `connectionPassword`. The password that matches the DN from `connectionUsername`. In the directory server, in the - DIT, the password is normally stored as a `userPassword` attribute in the corresponding directory entry. - -- `connectionProtocol`. 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. - -- `authentication`. Specifies the authentication method used when binding to the LDAP server. Can take either of the - values, `simple` (username and password, the default value) or `none` (anonymous). Note: Simple Authentication and - Security Layer (SASL) authentication is currently not supported. - -- `destinationBase`. 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 `ou=destinations,o=ActiveMQ,ou=system` (i.e. the default value). - -- `filter`. 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 `(cn=*)`. - -- `roleAttribute`. Specifies an attribute of the node matched by `filter`, whose value is the DN of a role. Default - value is `uniqueMember`. - -- `adminPermissionValue`. Specifies a value that matches the `admin` permission. The default value is `admin`. - -- `readPermissionValue`. Specifies a value that matches the `read` permission. The default value is `read`. - -- `writePermissionValue`. Specifies a value that matches the `write` permission. The default value is `write`. - -- `enableListener`. 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 `true`. - -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. - -ActiveMQ 5.x only has 3 permission types - `read`, `write`, and `admin`. These permission types are described on their -[website](http://activemq.apache.org/security.html). However, as described previously, ActiveMQ Artemis has 9 permission -types - `createAddress`, `deleteAddress`, `createDurableQueue`, `deleteDurableQueue`, `createNonDurableQueue`, -`deleteNonDurableQueue`, `send`, `consume`, `browse`, and `manage`. Here's how the old types are mapped to the new types: - -- `read` - `consume`, `browse` -- `write` - `send` -- `admin` - `createAddress`, `deleteAddress`, `createDurableQueue`, `deleteDurableQueue`, `createNonDurableQueue`, - `deleteNonDurableQueue` - -As mentioned, there are a few places where a translation was performed to achieve some equivalence.: - -- This mapping doesn't include the Artemis `manage` permission type since there is no type analogous for that in ActiveMQ - 5.x. +```xml +<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> +``` -- The `admin` 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 `admin` permission - to the 4 aforementioned permissions in Artemis. +- `class-name`. The implementation is + `org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin`. + +- `initialContextFactory`. The initial context factory used to connect to LDAP. + It must always be set to `com.sun.jndi.ldap.LdapCtxFactory` (i.e. the default + value). + +- `connectionURL`. Specifies the location of the directory server using an ldap + URL, `ldap://Host:Port`. You can optionally qualify this URL, by adding a + forward slash, `/`, followed by the DN of a particular node in the directory + tree. For example, `ldap://ldapserver:10389/ou=system`. The default is + `ldap://localhost:1024`. + +- `connectionUsername`. The DN of the user that opens the connection to the + directory server. For example, `uid=admin,ou=system`. Directory servers + generally require clients to present username/password credentials in order to + open a connection. + +- `connectionPassword`. The password that matches the DN from + `connectionUsername`. In the directory server, in the DIT, the password is + normally stored as a `userPassword` attribute in the corresponding directory + entry. + +- `connectionProtocol`. 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. + +- `authentication`. Specifies the authentication method used when binding to + the LDAP server. Can take either of the values, `simple` (username and +password, the default value) or `none` (anonymous). **Note:** Simple Authentication +and Security Layer (SASL) authentication is currently not supported. + +- `destinationBase`. 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 + `ou=destinations,o=ActiveMQ,ou=system` (i.e. the default value). + +- `filter`. 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 `(cn=*)`. + +- `roleAttribute`. Specifies an attribute of the node matched by `filter`, + whose value is the DN of a role. Default value is `uniqueMember`. + +- `adminPermissionValue`. Specifies a value that matches the `admin` + permission. The default value is `admin`. + +- `readPermissionValue`. Specifies a value that matches the `read` permission. + The default value is `read`. + +- `writePermissionValue`. Specifies a value that matches the `write` + permission. The default value is `write`. + +- `enableListener`. 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 `true`. + +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. + +ActiveMQ 5.x only has 3 permission types - `read`, `write`, and `admin`. These +permission types are described on their +[website](http://activemq.apache.org/security.html). However, as described +previously, ActiveMQ Artemis has 9 permission types - `createAddress`, +`deleteAddress`, `createDurableQueue`, `deleteDurableQueue`, +`createNonDurableQueue`, `deleteNonDurableQueue`, `send`, `consume`, `browse`, +and `manage`. Here's how the old types are mapped to the new types: + +- `read` - `consume`, `browse` +- `write` - `send` +- `admin` - `createAddress`, `deleteAddress`, `createDurableQueue`, + `deleteDurableQueue`, `createNonDurableQueue`, `deleteNonDurableQueue` + +As mentioned, there are a few places where a translation was performed to +achieve some equivalence.: + +- This mapping doesn't include the Artemis `manage` permission type since there + is no type analogous for that in ActiveMQ 5.x. + +- The `admin` 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 `admin` permission to the 4 aforementioned permissions in + Artemis. ## Secure Sockets Layer (SSL) Transport -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. +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. -For more information on configuring the SSL transport, please see [Configuring the Transport](configuring-transports.md). +For more information on configuring the SSL transport, please see [Configuring +the Transport](configuring-transports.md). ## User credentials Apache ActiveMQ Artemis ships with two security manager implementations: -- The legacy, deprecated `ActiveMQSecurityManager` that reads user credentials, i.e. user names, passwords and role -information from properties files on the classpath called `artemis-users.properties` and `artemis-roles.properties`. +- The legacy, deprecated `ActiveMQSecurityManager` that reads user credentials, + i.e. user names, passwords and role information from properties files on the + classpath called `artemis-users.properties` and `artemis-roles.properties`. -- The flexible, pluggable `ActiveMQJAASSecurityManager` 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. +- The flexible, pluggable `ActiveMQJAASSecurityManager` 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. ### JAAS Security Manager -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 `bootstrap.xml`. Here is an example using the `PropertiesLogin` JAAS login -module which reads user, password, and role information from properties files: +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 `bootstrap.xml`. +Here is an example using the `PropertiesLogin` JAAS login module which reads +user, password, and role information from properties files: - <jaas-security domain="PropertiesLogin"/> +```xml +<jaas-security domain="PropertiesLogin"/> +``` -No matter what login module you're using, you'll need to specify it here in `bootstrap.xml`. The `domain` attribute -here refers to the relevant login module entry in `login.config`. For example: +No matter what login module you're using, you'll need to specify it here in +`bootstrap.xml`. The `domain` attribute here refers to the relevant login +module entry in `login.config`. For example: - 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"; - }; +``` +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"; +}; +``` -The `login.config` file is a standard JAAS configuration file. You can read more about this file on -[Oracle's website](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/LoginConfigFile.html). +The `login.config` file is a standard JAAS configuration file. You can read +more about this file on [Oracle's +website](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/LoginConfigFile.html). In short, the file defines: -- an alias for an entry (e.g. `PropertiesLogin`) +- an alias for an entry (e.g. `PropertiesLogin`) -- the implementation class for the login module (e.g. `org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule`) +- the implementation class for the login module (e.g. + `org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule`) -- a flag which indicates whether the success of the login module is `required`, `requisite`, `sufficient`, or `optional` -(see more details on these flags in the [JavaDoc](https://docs.oracle.com/javase/8/docs/api/javax/security/auth/login/Configuration.html) +- a flag which indicates whether the success of the login module is `required`, + `requisite`, `sufficient`, or `optional` (see more details on these flags in + the + [JavaDoc](https://docs.oracle.com/javase/8/docs/api/javax/security/auth/login/Configuration.html) -- a list of configuration options specific to the login module implementation +- a list of configuration options specific to the login module implementation -By default, the location and name of `login.config` is specified on the Artemis command-line which is set by -`etc/artemis.profile` on linux and `etc\artemis.profile.cmd` on Windows. +By default, the location and name of `login.config` is specified on the Artemis +command-line which is set by `etc/artemis.profile` on linux and +`etc\artemis.profile.cmd` on Windows. #### Dual Authentication -The JAAS Security Manager also supports another configuration parameter - `certificate-domain`. This is useful when you -want to authenticate clients connecting with SSL connections based on their SSL certificates (e.g. using the `CertificateLoginModule` -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 `bootstrap.xml`: +The JAAS Security Manager also supports another configuration parameter - +`certificate-domain`. This is useful when you want to authenticate clients +connecting with SSL connections based on their SSL certificates (e.g. using the +`CertificateLoginModule` 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 `bootstrap.xml`: - <jaas-security domain="PropertiesLogin" certificate-domain="CertLogin"/> +```xml +<jaas-security domain="PropertiesLogin" certificate-domain="CertLogin"/> +``` And here's the corresponding `login.config`: - 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"; - }; +``` +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"; +}; +``` -When the broker is configured this way then any client connecting with SSL and a client certificate will be authenticated -using `CertLogin` and any client connecting without SSL will be authenticated using `PropertiesLogin`. +When the broker is configured this way then any client connecting with SSL and +a client certificate will be authenticated using `CertLogin` and any client +connecting without SSL will be authenticated using `PropertiesLogin`. ### JAAS Login Modules #### GuestLoginModule -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 `org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule`. -- `org.apache.activemq.jaas.guest.user` - the user name to assign; default is "guest" +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 +`org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule`. -- `org.apache.activemq.jaas.guest.role` - the role name to assign; default is "guests" +- `org.apache.activemq.jaas.guest.user` - the user name to assign; default is "guest" -- `credentialsInvalidate` - boolean flag; if `true`, reject login requests that include a password (i.e. guest login -succeeds only when the user does not provide a password); default is `false` +- `org.apache.activemq.jaas.guest.role` - the role name to assign; default is "guests" -- `debug` - boolean flag; if `true`, enable debugging; this is used only for testing or debugging; normally, it -should be set to `false`, or omitted; default is `false` +- `credentialsInvalidate` - boolean flag; if `true`, reject login requests that + include a password (i.e. guest login succeeds only when the user does not + provide a password); default is `false` + +- `debug` - boolean flag; if `true`, enable debugging; this is used only for + testing or debugging; normally, it should be set to `false`, or omitted; + default is `false` There are two basic use cases for the guest login module, as follows: -- Guests with no credentials or invalid credentials. +- Guests with no credentials or invalid credentials. -- Guests with no credentials only. +- Guests with no credentials only. -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 +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. - 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"; - }; +``` +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"; +}; +``` Depending on the user login data, authentication proceeds as follows: -- 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. - -- 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. +- 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. -- 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. +- 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. -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. +- 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. - 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"; +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. - 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"; - }; +``` +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"; +}; +``` Depending on the user login data, authentication proceeds as follows: -- 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. +- 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. -- 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. +- 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 + net result is authentication failure. -- 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. +- 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. #### PropertiesLoginModule -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 `org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule`. - -- `org.apache.activemq.jaas.properties.user` - the path to the file which contains user and password properties - -- `org.apache.activemq.jaas.properties.role` - the path to the file which contains user and role properties - -- `reload` - boolean flag; whether or not to reload the properties files when a modification occurs; default is `false` - -- `debug` - boolean flag; if `true`, enable debugging; this is used only for testing or debugging; normally, it -should be set to `false`, or omitted; default is `false` - -In the context of the properties login module, the `artemis-users.properties` file consists of a list of properties of the -form, `UserName=Password`. For example, to define the users `system`, `user`, and `guest`, you could create a file like -the following: - - system=manager - user=password - guest=password - -Passwords in `artemis-users.properties` can be hashed. Such passwords should follow the syntax `ENC(<hash>)`. Hashed -passwords can easily be added to `artemis-users.properties` using the `user` CLI command, e.g.: +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 +`org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule`. + +- `org.apache.activemq.jaas.properties.user` - the path to the file which + contains user and password properties + +- `org.apache.activemq.jaas.properties.role` - the path to the file which + contains user and role properties + +- `reload` - boolean flag; whether or not to reload the properties files when a + modification occurs; default is `false` + +- `debug` - boolean flag; if `true`, enable debugging; this is used only for + testing or debugging; normally, it should be set to `false`, or omitted; + default is `false` + +In the context of the properties login module, the `artemis-users.properties` +file consists of a list of properties of the form, `UserName=Password`. For +example, to define the users `system`, `user`, and `guest`, you could create a +file like the following: + +```properties +system=manager +user=password +guest=password +``` +Passwords in `artemis-users.properties` can be hashed. Such passwords should +follow the syntax `ENC(<hash>)`. Hashed passwords can easily be added to +`artemis-users.properties` using the `user` CLI command, e.g.: ```sh - ./artemis user add --username guest --password guest --role admin +./artemis user add --username guest --password guest --role admin ``` -This will use the default `org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec` to perform a "one-way" hash of -the password and alter both the `artemis-users.properties` and `artemis-roles.properties` files with the specified values. +This will use the default +`org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec` to perform a +"one-way" hash of the password and alter both the `artemis-users.properties` +and `artemis-roles.properties` files with the specified values. -The `artemis-roles.properties` file consists of a list of properties of the form, `Role=UserList`, where UserList is a -comma-separated list of users. For example, to define the roles `admins`, `users`, and `guests`, you could create a file -like the following: +The `artemis-roles.properties` file consists of a list of properties of the +form, `Role=UserList`, where UserList is a comma-separated list of users. For +example, to define the roles `admins`, `users`, and `guests`, you could create +a file like the following: - admins=system - users=system,user - guests=guest +```properties +admins=system +users=system,user +guests=guest +``` #### LDAPLoginModule -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 `org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule`. - -- `initialContextFactory` - must always be set to `com.sun.jndi.ldap.LdapCtxFactory` - -- `connectionURL` - 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, `/`, followed by the DN of a particular node in the directory - tree. For example, ldap://ldapserver:10389/ou=system. -- `authentication` - specifies the authentication method used when binding to the LDAP server. Can take either of - the values, `simple` (username and password), `GSSAPI` (Kerberos SASL) or `none` (anonymous). - -- `connectionUsername` - the DN of the user that opens the connection to the directory server. For example, - `uid=admin,ou=system`. Directory servers generally require clients to present username/password credentials in order - to open a connection. - -- `connectionPassword` - the password that matches the DN from `connectionUsername`. In the directory server, - in the DIT, the password is normally stored as a `userPassword` attribute in the corresponding directory entry. - -- `saslLoginConfigScope` - the scope in JAAS configuration (login.config) to use to obtain Kerberos initiator credentials - when the `authentication` method is SASL `GSSAPI`. The default value is `broker-sasl-gssapi`. - -- `connectionProtocol` - 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. - -- `userBase` - 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 `ou=User,ou=ActiveMQ,ou=system`, - the search for user entries is restricted to the subtree beneath the `ou=User,ou=ActiveMQ,ou=system` node. - -- `userSearchMatching` - specifies an LDAP search filter, which is applied to the subtree selected by `userBase`. - Before passing to the LDAP search operation, the string value you provide here is subjected to string substitution, - as implemented by the `java.text.MessageFormat` class. Essentially, this means that the special string, `{0}`, is - substituted by the username, as extracted from the incoming client credentials. - - 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, [Search Filters](https://docs.oracle.com/javase/jndi/tutorial/basics/directory/filter.html). - - For example, if this option is set to `(uid={0})` and the received username is `jdoe`, the search filter becomes - `(uid=jdoe)` after string substitution. If the resulting search filter is applied to the subtree selected by the - user base, `ou=User,ou=ActiveMQ,ou=system`, it would match the entry, `uid=jdoe,ou=User,ou=ActiveMQ,ou=system` - (and possibly more deeply nested entries, depending on the specified search depthâsee the `userSearchSubtree` option). - -- `userSearchSubtree` - specify the search depth for user entries, relative to the node specified by `userBase`. - This option is a boolean. `false` indicates it will try to match one of the child entries of the `userBase` node - (maps to `javax.naming.directory.SearchControls.ONELEVEL_SCOPE`). `true` indicates it will try to match any entry - belonging to the subtree of the `userBase` node (maps to `javax.naming.directory.SearchControls.SUBTREE_SCOPE`). - -- `userRoleName` - 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. - -- `roleBase` - if you want to store role data directly in the directory server, you can use a combination of role - options (`roleBase`, `roleSearchMatching`, `roleSearchSubtree`, and `roleName`) as an alternative to (or in addition - to) specifying the `userRoleName` 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 `ou=Group,ou=ActiveMQ,ou=system`, the search for role/group entries is restricted to the subtree beneath - the `ou=Group,ou=ActiveMQ,ou=system` node. - -- `roleName` - 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 full DN of the role is used. - -- `roleSearchMatching` - specifies an LDAP search filter, which is applied to the subtree selected by `roleBase`. - This works in a similar manner to the `userSearchMatching` option, except that it supports two substitution strings, - as follows: - - - `{0}` - substitutes the full DN of the matched user entry (that is, the result of the user search). For - example, for the user, `jdoe`, the substituted string could be `uid=jdoe,ou=User,ou=ActiveMQ,ou=system`. - - - `{1}` - substitutes the received username. For example, `jdoe`. - - For example, if this option is set to `(member=uid={1})` and the received username is `jdoe`, the search filter - becomes `(member=uid=jdoe)` after string substitution (assuming ApacheDS search filter syntax). If the resulting - search filter is applied to the subtree selected by the role base, `ou=Group,ou=ActiveMQ,ou=system`, it matches all - role entries that have a `member` attribute equal to `uid=jdoe` (the value of a `member` attribute is a DN). - - This option must always be set to enable role searching because it has no default value. Leaving it unset disables - role searching and the role information must come from `userRoleName`. - - If you use OpenLDAP, the syntax of the search filter is `(member:=uid=jdoe)`. - -- `roleSearchSubtree` - specify the search depth for role entries, relative to the node specified by `roleBase`. - This option can take boolean values, as follows: - - - `false` (default) - try to match one of the child entries of the roleBase node (maps to - `javax.naming.directory.SearchControls.ONELEVEL_SCOPE`). - - - `true` â try to match any entry belonging to the subtree of the roleBase node (maps to - `javax.naming.directory.SearchControls.SUBTREE_SCOPE`). - -- `authenticateUser` - boolean flag to disable authentication. Useful as an optimisation when this module is used just for - role mapping of a Subject's existing authenticated principals; default is `false`. - -- `referral` - specify how to handle referrals; valid values: `ignore`, `follow`, `throw`; default is `ignore`. - -- `debug` - boolean flag; if `true`, enable debugging; this is used only for testing or debugging; normally, it - should be set to `false`, or omitted; default is `false` - -Add user entries under the node specified by the `userBase` option. When creating a new user entry in the directory, -choose an object class that supports the `userPassword` attribute (for example, the `person` or `inetOrgPerson` object -classes are typically suitable). After creating the user entry, add the `userPassword` attribute, to hold the user's -password. - -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 `roleBase` node, where the `objectClass` of the child is `groupOfNames`. Set -the `cn` (or whatever attribute type is specified by `roleName`) of the new child node equal to the name of the -role/group. Define a `member` attribute for each member of the role/group, setting the `member` value to the DN of the -corresponding user (where the DN is specified either fully, `uid=jdoe,ou=User,ou=ActiveMQ,ou=system`, or partially, -`uid=jdoe`). - -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. +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 +`org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule`. + +- `initialContextFactory` - must always be set to + `com.sun.jndi.ldap.LdapCtxFactory` + +- `connectionURL` - 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, `/`, followed by the DN of a particular node in the directory + tree. For example, ldap://ldapserver:10389/ou=system. + +- `authentication` - specifies the authentication method used when binding to + the LDAP server. Can take either of the values, `simple` (username and + password), `GSSAPI` (Kerberos SASL) or `none` (anonymous). + +- `connectionUsername` - the DN of the user that opens the connection to the + directory server. For example, `uid=admin,ou=system`. Directory servers + generally require clients to present username/password credentials in order to + open a connection. + +- `connectionPassword` - the password that matches the DN from + `connectionUsername`. In the directory server, in the DIT, the password is + normally stored as a `userPassword` attribute in the corresponding directory + entry. + +- `saslLoginConfigScope` - the scope in JAAS configuration (login.config) to + use to obtain Kerberos initiator credentials when the `authentication` method + is SASL `GSSAPI`. The default value is `broker-sasl-gssapi`. + +- `connectionProtocol` - 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. + +- `userBase` - 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 + `ou=User,ou=ActiveMQ,ou=system`, the search for user entries is restricted to + the subtree beneath the `ou=User,ou=ActiveMQ,ou=system` node. + +- `userSearchMatching` - specifies an LDAP search filter, which is applied to + the subtree selected by `userBase`. Before passing to the LDAP search + operation, the string value you provide here is subjected to string + substitution, as implemented by the `java.text.MessageFormat` class. + Essentially, this means that the special string, `{0}`, is substituted by the + username, as extracted from the incoming client credentials. + + 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, [Search + Filters](https://docs.oracle.com/javase/jndi/tutorial/basics/directory/filter.html). + + For example, if this option is set to `(uid={0})` and the received username + is `jdoe`, the search filter becomes `(uid=jdoe)` after string substitution. If + the resulting search filter is applied to the subtree selected by the user + base, `ou=User,ou=ActiveMQ,ou=system`, it would match the entry, + `uid=jdoe,ou=User,ou=ActiveMQ,ou=system` (and possibly more deeply nested + entries, depending on the specified search depthâsee the `userSearchSubtree` + option). + +- `userSearchSubtree` - specify the search depth for user entries, relative to + the node specified by `userBase`. This option is a boolean. `false` + indicates it will try to match one of the child entries of the `userBase` node + (maps to `javax.naming.directory.SearchControls.ONELEVEL_SCOPE`). `true` + indicates it will try to match any entry belonging to the subtree of the + `userBase` node (maps to + `javax.naming.directory.SearchControls.SUBTREE_SCOPE`). + +- `userRoleName` - 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. + +- `roleBase` - if you want to store role data directly in the directory server, + you can use a combination of role options (`roleBase`, `roleSearchMatching`, + `roleSearchSubtree`, and `roleName`) as an alternative to (or in addition to) + specifying the `userRoleName` 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 `ou=Group,ou=ActiveMQ,ou=system`, the search for role/group entries + is restricted to the subtree beneath the `ou=Group,ou=ActiveMQ,ou=system` node. + +- `roleName` - 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 + full DN of the role is used. + +- `roleSearchMatching` - specifies an LDAP search filter, which is applied to + the subtree selected by `roleBase`. This works in a similar manner to the + `userSearchMatching` option, except that it supports two substitution strings, + as follows: + + - `{0}` - substitutes the full DN of the matched user entry (that is, the + result of the user search). For example, for the user, `jdoe`, the + substituted string could be `uid=jdoe,ou=User,ou=ActiveMQ,ou=system`. + + - `{1}` - substitutes the received username. For example, `jdoe`. + + For example, if this option is set to `(member=uid={1})` and the received + username is `jdoe`, the search filter becomes `(member=uid=jdoe)` after string + substitution (assuming ApacheDS search filter syntax). If the resulting search + filter is applied to the subtree selected by the role base, + `ou=Group,ou=ActiveMQ,ou=system`, it matches all role entries that have a + `member` attribute equal to `uid=jdoe` (the value of a `member` attribute is a + DN). + + This option must always be set to enable role searching because it has no + default value. Leaving it unset disables role searching and the role + information must come from `userRoleName`. + + If you use OpenLDAP, the syntax of the search filter is + `(member:=uid=jdoe)`. + +- `roleSearchSubtree` - specify the search depth for role entries, relative to + the node specified by `roleBase`. This option can take boolean values, as + follows: + + - `false` (default) - try to match one of the child entries of the roleBase + node (maps to `javax.naming.directory.SearchControls.ONELEVEL_SCOPE`). + + - `true` â try to match any entry belonging to the subtree of the roleBase + node (maps to `javax.naming.directory.SearchControls.SUBTREE_SCOPE`). + +- `authenticateUser` - boolean flag to disable authentication. Useful as an + optimisation when this module is used just for role mapping of a Subject's + existing authenticated principals; default is `false`. + +- `referral` - specify how to handle referrals; valid values: `ignore`, + `follow`, `throw`; default is `ignore`. + +- `debug` - boolean flag; if `true`, enable debugging; this is used only for + testing or debugging; normally, it should be set to `false`, or omitted; + default is `false` + +Add user entries under the node specified by the `userBase` option. When +creating a new user entry in the directory, choose an object class that +supports the `userPassword` attribute (for example, the `person` or +`inetOrgPerson` object classes are typically suitable). After creating the user +entry, add the `userPassword` attribute, to hold the user's password. + +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 `roleBase` node, where the `objectClass` of the child is +`groupOfNames`. Set the `cn` (or whatever attribute type is specified by +`roleName`) of the new child node equal to the name of the role/group. Define a +`member` attribute for each member of the role/group, setting the `member` +value to the DN of the corresponding user (where the DN is specified either +fully, `uid=jdoe,ou=User,ou=ActiveMQ,ou=system`, or partially, `uid=jdoe`). + +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. #### CertificateLoginModule -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: +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: -- 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. +- 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. -- To associate a list of groups with the received user identity, facilitating integration with the authorization feature. +- To associate a list of groups with the received user identity, facilitating + integration with the authorization feature. -- 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). +- 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). -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. +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. The certificate login module is implemented by the following class: - org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule +```java +org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule +``` -The following `CertLogin` login entry shows how to configure certificate login module in the login.config file: +The following `CertLogin` login entry shows how to configure certificate login +module in the login.config file: - 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"; - }; +``` +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"; +}; +``` -In the preceding example, the JAAS realm is configured to use a single `org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule` +In the preceding example, the JAAS realm is configured to use a single +`org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule` login module. The options supported by this login module are as follows: - `debug` - boolean flag; if true, enable debugging; this is used only for testing or debugging; normally, @@ -632,116 +781,183 @@ compares it with the subject DNs in the `users.properties` file by testing for s be careful to ensure that the subject DNs appearing in the `users.properties` file are an exact match for the subject DNs extracted from the user certificates. -Note: Technically, there is some residual ambiguity in the DN string format. For example, the `domainComponent` attribute -could be represented in a string either as the string, `DC`, or as the OID, `0.9.2342.19200300.100.1.25`. 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. - -The easiest way to obtain the subject DNs from the user certificates is by invoking the `keytool` utility to print the -certificate contents. To print the contents of a certificate in a keystore, perform the following steps: +- `org.apache.activemq.jaas.textfiledn.user` - specifies the location of the + user properties file (relative to the directory containing the login + configuration file). -1. Export the certificate from the keystore file into a temporary file. For example, to export the certificate with - alias `broker-localhost` from the `broker.ks` keystore file, enter the following command: +- `org.apache.activemq.jaas.textfiledn.role` - specifies the location of the + role properties file (relative to the directory containing the login + configuration file). - keytool -export -file broker.export -alias broker-localhost -keystore broker.ks -storepass password +- `reload` - boolean flag; whether or not to reload the properties files when a + modification occurs; default is `false` - After running this command, the exported certificate is in the file, `broker.export`. +In the context of the certificate login module, the `users.properties` file +consists of a list of properties of the form, `UserName=StringifiedSubjectDN`. +For example, to define the users, system, user, and guest, you could create a +file like the following: -1. Print out the contents of the exported certificate. For example, to print out the contents of `broker.export`, - enter the following command: - - keytool -printcert -file broker.export - - Which should produce output similar to that shown here: - - 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: - 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 - - The string following `Owner:` gives the subject DN. The format used to enter the subject DN depends on your - platform. The `Owner:` string above could be represented as either `CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ ST=Unknown,\ C=Unknown` - or `CN=localhost,OU=broker,O=Unknown,L=Unknown,ST=Unknown,C=Unknown`. - -The `roles.properties` file consists of a list of properties of the form, `Role=UserList`, where `UserList` is a -comma-separated list of users. For example, to define the roles `admins`, `users`, and `guests`, you could create a file -like the following: +```properties +system=CN=system,O=Progress,C=US +user=CN=humble user,O=Progress,C=US +guest=CN=anon,O=Progress,C=DE +``` - admins=system - users=system,user - guests=guest +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 `CN=system,O=Progress,C=US` 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 +`users.properties` file by testing for string equality. Consequently, you must +be careful to ensure that the subject DNs appearing in the `users.properties` +file are an exact match for the subject DNs extracted from the user +certificates. + +**Note:** Technically, there is some residual ambiguity in the DN string format. +For example, the `domainComponent` attribute could be represented in a string +either as the string, `DC`, or as the OID, `0.9.2342.19200300.100.1.25`. +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. + +The easiest way to obtain the subject DNs from the user certificates is by +invoking the `keytool` utility to print the certificate contents. To print the +contents of a certificate in a keystore, perform the following steps: + +1. Export the certificate from the keystore file into a temporary file. For + example, to export the certificate with alias `broker-localhost` from the +`broker.ks` keystore file, enter the following command: + + ```sh + keytool -export -file broker.export -alias broker-localhost -keystore broker.ks -storepass password + ``` + + After running this command, the exported certificate is in the file, + `broker.export`. + +1. Print out the contents of the exported certificate. For example, to print + out the contents of `broker.export`, enter the following command: + + ```sh + keytool -printcert -file broker.export + ``` + + Which should produce output similar to that shown here: + + ``` + 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: + 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 + ``` + + The string following `Owner:` gives the subject DN. The format used to enter + the subject DN depends on your platform. The `Owner:` string above could be + represented as either `CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ + ST=Unknown,\ C=Unknown` or + `CN=localhost,OU=broker,O=Unknown,L=Unknown,ST=Unknown,C=Unknown`. + +The `roles.properties` file consists of a list of properties of the form, +`Role=UserList`, where `UserList` is a comma-separated list of users. For +example, to define the roles `admins`, `users`, and `guests`, you could create +a file like the following: + +```properties +admins=system +users=system,user +guests=guest +``` -The simplest way to make the login configuration available to JAAS is to add the directory containing the file, -`login.config`, to your CLASSPATH. +The simplest way to make the login configuration available to JAAS is to add +the directory containing the file, `login.config`, to your CLASSPATH. ### Kerberos Authentication -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 +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 [Krb5LoginModule](https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html) -which executes the necessary Kerberos protocol steps to authenticate and obtain Kerberos credentials. +which executes the necessary Kerberos protocol steps to authenticate and obtain +Kerberos credentials. #### GSSAPI SASL Mechanism -Using SASL over [AMQP](using-AMQP.md), Kerberos authentication is supported using the `GSSAPI` SASL mechanism. -With SASL doing Kerberos authentication, TLS can be used to provide integrity and confidentially to the communications +Using SASL over [AMQP](using-AMQP.md), Kerberos authentication is supported +using the `GSSAPI` 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 `GSSAPI` SASL mechanism must be enabled on the AMQP acceptor in `broker.xml` by adding it to the `saslMechanisms` list url parameter: + +The `GSSAPI` SASL mechanism must be enabled on the AMQP acceptor in +`broker.xml` by adding it to the `saslMechanisms` list url parameter: `saslMechanisms="GSSAPI<,PLAIN, etc>`. - <acceptor name="amqp">tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI</acceptor> +```xml +<acceptor name="amqp">tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI</acceptor> +``` -The GSSAPI mechanism implementation on the server will use a JAAS configuration scope named `amqp-sasl-gssapi` to -obtain it's Kerberos acceptor credentials. An alternative configuration scope can be specified on the AMQP acceptor -using the url parameter: `saslLoginConfigScope=<some other scope>`. +The GSSAPI mechanism implementation on the server will use a JAAS configuration +scope named `amqp-sasl-gssapi` to obtain it's Kerberos acceptor credentials. An +alternative configuration scope can be specified on the AMQP acceptor using the +url parameter: `saslLoginConfigScope=<some other scope>`. -An example configuration scope for `login.config` that will pick up a Kerberos keyTab for the Kerberos acceptor Principal -`amqp/localhost` is as follows: +An example configuration scope for `login.config` that will pick up a Kerberos +keyTab for the Kerberos acceptor Principal `amqp/localhost` is as follows: - amqp-sasl-gssapi { - com.sun.security.auth.module.Krb5LoginModule required - isInitiator=false - storeKey=true - useKeyTab=true - principal="amqp/localhost" - debug=true; - }; +``` +amqp-sasl-gssapi { + com.sun.security.auth.module.Krb5LoginModule required + isInitiator=false + storeKey=true + useKeyTab=true + principal="amqp/localhost" + debug=true; +}; +``` #### Role Mapping -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 `Krb5LoginModule` login module. The [PropertiesLoginModule](#propertiesloginmodule) or - [LDAPLoginModule](#ldaploginmodule) can then be used to map -the authenticated Kerberos Peer Principal to an Apache ActiveMQ Artemis [Role](#role-based-security-for-addresses). Note -that the Kerberos Peer Principal does not exist as an Apache ActiveMQ Artemis user, only as a role member. - - org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required - ; - org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional - initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory - connectionURL="ldap://localhost:1024"; - authentication=GSSAPI - saslLoginConfigScope=broker-sasl-gssapi - connectionProtocol=s - userBase="ou=users,dc=example,dc=com" - userSearchMatching="(krb5PrincipalName={0})" - userSearchSubtree=true - authenticateUser=false - roleBase="ou=system" - roleName=cn - roleSearchMatching="(member={0})" - roleSearchSubtree=false - ; +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 `Krb5LoginModule` login module. The +[PropertiesLoginModule](#propertiesloginmodule) or +[LDAPLoginModule](#ldaploginmodule) can then be used to map the authenticated +Kerberos Peer Principal to an Apache ActiveMQ Artemis +[Role](#role-based-security-for-addresses). Note that the Kerberos Peer +Principal does not exist as an Apache ActiveMQ Artemis user, only as a role +member. + +``` +org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required + ; +org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional + initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory + connectionURL="ldap://localhost:1024"; + authentication=GSSAPI + saslLoginConfigScope=broker-sasl-gssapi + connectionProtocol=s + userBase="ou=users,dc=example,dc=com" + userSearchMatching="(krb5PrincipalName={0})" + userSearchSubtree=true + authenticateUser=false + roleBase="ou=system" + roleName=cn + roleSearchMatching="(member={0})" + roleSearchSubtree=false + ; +``` #### TLS Kerberos Cipher Suites -The legacy [rfc2712](https://www.ietf.org/rfc/rfc2712.txt) 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 *unsecure* channel. +The legacy [rfc2712](https://www.ietf.org/rfc/rfc2712.txt) 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 *unsecure* +channel. ## SASL @@ -751,81 +967,95 @@ Note: EXTERNAL will only be chosen if a subject is available from the TLS client ## Changing the username/password for clustering -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. +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. Please see [Management](management.md) for instructions on how to do this. ## Securing the console -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 `bootstrap.xml`: +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 `bootstrap.xml`: - <web bind="http://localhost:8161"; path="web"> - <app url="console" war="console.war"/> - </web> +```xml +<web bind="http://localhost:8161"; path="web"> + <app url="console" war="console.war"/> +</web> +``` -Alternatively you can edit the above configuration to enable secure access using HTTPS protocol. e.g.: +Alternatively you can edit the above configuration to enable secure access +using HTTPS protocol. e.g.: - <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> +```xml +<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> +``` -As shown in the example, to enable https the first thing to do is config the `bind` to be an `https` url. In addition, -You will have to configure a few extra properties desribed as below. +As shown in the example, to enable https the first thing to do is config the +`bind` to be an `https` url. In addition, You will have to configure a few +extra properties desribed as below. -- `keyStorePath` - The path of the key store file. +- `keyStorePath` - The path of the key store file. -- `keyStorePassword` - The key store's password. +- `keyStorePassword` - The key store's password. -- `clientAuth` - The boolean flag indicates whether or not client authentication is required. Default is `false`. +- `clientAuth` - The boolean flag indicates whether or not client + authentication is required. Default is `false`. -- `trustStorePath` - The path of the trust store file. This is needed only if `clientAuth` is `true`. +- `trustStorePath` - The path of the trust store file. This is needed only if + `clientAuth` is `true`. -- `trustStorePassword` - The trust store's password. +- `trustStorePassword` - The trust store's password. ## Controlling JMS ObjectMessage deserialization -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. - -Artemis keeps a `black list` to keep track of packages that are not trusted and a `white list` -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 `black list` -nor with the `white list`, the class deserialization will be denied -unless the white list is empty (meaning the user doesn't specify the white list at all). +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. + +Artemis keeps a `black list` to keep track of packages that are not trusted and +a `white list` 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 `black list` +nor with the `white list`, the class deserialization will be denied unless the +white list is empty (meaning the user doesn't specify the white list at all). A class is considered as a 'match' if -- its full name exactly matches one of the entries in the list. -- its package matches one of the entries in the list or is a sub-package of one of the entries. +- its full name exactly matches one of the entries in the list. +- its package matches one of the entries in the list or is a sub-package of one + of the entries. -For example, if a class full name is "org.apache.pkg1.Class1", some matching entries could be: +
<TRUNCATED>
