ldapcon-readme

Last Updated: 6 November, 2015

README APACHE FORTRESS END-TO-END SECURITY TUTORIAL:
----------------------------------------------------------------------

Covers these sections:
SECTION I - Machine Setup:
SECTION II - Apache Fortress Ten Minute Guide:
SECTION III - Apache Fortress End-to-End Security Tutorial
SECTION IV - Wicket Sample
SECTION V - Role Engineering Sample
SECTION VI - Fortress SAML Sample (Takes a couple of hours, probably better to try this one at home)

Sections 1 & 2 are required.
Sections 3 - 6 may be performed in any order.

****************************************************************************
---------------------------------------------------------------------------
SECTION I - Machine Setup:
---------------------------------------------------------------------------
****************************************************************************
During this section you will connect to the host machine that is running inside a public cloud.  This will be your test machine for the duration of the tutorial.

1. Obtain IP, hostname and creds for century-link cloud virtual machine from instructor.

2. Add hostname entry to your machine

3. log in using ssh:

ssh student@host-name
pw is F0rtr3ss

All of the source necessary to complete the tutorial has been staged under this folder:
/home/student/fortress

includes:
directory-fortress-core
directory-fortress-realm
directory-fortress-web
directory-fortress-rest
apache-fortress-demo
fortress-saml-demo
role-engineering-demo
wicket-sample

Additionally Tomcat and MySQL have both been installed and setup.  You will be required to enable each for SSL later in the tutorial.

****************************************************************************
---------------------------------------------------------------------------
SECTION II - Apache Fortress Ten Minute Guide:
---------------------------------------------------------------------------
****************************************************************************

During this section, you will be asked to install the prerequisite infrastructure for the end-to-end security tutorial.  Included are and ldap and web server used by the apache fortress system.

1. Open browser url to: http://symas.com/javadocs/apache-fortress-core/org/apache/directory/fortress/core/doc-files/ten-minute-guide.html

Follow the Steps to:
---------------------------------------------------------------------------
A. Setup Apache Directory Server
---------------------------------------------------------------------------

- Always use sudo when executing apacheds command.

- Don't need to download or extract, start with this:
sudo ./apacheds-2.0.0-M20-64bit.bin

- Step 4, place this location for java inside wrapper.conf file:
wrapper.java.command=/opt/jdk1.7.0_79/bin/java

---------------------------------------------------------------------------
B. Setup Apache Directory Studio
---------------------------------------------------------------------------
Skip Apache Directory Studio Setup

---------------------------------------------------------------------------
C. Build Apache Fortress Core
---------------------------------------------------------------------------

- Step 7, Don’t use Apache Directory Studio for schema import, instead do this:
ldapmodify -h localhost -p 10389 -D uid=admin,ou=system -w secret -a -f /home/student/fortress/directory-fortress-core/ldap/schema/apacheds-fortress.ldif

---------------------------------------------------------------------------
D. Build Apache Fortress Realm
---------------------------------------------------------------------------

- Run the maven install command:
cd directory-fortress-realm
mvn clean install

---------------------------------------------------------------------------
E. Setup Apache Tomcat Web Server
---------------------------------------------------------------------------
Already installed and setup

- Startup: server (as sudo or root):
/usr/local/tomcat7/bin/startup.sh

- Check the logs:
tail -f -n10000 /usr/local/tomcat7/logs/catalina.out

---------------------------------------------------------------------------
F. Build Apache Fortress Web
---------------------------------------------------------------------------
- Step 3, copy properties file using this command:
cp /home/student/directory-fortress-core/config/fortress.properties /home/student/directory-fortress-commander/src/main/resources

- Step 9, Skip the Selenium integration tests.          

- Open browser and test:
https://hostname:8080/fortress-web
creds: test/password

- Click on the links, to pull up various views on the data stored in apacheds.

---------------------------------------------------------------------------
G. Build Apache Fortress Rest
---------------------------------------------------------------------------
- You may skip this one.

****************************************************************************
---------------------------------------------------------------------------
SECTION III - Apache Fortress End-to-End Security Tutorial
---------------------------------------------------------------------------
****************************************************************************

During this section, you will be asked to setup cryptography keys and enable the usage of the apache fortress demo infrastructure over TLS (web, ldap and database servers).  After the necessary
infrastructure changes have been make, the application itself will be built and deployed to Tomcat.  Finally you may follow the test cases as described in the apache fortress demo javadoc.

- On your local machine, open browser, point to url: http://symas.com/javadocs/apache-fortress-demo/
Follow the Steps to:

---------------------------------------------------------------------------
A. Managing PKI Keys
---------------------------------------------------------------------------
always just use 'changeit' for password

