Second Factor Authentication with OpenAM 10.1

Overview

Second Factor Authentication (SFA) has become for many organizations a “must have” functionality and although several solutions are available the associated cost sometimes could be significant. Fortunately with open standards for authentication like OATH (you can find more here) low cost alternatives have surfaced the IAM space. Our last article discussed a scenario for upgrading OpenSSO 8.0 to OpenAM 10.1 and this time we will focus in one of the authentication features available in the new version. OpenAM 10.1 have two options to implement SFA, one using the HOTP authentication module which is based on a proprietary algorithm for one-time password (OTP) generation, and the second via the OATH module which implements the OATH standard. This article will focus in how to use both modules, highlighting the pros and cons of each option.

Some assumptions to consider

  • This article assumes that you are familiar with Sun/Oracle’s OpenSSO or ForgeRock’s OpenAM, concepts and configuration options
  • Basic knowledge of second factor authentication and the OATH standard, here you can find more information about it. Please note that OATH is not the same as OAuth, while OATH focus in authentication OAuth is an open standard for authorization

Second Factor Authentication

The main idea of using SFA is to strengthen the security beyond the basic user & password approach used to protect systems and OpenAM allows you to do that by using one of two modules in the configuration. The HOTP module works together with the Data Store module to retrieve user attributes like email or phone number and send one-time passwords to complete the authentication. OATH in the other hand is mean to work with devices like mobile phones and PDAs and support Time-Based One-Time Password (TOTP) and HMAC-Based One-Time Password (HOTP) algorithms. In short HOTP is an event-based algorithm where generated passwords have a short duration of live whereas TOTP passwords have longer live or are valid for a “long time”.

Figure 1 – OpenAM Authentication Service Architecture


2013-09-01-00

Setting SFA using the HOTP Module

The steps below describe how to setup second factor authentication using the HOTP module in OpenAM:

1. Login to OpenAM admin console and go to Access Control -> Top Level Realm -> Authentication -> Module Instances and define the following values for the HOTP module:

Parameter                             Value
Mail Server Hostname                  my-sso
Mail Server Host Port                 25
Mail Server Secure Connection         NO SSL/TLS
Email From Address                    no-reply@acme.local
One Time Password Validity Length     5
One Time Password Length              6
One Time Password Delivery            E-mail
Mobile Phone Number Attribute Name    telephoneNumber
Mobile Carrier Attribute Name         carLicense
Email Attribute Name                  mail

For simplicity, we are using three existing attributes from the inetOrgPerson object class to store the “Mobile Phone Number”, “Mobile Carrier” and “Email Address” values however in a real scenario you may need to extend a custom object class to accommodate some of these values. If you mail server uses basic authentication you will need also to specify the credentials.

Leave the other default values and save the changes.

2013-09-01-01

2. Go to Access Control -> Top Level Realm -> Authentication -> Authentication Chaining and click in the New button to create a new chain. Enter the following values:

Parameter        Value
Name             twofactorHOTP

Select the Add button twice to define two instances, one for the data store LDAP and the second for the OATH module. LDAP must have a “requisite” and the HOTP a “required” criteria, this is needed in order to retrieve the “Mobile Carrier”, “Phone Number” and “Email Address” from the user store (in our example LDAP) that later will be used by the HOTP module to send the OTP password. Use the following values to define the instances:

Instance            Criteria
LDAP                REQUISITE
HOTP                REQUIRED

Leave the other default values and save the changes.

2013-09-01-02

3. Set the authentication for users. For testing purposes this step is optional, however once your test is completed, you must set the authentication as indicated below to enable SFA for your end users.

Login to OpenAM and go to Access Control -> Top Level Realm -> Authentication -> Core and select “twofactorHOTP” as the default authentication chain for the “Organization Authentication Configuration” parameter and save the changes.

2013-09-01-03

4. Update the test user attributes with the “Mobile Carrier”, “Phone Number” and “Email Address” as needed by the HOTP module to send the OTP password. In our example, we will use the email address as a target to send the OTP password, however if you selected “SMS” or “SMS and E-mail” in the “One Time Password Delivery” configuration parameter, then you must also populate the “Mobile Carrier” and “Phone Number” attributes.

