Recently I joined ForgeRock as a senior consultant. After almost 15 years in the ops and integration world, working with SiteMinder, a bunch of peers have been asking me how SiteMinder compares to OpenAM and how they differ. So, now as a fully biased ForgeRock employee, I am documenting the process of translating that SiteMinder suite knowledge into OpenAM.
Part 4 - The Basics - Integrating a sample web site
Download the OpenAM Web Policy Agent from here:
This is a pretty big blog entry. However, each portion if not completed together isn’t as helpful. These are the steps required to integrate a sample web site with OpenAM. This will leverage a simple authorization policy allowing ‘authenticated users’ access to a ‘member’ page. The steps will follow as:
Create Authorization Policy
Create Agent profile
Configure Agent settings
Configure Authentication settings
Install IIS Agent
This assumes you have followed the previous steps and having a working OpenAM server. This blog will focus on creating a policy and installing and configuring an IIS agent.
In this example, we will protect a simple html page on IIS. There is a protected page on /app/ that we want protected. The landing page will be at “/index.html”. From there, we will click on the member link which will send us to /app/home.html.
amps.idmlabs.com/index.html (unprotected)
amps.idmlabs.com/app/home.html (authorized by policy)
*Major note of difference in philosophy from SiteMinder to OpenAM*
When you install a SiteMinder Web Agent and enable it, it will not deny any access by default. Policy is required in order to protect any URLs. It follows a blacklisting philosophy. All is allowed unless blocked by policy.
When you install a OpenAM Web Agent it is enabled by default and blocks access; redirecting to the openAM login URL. Agent configuration is needed to allow access to unprotected URLs. You would still be unauthorized after a successful authentication. You need to define policy to create the proper authorization rules to grant access. All is denied unless authorized by policy.
Lets start by creating an authorization policy first.
Login to OpenAM console. Click the Access Control tab, then in the realms table click on “/ (Top Level Realm)
Realm Properties screen:
Next, click on the policies tab.
Select the iPlanetAMWebAgentService. This is not a policy specific for apache or iPlanet based web servers. Its just a generic name created by default. You can rename it to anything you want. It is only a policy container object. Like a realm name within SiteMinder.
Once you have selected the Application, click on Add New Policy.
Step1 - Give it a name
Step2 - Specify the URL resource being protected. Click on the pattern that best represents the URL pattern. Then update the variables to represent your specific app URL. Don’t forget to click on the + to add it to the resources table. Click Next
Step3 - Select Actions such as Get and Post. Click Next.
Step4 - Define Subject Conditions. For our example, click on Subject condition and from the Type drop down, select Authenticated Users. Select the Grey box and drag it up to the “AND” table. Click on Next.
Step5 - Define Environmental Conditions. We can skip for this exercise but review this section for the many options you have. Click Next to proceed.
Step6 - Specify Response Attributes. This defines all the response attributes that the policy allows based on a successful decision. The agents can then be configured to select which of the allowed attributes it actually passes to the application. While not needed for this exercise, click on the Subject attributes and a drop down of all ldap attributes will be shown. Click on any attributes you wish to use. Click Next to continue.
Step7 - Review and click on Finish to complete the policy.
And done!
Click on OpenAM Console link on the top right hand corner.
Next, let’s create a web policy agent profile.
If not already there, go to Access Control-> / (Top Realm) and click on the Agents tab. Click on New.
Name: IISAppAgent
Password: Select a password for agent communication
Configuration: Keep the default, Centralized
Server URL: The URL of the OpenAM server, as an example, http://amps.idmlabs.com:8080/openam
Agent URL: The URL of the IIS server, http://amps.idmlabs.com:80
Click on Create.
Back at the Web Tab, the new IISAppAgent is listed.
Next, let’s configure the new agent profile
Click on your new agent. Click on the Application Tab. Under “Not Enforced URLs, enter a new value for the landing page of your sample app. In this case i can enter the FQDN to my index.html file and every other file i have at that directory level that I don’t want protected, or use wildcards. Since i also have a logout.html files i will use later, i will add *.html as the files to be ignored at that directory level. Make sure you select Enabled and Save.
Next click on the OpenAM Services Tab. Scroll down to the Agent Logout URL. This is like the SiteMinder ACO setting for LogoffURI. Enter the URL to your logout page. This will kill the OpenAM session when invoked.
Make sure you click on Save.
Next, let’s configure your authentication source.
When we first installed OpenAM, we defined a policy configuration LDAP instance as well as an user LDAP. the amadmin user exists within the policy configuration LDAP instance. This can be modified to disable this root account and promote unique users as OpenAM administrators. For this exercise, i am leaving the default root user. However, we want to leverage existing users in our user LDAP instance. The plan will be to continue to use the config ldap repository for administrative tasks (allowing us to login with amadmin), but have the realm authenticate against the user LDAP for authentication and authorization of our integrated apps.
Authentication Chaining
Authentication Chaining allows us to stack various authentication modules and define rules around how they are used: required, optional, requisite, or sufficient. These are based on the JAAS standard. As described by the OpenAM documentation:
When a required module fails, the rest of the chain is processed, but the authentication fails.
A required module might be used for login with email and password, but then fall through to another module to handle new users who have not yet signed up.
When an optional module fails, authentication continues.
An optional module might be used to permit a higher level of access if the user can present a X.509 certificate for example.
When a requisite module fails, authentication fails and authentication processing stops.
A requisite module might be used with exclusive SSO.
When a sufficient succeeds, authentication is successful and later modules in the chain are skipped.
You could set Windows Desktop SSO as sufficient, so authenticated Windows users are let through, whereas web users have to traverse another authentication module such as one requiring an email address and a password.
By default, one Authentication Chain is created. It only points to the internal config LDAP instance. The task will be to create a new Authentication Chain used by the user LDAP instance. Once created, the User LDAP chain will be used for authentication and the config LDAP will be only for Admin access.
The default chain is called ldapservice. For personal preferences I updated this one to use the User LDAP and created a new one called datastoreService for the config LDAP.
From the main OpenAM console, click on Access Control Tab, then click on the / (Top Level Realm). Click on the Authentication tab and scroll down to Authentication Chaining.
Click on ldapService
Click Add and from drop down select LDAP. Under Criteria, select REQUIRED. Select the DataStore and Remove.
Click Save and Back to Authentication.
Why Select LDAP? If you go back and look at the Module Instances, and select LDAP, you will see it is configured against the User LDAP instance configured at the time of OpenAM installation. You can add as many Modules as needed and add as many to Authentication Chains.
Back to the Authentication Chaining section, click on New. Enter the name of your new Authentication Chain, in my example, datastoreService.
Click on OK. You will be taken to the Properties Screen. Click ADD and select DataStore. Under Criteria select REQUIRED.
Click Save and Back to Authentication.
Next we assign the Authentication Chains properly. Under Core services, there are two drop down options. One is for Organization Authentication Configuration and the other is for Administrator Authentication Configuration. The Organization Authentication Configuration services when users access /openam/UI/Login. This is the default Authentication Chain for users. The Administrator Authentication Configuration serves when users access /openam/console. This is the default Authentication Chain for administrators.
Select the appropriate chain from the drop down for each.
Click on Save and Back to Access Control.
IMPORTANT NOTE
If you try to login as an admin to http://
Next step is to install the agent on IIS.
If you haven’t already, download the IIS agent.
https://backstage.forgerock.com/#!/downloads/OpenAM/Web%20Policy%20Agents/4.0.0/Microsoft%20IIS%20(64-bit)/?platformName=Microsoft%20IIS&platformVersion=7%20and%208&platformOs=Windows&platformArchitecture=64-bit%23list
IIS_WINNT_64bit_4.0.0.zip
Create a temporary password file. c:\pwd.txt. It should contain the agent password previously created. Make sure you delete this file when done registering the agent.
Stop IIS instance. “iisreset /stop” Expand the web agent zip file, for example, i have mine at c:\web_agent.
Make sure IIS has all Application Development services installed before you start install. Details can be found here:
Start the install process:
c:\> cd web_agents\iis_agent\bin
c:\web_agents\iis_agent\bin> agentadmin.exe --i --acceptLicence
Enter the Site ID from the located IIS instances.
Enter 1 for DEFAULT WEB SITE in our sample case.
You will see an error next on ssleay32.dll and libeay32.dll missing. This is only needed if you are running IIS secure. For this sample, we are running HTTP.
Just click on enter as this is a fresh install with no existing properties file. If you had one created already, it can be used for any additional web server agent installs.
To set properties from an existing configuration enter path to file
[ q or 'ctrl+c' to exit, return to ignore ]
Existing OpenSSOAgentBootstrap.properties file:
Next enter the URL to the OpenAM policy server
Enter the URL where the OpenAM server is running. Please include the
deployment URI also as shown below:
(http://openam.sample.com:58080/openam)
deployment URI also as shown below:
(http://openam.sample.com:58080/openam)
[ q or 'ctrl+c' to exit ]
OpenAM server URL:
http://amps.idmlabs.com:8080/openam
Next enter the URL to the IIS
Enter the Agent URL as shown below:
(http://agent.sample.com:1234)
[ q or 'ctrl+c' to exit ]
(http://agent.sample.com:1234)
[ q or 'ctrl+c' to exit ]
Agent URL:
http://amps.idmlabs.com:80
Agent profile name is the same as the one created on the policy server. In my example, IISAppAgent.
Enter the Agent profile name
[ q or 'ctrl+c' to exit ]
Agent Profile name: IISAppAgent
Next enter the realm for which this agent will service. For our sample, we left it at “/ (Top Level Realm)
Enter the Agent realm/organization
[ q or 'ctrl+c' to exit ]
Agent realm/organization name: [/]: /
[ q or 'ctrl+c' to exit ]
Agent realm/organization name: [/]: /
Finally, enter the path to the temporary password file.
Enter the path to a file that contains the password to be used
for identifying the Agent
[ q or 'ctrl+c' to exit ]
The path to the password file: c:\pwd.txt
for identifying the Agent
[ q or 'ctrl+c' to exit ]
The path to the password file: c:\pwd.txt
Confirm the parameters and enter ‘yes’ and enter to proceed.
Installation parameters:
Agent Profile password source: c:\pwd.txt
Confirm configuration (yes/no): [no]: yes
Validating...
Validating... Success.
Cleaning up validation data...
Creating configuration...
Installation complete.
OpenAM URL: http://amps.idmlabs.com:8080/openam
Agent URL: http://amps.idmlabs.com:80
Agent Profile name: IISAppAgent
Agent realm/organization name: /Agent Profile password source: c:\pwd.txt
Confirm configuration (yes/no): [no]: yes
Validating...
Validating... Success.
Cleaning up validation data...
Creating configuration...
Installation complete.
Restart IIS
Final Step - Testing
If you don’t already have a browser inspector plugin, i’d recommend you download Fiddler Web Debugger for windows. http://www.telerik.com/fiddler
Now go to your landing page. http://amps.idmlabs.com/index.html. My index.html page is extremely simple.
Click on “Members Login” and it sends you to http://amps.idmlabs.com/app/home.html.
You should be re-directed to the OpenAM Login screen. Similar to SiteMinder the URL will include the redirect parameters to the target URL.
Login with any valid LDAP user. The authorization policy was defined as “Any Authenticated User”.
Using Fiddler or any other web tracer, look for the OpenAM Session cookie. It is called iPlanetDirectoryPro. This cookie contains the OpenAM Session Token. It is the equivalent to SiteMinders SMSESSION.
This Fiddler snippet is from OpenAM initiating the authenticate call. Notice POST URL of /openam/json/authenticate.
Now the next step is the successful authentication and establishment of a session cookie. Notice the POST URL /openam/json/users?_action=idFromSession
There are additional steps you view on fiddler, however you will see the redirect to /app which is our target URL.
The next step is to now logout and invalidate the session. Recall we configured the agent to look for /logout.html as a trigger to kill the session. By clicking on the logout link and following on fiddler, we can see the logout flow:
Notice the POST URL with an action of logout for the session.
http://amps.idmlabs.com:8080/openam/json/sessions/AQIC5wM2LY4Sfcx8ZRkYzP1XPNqJtlWi22MpeN-sz7VZdXg.*AAJTSQACMDEAAlNLABQtMzI5ODAyMDQ4NDk5NzM2NjQ4Mg..*?_action=logout
The session is invalidated and we are redirected to a logout screen.
Following Fiddler, you should not see the iplanetdirectorypro session anymore.
Easy enough? This concludes the basics on setting up OpenAM from the point of view of an old SiteMinder Admin. In the future i will continue to use this platform to show how configure additional features such as Advanced Authentication, Federation, using REST, and more; all from this same deployment without the need of additional OpenAM components.
Ok, so feel free to now try it for yourself. Download the software at https://forgerock.org/downloads/ and discover the differences and simplicity of the ForgeRock platform.
