Deploy standalone ForgeRock OpenAM instance using AWS Elastic Beanstalk

There are many instances where a team wants to quickly deploy a stand-alone ForgeRock OpenAM instance in AWS to test a new feature or do a POC. It is easier to setup OpenAM in local machine, but it cannot be accessed through internet in case a POC needs to be done by integrating few applications.

The easiest way to deploy a standalone OpenAM instance in AWS within few minutes is to use AWS Elastic Beanstalk. Elastic Beanstalk is a service that allows you to quickly deploy and manage applications in AWS without spending too much time on writing scripts, infrastructure setup or software installation. It comes with pre-configured templates to provision a ec2 instance with tomcat, apache server and automatically deploy the war files.

There are few prerequisites for setting up OpenAM in AWS:

1. You need a AWS account. A free tier account is sufficient to setup OpenAM using EBS.
2. Basic knowledge on AWS like creating bucket and navigating the AWS Management console
3. Basic knowledge on Java web applications and how they are deployed in Tomcat servers.

Now, let us go through the steps to setup OpenAM using EBS. If you want to automate all the manual steps related to AWS, follow this blog for more details.

Step 1 : Build the EBS Deployment package

The first step is to build the deployment package for EBS. Follow these steps to create the deployment package:

• Download OpenAM war, preferably v5.5 and rename it as auth.war.
• Create a folder, say ebspackage and copy the auth.war to that folder.
• Create a separate web application (.war) with just one index.html page having the message “Health Check”. Name this war file as ROOT.war. Below is the structure of this web application.

• Copy ROOT.war to the ebspackage folder. The reason for creating this war is to override the default behavior of EBS. If only one war file is present in the deployment package, EBS will rename it to ROOT.war and deploy it to tomcat. This will create issues because OpenAM configuration will fail if it is deployed as the ROOT application in tomcat.
• Create a new folder called .ebextensions within ebspackage folder
• Create a new file called 00permissions.config in .ebextensions folder and copy the below contents to that file. This is a EBS specific config file format for running commands after the environment is fully provisioned. In this case, we are changing the permissions of tomcat8 installation folder because it will be used as the base directory for OpenAM setup.

container_commands:
  00fix_permissions_dirs:
    command: "chmod -R 775 /usr/share/tomcat8"

• Zip the contents of this folder and name it as ebspackage.zip. Both the war files and .ebextensions folder should be present in the root folder of the zip file. Otherwise, EBS will not deploy the war properly. When you open the zip file in a File Manager like 7Zip, it should show the below files list in the root folder.

Step 2 : Upload the deployment package to AWS S3 bucket

• Create a new bucket in AWS, say ebsopenam. Since AWS buckets are globally unique, please use a different name if this bucket name is already taken. For this blog, let us assume the bucket name as ebsopenam.
• Upload ebspackage.zip to this bucket

Step 3 : Create an environment in EBS to deploy OpenAM

• Login to AWS management console and navigate to Elastic Beanstalk service
• Click “Create New Application”

EBS Home Page

• Enter an application name.

Application Information

• Select “Create Web Server” in next screen

New Environment setup page

• Select the Environment Type.

1. “Predefined Configuration” is Tomcat
2. I selected Java 8 with Tomcat 8 option for AM 5.5. If you are planning to deploy lower versions like 12.x / 13.x, select different version of Java and Tomcat.
3. Change the Environment Type to Single Instance since we want to deploy only one instance of OpenAM.

Environment Type configuration page

• In Application Version screen, select “s3 URL” option and provide the path : https://s3.amazonaws.com/<bucket name>/ebspackage.zip. Please change the bucket name accordingly.

Application Version configuration page

• In Environment Information, enter the URL for this environment. This will be final URL for accessing OpenAM server. If the domain name is not available, it can be changed.

Environment Information configuration page

• Don’t select any option in Additional Resources screen.
• In Configuration Details, select the server configuration.

1. Select t2.micro since it is free of cost if you are still in free tier
2. Select a key pair to ssh to EC2 instance. If you don’t have a key pair, it can be generated from “EC2 Dashboard”. This is required if you want to ssh to the EC2 instance.
3. Select System Type as Basic.
4. Change Root Volume Type to “General Purpose (SSD)”

EC2 Instance configuration page