Go to Access Control -> Top Level Realm -> Subjects -> Users and edit the attributes for the test user. In our example we updated test user “tfa.user001” with the following values:

Parameter                             Value
Phone Number (telephoneNumber)        777-2020
Email Address (mail)                  tfa.user001@acme.local

In a production environment using SMS as the target for OTP delivery, you will need to populate the “Mobile Carrier” value for existing users and implement a similar method for new users in your data store.

5. To test the new configuration, enter http://my-sso:8080/openam/UI/Login?service=twofactorHOTP in a browser to login to OpenAM using the test user. OpenAM will prompt for the LDAP credentials and then if sucessful for the OTP password before the user interface can be shown to the user.

Figure 2 shows the initial login prompt and Figure 3 shows the page prompting to enter the OTP password, the user interface is displayed if both authencations succeed.

Figure 2 – OpenAM User and Password Login Page


2013-09-01-04

Figure 3 – OpenAM Second Factor Authentication (HOTP Module)


2013-09-01-05

Figure 4 shows the email notification sent by the HOTP module to the user if the Request OTP button is selected to get the OTP password.

Figure 4 – OTP Notification Sent by the HOTP Module


2013-09-01-06

The HOTP module was the first SFA module to be included in OpenAM however not following the OATH standard makes it incompatible with popular mobile applications like Google Authenticator that generate OTP passwords based on the OATH standard. In the other hand having the option to deliver the OTP via text messages (SMS) or E-mail help with scenarios where you do not have access to devices or applications that generates OTP passwords.

Setting SFA using the OATH Module

The steps below describe how to setup second factor authentication using the OATH module in OpenAM:

1. Login to OpenAM admin console and go to Access Control -> Top Level Realm -> Authentication -> Module Instances and define the following values for the OAHT module:

Parameter                    Value
One Time Password Length     6
Minimum Secret Key Length    32
Secret Key Attribute Name    postalAddress
OATH Algorithm to Use        HOTP
Counter Attribute Name       employeeNumber

For simplicity, we are using two attributes from the inetOrgPerson object class to store the “Counter” and “Secret Key” values however in a real scenario if you already use these attribute you may need to create an extended object class to accommodate these values.

Leave the other default values and save the changes.

2013-09-01-07

2. Go to Access Control -> Top Level Realm -> Authentication -> Authentication Chaining and click in the New button to create a new chain. Enter the following values:

Parameter                    Value
Name                         twofactorService

Select the Add button twice to define two instances, one for LDAP and the second for the OATH module. LDAP must have a “requisite” and OATH a “required” criteria, this is needed in order to retrieve the “Secret key” and “Counter” from the user store (in our example LDAP) that later will be used by the OATH module to generate the OTP password. Use the following values:

Instance                     Criteria
LDAP                         REQUISITE
OATH                         REQUIRED

Leave the other default values and save the changes.

2013-09-01-08

3. Set the authentication for users. For testing purposes this step is optional, however once your test is completed, you must set the authentication as indicated below to enable SFA for your end users.

Login to OpenAM and go to Access Control -> Top Level Realm -> Authentication -> Core and select “twofactorService” as the default authentication chain for the “Organization Authentication Configuration” parameter and save the changes.

2013-09-01-09

4. Update the test user attributes with the “Secret Key” and “Counter” values needed by the OATH module to generate OTP passwords. In our example, we used an open source tool “oathtool” which is part of the OATH toolkit to generate a 32-byte length key and decided to use an initial value of zero for the counter.

Go to Access Control -> Top Level Realm -> Subjects -> Users and edit the attributes for the test user. In our example we updated test user “tfa.user001” with the following values:

Parameter                              Value
Employee Number (employeeNumber)       0
Home Address (postralAddress)          A2CA4C950F3711F5EB49F3B5CDA5F739

In a production environment you will need to generate and populate the secret keys for each existing user and implement a similar mechanism for new users in your data store.

5. To test the new configuration, enter http://my-sso:8080/openam/UI/Login?service=twofactorService in a browser to login to OpenAM using the test user. OpenAM will prompt for the LDAP credentials and then if sucessful for the OTP password before the user interface can be shown to the user.

Figure 5 shows the initial login prompt and Figure 6 shows the page prompting to enter the OTP password, the user interface is displayed if both authencations succeed.

