Sun Java System Identity Server 6.2
Sample
 
Main Page

Sample Application for achieving SSO using SAML Web/Artifact profile and SAML Web/POST profile

Introduction

(I) SSO using SAML Web/Artifact profile

This sample application aims to demonstrate and explain how to achieve SSO between two different IS installations  using SAML's Web Artifact profile. In brief Web Artifact profile is something like follows: 
A web user authenticates to a source site. The web user then uses a secured resource at a destination site, without directly authenticating to the destination site. The following assumptions are made about this scenario for the purpose of this profile: 
  • The user is using a standard commercial browser and has authenticated to a source site by some means outside the scope of SAML. In Identity Server, IS server's Authentication service is used by the SAML Service to achieve this authentication.
  • The source site has some from of security engine in place that can track locally authenticated users. This typically takes the form of a session represented by an encrypted cookie or an encoded URL or some other technology. Identity Server SAML Service uses the SSOToken object stored as a cookie to track this piece of information.
At some point, the user attempts to access a target resource available from the destination site, and subsequently, through one or more steps (for example, redirection), arrives at an inter-site transfer service (which may be associated with one or more URIs) at the source site. Starting from this point, the web browser SSO profiles describe a canonical sequence of HTTP exchanges that transfer the user browser to an assertion consumer service at the destination site. Information about the SAML assertions provided by the source site and associated with the user, and the desired target, is conveyed from the source to the destination site by the protocol exchange. The assertion consumer service at the destination site can examine both the assertions and the target information and determine whether to allow access to the target resource, thereby achieving web SSO for authenticated users originating from a source site. Step 1: Accessing the Inter-Site Transfer Service

In step 1, the user's browser accesses the inter-site transfer service, with information about the desired target at the destination site attached to the URL. 

http://<inter-site transfer host name and path>?TARGET=<Target>
Where: 

<inter-site transfer host name and path>
This provides the host name, port number, and path components of an inter-site transfer URL at the source site. This is 

<protocol>:<servername>:<port>/amserver/SAMLAwareServlet in IS Server. 

Target=<Target>
This name-value pair occurs in the <searchpart> and is used to convey information about the desired target resource at the destination site. 


Step 2: Redirecting to the Destination Site

In step 2, the source site's inter-site transfer service responds and redirects the user's browser to the assertion consumer service at the destination site. 

http://<artifact receiver host name and path>?<SAML searchpart>
Where: 

< artifact receiver host name and path>
This provides the host name, port number, and path components of an artifact receiver   URL associated with the assertion consumer service at the destination site. In IS Server terms we call it the Partner URL i.e. the URL of the partner which receives the Artifact in the query string, with who we are trying to achieve the SSO

<SAML searchpart>= ?TARGET=<Target>?SAMLart=<SAML artifact> ?
A single target description MUST be included in the <SAML searchpart> component. 


Step 3: Accessing the Artifact Receiver URL

In step 3, the user's browser accesses the artifact receiver URL, with a SAML artifact representing the user's authentication information attached to the URL. This is actually a redirection which happens internally between inter site service and the artifact receiver of the partner. 

Internally a HTTP Get is made to 

http://< artifact receiver host name and path>?<SAML searchpart>
Where: 

< artifact receiver host name and path>
This provides the host name, port number, and path components of an artifact receiver  URL associated with the assertion consumer service at the destination site. 

<SAML searchpart>= ?TARGET=<Target>?SAMLart=<SAML artifact> ?


Steps 4 and 5: Acquiring the Corresponding Assertions

In steps 4 and 5, the destination site, in effect, dereferences the one or more SAML artifacts in its possession in order to acquire the SAML authentication assertion that corresponds to each artifact.
These steps MUST utilize a SAML protocol binding for a SAML request-response message exchange between the destination and source sites. The destination site functions as a SAML requester and the source site functions as a SAML responder. 

The destination site MUST send a <samlp:Request> message to the source site, requesting assertions by supplying assertion artifacts in the <samlp:AssertionArtifact> element. The request is sent using SOAP over HTTP(s) to the SOAP responder of the source site. In IS this is the <protocol>:<servername>:<port>/amserver/SAMLSOAPReceiver
 

Step 6: Responding to the User's Request for a Resource

In step 6, the user's browser is sent an HTTP response that either allows or denies access to the desired resource. 
 
 
 
 

