Windows Toolkit & Windows environment SSO Token Sample

Install the Toolkit and run Command Line Samples

After running the command line samples successfully, proceed with the App Server examples as required. This will ensure all connectivity and environment issues are resolved. Without working command line samples, debugging connectivity and environment issues using the App Server will be more difficult.

Tomcat App Server Samples

Sun App Server Samples

Possible Errors

Contact

Todo

Install the Toolkit and run Command Line Samples

To begin

Ensure you have JDK1.4.1_06 or above installed
Copy enclosed is61sdkwin32.zip to c:\dev\
right click, expand to is61sdkwin32, so you have directory c:\dev\is61sdkwin32

Edit .\samples\sso\Make & run* to reflect your JVM location

the .\lib\AMConfig.properties is preconfigured for an Identity Server on the
<>internet: www.identityprovider.net/amconsole --> for testing, login there.
test user: demo with password: password
alternatively edit the file .\lib\AMConfig.properties to reflect your internal Identity Server

Get SSO cookie value from browser

Mozilla/Firefox makes this the easiest: Tools --> Cookie Manager --> Manage Stored Cookies
or in IE, type in the URL bar: javascript:document.write(document.cookie); and bookmark.
Look for cookie iPlanetDirectoryPro on the server domain.

run C:\dev\is61sdkwin32\samples\sso\runsimple.bat "<token>"

this performs a simple validation with the token

<>edit and use runsimpleproxy.bat if you only have proxied access to internet. For internal testing this should not be required. JDK1.4.2 can use the control panel to configure proxy settings.

also C:\dev\is61sdkwin32\samples\sso\runsample.bat "<token>"

this does as the sample above, but sets/gets token against the SSO token and registers a listener (though it does not currently wait for callbacks).

<>edit and use runsampleproxy.bat if you only have proxied access to internet. JDK1.4.2 can use the control panel to configure proxy settings.

Output

# ./runsample AQIC5wM2LY4SfcwH8dqPPBZlpigLR12SKQRWDCwddpBtC%2BU%3D
SSOToken host name: 192.168.1.7
SSOToken Principal name: uid=mark,ou=people,dc=identityprovider,dc=net
Authentication type used: LDAP
IPAddress of the host: 192.168.1.7
The token ID is AQIC5wM2LY4SfcwH8dqPPBZlpigLR12SKQRWDCwddpBtC+U=
Property: Company is - Sun Microsystems
Property: Country is - USA
SSO Token Validation test Succeeded

Check enviro in the batch file to see what Paths & Classpaths are required.

You'll see debugging info in C:\dev\is61sdkwin32\debug\amSSOProvider
Look at C:\dev\is61sdkwin32\lib\AMConfig.properties for the minimum settings suggested.

Tomcat App Server Samples

Update the toolkit AMConfig.properties

C:\dev\is61sdkwin32\lib\AMConfig.properties

ensure you have the following settings:

com.iplanet.am.naming.url=http://<identity server host>:<port>/amserver/namingservice

com.iplanet.am.cookie.name=iPlanetDirectoryPro

#default is false, enable for Tomcat or you'll get "Data is not Base64 encoded"
#com.iplanet.am.cookie.encode=false
com.iplanet.am.cookie.encode=true

Get your AppServer running

Tomcat 4.1.30 obtained from:

http://apache.mirror.positive-internet.com/jakarta/tomcat-4/v4.1.30/bin/jakarta-tomcat-4.1.30.exe

Install into:

C:\dev\Tomcat 4.1.30

Note:

For testing I used the following command line to launch Tomcat, which does not run with security manager:
C:\dev\Tomcat 4.1.30\bin>catalina.bat run

If you start Tomcat from the services menu then you will need to ensure Tomcat sets the classpath & java command line (JVM Option Number 4 ? ) using the settings below. At quick glance, in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Apache Tomcat 4.1
there doesn't appear to be an immediately obvious way to set the classpath.

Update the Tomcat environment

C:\dev\Tomcat 4.1.30\conf\catalina.policy

at end of file, add:

// For IS SDK
grant {
permission java.security.SecurityPermission "putProviderProperty.Mozilla-JSS";
permission java.security.SecurityPermission "insertProvider.Mozilla-JSS";
};