- Step 2. b. vi : When creating a new certificate, You must use the actual hostname of machine for the value of the 'common name'.

---------------------------------------------------------------------------
B. Set Hostname Entry
---------------------------------------------------------------------------
This step has already been completed.  To verify enter this command:
hostname

This hostname must be entered as the 'common name' for the digitial certificate used.

---------------------------------------------------------------------------
C. Apache Directory SSL
---------------------------------------------------------------------------
- Step1, copy keystore created on earlier step, to the server's conf folder: 
sudo cp mykeystore /var/lib/apacheds-2.0.0-M20/default/conf

- Step3, Don’t use Apache Studio, instead:
ldapmodify -h localhost -p 10389 -D uid=admin,ou=system -w secret -a -f /home/student/fortress/directory-fortress-core/ldap/schema/apacheds-ldaps.ldif

- The above step alters the server config to use ssl with private keystore from above.  The server config file is here:
  /var/lib/apacheds-2.0.0-M20/default/conf/ou=config/ads-directoryserviceid=default/ou=servers/ads-serverid=ldapserver.ldif

- Step 6 - Restart the directory server.  Always use sudo with apacheds:
sudo /etc/init.d/apacheds-2.0.0-M20-default restart

- Step 7 - Check the server status to make sure its started back up:
sudo /etc/init.d/apacheds-2.0.0-M20-default status

---------------------------------------------------------------------------
D. Apache Fortress Core SSL
---------------------------------------------------------------------------

- Step 3 - Edit properties, replace all of the following:

# Use value from [Set Hostname Entry]:
ldap.host=GB3SCOLSYMAS99
ldap.port=10636

enable.ldap.ssl=true
# This can be set to 'true' for troubleshooting:
enable.ldap.ssl.debug=false

# Use truststore genned [Managing PKI Keys].
trust.store=/home/student/fortress/certs/mytruststore
trust.store.password=changeit

- Step 4 - run the maven install to change fortress default ldap coordinates and start using LDAPS:
mvn install

- Step 6 - run the Fortress console instead of junit tests:
mvn install -Pconsole

- Verify console works with LDAPS enabled by performing a user search:
Option 2 (Review)
Option 0 (Search User), accept default

---------------------------------------------------------------------------
E. Install MySQL
---------------------------------------------------------------------------

MySQL Already installed and configured for non-SSL usage

- (Start on) Step 7 : Configure MySQL to use SSL

a. to copy crypto stuff (from folder where keys generated):
sudo cp /home/student/fortress/certs/ca-cert.pem /etc/mysql
sudo cp /home/student/fortress/certs/server-cert.pem /etc/mysql
sudo cp /home/student/fortress/certs/server-key.pem /etc/mysql

b. edit the mysql config file:
sudo vi /etc/mysql/my.cnf

c. Add bind address to to the [mysqld] section of my.cnf file. Use hostname from Step B - Set Hostname Entry. 
d. Add key locations to the [mysqld] section of my.cnf file:

# change this hostname to your machine's hostname:
bind-address = GB3SCOLSYMAS99
# Use keys genned [Section II - Managing PKI Keys]:
ssl-ca=/etc/mysql/ca-cert.pem
ssl-cert=/etc/mysql/server-cert.pem
ssl-key=/etc/mysql/server-key.pem

e. Save and exit the my.conf file.
f. Restart MySQL daemon (Debian): 


---------------------------------------------------------------------------
F. Apache Tomcat SSL
---------------------------------------------------------------------------

- Step 1 - Copy keystore created during Managing PKI Keys to /usr/local/tomcat/conf folder. 
sudo cp /home/student/fortress/certs/mykeystore /usr/local/tomcat7/conf

- Step 2 -  Edit /usr/local/tomcat7/conf/server.xml file: 
sudo vi /usr/local/tomcat7/conf/server.xml

- Step 3
- Add the following metadata to the conf file below where a similar statement has been commented out.  We're going to use port 443 instead of 8443, and also disable weak DH ciphers:
<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector
    port="443" maxThreads="200"     ciphers="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_ECDSA_WITH_RC4_128_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDH_RSA_WITH_RC4_128_SHA,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA,TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_RC4_128_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_RC4_128_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,TLS_ECDH_ECDSA_WITH_NULL_SHA,TLS_ECDH_RSA_WITH_NULL_SHA,TLS_ECDHE_ECDSA_WITH_NULL_SHA,TLS_ECDHE_RSA_WITH_NULL_SHA"
    scheme="https" secure="true" SSLEnabled="true"
    keystoreFile="conf/mykeystore" keystorePass="changeit"
    clientAuth="false" sslProtocol="TLS"
/>

- Step 4 - Save and exit the file.
- Step 5 - Stop Tomcat (Debian):
sudo /usr/local/tomcat7/bin/shutdown.sh

