ADFS3 and OpenAM 12 - Part 5: CentOS/OpenAM install Overview
This is Part 5 of a series of articles describing how to integrate Open AM v12 and ADFS 3 (2012 R2). See:ADFS 3 (Windows 2012 R2) and OpenAM 12. In order to demonstrate this we need an OpenAM instance that will become a trusted 'Claims Provider' configured in ADFS.
If you already have an instance of OpenAM running and configured with SSL, then feel free to skip this part. Otherwise, the steps in this part assume assum e very limited knowledge of CentOS and OpenAM. There are plenty of other articles on this wiki, backstage.forgerock. com and the internet that describe, in more detail, the installation and configuration of CentOS and OpenAM. However, the steps here provide a shortcut to installing the environment for those who just want to prove the integration works. Whilst this part in the series can standalone from the previous parts (as they were all on the Windows machine) you should familiarise yourself with those steps because Part 6 will it all together. The previous parts are ADFS3 and OpenAM 12 - Part 1: Windows/IIS/Sample App, ADFS3 and OpenAM 12 - Part 2: Certificate Services, ADFS3 and OpenAM 12 - Part 3: ADFS Install, and ADFS3 and OpenAM 12 - Part 4: ADFS/WIF/Sample App
First, we'll download and install a CentOS image as the 2nd Virtual Machine in VirtualBox, then we'll install and configure an OpenAM instance. In between we'll also install the Java Development Kit, Tomcat (the JEE container we'll use for OpenAM), configure SSL, tweak the 'hosts' file and the CentOS firewall.
Bear in mind that as a JEE application, OpenAM can equally well run on Windows server, but these steps utilise CentOS.
Process
Create new CentOS VM
1. Download CentOS from http://www.centos.org/download/. I used the ‘DVD ISO’ link from that page. 2. In Virtual Box create a New machine 3. Give it a name. e.g. OpenAM. 4. In the Type dropdown, select Linux 5. In the version, select Red Hat (64bit), click Continue 6. On the Memory Size page, make sure it has at least 2GB (2048MB) 7. On the Hard Drive page, select ‘Create a Virtual Hard Drive now’ and click Create. 8. Choose VDI, then Continue 9. Allow hard drive to be dynamically allocated and click Continue 10. Make the size of the disk at least 15GB. Click Create.
Configure network and CD settings
1. In VirtualBox, click the newly created machine then ‘Settings’ 2. On the Network tab, change the Network Adapter to Bridged (unless you have other preferred settings…but remember that this machine and the Windows machine must be able to see each other). Choose a suitable adapter in ‘Name’ 3. Expand Advanced 4. Change the Adapter Type to Paravirtualized Network (virtio-net) 5. Change Promiscuous Mode to ‘Allow All’ 6. Select the Storage tab 7. Select the ‘Empty’ item under the ‘Controller: IDE’ node 8. Click the CD icon to the right of the ‘CD/DVD Drive’ dropdown 9. If it’s not already in the list select ‘Choose a virtual CD/DVD drive’ and select the CentOS ISO file you downloaded. 10. Click Ok 11. Start the VM
Configure CentOS
1. Allow the CentOS installation to run from the virtual CD 2. Choose your language preferences and click ‘Continue’ 3. When the ‘Installation Summary’ page appears, click the Installation Destination item in the System section. 4. Accept the defaults and click ‘Done’. 5. On the Installation Summary page, click Network & Hostname in the System section 6. In the Network and Hostname page, click the ‘Configure’ button 7. On the ‘General’ tab, select ‘Automatically connect to this network when it is available’. 8. On the IPv4 tab, change the ‘Method’ to Manual 9. Click ‘Add’ next to the Addresses table 10. Enter a static IP configuration that suits your network e..g 192.168.1.xx. 11. Click Save 12. In the Hostname field, type a suitable hostname, e.g. secure.openam.frlocal 13. Turn ‘On’ the network 14. Click Done 15. On the Installation Summary page, click Software Selection in the Software section 16. In the ‘Base Environment’ list, choose ‘Server with GUI’ 17. In the ‘Add-ons for selected environment’ list, select ‘Development Tools’ 18. Click Done 19. Click Begin Installation 20. Whilst server is configuring you can set root passwords and create users: a. Click Root password b. Enter a suitable root password and click Done c. Click Create User d. Enter username e.g. FRAdmin e. Select ‘Make this user Administrator’ f. Enter a suitable password g. Click Done h. Wait until server is configured 21. 21. Reboot when prompted. a. On restart, accept the License information b. Click Finish Configuration…server will restart again c. Login as the Admin user you created d. Click ‘Next’ until you reach the ‘Thank you’ screen and click ‘Start using CentOS’ e. Install the VBox Guest additions, restart the server f. Enable shared clipboard in VBox to allow copy/paste between guest and host
Install java
1. Open Terminal 2. Enter ‘sudo su’ and relevant password 3. Then a. cd /opt b. wget --no-cookies --no-check-certificate --header "Cookie: gpw_e24=http%3A%2F%2Fwww.oracle.com%2F; oraclelicense=accept- securebackup-cookie" http://download.oracle.com/otn-pub/java/jdk/7u72-b14/jdk-7u72-linux-x64.tar.gz c. tar xzf jdk-7u72-linux-x64.tar.gz d. cd /opt/jdk1.7.0_72/ e. alternatives --install /usr/bin/java java /opt/jdk1.7.0_72/bin/java 2 f. alternatives --config java i. select the JDK just downloaded/installed (e.g. item 2) g. alternatives --install /usr/bin/jar jar /opt/jdk1.7.0_72/bin/jar 2 h. alternatives --install /usr/bin/javac javac /opt/jdk1.7.0_72/bin/javac 2 i. alternatives --set jar /opt/jdk1.7.0_72/bin/jar j. alternatives --set javac /opt/jdk1.7.0_72/bin/javac 4. Now we’ll edit the config so that all users get the JAVA environment variables:
a. cd /etc/profile.d b. nano java_env.sh (this should launch the 'nano' text editor with a new file called java_env.sh that will automatically be called when the 'bash' terminal starts) c. paste in at the bottom: i. export JAVA_HOME=/opt/jdk1.7.0_72 ii. export JRE_HOME=/opt/jdk1.7.0_72/jre iii. export PATH=$PATH:/opt/jdk1.7.0_72/bin:/opt/jdk1.7.0_72/jre/bin d. save and close the file e. exit terminal 2. Test Java settings a. Open a terminal b. type ‘echo $JAVA_HOME’ which should return the path configured above
Download and Install Tomcat
1. In a terminal window (as FRAdmin): a. cd ~\Downloads b. mkdir tomcat c. cd tomcat d. wget http://apache.mirrors.tds.net/tomcat/tomcat-7/v7.0.57/bin/apache-tomcat-7.0.57.tar.gz e. sudo tar xvzf apache-tomcat-7.0.57.tar.gz -C /opt f. sudo mv /opt/apache-tomcat-7.0.57/ /opt/tomcat g. cd /opt/tomcat/bin h. sudo chmod +x *.sh i. cd /opt j. sudo chown -R fradmin:fradmin /opt/tomcat 2. Configure the Tomcat Java options a. cd /opt/tomcat/bin b. nano sentenv.sh c. Enter: export JAVA_OPTS="-server -Xms256m -Xmx1024m -XX:PermSize=256m -XX: MaxPermSize=512m” d. Save and close the file
Edit hosts so that the OpenAM server is fully qualified
1. In terminal: sudo nano /etc/hosts 2. Enter the IP address of the machine followed by the machine name (which must include at least 3 dots) e.g. 192.168.1.xx secure.openam.frlocal 3. Save and close the file 4. Start Tomcat (runs on default port of 8080 – edit server.xml if you need to change this) a. $CATALINA_HOME/bin/startup.sh 5. check you can access tomcat instance a. open browser (on CentOS server) and browse to http://
b.
At this point, we'll also edit 'hosts' so that this server can resolve the domain name to the Windows server
1. Edit the 'hosts' file (as the machine 'root' user): sudo nano /etc/hosts a. add an entry for the IP address and dns name of the ADFS server e.g. 192.168.1.xx adfs.adfstest.local
In order for ADFS to play nicely we need the Tomcat instance to be available on SSL which we’ll do with a self-signed certificate. So we now configure SSL for Tomcat (leveraged from http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html)
1. In terminal create a new keystore with a self-signed certificate - use ‘tomcat’ as the name, and ~/.ssl as the keystore, by typing: keytool -genkey -alias tomcat -keyalg RSA -keystore ~/.ssl 2. Follow the directions, entering the password for the keystore, details for the certificate, and password for the certificate…which must be the same password as for the keystore a. NB. When the tool asks for ‘First Name, Last Name’ be sure to enter the FQDN of the OpenAM service, e.g. secure.openam.frlocal This is because the tool uses this value for the CN of the cert which will be checked later by the browsers The other entries can be anything you like! 3. Edit $CATALINA_HOME/conf/server.xml file so that the Tomcat instance is available over SSL using the previously created certificate a. cd $CATALINA_HOME/conf/ b. nano server.xml i. Uncomment the ‘Connector’ associated with the SSL HTTP1.1 configuration ii. Add the following attributes to the Connector node (substituting values you used if different from these): keystoreFile="${user.home}/.ssl" keystorePass="Pa55word" iii. The entire node may look like this:
Restart tomcat
1. Stop Tomcat: $CATALINA_HOME/bin/shutdown.sh 2. Start Tomcat: $CATALINA_HOME/bin/startup.sh 3. Test by browsing to https://secure.openam.frlocal:8443 a. Note the https and the port specified. b. At this point the browser may state the connection is untrusted. This is because the certificate used is self-signed, rather than supplier by a trusted root Certificate Authority. Allow the browser to trust this certificate permanently (in Firefox, follow the browser instructions to add a permanent exception)
Now that we have tomcat running and listening on SSL, we can download & install OpenAM
1. In terminal, cd ~\Downloads 2. Create a directory to hold the OpenAM installation files: mkdir openam 3. In a browser, browse to https://backstage.forgerock.com/#/downloads/enterprise 4. Select the desired version of OpenAM (register/login if necessary) and download to the newly created folder. 5. If you downloaded the zip, then unzip the contents. 6. Copy the OpenAM-12.0.0.war as openam.war to the webapps folder of the tomcat. e.g. cp OpenAM-12.0.0.war /opt/tomcat/webapps/openam.war
Configure OpenAM
1. Browse to the openam application: https://secure.openam.frlocal:8443/openam 2. You should get the Configuration Options page. 3. Select ‘Create Custom Configuration’ 4. Accept the licence agreement 5. Enter default amadmin password, click Next 6. Enter correct cookie domain making sure it starts with a dot e.g. .openam.frlocal 7. Click Next 8. Accept the defaults on the Configuration Store page, click Next 9. On the User Data Store, select the Open AM User Data Store option, click Next. 10. Select 'No' on the Select Site Configuration Page and click Next 11. Enter a Policy Agent password…this must be different to the amadmin password entered earlier…click Next 12. On the final page click Create Configuration 13. Wait for the server to be configured 14. Click ‘Proceed to Login’ and login with amadmin user and password
Now we need to edit the CentOS firewall so that other computers can access the services it hosts.
1. From the CentOS 'Applications' menu, choose 'Sundry', then 'Firewall'. 2. Change the 'Configuration' drop-down to 'Permanent' - you may be prompted to enter your user password to confirm privilege elevation. 3. In 'Zone', select 'public' 4. Add all the ports that your services are listening on, using the TCP protocol. These will typically be the 'connector ports' defined in the tomcat 'server. xml' file e.g. 8080, 8443 5. In the Options menu, select 'Reload Firewalld'. Check the changes have been propogated to the runtime configuration.
Congratulations! You now have a base OpenAM v12 service installed on CentOS that is accessible to other machines using a self-signed SSL certificate. Up next, we'll configure this OpenAM service to provide claims to the ADFS instance configured in the previous parts - Part 6: ADFS3 and OpenAM 12 - Part 6: OpenAM/ADFS configuration