AM redirection using Policy Agent

From MsgServerDocWiki

How can I get Communications Express to redirect users with no Access Manager SSO session?

Communication Express (UWC) 6.3 removed the requirement to have Access Manager Single Sign On (SSO) configured in a schema 2 environment. One consequence of this change was that the Communication Express interface no longer creates a SSO Access Manager cookie when a user logged in. Communication Express can still be configured to log a user in based on their Access Manager SSO cookie (outside the scope of this document).

For environments that use Communications Express/UWC as a common login/access point this change can increase user frustration as there is now a need for multiple-logins for a 'single' sign-on environment.

UPDATE

UWC/CE 6.3 patch 122793-26 (Solaris Sparc),122794-26 (Solaris x86), 122795-26 (Redhat Linux) and later has added an entry-point into Access Manager (RFE#6798573) which can now be used to create the Access Manager SSO cookie instead of the Policy Agent approach mentioned in this document.

The following is applicable ONLY if Access Manager is enabled. In other words only if the uwcauth.identity.enabled parameter is set to "true" in the uwcauth.properties file

The fix for RFE#6798573 requires that either of the following parameters be set in the uwcauth.properties file:

uwcauth.identity.login.url
(OR)
uwcauth.identity.ssl.login.url

If neither of the parameters are set then this will result in a "HTTP Status 500" screen at the time of logging in. The uwc logs will show the following errors :

SEVERE: A Proper URL is not set for uwcauth.identity.ssl.login.url. This may result in errors
SEVERE: Check uwcauth.properties and set the uwcauth.identity.ssl.login.url parameter correctly

1 The Theory
2 Policy Agent Installation steps
3 Testing the Policy Agent
4 Policy Agent Removal steps
5 Policy Agent Troubleshooting Steps
6 Known limitation

[edit] The Theory

To address this new limitation, a Sun web-server policy agent can be installed on the web-server instance hosting the Communications Express interface to redirect users who don't have an Access Manager SSO cookie set to the Access Manager login console.

Once the user logs into the Access Manager console interface, a SSO cookie is created, and they are redirected back to the Communication Express interface. If Communication Express is configured to allow Access Manager SSO logins, the the user will be automatically granted access to Communications Express without needing to re-enter their username and password.

NOTE: These steps were developed and tested on a Communications Suite 5 Single Host installation.

[edit] Policy Agent Installation steps

Download Access Manager Web-Server 7.0 Policy Agent

The agent can be downloaded from the following location:

http://www.sun.com/download/products.xml?id=4648e019

Setup policy agent binaries

For this step you will need to substitute in the Access Manager LDAP user password (amldapuser password) into the "<amldapuser password>" field. Please note that by default this password is NOT the same as the Access Manager administrator user (amadmin).

cd /opt
unzip <path to sjsws_v70_SunOS_x86_agent.zip>
cd /opt/web_agents/sjsws_agent/bin
chmod u+x agentadmin certutil crypt_util
echo "<amldapuser password>" > /opt/web_agents/sjsws_agent/etc/passwd

Configure & install policy agent

cd /opt/web_agents/sjsws_agent/bin/
./agentadmin --install

[config path]: /var/opt/SUNWwbsvr7/https-<webserver>/config
[access manager hostname]: <access manager hostname e.g. am.domain.com>
[access manager port]: <access manager port e.g. 80>
[access manager protocol]: http (or https if using SSL for Access Manager)
[access manager services uri]: /amserver
[protected webserver hostname]: <uwc hostname e.g. mail.domain.com>
[protected webserver port]: <uwc port e.g. 80>
[protected webserver protocol]: http (or https if using SSL for UWC)
[agent profile name]: UrlAccessAgent
[password file]: /opt/web_agents/sjsws_agent/etc/passwd

Set correct permissions (so the policy agent can create/edit logs)

The permissions should be set to the user/group used by the web-server process, by default this will be webservd:webservd.

chown webservd:webservd /opt/web_agents/sjsws_agent/Agent_001/logs/debug/
chown webservd:webservd /opt/web_agents/sjsws_agent/Agent_001/logs/audit/

Modify policy agent configuration

Edit the /opt/web_agents/sjsws_agent/Agent_001/config/AMAgent.properties file.

Set the following option (you don't need the agent to enforce SSO policy):

com.sun.am.policy.agents.config.do_sso_only = true

If the above value isn't changed you will get an error like the following:

[20/Aug/2007:11:05:19] failure (19595): for host 129.158.87.76 trying to GET /uwc/auth, 
func_exec reports: HTTP2302: Function validate_session_policy aborted the request without 
setting the status code):

Set the following option (only enable enforcement for the uwc URL since this is the only one we care about):

com.sun.am.policy.agents.config.notenforced_list=http[s]://<uwc host>:<uwc port>/<uwc deploy directory>/*
com.sun.am.policy.agents.config.notenforced_list.invert=true

e.g.

com.sun.am.policy.agents.config.notenforced_list=http://mail.domain.com:80/uwc/*
com.sun.am.policy.agents.config.notenforced_list.invert=true

Set the following option (UWC doesn't currently remove the iPlanetDirectoryPro cookie on logout, so when the session gets redirected the cached value in the agent gets confused and you see the UWC login page - these settings cause the logout to remove the cookie):

com.sun.am.policy.agents.config.logout.url=http[s]://<uwc host>:<uwc port>/<uwc deploy directory>/base/UWCMain?op=logout
com.sun.am.policy.agents.config.logout.cookie.reset.list=iPlanetDirectoryPro;Domain=<cookie domain>

e.g.

com.sun.am.policy.agents.config.logout.url=http://mail.domain.com:80/uwc/base/UWCMain?op=logout
com.sun.am.policy.agents.config.logout.cookie.reset.list = iPlanetDirectoryPro;Domain=.domain.com

Set the following option (refer to discussion about this option here: http://forum.java.sun.com/thread.jspa?threadID=5234644)

com.sun.am.policy.am.login.url=http[s]://<access manager hostname>:<access manager port>/amserver/UI/Login?gotoOnFail=http[s]://<uwc host>:<uwc port>/<uwc deploy directory>

e.g.

com.sun.am.policy.am.login.url=http://am.domain.com:80/amserver/UI/Login?gotoOnFail=http://mail.domain.com:80/uwc

Restart webserver

This will activate the policy agent.

cd /var/opt/SUNWwbsvr7/https-<webserver>/bin
./stopserv;./startserv

[edit] Testing the Policy Agent

Once you have made the changes above, when you access the url http://<uwc host>:80/uwc/ you should now be redirected to the Access Manager console.

When you log into Access Manager console you should be redirected back to UWC.

If you have configured Communications Express to log you in based on your Access Manager SSO cookie, you should now be logged into the Communications Express interface without having to enter your username and password.

When your Access Manager session expires the policy agent prevents you from reaching UWC. The UWC java script that normally redirects you to logout url http://<uwc host>:80/uwc/base/UWCMain?op=logout once your session is expired is dependant on a server function. The policy agent now prevents access the server function that fills in the http://<uwc host>:80/uwc part of the URL and your users will be redirected to http://base/UWCMain?op=logout.

Edit the file [UWC-BASEDIR]/webmail/main.js and replace

...
top.window.location =  getUWCHost() + "/base/UWCMain?op=logout"
...
uwcurl = url + 'base/UWCMain?op=logout'
...

and make the URL absolute:

..
top.window.location =  "http://<uwc host>:80/uwc/base/UWCMain?op=logout"
...
uwcurl = 'http://<uwc host>:80/uwc/base/UWCMain?op=logout'
...

[edit] Policy Agent Removal steps

Un-install agent

cd /opt/web_agents/sjsws_agent/bin/
./agentadmin --uninstall

Restart Webserver

cd /var/opt/SUNWwbsvr7/https-<webserver>/bin
./stopserv;./startserv

[edit] Policy Agent Troubleshooting Steps

Please refer to the following documentation for generic Policy Agent troubleshooting information:

http://docs.sun.com/app/docs/doc/820-1130/gaudl?a=view

[edit] Known limitation

By default, Access Manager will search for uid=<user name> from the organisation rootsuffix, you cannot log in as uid@domain. This means that if you have two accounts with the same UID access won't be granted. Rectifying this limitation is outside the scope of this document.

The access manager naming service (to verify the access manager cookie) and access manager login (where your users login to access manager) need to have the same hostname. Refer to the Sun forum thread here for a workaround: http://forum.java.sun.com/thread.jspa?messageID=9968477

Retrieved from "http://msg.wikidoc.info/index.php/AM_redirection_using_Policy_Agent"