Automated installation and configuration of OpenAM

Posted 12 years ago by skatuscak

This blog is about automation of OpenAM architecture installation and configuration. As I recently automated architecture from my previous article [1] (simplified without using SSL), I would like to say something about issues I met.

All automation I did was in shell script, using also some basic tools like sed. As I wanted to keep it simple, I avoided usage of any non-standard tools like expect, that would have to be installed explicitly. This article is not step-by-step cookbook, how to automate complete OpenAM deployments. Instead, it provides tips and points out challenges for the automation.

JDK

For JDK there are two things to point out – one is that Sun JDK is unpacked to directory from which you run it, so you have to first go to this directory and then call installer binary. Second thing is that you need to press enter at the end of installation, this can be done by redirecting echo command without any parameters:

echo | ${INST_DIR}/jdk-6u26-linux-x64.bin

OpenDJ

For OpenDJ, the same as for graphical installation, you first have to copy OpenDJ to a directory, where you want to have it installed. There is no installation, setup command would only configure it. When you call setup without parameters, GUI setup is launched. To use CLI setup, there is also option to use –cli parameter, then you will be asked for every settings on console. And there is another way, most suitable for automation, to pass all setup value as parameters:

./setup -n -h ds-1.profiq.cz -p 1389 --adminConnectorPort 4444 
  -D "cn=Directory Manager" -w "dsmanager" -b dc=example,dc=com -a -i

GlassFish

For GlassFish setup, you have to accept CDDL license, to automate this you can also use echo command, echoing A as accept:

echo A | ${JAVA_HOME}/bin/java -Xmx256m -jar 
  ${PKG_DIR}/glassfish-installer-v2.1.1-b31g-linux.jar -console

Setup part running ant script is trivial (setting executable permision on ant and running ant script).

Next thing to do in GlassFish is to create domain. One non-trivial thing there is, how to pass password to asadmin command. There is a special password file for this, containing 2 lines, on one is a domain admin password and on other a master password:

AS_ADMIN_PASSWORD=domain2pwd
AS_ADMIN_MASTERPASSWORD=domain2master

When password file is ready, you can create domain just by running asadmin create-domain command with correct parameters:

./asadmin create-domain --domaindir ${INST_DIR}/glassfish/domains 
  --adminport 8989 --instanceport 1080 --user domain2adm 
  --passwordfile /tmp/domain.pwd oamdomain

Domain setup (modifying domain.xml) can be done easily using sed command:

sed "s/-client/-server/" -i domain.xml
sed "s/-Xmx512m/-Xmx1024m/" -i domain.xml

OpenAM

To deploy OpenAM to GlassFish you have to use asadmin deploy command, you just need to pass correct parameters, including password file that you already used to create a domain:

./asadmin deploy --user domain2adm --host oam-1.profiq.cz --port=8989 
  --contextroot opensso --name opensso --target server --passwordfile 
  /tmp/domain.pwd ${PKG_DIR}/opensso/deployable-war/opensso.war

To setup OpenAM, you have to use ssoConfiguratorTools. They are provided as part of OpenAM, however they are not installed by default. You need to unzip ssoConfiguratorTools.zip file to a place, from where you want to run it later. All the setup should be prepared in one config file first, you can find more details here [3]. In my case, configuration file is:

SERVER_URL=http://oam-1.profiq.cz:1080
DEPLOYMENT_URI=/opensso
BASE_DIR=/opt/oam-config
PLATFORM_LOCALE=en_US
AM_ENC_KEY=123456789012
ADMIN_PWD=oamadmin
AMLDAPUSERPASSWD=agentuser
COOKIE_DOMAIN=.profiq.cz

DATA_STORE=dirServer
DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER=ds-1.profiq.cz
DIRECTORY_PORT=1389
ROOT_SUFFIX=dc=example,dc=com
DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD=dsmanager

USERSTORE_TYPE=LDAPv3ForOpenDS
USERSTORE_SSL=SIMPLE
USERSTORE_HOST=ds-1.profiq.cz
USERSTORE_PORT=1389
USERSTORE_SUFFIX=dc=example,dc=com
USERSTORE_MGRDN=cn=Directory Manager
USERSTORE_PASSWD=dsmanager

When you have your configuration file prepared, you have to pass it to configurator:

java -jar configurator.jar -f /tmp/oam.conf

OpenAM Configuration

