OpenAM Installation

Unknown macro: toctreeview

Introduction

OpenAM 10.1.0-Xpress will not work with JRE newer than 7u21. Running OpenAM on JRE 7u25 or later will result in an exception: "Unable to do SSO or federation".

This guide will guide you through the installation of OpenAM and its dependencies. After this installation, you can follow the other guide of the XMS Installation.

First, here is a diagram to explain the relationships between each component.

OpenAM is the component that handles identities and entitlements. It relies on an internal LDAP database (for its configurations and user entitlements), and OpenDJ, which is also a LDAP database (to store identities, repositories...).

This guide was written using CentOS. Please adapt the commands to your operating system.

Prerequisite

The following components must be installed and configured on your system:

Java 6 and 7
Git
Glassfish
Maven 3
SVN 1.6.x (optional, only if you want to build OpenAM from source)

We won't cover the installation process of these components.

Keystore and Truststore Configuration

In order to run OpenAM and parts of XLcloud Web Console using secure HTTPS connections, you need to have a signed certificate. If you don't have one, you need to obtain it. You can either have a certificate signed by an authorized organization, or sign it yourself. Choose step a), b) or c), and then proceed to add certificates.

a) I Already Have a Certificate

In this case, you just need to create a keystore for Tomcat. For example, if your certificate is named xlc-cert.pem:

mkdir /.ssl
cd /.ssl
keytool -import -keystore xlc-keystore -file xlc-cert.pem -alias xlc

b) To Obtain a Certificate Signed by an Authorized Organization

mkdir /.ssl
cd /.ssl
keytool -keystore xlc-keystore -genkey -alias xlc

The above command will ask you questions about the keystore and certificate that you are about to generate. Answer them as follows:

Enter keystore password: choose a password
Re-enter new password: enter your password again
What is your first and last name?enter the same as openam.host in default.properties, eg.: iam.toolcloud.bull
What is the name of your organizational unit? any
What is the name of your organization? any
What is the name of your City or Locality? any
What is the name of your State or Province? any
What is the two-letter country code for this unit? any
Is CN=iam.xlcloud.org, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct? yes

Now you can generate a CSR (Certificate Signing Request):

keytool -keystore xlc-keystore -certreq -alias xlc -keyalg rsa -file xlc.csr

To receive a signed certificate, visit a site like http://www.thawte.com or http://www.verisign.com for more information.

Once you obtain the signed certificate (e.g. xlc-cert.pem), you can import it into the keystore for Tomcat:

keytool -import -keystore xlc-keystore -file xlc-cert.pem -alias xlc

c) To Obtain a Self-Signed Certificate

mkdir /.ssl
cd /.ssl
mkdir private
openssl req -new -x509 -days 3650 -extensions v3_ca -keyout private/xlc-key.pem -out xlc-cert.pem

The above command will ask you questions about the keystore and certificate that you are about to generate. Answer them as follows:

Enter PEM pass phrase: choose a password
Verifying - Enter PEM pass phrase: enter your password again
Country Name (2 letter code) [AU]: any
State or Province Name (full name) [Some-State]: any
Locality Name (eg, city) []: any
Organization Name (eg, company) [Internet Widgits Pty Ltd]: any
Common Name (e.g. server FQDN or YOUR name) []: enter the same as openam.host in default.properties, eg.: iam.toolcloud.bull
Email Address []: any

Next, create a keystore for Tomcat:

openssl pkcs12 -export -in xlc-cert.pem -inkey private/xlc-key.pem -out keystore.p12 -name xlc
keytool -importkeystore -srckeystore keystore.p12 -srcstoretype PKCS12 -destkeystore xlc-keystore

Add Certificate to Truststores

Now you can add your certificate (e.g. xlc-cert.pem) to a truststore used during OpenAM configuration:

keytool -import -file xlc-cert.pem -keystore xlc-cacerts -alias xlc