(II) SSO using SAML Web Browser/POST profile

The web browser/POST profile of SAML allows authentication information to be supplied to a destination site without the use of an artifact. 

There are three parties involved in the browser/POST profile. They are: Browser, Source Site, and Destination Site. The browser/POST profile consists of a series of two interactions, the first between a user equipped with a browser and a source site, and the second directly between the user and the destination site. The following section elucidates the four steps involved in browser/POST profile. 
 

Step 1: Accessing the Inter-Site Transfer Service

The user's browser accesses the inter-site transfer service, with information about the desired target at the destination site attached to the URL. 
 

Step 2: Generating and Supplying the Response

The source site generates HTML form data containing a SAML Response which contains an SSO assertion. 
 

Step 3: Posting the Form Containing the Response

The browser submits the form containing the SAML response to the destination site. 
 

Step 4: Responding to the User's Request for a Resource

The user's browser is sent an HTTP response that either allows or denies access to the desired resource. 

Sun Car Rental Sample Application

This Sample Application demonstrates Single Sign On between 2 Identity Server installations. A user is setup on one machine with email address of username@sun.com (amadmin here) and the postaladdress attribute ( Home Address on administration console) is used as the  membership level of the user either gold, silver or bronze. Once the user logs into the source site, web browser/Artifact profile or web browser/POST profile is used to achieve SSO. Some user specific attributes are also sent along with the SSO Assertion as Attribute Statements. This is determined by the siteAttributeMapper plugin (TestSiteAttributeMapper.java as bundled with the sample and present in com.iplanet.am.samples.saml.sso package) It is located under <IS-install-location>/SUNWam/samples/saml/sso/ directory. When the SAML Service performs the SSO it calls this configured plugin (This configuration is per partner as configured in the trusted site list and explained in the next section), which returns a list of Attributes which are then sent back as Attribute Statements as part of the SSO Assertion.

The destination site receives this Assertion and looks up the POST to target URLs configured on its site;  if it finds the TARGET its supposed to redirect to in the list, along with redirecting to TARGET it also does a FORM POST of the Assertion to the TARGET (which is demo/app_artifact.jsp or demo/app_postprofile.jsp in this case). app_artifact.jsp /app_postprofile.jsp reads the Assertion POSTed and redirects the user to gold, silver or bronze page based on the membership level.  It also displays some pertinent information from the Assertion in a small window on the left like: 

Authentication authority, email address, user id, membership level. 
Links on left allow user to access other pages, with access control enforced based on user's membership level. For example if the user has silver member level, then on clicking on link meant for "gold members" an error message is displayed. Link "Visit Inter Site Service" takes the user to the site's inter site service from where the user can again do a SSO with the other machine. 
 

Identity Server SAML Service Configuration

Now, let's get down to doing the configuration needed in the IS server to make this SSO happen.

The current sample is for achieving SSO between 2 machines arth.red.iplanet.com (lets call it A) and greed.sun.com (B). For achieving SSO between any other machines make machine names changes as the situation demands. Also in this example configuration it has been assumed that the deployment URI is amserver and the port is 58080 and the protocol is http. This configuration will have to be changed accordingly if the configuration scenario is different. Example if the port is 444 then wherever I have mentioned 58080 replace that with 444.
 

