Ellipse 8 Authentication guide

Ellipse 8 Open Authentication Guide

Commercial In Confidence
Copyright 2016 ABB
All Rights Reserved
Confidential and Proprietary
Legal Disclaimer
The product described in this documentation may be connected to, and/or communicate information and data via, a network
interface, which should be connected to a secure network. It is your sole responsibility to ensure a secure connection to the
network and to establish and maintain appropriate measures (such as but not limited to the installation of firewalls, application
of authentication measures, encryption of data, installation of antivirus programs, etc.) to protect the product, the network,
your systems, and the interface against any kind of security breach, unauthorised access, interference, intrusion, leakage,
damage, or corruption or theft of data. We are not liable for damages or losses related to any such security breach,
unauthorised access, interference, intrusion, leakage, damage, or corruption or theft of data.
Preface
The Ellipse 8 Open Authentication Guide is part of the Ellipse Technical Documentation Library. This documentation library
comprises a number of guides that provide information for the implementation, administration, and operation of the Ellipse
application in a secure, networked environment.

Summary information

Confidentiality
The contents of this document are confidential between ABB and its customers. The parties must keep the information herein
confidential at all times and not disclose it, or permit it to be disclosed, to any third party, apart from any of their officers,
employees, agents or advisers who have a specific need to access the information herein and have agreed to be bound by the
terms of confidentiality.

Document Control
Once the project is completed or terminated, this document will revert to an uncontrolled document status. No further advice
will be provided, and each recipient may either destroy the document or mark it as obsolete and retain it for future personal
reference.
All copies of this document will be issued electronically.

Who should use this guide?

This guide provides information on Ellipse 8 Authentication options for Ellipse Technical Consultants and customers seeking to
implement more advance authentication options such as:
Windows Desktop Single-Sign On Directory chaining Secure LDAP (SSL) Social authentication via OAuth 2.0 providers like
Google, Facebook, MSN

How to use this guide

This guide describes:

• Installation and configuration of OpenAM as the primary Access Management source for Ellipse
• Configuration of an existing Ellipse instance, Appliance or non-Appliance based to support integration with OpenAM

Purpose
This document is a guide to customers and consultants involved with establishing the security Architecture of Ellipse 8.
Scope
This section indicates what is included and also what is not included in the document.
The following is in scope and covered in a section of this document.

• Installation of OpenAM Server

• Testing OpenAM authentication modules
• Configuring Ellipse to use OpenAM
• What is needed prior to installation
• Troubleshooting authentication problems
The following is not covered in this document as it is out of scope.

• Configuring Active Directory or other LDAPv3 compliant directory service

Installation Definitions
The following table introduces terminology needed to understand the Ellipse Installation.

Term Definition
IP address Internet Protocol address; a numerical label assigned to each device (for example: computer, printer)
participating in a computer network.
Instance Example Ellipse production
Oracle Linux (OL) Free operating system variant based on Red Hat Enterprise Linux.

Table - Installation terminology and definitions

Installation Overview
The following table outlines the key tasks assoicated with the high level installation activities:

Activity Tasks
Prepare Identify servers/URLs and bind credentials of exsiting Active Directory or other LDAPv3 compliant directory
services that record existing organisational user profiles that Ellipse should authenticate against.
Download Download the OpenAM software (OpenAM Server, Tools, Configurator) plus additional Linux system
tools/packages.
Install Install and configure Ellipse to use basic, out-of-the-box authentication to an existing Active Directory service
or other LDAPv3 compliant directory service.
Configure Configure Web Policy agent and Ellipse to use OpenAM.
Prepare
1. Determine where OpenAM Enterprise Server is to be installed
Non-Appliance installations
Non Appliance customers will need to source an additional server, physical or virtual to accomodate the OpenAM Enterprise
software that Ellipse to redirect unauthentication requests to.
ABB recommends the OpenAM server to be sized according to the table following:

Server Core(s) RAM(GB) Minimum Disk Space Recommended Disk Space

OpenAM Server 2 4 20 120

The OpenAM server is not expected to require significant resources owing to the fact that the service itself is expected to do
very little processing in normal circumstances. Most processing occurs during login and logoff.
Appliance installations
Appliance based installations have at least two options:

a. source an additional server, physical or virtual to accomodate the OpenAM Enterprise software that Ellipse to redirect
unauthentication requests to
b. instal the OpenAM Server software on the Appliance host. The Appliance utility app-port-manager can be used to
"open" the ports required to ensure that traffic for OpenAM iServer s routed to the service.
• Verify Oracle Linux operating system instance created with root user access available
2. Get AD/LDAP search and credentials
• Obtain Bind DN and password to be used by Open config steps
• Ensure directory is populated with user profiles and associated attributes that should be used during the Ellipse
authentication processes.
• Record the DN and other important directory specific attributes and metadata
Download
1. Download these componets:
• Tomcat 8.0
http://download.fedoraproject.org/pub/epel/6/$basearch

• OpenAM Enterprise 12.0.0

https://backstage.forgerock.com/downloads/enterprise/openam/openam12/12.0.0/OpenAM-12.0.0.zip

• OpenAM Web Policy Agent 3.3.0

https://backstage.forgerock.com/downloads/enterprise/openam/webagents/stable/3.3.0/Linux/64/Apache-v2.2-Linux-64-Agent-3.3.0.zip

• OpenAM Configurator 12.0.0

https://backstage.forgerock.com/downloads/enterprise/openam/openam12/12.0.0/SSOConfiguratorTools-12.0.0.zip

• OpenAM Tools 12.0.0

https://backstage.forgerock.com/downloads/enterprise/openam/openam12/12.0.0/SSOAdminTools-12.0.0.zip

• You will need to have registered with ForgeRock to download the OpenAM Enterprise software and tools.
2. Download additional Linux system packages and tools
• Use yum to install the the OpenLDAP client tools plus other useful tools like netstat andtcpdump:
yum install openldap-client
yum install tcpdump sysstat
Install
This section describes the tasks required to install OpenAM and configure Ellipse to use OpenAM during the Ellipse
authentication phase.
All the tasks described in the "Prepare" section above are assumed to have been completed.
The OpenAM server should be installed its own server, physical or virtual in the same domain as the Ellipse application to be
protected. Cross domain configurations are considered more complex and may require consulting to assist.
Steps

1. Install OpenAM Server

• Create a DNS record for your OpenAM host - 'openam.domain'
• Add the output of 'hostname' to a new '127.0.0.1' entry in '/etc/hosts'
• Make sure the EPEL repo is configured in /etc/yum.repos.d
• Install Tomcat

yum install tomcat'

2. Deploy the OpenAM war
• Rename the downloaded OpenAM WAR to 'openam.war'
• Copy 'openam.war' to '/usr/share/tomcat/webapps' directory
• Start Tomcat

systemctl start tomcat

• Connect to the OpenAM server UI with a URL of the form:

http://<openam_server>:8080/openam
• Choose "Default Configuration". You should receive a message indicating that creation of the default configuration
succeeded.
3. Install Apache HTTTPD if required
• If you are attempting to reconfigure an Appliance you can skip this step and use the HTTP service on the CmdCtl guest. If
you are a non-Appliance installation then you should look to do the same in your installation by using the HTTP server
that is fronting your Ellipse online, EWS and VIP requests.
• If you are a non-Appliance installation that has not previously used Apache to front requests for Ellipse, EWS and/or VIP
then you will need to install and configure and instance of Apache HTTP server so that the OpenAM Web Policy Agent
software can be installed and configured to intercept requests for Ellipse online, EWS and or VIP.
• If you don't have an Apache HTTP server instance that is already fronting Ellipse, the you can install one using yum, on a
new or existing OL server, physical or virtual:
yum install httpd