Now when OpenAM setup is done, there comes most important part of this article – OpenAM configuration. In this part, I try to explain how to configure parts that you typically do via web browser using Admin Console. One option here is to simulate web browser using various tools, however this is not what I wanted. OpenAM brings ssoAdminTools package, that gives you command line tool to work with OpenAM configuration. I already shown some example how to use it in my article How to upgrade OpenAM [2].

As I explained in upgrade article, installation of Admin Tools is a bit tricky. First you have to unzip ssoAdminTools.zip to directory where you want to have it installed, and then run setup script and pass there your existing OpenAM configuration directory. Also you have to provide log and debug directory (that would be created):

./setup -p /opt/oam-config -d /opt/oam-debug -l /opt/oam-log

One more thing for ssoadm to prepare is password for amadmin user, this password should be stored in a file, that should not be readable by other users:

echo oamadmin > /tmp/amadmin.pwd
chmod 400 /tmp/amadmin.pwd

Now all important settings to use ssoadm command are done. Usage of this command is not trivial, I found 3 usefull pages related to this, one is ssoadm command line reference [4] that contain list of all ssoadm commands and parameters (without any explanation of usage), and other is about Scripting an OpenAM deployment [5], that contains some simple example of usage, however it is not usable as a general guide. A list of attributes [6] is also helpful.

For many things I had just to use Google to find how other people solve issues that I had.

Now I would proceed with settings that I did manually in [1], explaining step-by-step how to do it using ssoadm.

Access Control -> / (Top Level Realm)

• Realm Attributes -> New Value: da-1.profiq.cz

There are two subcommands of ssoadm, to get realm settings, one is get-realm to get realm property values, and other is get-realm-svc-attrs to get realm’s service attribute values. Both of them require from you to know exactly which property/attribute you would like to get.

I haven’t found any command how to list realm property values, and this is just what I needed to add this setting. Only what I found was listing of realm’s services:

./ssoadm show-realm-svcs -u amadmin -f /tmp/amadmin.pwd -e /

sunAMAuthFederationService
sunAMAuthDataStoreService
sunAMAuthWSSAuthModuleService
sunAMAuthHOTPService
iPlanetAMPolicyService
sunAMAuthSAEService

It didn’t  help me much, but I found some help in OpenAM mailing list archive [8]. Command to add this new value to Sun Organization Aliases is:

./ssoadm set-realm-attrs -u amadmin -f /tmp/amadmin.pwd -e / 
  -s sunIdentityRepositoryService 
  -p -a sunOrganizationAliases=da-1.profiq.cz

Attribute -a means, that value is appended to existing aliases, and old values are not lost.

Access Control -> / (Top Level Realm) -> Data Stores -> OpenDS

• LDAP Groups container Naming Attribute : ou
• LDAP Groups Container Value: groups
• LDAP People Container Naming Attribute : ou
• LDAP People Container Value: users

There is one easy and recommended way how to do it, however this way would not work correctly. This way is to use show-datastore subcommand to get data store configuration file, then modify this file and update it back, or as in [5] to create new data store based on original one.

Command to get existing configuration is:

./ssoadm show-datastore -u amadmin -f /tmp/amadmin.pwd -e / -m OpenDS > 
  /tmp/datastore.conf

And why this wouldn’t work – because of a simple reason, one of property in this file is:

sun-idrepo-ldapv3-config-authpw=********

If I modify this configuration file and run ssoadm update-datastore, it would modify also password and OpenAM would not be able to connect to a directory server.

However, from a file that I get, I am able to get properties that I need and modify them to values I want. Then it is enough to update only those values. So in my case I prepared datastore configuration file with these values:

sun-idrepo-ldapv3-config-group-container-name=ou
sun-idrepo-ldapv3-config-group-container-value=groups
sun-idrepo-ldapv3-config-people-container-name=ou
sun-idrepo-ldapv3-config-people-container-value=users

And then I called ssoadm update-datastore with this configuration file:

./ssoadm update-datastore -u amadmin -f /tmp/amadmin.pwd -e / -m OpenDS 
  -D /tmp/datastore.conf

Access Control -> / (Top Level Realm) -> Subjects

• Test User1 is displayed

This part is easy:

./ssoadm list-identities -u amadmin -f /tmp/amadmin.pwd -e / -t User 
  -x TestUser1

testuser1 (id=testuser1,ou=user,dc=example,dc=com)
Search of Identities of type User in realm, / succeeded.

However I haven’t found any simple way how to list all accessible users, it only works when I know users name. Also, difficult part there was that at first I was not able to find any user there, because of rewritten password in data store, that I mentioned above. But when I updated only selected properties (from original configuration), user is listed.