C:\dev\Tomcat 4.1.30\bin\catalina.bat

<>Set JDK at beginning of file:

rem $Id: catalina.bat,v 1.30 2003/10/06 12:23:29 remm Exp $
rem ---------------------------------------------------------------------------

set JAVA_HOME=C:\dev\j2sdk1.4.2_nb\j2sdk1.4.2
set BASE=C:\dev\is61sdkwin32
set PATH=%BASE%\lib;%BASE%\lib\jss
set JAVA_OPTS=-Djava.protocol.handler.pkgs=com.iplanet.services.comm -Xverify:none

C:\dev\Tomcat 4.1.30\bin\setclasspath.bat

<>Add JDK environment towards end of file:
<>
rem Set standard CLASSPATH
rem Note that there are no quotes as we do not want to introduce random
rem quotes into the CLASSPATH

set BASE=C:\dev\is61sdkwin32
set CLASSPATH=%JAVA_HOME%\lib\tools.jar;.;%BASE%\lib;%BASE%\locale;%BASE%\lib\jaas.jar;%BASE%\lib\am_services.jar;%BASE%\lib\am_sdk.jar;%BASE%\lib\jss311.
jar;%BASE%\lib\servlet.jar;%BASE%\lib\crimson.jar;%BASE%\lib\am_logging.jar;%BASE%\dtd;%BASE%\lib\SSOSample.jar

Increase Tomcat logging and enable Web access log:

C:\dev\Tomcat 4.1.30\conf\server.xml

after </Context>

before </Host>

Deploy and Run the Sample JSP's

Copy the samples runsimple.jsp and runsample.jsp
from c:\dev\is61sdkwin32\samples\sso
to C:\dev\Tomcat 4.1.30\webapps\ROOT

Login to the Identity Server to obtain a session.

Then try http://appserver.domain:<port>/runsimple.jsp and runsample.jsp