Not that some Non-Appliance, do-it-youself style installations, may see the package name changed from "httpd" to "httpd22" or "httpd24" corresponding to the version of Apache HTTP Server being used. Appliance installations currently use Apache HTTP Server 2.2.

4. Install OpenAM Web Policy Agent for Apache HTTP server for Ellipse
• Create password file for Web Agent -
echo <WEB_AGENT_PASSWORD> > /tmp/<envname>

• Run the Web Policy agent installer providing parameter values when prompted, as follows:
Param Value
OpenAM URL The URL where OpenAM server has been installed, usually of the form:
http://openam.domain:8080/openam
Agent URL The URL of the Apache instance where the Agent is installed, usually of the form:
http://ellipse-env.domain:80

• OpenAM URL - http://openam.techops.ventyx.abb.com:8080/openam

• Agent URL - http://lb.techops.ventyx.abb.com
• Refer to the OpenAM install documentation for more detail information -
http://docs.forgerock.org/en/openam-pa/3.3.0/web-install-guide/#chap-apache-24
• Ensure service starts on server boot

chkconfig httpd on; service httpd start

Configure
1. Configure OpenAM Realm
• Log into the OpenAM Server as the admin user 'amadmin'
• Create a new realm
Param Value
Name <envname> where envname is the name of the Ellipse environment to be protected
Realm/DNS Aliases Load balanced Ellipse environment access URL On an Appliance this would usually be something
like: ellipse-<envname>.appliancehost.domain

• Select the realm created above and navigate to Authentication > Core > All Core Settings and set parameter values as
follows:
Param Value
User Profile Dynamic
User Attribute Mapping to Session Attribute <uid_attr_name>|UserToken

where <uid_attr_name> is the name of the LDAP record atribute that holds the user name to be authenticated. This entry is
critical because it creates the mapping between the LDAP profile attribute and the OpenAM session attribute that the Ellipse
code will use to verify token validity.

• Execution of the above step is critical because it ensures that the username entered by the user is available to Ellipse as
a session attribute. Ellipse uses the OpenAM security token generated after successfull authentication to retrieve the
session and then extract the session attribute created to record the user name. For example, under AD, the
"samAccountName" usually records the users Windows domain account user name. If this attribute were to be the one
that is determined to holds the name of the Ellipse user, then the attributed map value would be
"samAccountName|UserToken".
• Note that the "UserToken" portion of the example mapping must be the same as the value of JBoss system property
named "mincom.openam.usertoken" which defaults to "UserToken"
• Save the configuration changes
2. Create new Authentication Module(s)
• Navigate to Access Control > realm-ellipse-<envname> > Authenticaton > Module Instances > new, setting parameters
as follows:
Param Value
Name <custLDAPname>
Type LDAP or Active Directory or Windows Desktop SSO or OAuth 2.0 / OpenID Connect