Figure 5 – OpenAM User and Password Login Page


2013-09-01-10

Figure 6 – OpenAM Second Factor Authentication (OATH Module)


2013-09-01-11

ForgetRock have done a good job in adding the OATH module, opening the door to implement SFA at a very low cost in OpenAM. Typical deployments needed keyfobs or tokens delivered to end users to generate OTP passwords but now with applications like Google Authenticator you can use mobile devices instead to generate OTP passwords eliminating the need to buy keyfobs or tokens for your end users. Will be nice however to see some exhanced features in the OATH module like support to send OTP passwords via E-mail or text messages (SMS) in the same way as the HOTP module does and the ability to distribute the secret key to end users, for example via E-mail to facilitate the setup of applications that generate OTP passwords like Google Authenticator.

*** The End ***

  

Upgrading OpenSSO v8.0 to OpenAM v10.1

Overview

Oracle OpenSSO (formerly SUN OpenSSO) has been around for quite some time now and there are still many organizations who continue running their businesses with this product. ForgeRock, the company who took over OpenSSO source code continued its development and has now released several iterations under the OpenAM name that make the idea of an upgrade very attractive. For those who want to continue in the OpenSSO legacy this could represent benefits in taking advantage of the new features besides the low cost and support offered by ForgeRock. This article will review the upgrade process but a further article will focus in some of the new features available in the latest version of OpenAM.

Some assumptions to consider

  • This article assumes that you are familiar with OpenSSO product, OpenSSO agents concepts and configuration options
  • Knowledge of Oracle Directory Server Enterprise Edition, also known as SUN Directory Server Enterprise Edition (DSEE) is recommended since the scenario described in this article will use DSEE as the OpenAM user store
  • Familiar with IBM WebSphere Application Server (WAS) deployments, instances and Network Deployment Manager configuration

The Scenario

The scenario used in our upgrade process consisted of an OpenSSO v8.0 configuration running on top of GlassFish Application Server v2.1 with a separate LDAP server (DSEE v6.3) hosting the user and configuration data stores, and an OpenSSO J2EE Agent v3.0 installed on IBM WebSphere Application Server v6.1. OpenAM v10.1.0 out of the box allows you to use OpenDJ, a Java base LDAP directory server to store user and configuration data, however many organizations out there are using DSEE as the user and configuration data store because this product has a long history of being very stable in production environments. As a reference in Figure 1, we show the architecture for our scenario.

Figure 1 – OpenSSO Architecture (before upgrade)


Image00

The approach used to perform the upgrade consisted of the following steps:

  1. Since there is not direct upgrade path from OpenSSO v8.x to OpenAM v10.x, we will do a fresh installation of OpenAM v10.x in a separate machine
  2. Once the installation is complete, we will configure OpenAM v10.x with a new configuration data store and configure it to point to the existing user store in DSEE v6.3
  3. We will manually copy the OpenSSO configuration to the new OpenAM server
  4. Since the agent software in OpenSSO is still compatible with OpenAM, we will reconfigure the agent to point to the new OpenAM server
  5. Once all the previous steps are completed, we will test the new configuration and consider the upgrade process completed

Step 1: Installing OpenAM

This step assumes that we have installed GlassFish v.2.1 or a close version in the target server. One prerequisite to keep in mind is that OpenAM requires at least Java v1.6 installed to work properly. Additionally, memory in the GlassFish server needs to be adjusted. In our sample scenario we made the following changes:

1. Login to the GlassFish admin console and select Application Server -> JVM Settings -> JVM Options, and enter the following parameter-values (together) in the configuration:

-XX:MaxPermSize=256m
-Xmx1024m

Image01

2. Deploy the OpenAM war file in GlassFish. Login to the admin console and select Application -> Web Applications -> Deploy and enter the following values, assuming the openam.war file resides in the c:\temp\openam folder.

Parameter         Value
Path              c:\temp\openam\openam-server-10.1.0-Xpress.war
Context root      opensso

Step 2: Configuring OpenAM Data Stores

Once OpenAM has been deployed, the next step is to setup the configuration data store. We created a new instance in the DSEE server to host the OpenAM configuration, below the details:

1. Login to DSEE admin console (aka DSCC) and go to Directory Servers -> Servers -> New Server and enter the following values:

Parameter               Value
Hostname                my-ds6
LDAP Port               60389
SSL Port                60636
Instance Path           c:\ds6-amconfig
Directory Manager       cn=Directory Manager
Password                *********
Runtime ID              Administrator
Password                *********
DSCC Agent Port         11162 (Default)
Description             Acme OpenAM Configuration

Image02

Select Next and choose the default values to create the new instance. Go to Directory Servers -> MY-DS6:60389 -> Suffixes to create a new suffix for the store. For our scenario, we enter the following value:

dc=openam,dc=acme,dc=com

Image03

Click Next, choose do not replicate, select the target server (in our case MY-DS6:60389), continue choosing the default values and location, and then select create top entry. Once completed, make sure to start the new instance before continuing with the next step.

2. Open a browser window and type the following URL to access the OpenAM configuration wizard.


http://my-sso:8080/openam/config/options.htm

Select Create New Configuration (Custom Configuration), define you administrator password and enter the following values:

Parameter          Value
URI                http://my-sso.acme.local
Cookie domain      .acme.local
Local              en_US
Config Directory   c:\Documents and Settgins\Default User\openam

Click Next and enter the following values for the configuration data store location:

Parameter          Value
Config Data Store  [Select OpenDJ or DSEE]
SSL Enable         [unchecked]
Hostname           my-ds6
Port               60389
Entry key          *****************
Root suffix        dc=openam,dc=acme,dc=com
User Logon ID      cn=Directory Manager
Password           *********

Click Next and enter the following values for the user data store location:

Parameter          Value
Config Data Store  [Select DSEE]
SSL Enable         [unchecked]
Hostname           my-ds6
Port               389
Root suffix        dc=acme,dc=com
User Logon ID      cn=Directory Manager
Password           *********

Additionally, the configuration wizard will aks for site configuration and to define the password for the default policy agent, specify the following values:

Parameter                    Value
Site Config                  [Choose No]
Default Policy Agent Pwd     ********