Access Control -> / (Top Level Realm) -> Authentication -> All Core Settigns…

• User Profile: Ignored

For this setting, there is needed to set a correct attribute for correct service. Name of service and attribute can be found here [7]:

So the final command is:

./ssoadm set-realm-svc-attrs -u amadmin -f /tmp/amadmin.pwd -e / 
  -s iPlanetAMAuthService 
  -a iplanet-am-auth-dynamic-profile-creation=ignore

Access Control -> / (Top Level Realm) -> Agents -> Web -> Agent -> New…

• Name: webagent
• Password: webagent
• Re-Enter Password: webagent
• Configuration: Centralized
• Server URL: https://oam-1.profiq.cz:1080/opensso
• Agent URL: https://da-1.profiq.cz:8080
• Create

To create a Web Agent, there is a subcommand create-agent, with all required parameters:

./ssoadm create-agent -u amadmin -f /tmp/amadmin.pwd -e / -b webagent 
  -t WebAgent -a userpassword=webagent 
  -s http://oam-1.profiq.cz:1080/opensso -g http://da-1.profiq.cz:8080

Parameter -b is to set webagent name, -a userpassword is to set its password (see that -a means attribute, and value is added there using = character), -s is to set OpenAM Server URL and -g is to set Agent URL. One special parameter is -t and it is used to set a type of an agent. However, I was not able to find the list of values that can be used there, and for example for 2.2 agent, I was not able to find a way how to create it.

You can also verify whether agent is created correctly using subcommand show-agent:

./ssoadm show-agent -u amadmin -f /tmp/amadmin.pwd -e / -b webagent

Access Control -> / (Top Level Realm) -> Policies -> New Policy…

• Name: Protected Resource 1

Rules -> New…

Step 1 of 2: Select Service Type for the Rule

• Service Type: URL Policy Agent (with resource name)
• Next

Step 2 of 2: New Rule

• Name: URL Rule – HTTPS
• Resource Name: https://da-1.profiq.cz:8081/*
• GET: check, Allow
• POST: check, Allow
• Finish

Rules -> New…

Step 1 of 2: Select Service Type for the Rule

• Service Type: URL Policy Agent (with resource name)
• Next

Step 2 of 2: New Rule

• Name: URL Rule – HTTP
• Resource Name: http://da-1.profiq.cz:8080/*
• GET: check, Allow
• POST: check, Allow
• Finish

Subjects -> New…

Step 1 of 2: Select Subject Type

• Type: OpenAM Identity Subject
• Next

Step 2 of 2: New Subject – OpenAM Identity Subject

• Name: Test Subject
• Filter: User
• Search
• In available list you should see available user, Add testuser1.
• Finish

Policies are a bit tricky to create. There are too many properties to set and settings are structured, so there is used XML format for that. The easiest way how to get this its structure is to create some policy manually using Admin Console (via web browser), and then export this policy using ssoadm – this part is not to automate, it’s just preparation for automation.

./ssoadm list-policies -u amadmin -f /opt/oam.pwd -e / -o /tmp/policies

In my case, output looks like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Policies
PUBLIC "-//OpenSSO Policy Administration DTD//EN"
"jar://com/sun/identity/policy/policyAdmin.dtd">

<!-- extracted from realm, / -->
<Policies>
<Policy name="Protected Resource 1" 
  createdby="id=amadmin,ou=user,dc=example,dc=com" 
  lastmodifiedby="id=amadmin,ou=user,dc=example,dc=com" 
  creationdate="1325829744460" lastmodifieddate="1325829744460" 
  referralPolicy="false" active="true" >
<Rule name="HTTP">
<ServiceName name="iPlanetAMWebAgentService" />
<ResourceName name="http://da-1.profiq.cz:8080/*" />
<AttributeValuePair>
<Attribute name="POST" />
<Value>allow</Value>
</AttributeValuePair>
<AttributeValuePair>
<Attribute name="GET" />
<Value>allow</Value>
</AttributeValuePair>
</Rule>
<Rule name="HTTPS">
<ServiceName name="iPlanetAMWebAgentService" />
<ResourceName name="https://da-1.profiq.cz:8081/*" />
<AttributeValuePair>
<Attribute name="POST" />
<Value>allow</Value>
</AttributeValuePair>
<AttributeValuePair>
<Attribute name="GET" />
<Value>allow</Value>
</AttributeValuePair>
</Rule>
<Subjects name="Subjects:1325829665266Qs738aE=" description="">
<Subject name="Test Subject" type="AMIdentitySubject" includeType="inclusive">
<AttributeValuePair><Attribute name="Values"/>
  <Value>id=testuser1,ou=user,dc=example,dc=com</Value>