• Select the new LDAP module created above (exanmple was custLDAPname>, and enter parameters as follows:
Param Value
Primary LDAP Server IP address:port or hostname:port of the customer's primary Active Directory or
other LDAPv3 compliant directory server
Secondary LDAP Server IP address:port or hostname:port of the customer's secondary Active Directory or
other LDAPv3 compliant directory server
DN to Start User Search DN to search for users
Bind User DN DN of a user with "bind" authority to the Directory Service
Bind User Password Password of user with "bind" authority to the Directory Service
Attribute Used to Retrieve User Profile LDAP attribute name that will be used to locate the user profile from the OpenAM
Datastore
Attributes Used to Search for a User to LDAP attribute names that will be used to find the user to be authenticated
be Authenticated
User Search Filter Optional, in most cases not require. Used to further filter the LDAP search task.
Search Scope SUBTREE

• Navigate to Access Control > realm-ellipse-<envname> > Authenticaton > Authentication Chaining > ldapService,
setting parameters as follows:
Param Value
Instance LDAP
Criteria REQUISITE
On an Appliance this would usually be something like:
ellipse-<envname>.appliancehost.domain
Instance to 'LDAP' and Criteria to 'REQUIRED', save

3. Configure OpenAM Web Agent

• Log into the OpenAM Server as an Administrator - 'amadmin'
• Navigate to Access Control -> / (Top Level Realm) -> Agents
• Select "New" to create a new agent with paramaters as follows:
Param Value
Name <envname> where envname is the name of the Ellipse environment to be protected
Configuration Centralised
Server URL 'http://openam.domain:8080/openam'
Agent URL 'http://lb.ventyx.abb.com:80'

• Select the new <envname> agent

• Select "General" tab and update parameter(s) as follows:
Param Value
SS0 Only Mode Enabled

• Save the agent changes

• Navigate to Access Control > realm-ellipse-<envname> > Services and update parameter(s) as follows:
Param Value
Login URL 'http://openam.<domain>:8080/openam/UI/Login?realm=<envname>' +
Logout URL 'http://openam.techops.ventyx.abb.com:8080/openam/UI/Logout?realm=<envname>'

• Save the OpenAM Services changes

Param Value
LDAP Server IP address or host name and port of the LDAP server you are adding as an Authentication
module
LDAP Bind DN Name of a user that can bind to the directory server
LDAP Bind Password Password of user that can bind to the directory server
LDAPv3 Plug-in Search SCOPE_SUB (recommended)
Scope

4. Deploy OpenAM Web Policy Agent to Apache HTTP Server

Note
Even though the profile and session attribute mapping settings are marked as "Hot-Swappable: yes", setting changes
still seem to take quite some time to come into effect. The amount of time is supposed to be controlled by the Agent
configuration refresh interval setting. If you want the change to persist immediately, you should restart the agent with
"service httpd restart"

5. Configure Ellipse for OpenAM integration

• Add these properties to the JVM args for each Ellipse JBoss instance associated with a given environment:
-Dmincom.openam.enabled=true
-Dellipse.jaas.disabled=false
-Dmincom.openam.http.enabled=true
-Dmincom.openam.server=http://aubne-s-dl0023.dev.mincom.com:8080/openam
-Dmincom.openam.uidheader=UserToken
-Dmincom.openam.skipsessionvalidate=true

Use this parameter when you want the RIA code to extract the username to sign on to Ellipse with from a HTTP header
embedded in the request by OpenAM agent after successful authentication via the OpenAM server. This authentication
mechanism is used mostly in development and test environments only as it is less secure than the alternative which is to use
call OpenAM service with the OpenAM authentication token to retrieve the user name.
login with:
http:/ellipse-envname.apliancehostname.domain/ria/ui.html
Manual configuration of Apache HTTP Server to use the
Web Policy Agent
Installation of the Web Policy Agent is supposed to update your Apache httpd.conf configuration to include the OpenAM Web
Policy Agent modules, effectively "activating" the Web Policy Agent intercept point. In our experience, the OpenAM Web Policy
Agent software installation does NOT always reliably perform this change and it needs to be checked following apparent
successful installation of the Web Policy Agent.
To check if the OpenAM Web Policy Agent module has been installed in the main Apache configuration configuration file and/or
any of the folder that Apache is configured to look for configuration files, most commonly in:
/etc/httpd/httpd.conf /etc/httpd/conf.d/*
use an editor or search tool to look for this directive. Following is an example using "grep" to search:

[root@cmdctl01 httpd]# cd /etc/httpd/

[root@cmdctl01 httpd]# grep -r "include /root/web_agents/apache22_agent/Agent_001/config/dsame.conf" *
conf.d/openam.conf:include /root/web_agents/apache22_agent/Agent_001/config/dsame.conf
[root@cmdctl01 httpd]#

Both Appliance and non-Applioance installations may consider introducing an additional HTTP configuration file (under conf.d)
in order to ensure that the OpenAM Web Policy agent is configured to intercept requests passing through the Apache instance
on the "cmdctl" guest and destined for Ellipse.

1. Create a new file "/etc/httpd/conf/conf.d/openam.conf".

2. Insert these lines:

include ${web_agent_home}/web_agents/apache22_agent/Agent_001/config/dsame.conf
where ${web_agent_home} is the fully qualified path of the location where the OpenAM Web Policy Agent software was
installed/unzipped.

1. Restart the Apache HTTP server:

service httpd restart

Configure JBoss Changes
In addition to the required Apache HTTP configuration changes, each JBoss application server instance for a given environment
needs to have some JVM arguments added so that the Ellipse instance on that guest will properly deal with the OpenAM
security tokens that will be passed by the Web Policy agent to Ellipse after successful authentication has occurred.
The only change required irst is to make sure all timed-out connections between the JBoss server and the client (in our case,
modjk) are disposed of, and the second to modify the timeout between JBoss and the database.

1. On each JBoss server, edit the file "/etc/jboss-as/ellipse.conf".

2. Add the following JVM arguments to the JAVA_OPTS variable:
-Dellipse.jaas.disabled=false
-Dmincom.openam.http.enabled=true
-Dmincom.openam.uidheader=UserToken
-Dmincom.openam.server=<openam_url>

::Note: that the change must be performed on __all__ Ellipse server types / guests for a given environment. A typical production environment will often include:

• Ellipse Online servers (x3)

• Ellipse Batch server (x1)
• Ellipse Web Services server (x1)
• Restart each of the the JBoss servers that you modify JAVA_OPTS.
Installation Verification
Steps
Start OpenAM Server
The OpenAM server which provides Ellipse Online runs as a service and should start on each boot of the virtual server. These
commands must be run as the root user.

1. Start OpenAM server

[root@amserverhost]$ systemctl start tomcat

2. Login to Ellipse to confirm successful startup

Start Ellipse Batch
The JBoss Application Server which provides Ellipse Batch functionality runs as a service and should start on each boot of the
virtual server. These commands must be run as the root user.

1. To start manually

[root@batchhost]$ systemctl start ellipse

2. Check the BATCH.Log for startup. The Ellipse Batch JBoss server logs are at

/opt/ellipse/jboss-as-7.1.1.Final.noHornetQ/standalone/log/server.log
Start Web Policy agent (Apache HTTP Server)
The OpenAM Web Policy Agent runs inside the Apache Web Server which fronts the Ellipse instance. The Apache server should
already be defined as a service which start automatically when the server / guest boots.

1. Start

[root@wwwhost]$ service httpd start

2. Open a browser and navigate to your normal Ellipse URL, usaully of the form:

http://ellipse-<envname>.appliancehost.domain/ria/ui.html

The Ellipse login screen is displayed

Shutting systems down

Stopping the Apache HTTP Server (Load Balancer)

To stop:

[root@wwwhost]$ service httpd stop

Stopping Ellipse
This procedure applies to Ellipse Online, Ellipse Batch and Ellipse Web Services instances.
To stop:

[root@batchhost]$ systemctl stop ellipse

If JBoss does not shutdown in less than one minute:

[root@batchhost]$ kill <jboss-pid>

Stopping the Tomcat service

The Tomcat Server can be stopped. GeoServer will automatically be stopped by Tomcat.

1. Stop the Tomcat Server

[root@openam]$ # systemctl stop tomcat

Disabling the Web Policy Agent

You can disable the Web Policy agent by:

• removing the Apache HTTP "include" conf directive (added automatically by the Web Policy Agent install or in some cases
manually after the install by the installer)
• restarting Apache HTTP
Note that if you do disable the Web Policy Agent then you'll need to also remove the JVM args added to Ellipse which "tell"
Ellipse to look for the security tokens generated by the Web Policy Agent following a successful authentication request during
Ellipse sign-on.