• No need to add any tags in Environment Tags screen.
• In Permissions screen, leave the default values and click Next. EBS will automatically create the instance profiles.
• Review the configuration and make changes, if required. If everything looks good, click Launch button.
• EBS will start provisioning the resources and deploy the war files. If the deployment is successful, you should see the below screen with the URL that was configured in Environment Information configuration.

Environment URL

• If you open this <EBS URL> in browser, it should show the “Health Check” index.html page from the ROOT.war application.
• If you open <EBS URL>/auth, it will show the OpenAM Configuration page.
• In case you face any issues, you can check the EBS logs by navigating to Logs and selecting the “Request Logs” button.

Request Logs

• Alternatively, you can get the ec2 instance Public IP Address from EC2 Dashboard > Instances screen, ssh to the server using the key pair and check the tomcat or apache logs. In case you didn’t configure any ec2 key pair in Configuration Details screen, you can’t ssh to the ec2 instance.

Step 4 : Configure OpenAM instance

• In AWS Management console, go to EC2 Dashboard > Instances and locate the ec2 instance created by EBS. The name of this ec2 instance should be almost same as the ebs environment name.
• Copy the Public DNS (IPv4) value. It should be something like “ec2-nn-nnn-nnn-nn.compute-1.amazonaws.com” where nn are numbers. These numbers should match the IPv4 Public IP value.
• Open this URL : http://ec2-nn-nnn-nnn-nn.compute-1.amazonaws.com/auth in browser. It should display the OpenAM configuration screen

• Select “Create Default Configuration” and enter amadmin user’s password. If everything goes fine, it should automatically finish the setup and show “Proceed to Login” popup.

• Click “Proceed to Login “ and enter amadmin / <configured password> to login to console.

• Go to Deployment > Sites and click “Add a site”
• Enter a name for the site and set the <EBS Environment URL>/auth as the Primary URL for the site

• Go to Configure > Server Defaults > Advanced

• Add the fqdn key: com.sun.identity.server.fqdnMap[ebs environment URL domain name]= ebs environment URL domain name

• Go to Configure > Global Services > Platform
• Remove the existing cookie domain and add the ebs environment URL domain name. Please note that “us-east-1.elasticbeanstalk.com” is a TLD. So, you can’t add it as a cookie domain. Refer https://publicsuffix.org/list/public_suffix_list.dat for full list of TLDs.

• After saving the changes, logout of the console and return to login page.
• If you try to login, it will fail because we removed ec2-nn-nnn-nnn-nn.compute-1.amazonaws.com” from the Cookie domains.
• Change the URL to “http://<ebs environment url>/auth” and login with amadmin. It should work.

That’s it!! If you successfully completed all the steps, you will have a working standalone OpenAM instance in AWS which can be accessed through internet. With free tier AWS account, the total cost for setting up this environment was 0$.

In case you need a custom domain name instead of default “elasticbeanstalk.com” domain, configure Route53 to point the custom domain to EBS environment URL and modify the site configuration, cookie domains accordingly in OpenAM configuration. Refer this link.

If you want a more secure environment i.e. accessible only to internal users, select “Create this environment inside a VPC” option in “Addition Resources” while creating a new environment. Refer this link for more details.

Troubleshooting Tips

Unable to access OpenAM (/auth) :

• ssh to ec2 and navigate to /usr/share/tomcat8/webapps and check whether ROOT.war and auth.war got deployed
• If you don’t see these war files, most probably the deployment package was not bundled properly.
• Please note that if you are deploying lower versions of OpenAM in a different version of tomcat, say tomcat7, folder will be different.

OpenAM Configuration fails:

• ssh to ec2 and check the permissions for /usr/share/tomcat8 folder. It should have write access for tomcat user. Otherwise, OpenAM can’t create folders during configuration setup.
• If you don’t see write access for tomcat user, most probably the .ebextensions folder is not properly setup in deployment package. There should be .ebextensions folder in the root folder of zip package. This folder should have just one file 00permissions.config with the chmod command to change the folder permissions.
• In case the setup fails after executing few steps, OpenAM would have already created “auth” folder under /usr/share/tomcat8. In order to restart the configuration from first, ssh to ec2 instance and delete the auth folder as well as .openamcfg folder, restart the tomcat using “sudo /etc/init.d/tomcat8 restart” command.
• Another easier way to restart tomcat server is to use AWS console. From EBS Dashboard, select Actions > Restart App Server(s)

In the next blog, we will see how to use this OpenAM instance to define policies for API Gateway.