Installing and deploying an Apache web policy agent for OpenAM

par | Sep 14, 2016 | Gestion des Identités, Sécurité, SSO

This article describes how to install an Apache web policy agent for OpenAM.

The components used are:

  • Apache 2.4
  • OpenAM 12
  • OpenAM Web policy agent 4.01

Below are described all the different steps to be achieve this.

1)  Installation of an apache 2.4 server source package

Apache is available as an opensource distribution. You first need to compile and install it. Apache 2.4 compilation and configuration is described at:
OpenAM-compiling Apache Server 2.4

Once installed, the following layout is obtained:

cd <install-apache-install-dir>; ls
bin cgi-bin error include logs manual
build conf htdocs icons lib man modules

2) Creation/Configuration  of an apache virtual server (Port 9000)

An apache virtual server at port 9000, with index.hml as default URL

2.1) creation of new htdocs_9000 directory, for apache URL

A new virtual apache virtual server is created at port 9000, with index.hml as default URL.
cp -r <install-apache-install-dir>/htdocs <install-apache-install-dir>/htdocs_9000

2.2) Modification of httpd.conf
Creation of apache server (port 9000 in httpd.conf) apache server configuration is located in file <install-apache-install-dir>/conf/httpd.conf
The default listen port 80 is commented out, and following lines are added.

# Apache shoudl listen on port 9000
#Listen 80 -----> Line to be commented out
Listen 9000

DocumentRoot "/htdocs_9000"
ServerName openam.example.com

2.3) Start of apache server (URL 9000)

cd <install-apache-install-dir>/bin
./apachectl start

2.4) Test of a apache Server
In a brower  URL enter

"https://openam.example.com:900/index.html"
It should returns an error message "403 forbidden."

You don’t have permission to access /index.html on this server.

It is the normal behaviour, as apache server server has processed this request which is not authenticated, and hence rejected.
OpenAM Agent once configured and deployed in OpenAm will allow this request to be processed successfully after authentication.

3) Downloading OpenAM policy web agent
The latest available policy web agent distribution available from forgerock is 4.00 or 4.01 (subscription only )

mkdir Apache_v24_Linux_64bit_4.0.1

cd Apache_v24_Linux_64bit_4.0.1
unzip Apache_v24_Linux_64bit_4.0.1.zip
Archive: Apache_v24_Linux_64bit_4.0.1.zip
creating: web_agents/apache24_agent/
creating: web_agents/apache24_agent/log/
creating: web_agents/apache24_agent/instances/
creating: web_agents/apache24_agent/config/
inflating: web_agents/apache24_agent/config/agent.vcl3.template
inflating: web_agents/apache24_agent/config/agent.vcl.template
inflating: web_agents/apache24_agent/config/agent.conf.template
inflating: web_agents/apache24_agent/config/mod_iis_openam_schema.xml
creating: web_agents/apache24_agent/legal/
inflating: web_agents/apache24_agent/legal/THIRDPARTYREADME.txt
inflating: web_agents/apache24_agent/legal/CDDLv1.0.txt
inflating: web_agents/apache24_agent/legal/Forgerock_License.txt
creating: web_agents/apache24_agent/lib/
inflating: web_agents/apache24_agent/lib/mod_openam.so
creating: web_agents/apache24_agent/bin/
inflating: web_agents/apache24_agent/bin/agentadmin

4) Registering web policy apache agent with openAM
The different steps to be accomplished when registering a new agent are:

login to OpenAM Console as an administrative user.

On the Realms menu of the OpenAM console, select the realm in which the agent profile is to be managed.

Click the Agents link, and select the web tab.

4.1. In the Name field, enter a name for the agent profile.
4.2. In the Password and Re-Enter Password fields, enter a password for the new agent profile.
4.3. Click Local or Centralized (Default) to determine where the agent properties are stored.
4.4. In the Server URL field, enter the URL to OpenAM. For example, .

4.5. In the Agent URL field, enter the primary URL of the web or application server protected by the policy agent.
for web agents, an example URL would look like: .
Click create

5) Deploying web policy agent in apache server

5.1. Stop the apache server if it is running.
5.2. create a password file to store web policy agent password
(It is the same password that you have registered previously with openam, when registering the web policy agent)

echo passsword > /Apache_v24_Linux_64bit_4.0.1/agent_pwd.txt

5.3. Adjust permission on web policy agent password file

chmod 400 /Apache_v24_Linux_64bit_4.0.1/agent_pwd.txt

5.4. During deployment, the following question will be asked:
-web agent policy password path
-apache configuration directory path
-openam URL
-agent URL

Example:

cd Apache_v24_Linux_64bit_4.0.1/web_agents/apache24_agent/bin

./agentadmin --i
....
....

Do you completely agree with all the terms and conditions
of this License Agreement (yes/no): [no]: yes

OpenAM Web Agent for Apache Server interactive installation.

Enter the complete path to the httpd.conf file which is used by Apache HTTP
Server to store its configuration.
[ q or 'ctrl+c' to exit ]
Configuration file [/opt/apache/conf/httpd.conf]: /apache24/conf/httpd.conf

To set properties from an existing configuration enter path to file
[ q or 'ctrl+c' to exit, return to ignore ]
Existing OpenSSOAgentBootstrap.properties file:

Enter the URL where the OpenAM server is running. Please include the
deployment URI also as shown below:
)
[ q or 'ctrl+c' to exit ]
OpenAM server URL: 

Enter the Agent URL as shown below:
)
[ q or 'ctrl+c' to exit ]
Agent URL: 

Enter the Agent profile name
[ q or 'ctrl+c' to exit ]
Agent Profile name: apache24_server_9000

Enter the Agent realm/organization
[ q or 'ctrl+c' to exit ]
Agent realm/organization name: [/]:

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 and name of the password file: /Apache_v24_Linux_64bit_4.0.1/agent_pwd.txt

Installation parameters:

OpenAM URL: 
Agent URL: 
Agent Profile name: apache24_server_9000
Agent realm/organization name: /
Agent Profile password source: /Apache_v24_Linux_64bit_4.0.1/agent_pwd.txt

Confirm configuration (yes/no): [no]: yes

Validating...

Validating... Success.

Cleaning up validation data...

Creating configuration...

Installation complete.

6. Final agent configuration (check SSO only mode)

login to OpenAM Console as an administrative user.

On the Realms menu of the OpenAM console, select the realm in which the agent profile is to be managed.Click the Agents link, and select the web tab.

Select the agent name to update (apache24_server_9000)
goto to global tab and select SSO.
In the global section, check « SSO only mode » (This Agent will just enforce authentication (SSO), but no authorization for policies.)

7)  start apache server

cd /apache24/bin
./apachectl start

8) Testing
==========
In a brower enter URL:

It should redirect to openam web page authentication, asking for username/password. You can authenticate with the usual test user (demo/changeit).

Once authenticated, it should display message « It works »

9) Troubleshooting

In order to troubleshoot, you increase the agent log level:
On the Realms menu of the OpenAM console, select the realm in which the agent profile is to be managed.
Click the Agents link, and select the web tab.

Select the agent name to update (apache24_server_9000)
goto to global tab
in the General section, select log level to « ALL »

10) pointers

Openam 4.00 web policy agent documentation
https://forgerock.org/openam/doc/bootstrap/web-users-guide/index.html#chap-apache

Apache virtual hosts example
https://httpd.apache.org/docs/2.4/en/vhosts/examples.html

 

janua
Les derniers articles par janua (tout voir)