From c2be2d452c6c8bcb0675bc2a8f154c3d17bdf32a Mon Sep 17 00:00:00 2001 From: jbertram Date: Tue, 19 Jan 2016 10:01:47 -0600 Subject: [PATCH] ARTEMIS-352 security examples readme fix --- .../standard/security-ldap/readme.html | 101 ++++++++++++------ .../src/main/resources/example.ldif | 2 +- .../features/standard/security/readme.html | 53 ++++----- 3 files changed, 90 insertions(+), 66 deletions(-) diff --git a/examples/features/standard/security-ldap/readme.html b/examples/features/standard/security-ldap/readme.html index fad945a7c1..430b319104 100644 --- a/examples/features/standard/security-ldap/readme.html +++ b/examples/features/standard/security-ldap/readme.html @@ -25,12 +25,12 @@ under the License. -

JMS Security Example

+

JMS Security LDAP Example

To run the example, simply type mvn verify from this directory, 
or mvn -PnoServer verify if you want to start and create the server manually.
-

This example shows how to configure and use security using ActiveMQ Artemis with LDAP.

+

This example shows how to configure and use security using ActiveMQ Artemis and the Apache DS LDAP server.

With security properly configured, ActiveMQ Artemis can restrict client access to its resources, including connection creation, message sending/receiving, etc. This is done by configuring users and roles as well as permissions in @@ -42,41 +42,81 @@ under the License.

For a full description of how to configure security with ActiveMQ Artemis, please consult the user manual.

-

This example demonstrates how to configure users/roles, how to configure topics with proper permissions using wild-card - expressions, and how they take effects in a simple program.

+

This example demonstrates how to configure users/roles in the Apache DS LDAP server, how to configure topics with + proper permissions using wild-card expressions, and how they take effects in a simple program.

-

First we need to configure users with roles. Users and Roles are configured in activemq-users.xml. This example has four users - configured as below

+

Users and roles are configured in Apache DS. The SecurityExample class will start an embedded version of Apache + DS and load the contents of example.ldif which contains the users and passwords for this example.

      
-		   <user name="bill" password="activemq">
-		      <role name="user"/>
-		   </user>
+         dn: dc=activemq,dc=org
+         dc: activemq
+         objectClass: top
+         objectClass: domain
 
-		   <user name="andrew" password="activemq1">
-		      <role name="europe-user"/>
-		      <role name="user"/>
-		   </user>
+         dn: uid=bill,dc=activemq,dc=org
+         uid: bill
+         userPassword: activemq
+         objectClass: account
+         objectClass: simpleSecurityObject
+         objectClass: top
 
-		   <user name="frank" password="activemq2">
-		      <role name="us-user"/>
-		      <role name="news-user"/>
-		      <role name="user"/>
-		   </user>
+         dn: uid=andrew,dc=activemq,dc=org
+         uid: andrew
+         userPassword: activemq1
+         objectClass: account
+         objectClass: simpleSecurityObject
+         objectClass: top
 
-		   <user name="sam" password="activemq3">
-		      <role name="news-user"/>
-		      <role name="user"/>
-		   </user>
+         dn: uid=frank,dc=activemq,dc=org
+         uid: frank
+         userPassword: activemq2
+         objectClass: account
+         objectClass: simpleSecurityObject
+         objectClass: top
+
+         dn: uid=sam,dc=activemq,dc=org
+         uid: sam
+         userPassword: activemq3
+         objectClass: account
+         objectClass: simpleSecurityObject
+         objectClass: top
+
+         ###################
+         ## Define roles ##
+         ###################
+
+         dn: cn=user,dc=activemq,dc=org
+         cn: user
+         member: uid=bill,dc=activemq,dc=org
+         member: uid=andrew,dc=activemq,dc=org
+         member: uid=frank,dc=activemq,dc=org
+         member: uid=sam,dc=activemq,dc=org
+         objectClass: groupOfNames
+         objectClass: top
+
+         dn: cn=europe-user,dc=activemq,dc=org
+         cn: europe-user
+         member: uid=andrew,dc=activemq,dc=org
+         objectClass: groupOfNames
+         objectClass: top
+
+         dn: cn=news-user,dc=activemq,dc=org
+         cn: news-user
+         member: uid=frank,dc=activemq,dc=org
+         member: uid=sam,dc=activemq,dc=org
+         objectClass: groupOfNames
+         objectClass: top
+
+         dn: cn=us-user,dc=activemq,dc=org
+         cn: us-user
+         member: uid=frank,dc=activemq,dc=org
+         objectClass: groupOfNames
+         objectClass: top
-

- Each user has three properties available: user name, password, and roles it belongs to. It should be noted that - a user can belong to more than one role. In the above configuration, all users belong to role 'user'. User 'andrew' also - belongs to role 'europe-user', user 'frank' also belongs to 'us-user' and 'news-user' and user 'sam' also belongs to 'news-user'. -