The following configuration steps need to be followed, as user amadmin. Go to http://servername:port/amconsole

  1. On machine B  go into Service Management->SAML->SiteID and issuer name where there is an entry like: 
  2. instanceID=greed.sun.com:58080|siteid=Yl1KZ1qcHktuAdSDBSAO4Wkcz6c=|
    issuerName=greed.sun.com:58080
    copy the siteID string which is Yl1KZ1qcHktuAdSDBSAO4Wkcz6c= here and use it as specified in step 3. 
  3. Get the IP address of machine B (say 192.12.12.34) 
  4. On machine A go to Service Management->SAML->trusted partner sites add the following entry for machine B (a trusted partner with who we wish to achieve SSO). 
  5. sourceID=Yl1KZ1qcHktuAdSDBSAO4Wkcz6c=
    SAMLUrl=http://greed.sun.com:58080/amserver/SAMLAwareServlet
    POSTUrl=http://greed.sun.com:58080/amserver/SAMLPOSTProfileServlet
    target=greed.sun.com
    hostlist=192.12.12.34
    siteattributemapper=com.iplanet.am.samples.saml.sso.TestSiteAttributeMapper
    SOAPUrl=http://greed.sun.com:58080/amserver/SAMLSOAPReceiver
    issuer=greed.sun.com:58080
    where the source ID is as saved in 1 and hostlist=<IP address> is IP address of machine B. 
  6. On A, go to ServiceManagement->SAML->POST to Target URLs and add http://arth.red.iplanet.com:58080/demo/app_artifact.jsp then add another one http://arth.red.iplanet.com:58080/demo/app_postprofile.jsp 
  7. On machine A go into Service Management->SAML->SiteID and issuer name where there is an entry like: 
  8. instanceID=arth.red.iplanet.com:58080|
    siteid=VoKyj7WH9TJjfl/sX31iakdFKQA=|issuerName=arth.red.iplanet.com:58080
    copy the siteID string which is here VoKyj7WH9TJjfl/sX31iakdFKQA= and use it as specified in step 7. 
  9. Get the IP address of machine A (say 192.12.12.33) 
  10. On machine B go to Service Management->SAML->trusted partner sites add the following entry for machine A (a trusted partner with who we wish to achieve SSO). 
  11. sourceID=VoKyj7WH9TJjfl/sX31iakdFKQA=
    SAMLUrl=http://arth.red.iplanet.com:58080/amserver/SAMLAwareServlet
    POSTUrl=http://arth.red.iplanet.com:58080/amserver/SAMLPOSTProfileServlet
    target=arth.red.iplanet.com
    hostlist=192.12.12.33
    siteattributemapper=com.iplanet.am.samples.saml.sso.TestSiteAttributeMapper
    SOAPUrl=http://arth.red.iplanet.com:58080/amserver/SAMLSOAPReceiver.
    issuer=arth.red.iplanet.com:58080
  12. On machine B, go to ServiceManagement->SAML->POST to Target URLs and add http://greed.sun.com:58080/demo/app_artifact.jsp, then add another one http://greed.sun.com:58080/demo/app_postprofile.jsp 

  13.  

     

    The rest of the instructions need to be followed for  both machines.
     

  14. cd /<IS-install-location>/SUNWam/samples/saml/sso/ as root and run gmake. In the build environment its in /tools/ns/bin/gmake. For Windows200 machines go to where the product has been installed SunONE/SunONEIS by default, so for default go to /SunONE/SunONEIS/samples/sso/ and run make.bat
  15. cp SAMLSampleApp.jar /<IS-install-location>/SUNWam/lib for Solaris. For Windows2000, this file gets copied automatically in the installation's lib directory. 
  16. Change  web server 's classpath. In <ws-install-location>/https-<servername>/config/server.xml add /<IS-install-location>/SUNWam/lib/SAMLSampleApp.jar to the serverclasspath
  17. deploy the application per the web container IS is deployed on. For example on Sun Java System webserver 6.1 the deploy location will be <ws-install-location>/docs
    • cp -r  /<IS-install-location>/SUNWam/samples/saml/sso/demo <ws-install-location>/docs/demo/ directory. In case of W2K use the appropriate means available to copy directory recursively. Ensure that directory <ws-install-location>/docs/demo/ gets created and has  following structure:
      • <ws-install-location>/docs/demo/
        • app_artifact.jsp 
        • demo_artifact.jsp     
        • reserve.html
        • app_postprofile.jsp 
        • demo_postprofile.jsp 
        • silver.jsp
        • bronze.jsp 
        • gold.jsp
        • contact.html 
        • images 
          • corp-main-smp-screen.jpg 
          •  sunOne.gif
          • corp-main-smp-shirtback.jpg
  18. cd /<IS-install-location>/docs/demo/. For Windows2000 machines go to where the product has been installed SunONE/SunONEIS by default, so for default go to /SunONE/SunONEIS/docs/demo/. As install user (root here for Solaris), in file demo_artifact.jsp and demo_postprofile.jsp on machine B replace both <PARTNER_HOST> occurences by machine A's name. For example, in demo_artifact.jsp, in the lines looking like this: 
  19. <td><a>PARTNER_HOST</a></td>
    <td><a href="<%= reqBase%>/amserver/SAMLAwareServlet?
    TARGET=http://PARTNER_HOST:58080/demo/app_artifact.jsp">
    Car Rental Application</a></td>
    On machine B changes to 
    <td><a>arth.red.iplanet.com</a></td>
    <td><a href="<%= reqBase%>/amserver/SAMLAwareServlet?
    TARGET=http://arth.red.iplanet.com:58080/demo/app_artifact.jsp">
    Car Rental Application</a></td>
    For example, in demo_postprofile.jsp, in the lines looking like this: 
    <td><a>PARTNER_HOST</a></td>
    <td><a href="<%= reqBase%>/amserver/SAMLPOSTProfileServlet?
    TARGET=http://PARTNER_HOST:58080/demo/app_postprofile.jsp">
    Car Rental Application</a></td>
    On machine B changes to 
    <td><a>arth.red.iplanet.com</a></td>
    <td><a href="<%= reqBase%>/amserver/SAMLPOSTProfileServlet?
    TARGET=http://arth.red.iplanet.com:58080/demo/app_postprofile.jsp">
    Car Rental Application</a></td>
    For machine A  put machine B's name for the above string. 
  20. cd /<ws-install-location>/docs/demo/. For Windows200 machines go to where the product has been installed SunONE/SunONEIS by default, so for default go to /SunONE/SunONEIS/docs/demo/. In files reserve.html and contact.html replace 
    • PROTOCOL by the protocol ( http in this sample) 
    • SERVERHOST by server name being used (arth.red.iplanet.com on machine A and greed.sun.com on B in this sample) 
    • SERVERPORT by the port the IS server is running on (58080 in this sample). 
    If the deployment URI is different from amserver please replace amserver by the URI in these two files after editing them manually. 
  21. To test web browser/post profile, the user has to set up an keyentry in a keystore. For details, please refer to <IS-install-location>/SUNWam/samples/saml/xmlsig/keytool.txt (on Solaris) or <IS-install-location>/samples/saml/xmlsig/keytool.txt (on Windows2000). 
  22. Start the Sun Java System web server.
  23. Log in as amadmin, go to Identity Management->users>amadmin. Add email address as amadmin@sun.com and "Home Address" as "gold" or "silver" or "bronze". (For sample purposes we are trying to use the attribute postaladdress to represent membership level of user.)