[ root(/) jsp's are converted to servlets and compiled into C:\dev\Tomcat 4.1.30\work\Standalone\localhost\_ ]

(If you wish to test the internet server www.identityprovider.net then you must update your workstation hosts file so that your local machine and app server believe they are in the .identityprovider.net domain and then run http://<yourhost>.identityprovider.net:8080/runsimple.jsp to test).

Output

Runsample SSO Token Test jsp
SSOToken host name: 192.168.1.7
SSOToken Principal name: uid=mark,ou=people,dc=identityprovider,dc=net
Authentication type used: LDAP
IPAddress of the host: 192.168.1.7

The token ID is AQIC5wM2LY4SfczVuj4yqSMQV7VPyOzkGDIV4VXTHZPUwa0=

Property: Company is - Sun Microsystems
Property: Country is - USA

SSO Token Validation test Succeeded

Your finished !

Sun App Server Samples

NOTE: pathing in this section refers to Solaris version, adapt paths as required.

Get your AppServer running

(you may have your app server running already so this step may not be needed).

This is built into Solaris 9 and needs configuration and enabling only:

asadmin create-domain --sysuser nobody --adminuser admin --adminpassword password --adminport 4848 domain1
su nobody
asadmin start-domain --domain domain1

use the console on port 4848 to create a new application server instance: server1 on 4080 or another port.

Update the AppServer environment

/var/appserver/domains/domain1/server1/config/server.policy

at end of file, add:

// For IS SDK
grant {
permission java.security.SecurityPermission "putProviderProperty.Mozilla-JSS";
permission java.security.SecurityPermission "insertProvider.Mozilla-JSS";
};

Use the admin console to complete the updates

(this updates: /var/appserver/domains/domain1/server1/config/server.xml)

Domains --> domain1 --> App Server Instances --> server1 --> JVM Settings --> Path Settings

add to Classpath Suffix:

/IS_CLASSPATH_BEGIN_DELIM
/opt/is61sdksolaris/lib/xmlsec.jar
/opt/is61sdksolaris/lib/dom4j.jar
/opt/is61sdksolaris/lib/jakarta-log4j-1.2.6.jar
/opt/is61sdksolaris/lib/jaxm-runtime.jar
/opt/is61sdksolaris/lib
/opt/is61sdksolaris/locale
/opt/is61sdksolaris/lib/jss3.jar
/opt/is61sdksolaris/lib/am_sdk.jar
/opt/is61sdksolaris/lib/am_services.jar
/opt/is61sdksolaris/lib/am_sso_provider.jar
/opt/is61sdksolaris/lib/swec.jar
/opt/is61sdksolaris/lib/acm ecrypt.jar
/opt/is61sdksolaris/lib/iaik_ssl.jar
/opt/is61sdksolaris/lib/servlet.jar
/opt/is61sdksolaris/lib/am_logging.jar
/opt/is61sdksolaris/lib/commons-logging.jar
/IS_CLASSPATH_END_DELIM

add to Native Lib. Path Suffix:

/opt/is61sdksolaris/lib/secv1sparc

then SAVE

(the App Server server1 will highlight, with a restart request, but don't restart yet)

--> JVM Options

add:

-Djava.protocol.handler.pkgs=com.iplanet.services.comm
note: the functionality demonstrated doesn't require this but it may be required for more advanced interaction.
add -server to configure the JVM for best longer running optimisation as opposed to the default optimisation for quick startup.
also, it's probably wise to increase the JVM size, so change -Xms128m -Xmx256m to -Xms512m -Xmx1024m (assuming a 2GB machine used for nothing else, double the higher limit if on 3GB machine or as best practices dictate).
If using a proxy, add -Dhttp.proxyHost=proxyhost.com and -Dhttp.proxyPort=8080
Performance Tuning: Java Business Benchmark Indicates the following for optimal JVM performance with JDK1.4.2:
-Xbatch -XX:+AggressiveHeap -Xss128k -verbose:gc
It also suggests that the JVM heap size be increased to the maximum that the 32bit JVM can take, which would be 3900MB, although on a 4GB machine, 3GB is suggested to allow for OS/App Server activities. Minimum heap should equal the maximum for production/stable configurations to prevent memory thrashing:-Xms3072m -Xmx3072m

then SAVE

Apply Changes and Restart App Server server1

Deploy and Run the Sample JSP's

Copy the samples runsimple.jsp and runsample.jsp
from /opt/is61sdksolaris/samples/sso
to /var/appserver/domains/domain/server1/docroot.

Login to the Identity Server to obtain a session.

Then try http://appserver:4080/runsimple.jsp and runsample.jsp

(If you wish to test the internet server www.identityprovider.net then you must update your workstation hosts file so that your local machine and app server believe they are in the .identityprovider.net domain and then run http://<yourhost>.identityprovider.net:4080/runsimple.jsp to test).

Output

<>

Your finished !

Possible Errors

cookie error

In the first instance ensure you are connecting from a client machine that is present in the same cookie domain as the Identity Server.

Sun ONE Application Server - HTTP Status 500 Error
The server encountered an internal error (Internal Server Error) that prevented it from fulfilling this request.
Type: Exception Report

Message: Internal Server Error

Exception

javax.servlet.ServletException: SessionID.parseSessionString :sid value is null or empty

Session expired or wrong machine

(AMConfig.properties-->namingURL configured incorrently)

javax.servlet.ServletException: AQIC5wM2LY4SfcwgXzArOAn2yCnPv9fnMR6npRJF4HRp02U= Session was not obtained

main: ERROR: Unable to load jss library

if you have JSS library environment problems then you'll see variants of the following so check your paths: Solaris uses LD_LIBRARY_PATH or Native Lib Path Suffix path, and Windows requires PATH.

main: ERROR: Unable to load jss library
Exception in thread "main" java.lang.UnsatisfiedLinkError: Unable to load jss library or one of its dependencies
        at org.mozilla.jss.CryptoManager.loadNativeLibraries(CryptoManager.java:1272)
        at org.mozilla.jss.CryptoManager.initialize(CryptoManager.java:756)
        at com.iplanet.services.util.JSSEncryption.<clinit>(JSSEncryption.java:237)
        at java.lang.Class.forName0(Native Method)

Contact

Regards,

mark.davis@sun.com

NHS Todo

Fix DTD logging error in toolkit. Not Possible, reduce debug level to error.
Complete Demo Listener Functionality, receiving callback but not parsing and outputting the 3 states. Tomcat doesn't appear to accept /servlet/<deployed class> as Sun Appserver does.
Nice Installer ?