You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by sm...@apache.org on 2023/06/23 21:41:53 UTC
[directory-fortress-enmasse] branch master updated: 3.0 preps, formatting, parameterize version
This is an automated email from the ASF dual-hosted git repository.
smckinney pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/directory-fortress-enmasse.git
The following commit(s) were added to refs/heads/master by this push:
new 4d9240d 3.0 preps, formatting, parameterize version
4d9240d is described below
commit 4d9240de158fa8bcbeb49d7668f8a589f8503638
Author: Shawn McKinney <sm...@symas.com>
AuthorDate: Fri Jun 23 16:41:47 2023 -0500
3.0 preps, formatting, parameterize version
---
README-MULTITENANCY.md | 42 +++----
README-QUICKSTART.md | 72 ++++++------
README-SECURITY-MODEL.md | 6 +-
README.md | 288 +++++++++++++++++++++++------------------------
4 files changed, 205 insertions(+), 203 deletions(-)
diff --git a/README-MULTITENANCY.md b/README-MULTITENANCY.md
index 4e3054f..f7e3aec 100644
--- a/README-MULTITENANCY.md
+++ b/README-MULTITENANCY.md
@@ -44,17 +44,17 @@ For an overview of how fortress multitenancy works:
Fortress Realm uses the tenant id inside the context.xml file:
- ```
- <Context path="/commander" reloadable="true">
-
- <Realm className="org.apache.directory.fortress.realm.tomcat.Tc7AccessMgrProxy"
- defaultRoles=""
- containerType="TomcatContext"
- realmClasspath=""
- contextId="HOME"
- />
- </Context>
- ```
+```xml
+<Context path="/commander" reloadable="true">
+
+ <Realm className="org.apache.directory.fortress.realm.tomcat.Tc7AccessMgrProxy"
+ defaultRoles=""
+ containerType="TomcatContext"
+ realmClasspath=""
+ contextId="HOME"
+ />
+</Context>
+```
* In this example, all realm security checks are bound for the HOME tenant.
@@ -63,15 +63,15 @@ Fortress Realm uses the tenant id inside the context.xml file:
Fortress Rest uses the tenant id found inside the request *contextId* element:
- ```
- <FortRequest>
- <contextId>acme123</contextId>
- <entity xsi:type="permission" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <objName></objName>
- <opName></opName>
- </entity>
- </FortRequest>
- ```
+```xml
+<FortRequest>
+ <contextId>acme123</contextId>
+ <entity xsi:type="permission" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <objName></objName>
+ <opName></opName>
+ </entity>
+</FortRequest>
+```
* This operation is scoped to tenat acme123's subtree.
@@ -83,4 +83,4 @@ Why are there are two locations for setting the tenant id?
* The setting in the meta-inf file determines where the caller's HTTP basic auth credentials are validated.
* The contextId in the request determines the subtree the request's operation is bound to.
___________________________________________________________________________________
-#### END OF README-MULTITENANCY
\ No newline at end of file
+#### END OF README-MULTITENANCY
diff --git a/README-QUICKSTART.md b/README-QUICKSTART.md
index 5aba675..d5a285a 100644
--- a/README-QUICKSTART.md
+++ b/README-QUICKSTART.md
@@ -16,7 +16,7 @@
under the License.
# README-QUICKSTART for Apache Fortress Rest
- * version 2.0.8
+ * version 3.0.0
-------------------------------------------------------------------------------
## Table of Contents
@@ -37,7 +37,7 @@ This document contains instructions to deploy a pre-built Apache Fortress Rest w
## SECTION 1. Prerequisites
Minimum software requirements:
- * Java SDK >= 11
+ * Java SDK >= 17
* Apache Maven >= 3
* Apache Tomcat >= 10
* git
@@ -57,9 +57,9 @@ Set the java system properties in tomcat with the target ldap server's coordinat
a. For OpenLDAP:
- ```
- JAVA_OPTS="-Dversion=2.0.8 -Dfortress.admin.user=cn=Manager,dc=example,dc=com -Dfortress.admin.pw=secret -Dfortress.config.root=ou=Config,dc=example,dc=com"
- ```
+```
+JAVA_OPTS="-Dversion=[version] -Dfortress.admin.user=cn=Manager,dc=example,dc=com -Dfortress.admin.pw=secret -Dfortress.config.root=ou=Config,dc=example,dc=com"
+```
b. For ApacheDS:
```
@@ -70,19 +70,21 @@ Set the java system properties in tomcat with the target ldap server's coordinat
#### 4. Download the fortress realm proxy jar into tomcat/lib folder:
- ```
- wget https://repo.maven.apache.org/maven2/org/apache/directory/fortress/fortress-realm-proxy/2.0.8/fortress-realm-proxy-2.0.8.jar -P $TOMCAT_HOME/lib
- ```
+```bash
+wget https://repo.maven.apache.org/maven2/org/apache/directory/fortress/fortress-realm-proxy/[version]/fortress-realm-proxy-[version].jar -P $TOMCAT_HOME/lib
+```
where *TOMCAT_HOME* matches your target env.
+ where *[version]* is a particular fortress release, e.g. 3.0.0.
#### 5. Download the fortress rest war into tomcat/webapps folder:
- ```
- wget http://repo.maven.apache.org/maven2/org/apache/directory/fortress/fortress-rest/2.0.8/fortress-rest-2.0.8.war -P $TOMCAT_HOME/webapps
- ```
+```bash
+wget http://repo.maven.apache.org/maven2/org/apache/directory/fortress/fortress-rest/[version]/fortress-rest-[version].war -P $TOMCAT_HOME/webapps
+```
where *TOMCAT_HOME* matches your target env.
+ where *[version]* is a particular fortress release, e.g. 3.0.0.
#### 6. Restart Tomcat.
@@ -92,40 +94,40 @@ ________________________________________________________________________________
#### 1. Git the package.
a. from git:
- ```
- git clone --branch 2.0.8 https://gitbox.apache.org/repos/asf/directory-fortress-enmasse.git
- cd directory-fortress-enmasse
- mvn clean install
- ```
+```bash
+git clone --branch [version] https://gitbox.apache.org/repos/asf/directory-fortress-enmasse.git
+cd directory-fortress-enmasse
+mvn clean install
+```
b. or [apache fortress downloads](https://directory.apache.org/fortress/download/download-sources.html)
- ```
- unzip fortress-rest-2.0.8.zip
- cd fortress-rest-2.0.8
- mvn clean install
- ```
+```bash
+unzip fortress-rest-[version].zip
+cd fortress-rest-[version]
+mvn clean install
+```
#### 2. From the project folder, run maven install to Apache Fortress RBAC security policy for Rest server:
- ```maven
- mvn install -Dload.file=src/main/resources/FortressRestServerPolicy.xml
- ```
+```bash
+mvn install -Dload.file=src/main/resources/FortressRestServerPolicy.xml
+```
* This step creates test user, roles, needed for tests to be successfully run.
#### 3. Optional, load a sample security policy for ARBAC.
- ```maven
- mvn install -Dload.file=src/main/resources/FortressRestArbacSamplePolicy.xml
- ```
+```bash
+mvn install -Dload.file=src/main/resources/FortressRestArbacSamplePolicy.xml
+```
* See [README-SECURITY-MODEL](./README-SECURITY-MODEL.md)
___________________________________________________________________________________
## SECTION 4. Test
#### 1. Smoke test a few services:
- ```
- mvn test -Dtest=EmTest
- ```
+```bash
+mvn test -Dtest=EmTest
+```
#### 2. Complete *SECTION 7: Alternate testing procedures* in [Fortress Core README.md](https://github.com/apache/directory-fortress-enmasse/blob/master/README.md)
___________________________________________________________________________________
@@ -162,8 +164,8 @@ ________________________________________________________________________________
Setting Apache Fortress external configurations via Java System properties can be done using the startup scripts for the server instance. For example, the following are valid configurations.
a. Connect to an OpenLDAP over localhost, port 389 (defaults) using unencrypted connections. The runtime has ARBAC02 checks enabled.
- ```concept
-JAVA_OPTS=" -Dversion=2.0.8 \
+```concept
+JAVA_OPTS=" -Dversion=[version] \
-Dfortress.admin.user=cn=Manager,dc=example,dc=com \
-Dfortress.admin.pw=secret \
-Dfortress.config.root=ou=Config,dc=example,dc=com \
@@ -171,8 +173,8 @@ JAVA_OPTS=" -Dversion=2.0.8 \
-Dfortress.is.arbac02=true"
```
b. Connect to ApacheDS server over an encrypted connection, the truststore found on the classpath.
- ```concept
-JAVA_OPTS=" -Dversion=2.0.8 \
+```concept
+JAVA_OPTS=" -Dversion=[version] \
-Dfortress.host=mydomainname.com \
-Dfortress.port=1636 \
-Dfortress.ldap.server.type=apacheds \
@@ -187,7 +189,7 @@ JAVA_OPTS=" -Dversion=2.0.8 \
c. This one OpenLDAP again, use encrypted connections, truststore located on fully qualified path.
```concept
-JAVA_OPTS=" -Dversion=2.0.8 \
+JAVA_OPTS=" -Dversion=[version] \
-Dfortress.host=mydomainname.com \
-Dfortress.port=636 \
-Dfortress.ldap.server.type=openldap \
diff --git a/README-SECURITY-MODEL.md b/README-SECURITY-MODEL.md
index 646b6de..1eca460 100644
--- a/README-SECURITY-MODEL.md
+++ b/README-SECURITY-MODEL.md
@@ -189,7 +189,7 @@ c. Some services (#'s 9,10,11,12 in ARBAC table) perform a range check on the ta
b. Execute the policy load [FortressRestServerPolicy](./src/main/resources/FortressRestServerPolicy.xml) into LDAP:
-```maven
+```bash
mvn install -Dload.file=src/main/resources/FortressRestServerPolicy.xml
```
@@ -198,7 +198,7 @@ mvn install -Dload.file=src/main/resources/FortressRestServerPolicy.xml
## 6. ARBAC policy load
a. The ARBAC policies are enforced when the following property is present in runtime *fortress.properties*:
-```
+```properties
# Boolean value. Disabled by default. If this is set to true, the runtime will enforce administrative permissions and ARBAC02 DA checks:
is.arbac02=true
```
@@ -239,7 +239,7 @@ UserOUs="DEV0,DEV1,DEV2,DEV3,DEV4,DEV5,DEV6,DEV7,DEV8,DEV9,DEV10,
d. To load the [FortressRestArbacSamplePolicy](./src/main/resources/FortressRestArbacSamplePolicy.xml) into LDAP:
-```maven
+```bash
mvn install -Dload.file=src/main/resources/FortressRestArbacSamplePolicy.xml
```
diff --git a/README.md b/README.md
index 700ab0e..04d4c80 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@
under the License.
# README for Apache Fortress Rest
- * Version 2.0.8
+ * Version 3.0.0
* Apache Fortress Rest System Architecture Diagram
@@ -82,24 +82,24 @@ Everything else covered in steps that follow. Tested on Debian and Redhat syste
#### 1. Download the source.
a. from git:
- ```
- git clone --branch 2.0.8 https://gitbox.apache.org/repos/asf/directory-fortress-enmasse.git
- cd directory-fortress-enmasse
- ```
+```bash
+git clone --branch [version] https://gitbox.apache.org/repos/asf/directory-fortress-enmasse.git
+cd directory-fortress-enmasse
+```
b. or [apache fortress downloads](https://directory.apache.org/fortress/download/download-sources.html)
#### 2. Build the source.
- ```
- mvn clean install
- ```
+```bash
+mvn clean install
+```
#### 3. Now build the javadoc:
- ```
- mvn javadoc:javadoc
- ```
+```bash
+mvn javadoc:javadoc
+```
#### 4. View the generated document here: [./target/site/apidocs/overview-summary.html](./target/site/apidocs/overview-summary.html).
@@ -110,26 +110,27 @@ This web app uses Java EE security.
#### 1. Download the fortress realm proxy jar into tomcat/lib folder:
- ```bash
- wget https://repo.maven.apache.org/maven2/org/apache/directory/fortress/fortress-realm-proxy/2.0.8/fortress-realm-proxy-2.0.8.jar -P $TOMCAT_HOME/lib
- ```
+```bash
+wget https://repo.maven.apache.org/maven2/org/apache/directory/fortress/fortress-realm-proxy/[version]/fortress-realm-proxy-[version].jar -P $TOMCAT_HOME/lib
+```
* Where `$TOMCAT_HOME` points to the execution env.
+ * Where `[version]` points to the particular release, e.g. 3.0.0.
Note: The realm proxy enables Tomcat container-managed security functions to call back to fortress.
#### 2. Optional - Prepare tomcat to allow autodeploy of rbac-abac-sample web app:
- ```bash
- sudo vi /usr/local/tomcat8/conf/tomcat-users.xml
- ```
+```bash
+sudo vi /usr/local/tomcat10/conf/tomcat-users.xml
+```
#### 3. Optional - Add tomcat user to deploy rbac-abac-sample:
- ```xml
- <role rolename="manager-script"/>
- <user username="tcmanager" password="m@nager123" roles="manager-script"/>
- ```
+```xml
+<role rolename="manager-script"/>
+<user username="tcmanager" password="m@nager123" roles="manager-script"/>
+```
#### 4. Restart tomcat for new settings to take effect.
@@ -138,75 +139,75 @@ This web app uses Java EE security.
#### 1. Copy the fortress.properties example:
- ```bash
- cp src/main/resources/fortress.properties.example src/main/resources/fortress.properties
- ```
+```bash
+cp src/main/resources/fortress.properties.example src/main/resources/fortress.properties
+```
#### 2. Edit the file:
- ```bash
- vi src/main/resources/fortress.properties
- ```
+```bash
+vi src/main/resources/fortress.properties
+```
Pick either Apache Directory or OpenLDAP server:
a. Prepare fortress for ApacheDS usage:
- ```properties
- # This param tells fortress what type of ldap server in use:
- ldap.server.type=apacheds
+```properties
+# This param tells fortress what type of ldap server in use:
+ldap.server.type=apacheds
- # Use value from [Set Hostname Entry]:
- host=localhost
+# Use value from [Set Hostname Entry]:
+host=localhost
- # ApacheDS defaults to this:
- port=10389
+# ApacheDS defaults to this:
+port=10389
- # These credentials are used for read/write access to all nodes under suffix:
- admin.user=uid=admin,ou=system
- admin.pw=secret
- ```
+# These credentials are used for read/write access to all nodes under suffix:
+admin.user=uid=admin,ou=system
+admin.pw=secret
+```
-- Or --
b. Prepare fortress for OpenLDAP usage:
- ```properties
- # This param tells fortress what type of ldap server in use:
- ldap.server.type=openldap
+```properties
+# This param tells fortress what type of ldap server in use:
+ldap.server.type=openldap
- # Use value from [Set Hostname Entry]:
- host=localhost
+# Use value from [Set Hostname Entry]:
+host=localhost
- # OpenLDAP defaults to this:
- port=389
+# OpenLDAP defaults to this:
+port=389
- # These credentials are used for read/write access to all nodes under suffix:
- admin.user=cn=Manager,dc=example,dc=com
- admin.pw=secret
- ```
+# These credentials are used for read/write access to all nodes under suffix:
+admin.user=cn=Manager,dc=example,dc=com
+admin.pw=secret
+```
-------------------------------------------------------------------------------
## SECTION 5. Build and deploy directory-fortress-rest
#### 1. Verify the java and maven home env variables are set.
- ```maven
- mvn -version
- ```
+```maven
+mvn -version
+```
- This sample requires Java 8 and Maven 3 to be setup within the execution env.
+ This sample requires Java >= 17 and Maven >= 3 to be setup within the execution env.
#### 2. Load the default security policy for Fortress REST.
- ```
- mvn install -Dload.file=src/main/resources/FortressRestServerPolicy.xml
- ```
+```bash
+mvn install -Dload.file=src/main/resources/FortressRestServerPolicy.xml
+```
#### 3. Optional, load a sample security policy for ARBAC.
- ```maven
- mvn install -Dload.file=src/main/resources/FortressRestArbacSamplePolicy.xml
- ```
+```bash
+mvn install -Dload.file=src/main/resources/FortressRestArbacSamplePolicy.xml
+```
* See [README-SECURITY-MODEL](./README-SECURITY-MODEL.md)
* *-Dload.file* automatically loads the [directory-fortress-rest security policy](src/main/resources/FortressRestServerPolicy.xml) data into ldap.
@@ -215,38 +216,38 @@ This web app uses Java EE security.
#### 4. Deploy to Tomcat:
a. If using autodeploy feature, verify the Tomcat auto-deploy options are set correctly in the [pom.xml](pom.xml) file:
- ```xml
- <plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>tomcat-maven-plugin</artifactId>
- <version>1.0-beta-1</version>
- <configuration>
- ...
- <url>http://localhost:8080/manager/text</url>
- <path>/${project.artifactId}</path>
- <username>tcmanager</username>
- <password>m@nager123</password>
- </configuration>
- </plugin>
- ```
+```xml
+<plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>tomcat-maven-plugin</artifactId>
+ <version>1.0-beta-1</version>
+ <configuration>
+ ...
+ <url>http://localhost:8080/manager/text</url>
+ <path>/${project.artifactId}</path>
+ <username>tcmanager</username>
+ <password>m@nager123</password>
+ </configuration>
+</plugin>
+```
b. Now, automatically deploy to tomcat server:
- ```maven
- mvn clean tomcat:deploy
- ```
+```bash
+mvn clean tomcat:deploy
+```
c. To automatically redeploy sample app:
- ```maven
- mvn clean tomcat:redeploy
- ```
+```bash
+mvn clean tomcat:redeploy
+```
d. To manually deploy app to Tomcat:
- ```bash
- cp target/fortress-rest-[version].war $TOMCAT_HOME/webapps
- ```
+```bash
+cp target/fortress-rest-[version].war $TOMCAT_HOME/webapps
+```
* Where `$TOMCAT_HOME` points to the execution env.
@@ -254,9 +255,9 @@ ________________________________________________________________________________
## SECTION 6. Unit Test
Run unit test:
- ```
- mvn test -Dtest=EmTest
- ```
+```
+mvn test -Dtest=EmTest
+```
Test Notes:
* The Fortress Rest application must be deployed and running within your servlet container before the unit tests will complete successfully. If your app server
@@ -278,7 +279,7 @@ ________________________________________________________________________________
* Add these properties to slapd.properties or build.properties file:
- ```
+```properties
enable.mgr.impl.rest=true
# This user account is added automatically during deployment of fortress-rest via -Dload.file=./src/main/resources/FortressRestServerPolicy.xml:
@@ -287,30 +288,29 @@ http.pw=password
http.host=localhost
http.port=8080
http.protocol=http
-
- ```
+```
2. Next, from **FORTRESS_CORE_HOME** enter the following command:
- ```
- mvn install
- ```
+```
+mvn install
+```
* This will update the fortress.properties with the settings in the build and slapd.prooperties.
3. Now run the integration tests:
- ```
- mvn -Dtest=FortressJUnitTest test
- ```
+```
+mvn -Dtest=FortressJUnitTest test
+```
* If everything was setup correctly the Apache Fortress Core tests will drive the tests via Apache Fortress Rest calls.
4. Next, from **FORTRESS_CORE_HOME** enter the following command:
- ```
- mvn test -Pconsole
- ```
+```
+mvn test -Pconsole
+```
* Console operations will now run through Apache Fortress Rest.
@@ -323,28 +323,28 @@ This section describes the properties needed to control fortress rest.
The host name can be specified as a fully qualified domain name or IP address:
- ```
- # Host name and port of LDAP DIT:
- host=localhost
- port=10389
- ```
+```properties
+# Host name and port of LDAP DIT:
+host=localhost
+port=10389
+```
#### 2. LDAP Server type. Each LDAP server impl
- ```
- # If ApacheDS server:
- ldap.server.type=apacheds
- ```
+```properties
+# If ApacheDS server:
+ldap.server.type=apacheds
+```
- ```
- # Else if OpenLDAP server:
- ldap.server.type=openldap
- ```
+```properties
+# Else if OpenLDAP server:
+ldap.server.type=openldap
+```
- ```
- # Else leave blank:
- #ldap.server.type=other
- ```
+```properties
+# Else leave blank:
+#ldap.server.type=other
+```
* note: has different behavior on operations like password policies and audit. If using a 3rd type of server that isn't formally supported, leave blank or type is other.
@@ -352,24 +352,24 @@ This section describes the properties needed to control fortress rest.
This service account must have read/write privileges over the entire Fortress LDAP Directory Information Tree (DIT):
- ```
- # If ApacheDS it will look something like this:
- admin.user=uid=admin,ou=system
- admin.pw=secret
- ```
+```properties
+# If ApacheDS it will look something like this:
+admin.user=uid=admin,ou=system
+admin.pw=secret
+```
- ```
- # Else If OpenLDAP it will look something like this:
- admin.user=cn=Manager,dc=example,dc=com
- ```
+```properties
+# Else If OpenLDAP it will look something like this:
+admin.user=cn=Manager,dc=example,dc=com
+```
#### 4. Define the number of LDAP connections to use in the pool
- ```
- # This is min/max settings for LDAP connections. For testing and low-volume instances this will work:
- min.admin.conn=1
- max.admin.conn=10
- ```
+```properties
+# This is min/max settings for LDAP connections. For testing and low-volume instances this will work:
+min.admin.conn=1
+max.admin.conn=10
+```
Notes on connection pools:
* This setting will be proportional to the number of concurrent users but won't be one-to-one.
@@ -379,27 +379,27 @@ This section describes the properties needed to control fortress rest.
This will match your LDAP's server's config node per Fortress Core setup:
- ```
- # This node contains fortress properties stored on behalf of connecting LDAP clients:
- config.realm=DEFAULT
- config.root=ou=Config,dc=example,dc=com
- ```
+```properties
+# This node contains fortress properties stored on behalf of connecting LDAP clients:
+config.realm=DEFAULT
+config.root=ou=Config,dc=example,dc=com
+```
#### 6. If using LDAPS.
- ```
- # Used for SSL Connection to LDAP Server:
- enable.ldap.ssl=true
- enable.ldap.ssl.debug=true
- trust.store=/fully/qualified/path/and/file/name/to/java/truststore
- trust.store.password=changeit
- ```
+```properties
+# Used for SSL Connection to LDAP Server:
+enable.ldap.ssl=true
+enable.ldap.ssl.debug=true
+trust.store=/fully/qualified/path/and/file/name/to/java/truststore
+trust.store.password=changeit
+```
#### 7. If using ApacheDS and setting password policies, point to the correction location.
- ```
- # ApacheDS stores its password policies objects here by default:
- apacheds.pwpolicy.root=ou=passwordPolicies,ads-interceptorId=authenticationInterceptor,ou=interceptors,ads-directoryServiceId=default,ou=config
- ```
+```properties
+# ApacheDS stores its password policies objects here by default:
+apacheds.pwpolicy.root=ou=passwordPolicies,ads-interceptorId=authenticationInterceptor,ou=interceptors,ads-directoryServiceId=default,ou=config
+```
#### END OF README