And answer "yes" when asked by the last command. You also need to add the certificate to the GlassFish truststore (by default its located in: glassfish3/glassfish/domains/domain1/config/cacerts.jsk):

keytool -import -file toolcloud-cert.pem -keystore /home/amg/glassfish3/glassfish/domains/domain1/config/cacerts.jks -alias xlc

You might need to change the above path according to your GlassFish installation. Again, answer "yes".

Tomcat

To install Tomcat server, do the following (take the latest version of the URL here: http://apache.mirrors.tds.net/tomcat/):

wget http://apache.mirrors.tds.net/tomcat/tomcat-7/v7.0.42/bin/apache-tomcat-7.0.42.tar.gz
tar xvzf apache-tomcat-7.0.42.tar.gz -C /opt
mv /opt/apache-tomcat-7.0.42/ /opt/tomcat
chmod +r /opt/tomcat/conf/*
echo 'CATALINA_HOME=/opt/tomcat' >> /.basic
source /.bashrc

Change the port Tomcat listens on to 8082, by modifying /opt/tomcat/conf/server.xml, and changing the port of the connector associated with the HTTP protocol:

It will also enable secure HTTPS connections. Note that you might need to change keystoreFile and keystorePass according to your keystore configuration. You can now start Tomcat:

$CATALINA_HOME/bin/startup.sh

Check at https://your-server-ip-or-domain-name:8082 if Tomcat works. If not, that probably comes from your iptables settings, since by default, CentOS blocks almost every port. Run:

service iptables stop
chkconfig iptables off

and try again. If it works, you can add the appropriate line to your iptables to allow input on port 8082, and re-activate your iptables.

Create file /opt/tomcat/bin/setenv.sh with the following content:

export JAVA_OPTS="-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server -Xms256m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512m -XX:+DisableExplicitGC"

and restart Tomcat.

GlassFish

Get the machine's IP address with:

ifconfig eth0 | grep "inet ad" | cut -f2 -d: | awk '{print $1}'

And the hostname with the hostname command. Add it to /etc/hosts like this:

<ip_address> localhost <hostname>

Then edit the file /opt/glassfish3/glassfish/domains/domain1/config/domain.xml and replace port 8080 with another one. For example, 8282 (8181 is used for SSL connections). You have to replace occurrences of 8080 in this file.

Finally, you can run the glassfish server with:

/opt/glassfish3/glassfish/bin/asadmin start-domain

Check at http://your-server-ip-or-domain-name:8282 if Glassfish works.

OpenDJ

Go here: http://www.forgerock.org/opendj.html and get the latest ZIP link (take the [ZIP] link, no the [zip file] link).

Then run:

unzip <name-of-the-downloaded-file>.zip
mv opendj/ /opt
cd /opt/opendj
./setup cli

The installation process starts. Here is what you must answer to the questions (in bold the values that differ from default settings):

Initial root user: press Enter (use default setting)
Password for the initial root user and its confirmation: choose one
Server host name: choose one (set in in your hosts); for us, it's centos-vm
Connections port for LDAP clients: 1389
Connections port for Administrators: chose a different one (whichever)
Create base DN: press Enter (use default setting)
Base DN: dc=xlcloud,dc=bull,dc=com
Populating the database: press Enter (use default setting)
Enable SSL: press Enter (use default setting)
Enable TLS: press Enter (use default setting)
Start the server: press Enter (use default setting)
Action regarding the configuration: press Enter (use default setting)

Now, the LDAP server is installed, but we should import some settings. We stop OpenDJ, copy two files which name starts with 99 to a OpenDJ folder, then restart OpenDJ and run a specific command to import the content of these files. Don't forget to edit the following commands so that they match your settings (especially PORT - port for administrators and PASSWORD - initial root user password):

/opt/opendj/bin/stop-ds
cp /xlcloud-ci/xms/data-setup/target/99* /opt/opendj/config/schema
/opt/opendj/bin/start-ds
/opt/opendj/bin/import-ldif -b "dc=xlcloud,dc=bull,dc=com" ldifFile /xlcloud-ci/xms/data-setup/target/xlcloud-ldap-sample-data.ldif clearBackend -h localhost -p PORT -D "CN=Directory Manager" -w PASSWORD

It should output that the import task has been successfully completed.

OpenAM

We'll assume that you have pulled our XLcloud source repositories. Go to folder /xlcloud-ci/xms/iam/installation/src/main/resources/scripts, this will now be the root directory of all of the following commands.

Define the host

OpenAM will require a proper hostname to work. That is to say, if you're installing it on your own computer, you can't just put localhost in the installation settings or it won't work. You need to define a hostname for your machine, like xlcloud, and add it to your hosts file:

In /etc/hosts

127.0.0.1 localhost iam.toolcloud.bull

This has to be a valid hostname. Otherwise, the OpenAM configurer in install_openam.sh script might fail.

Get OpenAM binaries

You need to obtain several OpenAM binaries. There are two ways to do it. The preferred one is to download them from OpenAM website:https://backstage.forgerock.com/#/downloads/enterprise. In order to do this, you will need to register. Once you do, download files war, tools and configurator version 10.1.0:

Alternatively, if you do not want to register, you can build OpenAM from source:

svn checkout https://svn.forgerock.org/openam/tags/10.1.0-Xpress
cd ./10.1.0-Xpress/openam
mkdir -p target/license
touch target/license/ForgeRock_License.txt
mvn install -DskipTests=true

To perform the above commands you need SVN version 1.6.x. Using SVN 1.7.x will result in the OpenAM build failing.

Build OpenAM Extensions

The next step is to build OpenAM extensions. The project is located inside the repository under
./xms/iam/xlc-openam-ext/

cd /xms/iam/xlc-openam-ext/
mvn clean install -DxlcloudEnvProperties=/home/amg/xlcloud.properties

In the command above, you cannot use /xlcloud.properties as the path to your properties file. You need to specify the full path.

Prepare scripts

Once again check parameters described in Clone and Build XMS project and customize them to your installation. Sections of interest to you will be IAM, IAM Installation, User Repository and Data Setup.

If in your Keystone installation there already exists a user with the same name as specified in the defaultAdminName property, the configure_openam.sh script will fail. You need to choose a name that does not exist in Keystone. The same is true for adminsGroupName – there cannot be a tenant in Keystone with the same name.

After properties are fully prepared, build installation project located inside the directory
/xms/iam/installation/

cd /xms/iam/installation
mvn clean install -DxlcloudEnvProperties=/home/amg/xlcloud.properties
cd target/scripts
chmod +x *.sh

In the command above, you cannot use /xlcloud.properties as the path to your properties file. You need to specify the full path.

Before you run the scripts, you will need to set some environment variables. Firstly, if you do not use the default localtion of a Maven repository (/.m2/repository), you should export it, e.g.:

export MAVEN_REPO=/.m2/my_repo

If you built OpenAM from source, that should be all. However, if you downloaded the files, you need to indicate their locations, e.g.:

export OPENAM_ORIGINAL_WAR=/Downloads/openam_10.1.0.war
export OPENAM_SSOADM_ZIP=/Downloads/ssoAdminTools_10.1.0.zip
export OPENAM_CONFIGURER_ZIP=/Downloads/ssoconfiguratortools_10.1.0.zip

Patch

Now that we have all of the dependencies and the scripts know where to find them, we're going to patch the original .war file of OpenAM to include our settings.

Run ./patch_openam_war.sh script. If everything went correctly, the last line should indicate the folder where is located the patched openam-xlc.war file.

Deploy

Make sure that you have set the JAVA_HOME environment variable,

Copy the patched .war file into the /opt/tomcat/webapps/ folder with the name openam.war:

cp openam-xlc.war /opt/tomcat/webapps/openam.war

Wait a few minutes while Tomcat is deploying OpenAM. When you see a configuration screen like the following on https://your-server-ip-or-domain-name:8082/openam, you can go to the next step.

Install

If you've already used the installation script before on this machine, delete the folder /opt/openam-config (or whatever folder you set as the openam.baseDir property).

Run ./install_openam.sh script. Verify the log file to see if it was executed properly. If not, one cause of the problem was an unknown error with Tomcat, try to restart the Tomcat server, and re-run the command.

After its execution, go again to https://your-server-ip-or-domain-name:8082/openam, and this time, you should see an admin console like the following:

You can login using amadamin account, and the password is the one you set in the settings file.

At least for the execution of install_openam.sh the user that started Tomcat must have write permission for /opt/openam-config (or the directory that was configured as openam.baseDir).

Configure

The config script requires JRE6 to work (though OpenAM will require JRE7 to run). Hence, to proceed with the installation export the JAVA_HOME like:

export JAVA_HOME=/usr/lib/jvm/java-6-openjdk-amd64/jre

Now you can run ./configure_openam.sh.

That's a known bug from ssoadm, which outputs the following error if you try to run the configure_openam.sh script using JRE7:

Logging configuration class "com.sun.identity.log.s1is.LogConfigReader" failed
java.lang.NullPointerException
Exception in thread "main" java.lang.NoClassDefFoundError: Could not initialize class com.sun.identity.log.Logger
        at com.sun.identity.cli.CommandManager.destroySSOTokens(CommandManager.java:782)
        at com.sun.identity.cli.CommandManager.<init>(CommandManager.java:201)
        at com.sun.identity.cli.CommandManager.main(CommandManager.java:148){{/code}}

Verify that everything executed properly

Once the scripts has finished running, verify that:

there were no error messages in the console output
the log files (as indicated by scripts) have no error messages
the status file (as indicated by the script) has all commands finished with status 0

Finally, go to https://your-server-ip-or-domain-name:8082/openam, and then:

in Access Control, xlc, Subjects, you should see a table with the user xlcadmin (or the name you set in the defaultAdminName property)
in Access Control, xlc, Data Stores, you should see the xlc-repo and by clicking on it, you should see the correct properties
in Federation, you should have one circle of trust named xlc-cot, and one of its entities should be the URL of openam you set earlier

If one of these points cannot be validated, check the following section, Help, to find out what went wrong.

If everything went as expected, congratulations! You just installed OpenAM.

Help

A lot of things can go wrong during the installation process. Be sure to use this section to help you through your investigation process.

Check the logs

Most importantly, you should check the logs generated by the scripts (patch_openam_war, install_openam and configure_openam).

You won't find relevant logs in the usual /var/log/ directory. Tomcat uses Catalina to store its log, and you can find them in:

/opt/tomcat/logs/catalina.out

That's the first one to check if something went wrong and you have no idea why. You can also check:

/opt/openam-config/openam/debug

for more logs, especially the file IdRepo.

Check the ports

Most of the time, the errors are caused by a port being already used by another process. You can find more information with:

netstat -netlp | grep <number-of-the-port>

and then kill the associated process.

Restart Tomcat

When something when wrong (for whatever reason), I found out that I had to restart Tomcat so the changes I made to the configuration are properly applied.

Shutdown Tomcat:

/opt/tomcat/bin/shutdown.sh

You can also delete OpenAM dir and openam.war file:

rm -rf /opt/tomcat/webapps/openam /opt/tomcat/webapps/openam.war

Put another war file in the /webapps folder (if you want), and then restart Tomcat:

/opt/tomcat/bin/startup.sh

Since Tomcat will have to deploy the app you put in /webapp folder at restart, this may take a while.

Kumpulan Tutorial Kito

Kamis, 04 Agustus 2016

Openam install