</AttributeValuePair>
</Subject>
</Subjects>
</Policy>
</Policies>

The structure is easy to read, and when you know the format, you can easily prepare your own policies. In this case I kept there also link to SSL Web Server instance, to show how there can be 2 rules in one policy. When you have your policies prepared in XML file, you just need to import them to OpenAM using create-policies subcommand:

./ssoadm create-policies -u amadmin -f /opt/oam.pwd -e / -X /tmp/policies

Sun Web Server

For Sun Web Server, there is possible to use silent install, but you need to have prepared a state file containing the configuration, and pass this file to an installer. One way how to get this file is to do manual installation first, using savestate parameter:

./setup --savestate

In my case, state file looks like this:

[STATE_BEGIN Sun Java System Web Server cd1882504a4a1bc91210ec402c269d9e7ded29b4]
defaultInstallDirectory = /sun/webserver7
currentInstallDirectory = /opt/ws7
UPGRADE = false
SELECTED_COMPONENTS = svrcore,admincli
USE_BUNDLED_JDK = true
JDK_LOCATION =
IS_ADMIN_NODE = false
STARTUP_ONBOOT = false
CREATE_SERVICE = false
ADMIN_HOST = da-1.profiq.cz
ADMIN_SSL_PORT = 8990
ADMIN_PORT =
ADMIN_UID = profiq
ADMIN_NAME = admin
ADMIN_PASSWD = web4dmin
NODE_HOST =
NODE_SSL_PORT =
REGISTER_NODE =
WEB_SERVERNAME = da-1.profiq.cz
WEB_PORT = 8080
WEB_UID = profiq
WEB_DOCROOT =
SIXTYFOURBIT_INSTALL = false
CONFIG_NAME = da-1.profiq.cz
SKIP_INSTANCE_CREATION =
START_ADMIN = true
[STATE_DONE Sun Java System Web Server cd1882504a4a1bc91210ec402c269d9e7ded29b4]

You can intuitively find out, which property means what, so if you know the format, you can just take existing state file, edit it to your values and use it, without doing manual installation to get it.

Installation with state file is simple:

./setup --silent /tmp/wsstatefile

OpenAM Web Agent

As I used Sun Web Server, I used also OpenAM Web Agent for Sun Web Server. This web agent is provided in a zip file sjsws_v70_Linux_64_agent_304.zip, that is again not directly installable, it should be just unzipped and then called agentadmin to set it up.

There is one little trick for an automation. Before installation starts, you are asked to answer yes on an license agreement. I tried to send there yes using echo and pipe, however it didn’t work for me, so I used small workaround. I found out, that this license is checked using file web_agents/sjsws_agent/data/license.log, so before installation started, I prepared content of this file to look as license was already agreed:

echo "profiq=01/15/2012 04:52:07 CET" > 
  ${INST_DIR}/web_agents/sjsws_agent/data/license.log

When this is set, I’m not asked to confirm license agreement anymore and installation can be automated.

Silent installation of OpenAM Web Agent is very similar to silent installation of Web Server, you need a state file and you can get it by proceeding manual installation with saveResponse parameter, or you can create it by yourself when you know the format.

To get a state file using manual installation use this command:

${INST_DIR}/web_agents/sjsws_agent/bin/agentadmin --install 
  --saveResponse /tmp/wastatefile

In my case, state file looks like this:

CONFIG_DIR= /opt/ws7/https-da-1.profiq.cz/config
AM_SERVER_URL= http://oam-1.profiq.cz:1080/opensso
AGENT_URL= http://da-1.profiq.cz:8080
AGENT_PROFILE_NAME= webagent
AGENT_PASSWORD_FILE= /tmp/webadmin.pwd

With state file, silent installation is proceeded by this command:

${INST_DIR}/web_agents/sjsws_agent/bin/agentadmin --install 
  --useResponse /tmp/wastatefile

And that’s all, when you automated all steps from [1] correctly, you can try to connect to Web Server, and you should get OpenAM login page, and after successful login Web Server default page – the same results as if all was installed and configured manually.
Refereces
[1] How to install and configure OpenAM Web Policy Agent

[2] How to upgrade OpenAM

[3] OpenAM – Configurator Parameters

[4] ssoadm command line reference

[5] Scripting an OpenAM deployment

[6] Authentication Attributes

[7] Authentication Attributes – Core

[8] [OpenAM] New DNS Alias for Top Level realm