User name and password consists of a valid account that can be used to establish connections to a ActiveMQ Artemis server, while roles are used in controlling the access privileges against ActiveMQ Artemis topics and queues. You can achieve this control by @@ -129,13 +169,8 @@ under the License.

To illustrate the effect of permissions, three topics are deployed. Topic 'genericTopic' matches 'jms.topic.#' wild-card, topic 'news.europe.europeTopic' matches jms.topic.news.europe.#' wild-cards, and topic 'news.us.usTopic' matches 'jms.topic.news.us.#'.

-

With ActiveMQ Artemis, the security manager is also configurable. You can use JAASSecurityManager or JBossASSecurityManager based on you need. Please - check out the activemq-beans.xml for how to do. In this example we just use the basic ActiveMQSecurityManagerImpl which reads users/roles/passwords from the xml - file activemq-users.xml. - -

Example step-by-step

-

To run the example, simply type mvn verify -Pexample from this directory

+

To run the example, simply type mvn verify from this directory

  1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config
    2. diff --git a/examples/features/standard/security-ldap/src/main/resources/example.ldif b/examples/features/standard/security-ldap/src/main/resources/example.ldif index da135dadc6..169fbce062 100644 --- a/examples/features/standard/security-ldap/src/main/resources/example.ldif +++ b/examples/features/standard/security-ldap/src/main/resources/example.ldif @@ -49,7 +49,7 @@ objectClass: simpleSecurityObject objectClass: top ################### -## Define groups ## +## Define roles ## ################### dn: cn=user,dc=activemq,dc=org diff --git a/examples/features/standard/security/readme.html b/examples/features/standard/security/readme.html index d25dd4295e..749ed794ee 100644 --- a/examples/features/standard/security/readme.html +++ b/examples/features/standard/security/readme.html @@ -45,38 +45,32 @@ under the License.

    This example demonstrates how to configure users/roles, how to configure topics with proper permissions using wild-card expressions, and how they take effects in a simple program.

    -

    First we need to configure users with roles. Users and Roles are configured in activemq-users.xml. This example has four users - configured as below

    +

    First we need to configure users with roles. For this example, users and roles are configured in artemis-users.properties + and artemis-roles.properties. The artemis-users.properties file follows the syntax of + <user>=<password>. This example has four users configured as below 

          
-		   <user name="bill" password="activemq">
-		      <role name="user"/>
-		   </user>
-
-		   <user name="andrew" password="activemq1">
-		      <role name="europe-user"/>
-		      <role name="user"/>
-		   </user>
-
-		   <user name="frank" password="activemq2">
-		      <role name="us-user"/>
-		      <role name="news-user"/>
-		      <role name="user"/>
-		   </user>
-
-		   <user name="sam" password="activemq3">
-		      <role name="news-user"/>
-		      <role name="user"/>
-		   </user>
+         bill=activemq
+         andrew=activemq1
+         frank=activemq2
+         sam=activemq3
+     
+
    + +

    The artemis-roles.properties file follows the syntax of <role>=<users> where <users> can be + a comma-separated list of users from artemis-users.properties (since more than one user can belong in a + particular role). This example has four roles configured as below

    + + 
    +     
+         user=bill,andrew,frank,sam
+         europe-user=andrew
+         news-user=frank,sam
+         us-user=frank
    -

    - Each user has three properties available: user name, password, and roles it belongs to. It should be noted that - a user can belong to more than one role. In the above configuration, all users belong to role 'user'. User 'andrew' also - belongs to role 'europe-user', user 'frank' also belongs to 'us-user' and 'news-user' and user 'sam' also belongs to 'news-user'. -

    User name and password consists of a valid account that can be used to establish connections to a ActiveMQ Artemis server, while roles are used in controlling the access privileges against ActiveMQ Artemis topics and queues. You can achieve this control by @@ -129,13 +123,8 @@ under the License.

    To illustrate the effect of permissions, three topics are deployed. Topic 'genericTopic' matches 'jms.topic.#' wild-card, topic 'news.europe.europeTopic' matches jms.topic.news.europe.#' wild-cards, and topic 'news.us.usTopic' matches 'jms.topic.news.us.#'.

    -

    With ActiveMQ Artemis, the security manager is also configurable. You can use JAASSecurityManager or JBossASSecurityManager based on you need. Please - check out the activemq-beans.xml for how to do. In this example we just use the basic ActiveMQSecurityManagerImpl which reads users/roles/passwords from the xml - file activemq-users.xml. - -

    Example step-by-step

    -

    To run the example, simply type mvn verify -Pexample from this directory

    +

    To run the example, simply type mvn verify from this directory

    1. First we need to get an initial context so we can look-up the JMS connection factory and destination objects from JNDI. This initial context will get it's properties from the client-jndi.properties file in the directory ../common/config