Now we are all set. 

To test web browser/Artifact profile, go to http://arth.red.iplanet.com:58080/demo/demo_artifact.jsp, log in as amadmin, Click on "Sun Car Rental" next to the greed.sun.com you should be able to SSO to machine B as see the sample Application. Depending on the entry you specified in the postaladdress attribute gold/silver/bronze you should see different pages. 

To test web browser/POST profile, go to http://arth.red.iplanet.com:58080/demo/demo_postprofile.jsp, log in as amadmin, Click on "Sun Car Rental" next to the greed.sun.com you should be able to SSO to machine B as see the sample Application. Depending on the entry you specified in the postaladdress attribute gold/silver/bronze you should see different pages. 

Now can go the other way around, do SSO from B to A, after choosing "Visit Inter Site Service". 

NOTE: if <IS-install-location>/lib/AMConfig.properties has debug=message, debug logs can be found at /var/opt/SUNWam/debug/samlSample and /var/opt/SUNWam/debug/amSAML for Solaris and /SunONE/SunONEIS/debug directory on Windows2000. 

Configure with SSL with client Authentication Enabled

If the identity server is running SSL with client authentication on (which is the recommended one for SAML Service), one needs to do the following steps in addition to the above mentioned configuration. 
  1. Assuming docs to turn SSL on from administration guide have been followed and the identity server is already running SSL with client auth successfully. 
  2. In the above configuration replace all instances of "http" in the URLs with "https", including the the protocol in "POST to target URLs" parameter. In addition under "Service Configuration" - > SAML ->  site ID and site issuer name, replace the protocol in the instance ID attribute to "https" too. 
  3. In the points 3 and 7 in the above section add one more attribute to the trusted partner configuration 

  4. authtype=SSL
    The point is that the server whose configuration is being defined in trusted partner list is running in SSL then this attribute needs to be specified. If only one server is running SSL and the other is not then this attribute will be set on the non SSL server for trusted partner info. of the server running SSL
  5. For machine A (arth) import the client certificate of machine B (greed) into the certdb by running the following command as root. 
  6. For Solaris
    setenv LD_LIBRARY_PATH <ws-install-location>/bin/https/lib
    
    cd <ws-install-location>/bin/https/admin/bin
    ./certutil  -A -n greed -t P -d <ws-install-location>/alias -P
    https-arth.red.iplanet.com-arth- -f /etc/opt/SUNWam/config/.wtpass 
    - i infile
    Where: 

    -d is the com.iplanet.am.admin.cli.certdb.dir parameter from <IS-install-location>/SUNWam/lib/AMConfig.properties

    -P is the com.iplanet.am.admin.cli.certdb.prefix parameter from <IS-install-location>/SUNWam/lib/AMConfig.properties

    -f is the com.iplanet.am.admin.cli.certdb.passfile parameter from <IS-install-location>/SUNWam/lib/AMConfig.properties

    -i is the client certificate of B (greed). 

    For Windows2000

    assuming product is installed in c:\sunone\sunoneis directory 

    cd to c:\sunone\sunoneis\bin\https\admin\bin
    certutil -A -n greed -t P  -d c:\sunone\sunoneis\alias
    -P -P  https-arth.red.iplanet.com-arth- -f  \sunone\sunoneis\config\.wtpass
    -i infile
    Where: 

    -d is the com.iplanet.am.admin.cli.certdb.dir parameter from c:\sunone\sunoneis\lib\AMConfig.properties

    -P is the com.iplanet.am.admin.cli.certdb.prefix parameter from c:\sunone\sunoneis\lib\AMConfig.properties

    -f is the com.iplanet.am.admin.cli.certdb.passfile parameter from c:\sunone\sunoneis\lib\AMConfig.properties

    -i is the client certificate of B (greed). 

    -n is the nickname of the certificate. 

  7. For machine B (greed) import the client certificate of machine A (arth) into the certdb by running the following command 
  8. For Solaris

    as user "root" 

    setenv LD_LIBRARY_PATH <ws-install-location>/bin/https/lib
    
    cd <ws-install-location>/bin/https/admin/bin
    ./certutil  -A -n arth -t P -d <ws-install-location>/alias -P 
    https-greed.sun.com-greed- -f  /etc/opt/SUNWam/config/.wtpass 
    - i infile
    Where: 

    -d is the com.iplanet.am.admin.cli.certdb.dir parameter from <IS-install-location>/SUNWam/lib/AMConfig.properties

    -P is the com.iplanet.am.admin.cli.certdb.prefix parameter from <IS-install-location>/SUNWam/lib/AMConfig.properties

    -f is the com.iplanet.am.admin.cli.certdb.passfile parameter from <IS-install-location>/SUNWam/lib/AMConfig.properties. If this file does not exist it needs to be created first and the password put there, in cleartext. 

    -i is the client certificate of B (arth). 

    For Windows2000

    assuming product is installed in c:\sunone\sunoneis directory

    Add c:\sunone\sunoneis\bin\https\lib to the PATH environment variable.
    cd c:\sunone\sunoneis\bin\https\admin\bin
    certutil -A -n arth -t P  -d c:\sunone\sunoneis\alias
    -P -P  https-greed.red.iplanet.com-greed- -f  \sunone\sunoneis\config\.wtpass
    -i infile
    Where: 

    -d is the com.iplanet.am.admin.cli.certdb.dir parameter from c:\sunone\sunoneis\lib\AMConfig.properties

    -P is the com.iplanet.am.admin.cli.certdb.prefix parameter from c:\sunone\sunoneis\lib\AMConfig.properties

    -f is the com.iplanet.am.admin.cli.certdb.passfile parameter from c:\sunone\sunoneis\lib\AMConfig.properties. If this file does not exist it needs to be created first and the password put there in cleartext. 

    -i is the client certificate of B (gree). 

    -n is the nickname of the certificate. 

  9. On machine A change the hostlist parameter in the partner configuration to include the nickname of machine B's client cert so replace hostlist=192.12.12.34 by hostlist = 192.12.12.34, greed in Service Management -> SAML-> trusted partner sites. 
  10. On machine B change the hostlist parameter in the partner configuration to include the nickname of machine A's client cert so replace hostlist=192.12.12.33 by hostlist = 192.12.12.34, arth in Service Management -> SAML-> trusted partner sites 
  11. Restart server.