Finally, confirm the configuration settings and once the configuration is completed select Proceed to login to access OpenAM (http://my-sso:8080/openam/console). Use the following values in the login page to access the admin console.

Parameter          Value
User               amadmin
Password           [password entered at the begining of the configuration wizard]

Image04

One important thing to consider when configuring the user data store thru the wizard is that OpenAM will assume that the store has a compatible OpenAM schema (e.g. choosing OpenDJ or DSEE) however this is not always the case. For example in our scenario we have OpenSSO configured to use a “Generic LDAP” user store which happens to be DSEE, now starting with OpenAM v9.x ForgeRock removed the “Generic LDAP” option to define a data store, meaning that if you have a generic LDAP store in your OpenSSO configuration, then there are many chances that once you completed the wizard, simple operations like adding a user or group within OpenAM will fail with LDAP schema errors or similar.

The easy way to overcome this limitation is to edit the data store configuration in OpenAM soon after the wizard is complete and remove any object class that belongs to the OpenAM schema or does not represent a generic LDAP object class. This task needs to be carefully analyzed as you could ended up removing classes that can impact your configuration, however if you are aware of the classes that your directory is using, then this should be a simple task. For example in our scenario and since we were using a “Generic LDAP” store we performed the following actions.

Login to OpenAM admin console and select Access Control -> Top Level Realm -> Data Stores -> Sun DS with AM schema and proceed as follow:

Removed all user object classes starting with “iplanet…” and leave only the values indicated below:

Parameter                    Values
LDAP User object Class       person, inetorgperson, organizationalperson, inetuser, top

Removed all group object classes starting with “iplanet…” and leave only the values indicated below:

Parameter                    Values
LDAP Groups Object Class     groupofuniquenames, top

Update the attribute for group membership

Parameter                             Values
Attribute Name for Group Membership   memberOf

Image09

Optionally, if you do not want to remove object classes or unsure of what classes your directory is using, then you can import the OpenAM schema into DSEE. One way is importing the .ldif files installed by OpenAM using DSCC. The schema files are copied to the configuration directory specified during the wizard. In our case, the location is C:\Documents and Settings\Default User\openam\ldif\odsee.

Step 3: Copying the OpenSSO configuration to OpenAM

At this point the data stores configuration is completed and we can access the OpenAM interface, therefore the next step will be to manually copy the OpenSSO configuration to the new OpenAM server. Since the interfaces are very similar this task can be straight forward but will also depend on how complex the OpenSSO configuration is, in our sample scenario we copied the following definitions:

1. Login to OpenAM (http://my-sso:8080/openam/console) and select Access Control -> Top Level Realm -> Data Stores -> Sun DS with AM Schema and add or modify the following values:

Parameter                                       Value
LDAP Groups container Naming Attribute          ou
LDAP Groups Container Value                     groups
LDAP People Container Naming Attribute          ou
LDAP People Container value                     people
User Status Active Value                        true
User Status Inactive Value                      false

Image05

2. Save the previous changes and go to Access Control -> Top Level Realm -> Authentication. Select Authentication Chaining -> New to create a new authentication chain for the LDAP user store. Use the following values:

Name               ldapService

Parameter          Value               Criteria
Instance           LDAP                Required

Image06

Once created, do the same to create another authentication chain “adminAuthService” for the default OpenAM data store (configuration data store)

Name               adminAuthService

Parameter          Value              Criteria
Instance           DATASTORE          Required

Then, go back to Access Control -> Top Level Realm -> Authentication and select Core to define the authentication services for the admin and user interfaces. Select the following values:

Parameter                                       Value

Organization Authentication Configuration       ldapService
Administration Authentication Configuration     adminAuthService

Image07

3. Test access to the OpenAM admin console and the user interface using the “amadmin” account and one of the existing user accounts respectively. Note that when accessing the admin console you are actually using the “adminAuthService” service to validate your credentials against the configuration store, and when accessing the user interface you are using the “ldapService” service to validate your credentials against the user store.

To access the OpenAM admin console (http://my-sso:8080/openam/console), enter the following values:

Parameter           Value
User                amadmin
Pass                *******

To access the OpenAM user interface (http://my-sso:8080/openam/UI/Logon), enter the following values:

Parameter          Value

User                [valid user account]
Pass                *******

Step 4: Configuring OpenSSO J2EE Agent to use OpenAM

Since our existing user data store had already their password policies modified to work with OpenSSO, we will focus only in defining the J2EE agent profile in OpenAM and then reconfigure the agent software installed in the WAS server.

1. Login to OpenAM and select Access Control -> Top Level Realm -> Agents -> J2EE -> Agent -> New to define a new agent profile, enter the following values:

Parameter          Value
Name               wasagent
Password           ********
Configuration      centralized
Server URL         http://my-sso.acme.local:8080/openam
Agent URL          http://my-was.acme.local:9080/agentapp
NOTE: the hostnames must be FQDN

2. Go to Access Control -> Top Level Realm -> Agents -> J2EE -> Group -> New to define a new group:

Parameter          Value
Group name         wasadmin
Server URL         http://my-sso.acme.local:8080/openam

3. Go to Access Control -> Top Level Realm -> Agents -> J2EE -> Agent -> wasagent -> Global to specify the group name:

Parameter          Value
Group              wasadmin

4. Go to Access Control -> Top Level Realm -> Agents -> Agent Authenticator -> New to define a new agent authenticator:

Parameter          Value
Name               agentAuth
Password           ********

Once created, edit the definition and make sure to select the following values:

Parameter                             Value
Agent Profiles allowed to read        wsc, wsp, SecurityTokenService

5. Go to Access Control -> Top Level Realm -> Agents -> J2EE -> wasagent -> Application -> Privilege Attributes Processing and make sure to remove “Role” from Privileged Attribute Type.

6. Go to Access Control -> Top Level Realm -> Agents -> J2EE -> wasagent -> SSO -> Cookie Reset and enable the “Cookie Reset” checkbox. In the “Cookie Reset Name List” add “LptaToken” and LptaToken2” to the current values.

7. Go to Access Control -> Top Level Realm -> Subjects -> User -> New to create the agent and WAS user accounts. Use the following values:

Parameter          Value
ID                 wasagent
Last Name          wasagent
Full Name          wasagent
Password           ********
User Status        Active

ID                 wasadmin
Last Name          wasadmin
Full Name          wasadmin
Password           ********
User Status        Active

8. Go to Access Control -> Top Level Realm -> Subjects -> Group -> New to create the agent and WAS group names:

Parameter          Value
Group ID           wasagentgroup
Group ID           wasadmingroup

9. Assign each user to their respective group. Make sure to assign “Read and write access to all realm and policy properties” for group “wasagentgroup” (Access Control -> Top Level Realm -> Privileges). Use the values below as a reference:

Group Name         Privileges         Users
wasagentgroup      R/W all realm      wasagent 
wasadmingroup                         wasadmin

10. Define the URL policies. Go to Access Control -> Top Level Realm -> Policies -> New Policy to define the OpenAM policies, for our scenario we defined the following policies to protect WAS applications and the administrative console:

Policy Name        Protected Resource
WAS_APP_POLICY     http://my-was.acme.local:9080/*
WAS_CONSOLE_POLICY https://my-was.acme.local:9043/*

http://my-was.acme.local:9060/*

Image08

Below the details for each policy

Policy Name        WAS_APP_POLICY

Rule Name          Type                 Resource Name                         Permission
WASApp1            URL Policy Agent     http://my-was.acme.local:9080/*       GET (Allow)/POST (Allow)

Subjects                     Type
authenticatedUsers           Authenticated Users

Policy Name        WAS_CONSOLE_POLICY

Rule Name          Type                  Resource Name                         Permission
WASConsole1        URL Policy Agent      http://my-was.acme.local:9060/*       GET (Allow)/POST (Allow)
WASConsole2        URL Policy Agent      https://my-was.acme.local:9043/*      GET (Allow)/POST (Allow)

Subjects                     Type
authenticatedUsers           Authenticated Users

11. Import the OpenAM certificate into WAS. Go to the OpenAM server and enter the following commands to export the certificate.

set JAVA_HOME= C:\Program Files\Java\jdk1.6.0_21
cd C:\Sun\AppServer\domains\domain1\config
"%JAVA_HOME%"\bin\keytool -export -alias s1as -keystore cacerts.jks -storepass changeit > s1as_ca_openam.pem

Copy the “s1as_ca_openam.pem” file to a temporary folder in the WAS server (C:\temp). In the WAS server follow the instructions below to import the certificate.

set JAVA_HOME=C:\Program Files\IBM\WebSphere\AppServer\java
cd C:\Program Files\IBM\WebSphere\AppServer\bin
ikeyman
File -> Open -> C:\Program Files\IBM\WebSphere\AppServer\java\jre\lib\security -> cacerts
Password: changeit
Add -> Binary DER -> c:\temp\s1as_ca_openam.pem
Label: openam10ca
File -> Exit

12. Since the agent software is already installed and deployed in WAS we don’t need to deploy the agent war file instead just re-install the instance profiles as indicated in the next steps.

13. Uninstall the agent instance profiles. Go to the WAS server where the agent software is installed and run the “agentadmin” script tool with the “uninstall” parameter. In our case, we run this command three times because we have three different instances in WAS: one for the Server, a second for the Node Agent, and the last one for the Network Deployment Manager.

agentadmin --uninstall

Parameter          Value
Location           C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\MY-WASCell01\nodes\MY-WASNode01\servers\server1
Instance           server1
Root dir           C:\Program Files\IBM\WebSphere\AppServer

agentadmin --uninstall

Parameter          Value
Location           C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\MY-WASCell01\nodes\MY-WASNode01\servers\nodeagent
Instance           nodeagent
Root dir            C:\Program Files\IBM\WebSphere\AppServer

agentadmin --uninstall

Parameter          Value
Location           C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\config\cells\MY-WASCell01\nodes\MY-WASCellManager01\servers\dmgr
Instance           dmgr
Root dir           C:\Program Files\IBM\WebSphere\AppServer

Re-start WAS

Important: if you want to re-initialize the counter used by the “agentadmin” tool to name the agent configuration folders, you can follow these instructions:

Update agent counter to 0 (for folder creation....Agent_001, etc)
Edit C:\WASPolicyAgent3\j2ee_agents\websphere_v61_agent\data\.amAgentLookup to change the counter to 0

14. Re-install the agent profiles. Go to the WAS server where the agent software is installed and run the “agentadmin” tool with the “install” parameter. In our case, we run this command three times because we have three different instances in WAS: one for the Server, a second for the Node Agent, and the last one for Network Deployment Manager.

IMPORTANT NOTE
Because WAS uses the IBM JDK, you must update the installation script tool (agentadmin) to properly encrypt the password file. Edit the script tool file:

C:\WASPolicyAgent3\j2ee_agents\websphere_v61_agent\bin\agentadmin.bat

Replace line:
"%JAVA_VM%" -classpath %AGENT_CLASSPATH% com.sun.identity.install.tools.launch.AdminToolLauncher %*

With:
"%JAVA_VM%" -classpath %AGENT_CLASSPATH% -DamKeyGenDescriptor.provider=IBMJCE -DamCryptoDescriptor.provider=IBMJCE -DamRandomGenProvider=IBMJCE com.sun.identity.install.tools.launch.AdminToolLauncher %*

Now, you can run the agentadmin tool to install the profiles as indicated below:

agentadmin --install

=> For server1
Parameter                    Value
SERVER_INSTANCE_DIR          C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\MY-WASCell01\nodes\MY-WASNode01\servers\server1
SERVER_INSTANCE_NAME         server1

agentadmin --install

=> For nodeagent
Parameter                    Value
SERVER_INSTANCE_DIR          C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv01\config\cells\MY-WASCell01\nodes\MY-WASNode01\servers\nodeagent
SERVER_INSTANCE_NAME         nodeagent

agentadmin --install

=> For dmgr
Parameter                    Value
SERVER_INSTANCE_DIR          C:\Program Files\IBM\WebSphere\AppServer\profiles\Dmgr01\config\cells\MY-WASCell01\nodes\MY-WASCellManager01\servers\dmgr
SERVER_INSTANCE_NAME         dmgr

For all the above cases, make sure to specify

Parameter                    Value
HOME_DIRECTORY(ROOT)         C:\Program Files\IBM\WebSphere\AppServer
AM_SERVER_URL                http://my-sso.acme.local:8080/openam
AGENT_URL                    http://my-was.acme.local:9080/agentapp
AGENT_PROFILE_NAME           wasagent
AGENT_PASSWORD_FILE          c:\temp\agentpwd.txt         => text file containing agent password in clear text

After the agent configuration is complete, edit the agent configuration file and update the logout URI:

Edit C:\WASPolicyAgent3\j2ee_agents\websphere_v61_agent\Agent_001\config\OpenSSOAgentConfiguration.properties and change the following line.

From:
com.sun.identity.agents.config.logout.uri[ibm/console] = /ibm/console/logoff.do

To:
com.sun.identity.agents.config.logout.uri[ibm/console] = /ibm/console/logout.do

The above configuration assumes that the agent was already installed in WAS, therefore other configuration settings needed in WAS will not be documented in this procedure. See the J2EE Agent for WebSphere documentation for more details in updating the class path, adding a trust interceptor, creating user and groups and enabling security in WAS to integrate the WAS admin console with OpenAM.

Step 5: Testing the New OpenAM Configuration

For development purposes, WAS administrative security does not need to be enabled. For example, you can use the sample application that comes with the J2EE Agent to test the OpenAM configuration. You only need to enable Application Security and Java 2 Security and test the application (assuming the sample application has been deployed in WAS).

For example, entering http://my-was.acme.local:9080/agentsample/public/welcome.html in a browser will redirect us to the OpenAM login page to enter a valid user credential.

Now, if we enable WAS administrative security, we can also protect the WAS admin console. Trying the following URL https://my-was.acme.local:9043/ibm/console will redirect us to the OpenAM login page.

Figure 2 shows the OpenAM login page that is displayed when a user tries to access the agent sample application. The sample application is displayed in Figure 3.

Figure 2 – Accessing a protected application


Image10

Figure 3 – Sample protected application


Image11

Figure 4 shows the OpenAM login page that is displayed when a user tries to access the WAS admin console. The admin console is displayed in Figure 5.

Figure 4 – Accessing the WAS admin console


Image12

Figure 5 –WAS admin console


Image13

The following figure shows the final architecture with OpenAM v10.1.0

Figure 6 – OpenSSO Architecture (after upgrade)


Image14