- Verify that is shutdown:
ps -ef | grep tomcat

- If it shows up in list, kill it:
sudo kill -9 pid

- Nowj start the tomcat server back up:
sudo /usr/local/tomcat7/bin/startup.sh

- Tail the logs to see if anything bad happened:
tail -f -n10000 /usr/local/tomcat7/logs/catalina.out

- Verify that the cert works in your browser by pulling up tomcat landing page:
https://hostname

NOTE: You will of course get a warning in your browser for a self-signed certificate.  Once you get past this, the tomcat landing page should render.

---------------------------------------------------------------------------
G. Apache Fortress Demo
---------------------------------------------------------------------------

- Step 1 : Already downloaded and staged to /home/student/fortress/apache-fortress-demo

- Step 2 : skip

- Step 3 : skip

- Step 4 - Change directory: 
/home/student/fortress/apache-fortress-demo

- Step 5 - stage property file:
cp ./src/main/resources/fortress.properties.example ./src/main/resources/fortress.properties

- Step 6 : Change the host name to use current host name:
host=GB3SCOLSYMAS99

- Step 6 : Change the database url to use current host name
database.url=jdbc:mysql://GB3SCOLSYMAS99:3306/demoDB?useSSL=true&requireSSL=true

- Step 6 : Change the to use the mytrustore genned earlier:
trust.store=/home/student/fortress/certs/mytruststore

- Step 7 - Save and exit the file.

- Step 8 - To build and deploy this web application, and load security policy into ldap, run this command: 
mvn tomcat:deploy -Dload.file

- Skip Step 11 (Apache Selenium Tests)

- Step 12 - Manually test by connecting to web app:
https://GB3SCOLSYMAS99/apache-fortress-demo


****************************************************************************
---------------------------------------------------------------------------
SECTION IV - Wicket Sample
---------------------------------------------------------------------------
****************************************************************************
This project has already been staged:
/home/student/fortress/wicket-sample

During this section, you will be asked to enable security for a very simple web application.  Here the focus will be on how to integrate with Apache Fortress rather than what constitutues a 'secure' web application.

- Open browser to url: https://github.com/shawnmckinney/wicket-sample
Follow the Steps to install app, add security, and run the tests.

More info here:
http://iamfortress.net/2015/03/13/enabling-java-ee-and-fortress-security-inside-an-apache-wicket-web-app/


****************************************************************************
---------------------------------------------------------------------------
SECTION V - Role Engineering Sample
---------------------------------------------------------------------------
****************************************************************************

- During this section, you will be asked to take a look at the role engineering process from beginning to end.  Here the focus will be on security use cases and how they are applied to a sample application.

- Open browser to url: https://github.com/shawnmckinney/role-engineering-sample
Follow the Steps to install, and run the tests.

- More info here:
http://iamfortress.net/2015/03/05/the-seven-steps-of-role-engineering/

- This project has already been staged:
/home/student/fortress/role-engineering-sample

- Step 1 - step into staging folder:

- Step 2 - copy the properties file:

- Step 3 - Build, deploy, load security policy:
mvn clean tomcat:deploy -Dload.file

- Step 4 - Point your browser to the web app.  
http://hostname:8080/role-engineering-sample

- Step 5 - try different users:

ssmith/password
rtaylor/password
johndoe/password


****************************************************************************
---------------------------------------------------------------------------
SECTION VI - Fortress SAML Sample
---------------------------------------------------------------------------
****************************************************************************
Notes: 

- This sample takes a couple of hours to complete.  
- It is comprised of the following sub-sections, each corresponding to a README file in the github project:

Part 1 - SPRING-SECURITY-SAML2-SAMPLE - here we deploy the spring saml sample and use it to generate the necessary service provider metadata for our saml testing.
Part 2 - REGISTER-SSOCIRCLE - here you are directed to sign up for account with ssocircle.com.  We will use this as our test Identity Provider (so we don't have to set one up ourselves)
Part 3 - MAIN README - in this section we build, deploy and run the fortress-saml-demo web app.  

- The fortress-sample-demo source code has already been staged:
/home/student/fortress/fortress-saml-demo

- Open browser to url: https://github.com/shawnmckinney/fortress-saml-demo
The main instructions are here.


To complete the tutorial, follow these steps:

---------------------------------------------------------------------------
Part 1 - SPRING-SECURITY-SAML2-SAMPLE
---------------------------------------------------------------------------

- Step 0 - Install Gradle:
$ sudo add-apt-repository ppa:cwchien/gradle
$ sudo apt-get update
$ sudo apt-get install gradle

- Step 1 - Pull down and Extract, and cd:
wget https://github.com/UniconLabs/shibboleth-sample-java-sp/archive/master.zip -O shibboleth-sample-java-sp.zip
unzip shibboleth-sample-java-sp.zip
cd shibboleth-sample-java-sp-master/

- Step 2 - Edit Spring SecurityContext.xml, enable to use SSOCircle IdP:
vi src/main/webapp/WEB-INF/securityContext.xml

- Step 3 - Pull down metadata:
wget http://idp.ssocircle.com/idp-meta.xml -o /tmp/idp-metadata.xml

- Step 4 - Edit Service Provider property file, point to IdP metadata just pulled down:
vi src/main/webapp/WEB-INF/sp.properties 
idp.metadata=/tmp/idp-metadata.xml

- Step 5 - Deploy shibboleth-sample-java-sp 
gradle build
gradle deploy
sudo cp build/libs/sp.war /usr/local/tomcat7/webapps/

- Step 6 - Pull up the shibboleth-sample-java-sp home page in the browser:
Use this URL: http://hostname:8080/sp

- Step 7 - Click on Metadata Administration link.

- Step 8 - Accept default uid/password, and click on Login button

- Step 9 - Click on Generate new service provider metadata button

- Step 10 - Entity Id, enter a unique value, needs to be globally unique, e.g. fortress-saml-demo-9876214

- Step 11 - Entity Base URL, e.g. http://host-name:8080/fortress-saml-demo (where host-name corresponds with your machine's host name, context must be fortress-saml-demo, which matches target web app)

- Step 12 - Click on Generate Metadata button at the bottom of the page.

- Step 13 - Copy the buffer

- Step 14 - Save it with an '.xml' extension. We'll need it later on during the REGISTER-SSOCIRCLE.md steps.

---------------------------------------------------------------------------
Part 2 - REGISTER-SSOCIRCLE
---------------------------------------------------------------------------

- Step 1 - Goto website: http://www.ssocircle.com

- Step 2 - Click on Signin/Register->Register menu option.

- Step 3 - Fill in the info in the web form:

User Name [a-zA-Z.-]:
this is the userid you will use to log into the SSO Circle Identity Provider (IdP)

Required Field Password - at least 8 characters:
this is the password you will use to log into the IdP

Required Field First Name:
enter anything

Required Field Last Name:
enter: sam*

this field maps to a fortress userId.  For now enter 'sam*' who will be allowed full access to fortress-saml-sample web app.

Required Field Full Name:
anything

Required Field Email Address:
this email address must be valid.  it is needed for registration confirmation later.

- Step 4 - complete the registration via confirmation message sent to email address entered above.

- Step 5 - login into SSOCircle.com IdP

- Step 6 - Add Service Provider Metadata to SSOCircle.com
a. click on Manage Metadatasrc/main/resources/fortress.propertiessrc/main/resources/fortress.properties
b. click on Add new Service Provider
paste the Service Provider Metadata, generated in previous section into the buffer.
c. Enter the FQDN of the ServiceProvider, use your machine's hostname, ex.: GB3SCOLSYMAS99
d. enable the LastName checkbox
e. click on Submit button 
f. wait for the confirmation message. This could take a minute or two. 

Step 7 - The IdP should be ready for use.

---------------------------------------------------------------------------
Part 3 - MAIN README.md
---------------------------------------------------------------------------

---------------------------------------------------------------------------
Prepare fortress-saml-demo package
---------------------------------------------------------------------------

During this section, you will be asked to combine SAML 2.0 authentication with RBAC.  

Step 1 & 2 - Download ZIP & Extract the zip archive, have already been completed.

Step 3 - cd fortress-saml-demo
/home/student/fortress/fortress-saml-demo

Step 4 - Copy fortress.properties.example to fortress.properties.
cp src/main/resources/fortress.properties.example src/main/resources/fortress.properties

Step 5 - Edit securityContext.xml file, bean id metadataGeneratorFilter, replace the property entityId's 
vi src/main/webapp/WEB-INF/securityContext.xml

- display the line #'s:
:set nu  

- go to line 116, replace entityId with what you used before in SP metadata generator step:
116                 <property name="entityId" value="fortress-saml-demo-9876"/>


---------------------------------------------------------------------------
Build and deploy fortress-saml-demo
---------------------------------------------------------------------------

Step 1 - No need to set java or maven home

Step 2 - Deploy the fortress-saml-demo Web App to Tomcat, and import fortress security policy for this app:
mvn clean tomcat:deploy -Dload.file

- To test the app, use the same URL that is in SP metadata imported into IdP.  For example:
https://GB3SCOLSYMAS10:443/fortress-saml-demo


More info here:
https://github.com/shawnmckinney/fortress-saml-demo


**** End of Security Tutorial README *****