| Main Page
 Achieving Single Sign On using SAML profile
 
 1. Introduction
    This sample illustrates how to achive Single Sign On using Web/Artifact
    and Web/POST profiles.
     
 
 2. Single Sign On using SAML Web/Artifact profile
    This sample application aims to demonstrate and explain how to achieve
    SSObetween two different Access Manager 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:
 
 a. The user is using a standard commercial browser and has
          authenticated to a source site by some means outside the scope
	  of
 SAML. In Access Manager, Authentication service
	  is used by theSAMLService to achieve this
	  authentication.
 b. 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. Access Manager
 SAMLService uses theSSOTokenobject 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 SSOprofiles 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 webSSOfor authenticated users originating
    from a source site. 
    
 Step 1: Accessing the Inter-Site Transfer ServiceIn 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 Access Manager 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 SiteIn 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 Access Manager 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 URLIn 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 AssertionsIn 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 usingSOAPoverHTTP(s)to theSOAPresponder of the source
    site. In Access Manager this is the<protocol>:<servername>:<port>/amserver/SAMLSOAPReceiver
    
 Step 6: Responding to the User's Request for a ResourceIn step 6, the user's browser is sent an HTTP response that either allows
    or denies access to the desired resource.
 
 3. Single Sign On 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 ServiceThe 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 ResponseThe source site generates HTML form data containing a SAML Response
    which contains anSSOassertion.
    
 Step 3: Posting the Form Containing the ResponseThe browser submits the form containing the SAML response to the
    destination site.
    
 Step 4: Responding to the User's Request for a ResourceThe user's browser is sent an HTTP response that either allows or denies
    access to the desired resource.
 
 4. Sun Car Rental Sample Application
    This Sample Application demonstrates Single Sign On between 2 Access
    Manager installations. A user is setup on one machine with email address
    of username@sun.com(amadmin here) and thepostaladdressattribute (Home
    Address on administration console) is used as the membership level of the
    user eithergold,silverorbronze. Once the user logs
    into the source site,web browser/Artifactprofile or web browser/POST
    profile is used to achieveSSO. Some user specific attributes
    are also sent along with theSSOAssertion as Attribute Statements. This
    is determined by thesiteAttributeMapperplugin
    (TestSiteAttributeMapper.javaas bundled with the sample and present incom.iplanet.am.samples.saml.ssopackage) It is located under<INSTALL_DIR>/SUNWam/samples/saml/sso/directory. When theSAMLService performs theSSOit 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 theSSOAssertion. 
    The destination site receives this Assertion and looks up the POSTto target
    URLs configured on its site;  if it finds theTARGETits supposed to
    redirect to in the list, along with redirecting toTARGETit also does a
    FORM POST of the Assertion to theTARGET(which isdemo/app_artifact.jspordemo/app_postprofile.jspin this case).app_artifact.jsp/app_postprofile.jspreads the Assertion POSTed and redirects the user togold,silverorbronzepage 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 SSOwith the other machine. 
    
 Access Manager Now, let's get down to doing the configuration needed in the Access
    Manager server to make thisSAMLService ConfigurationSSOhappen.
    The current sample is for achieving SSObetween 2 machinesarth.red.iplanet.com(lets call it A) andgreed.sun.com(B). For
    achievingSSObetween any other machines make machine names changes as the
    situation demands. Also in this example configuration it has been assumed
    that the deployment URI isamserverand the port is58080and the protocol
    ishttp. 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. If both machines are
    in the same domain, please make sure cookie names are different. You can
    change cookie name by changing property "com.iplanet.am.cookie.name" in
    /etc/opt/SUNWam/config/AMConfig.properties 
    The following configuration steps need to be followed, as user amadmin. Go
    tohttp://servername:port/amconsole 
 
On machine B Click on "Federation" tab
    Click on "SAML" tab
    Click "edit" link of the only entry of "Site Identifiers" to go to
       "Edit Site Identifier" page. Make sure "Instance ID" has correct
       protocol and port if you changed Access Manager server protocol or port.
       Copy the Site IDvalue. This will be used at step 7. Click "Save" if you make any change or "Cancel" to go back to
       previous page.
    On machine A Click on "Federation" tab
    Click on "SAML" tab
    Click "New" under "Trusted Partners" to go to
       "Select trusted partner type and profile" page. Check "Artifact" and
       "Post" under both "Destination" and "Source" and click "Next" to go to
       "Add New Trusted Partner" page.
       Set attributes like the following:
       
       Source ID: <the one obtained from step 3>
       Target: greed.sun.com
       Site Attribute Mapper: com.iplanet.am.samples.saml.sso.TestSiteAttributeMapper
       SAML URL: http://greed.sun.com:58080/amserver/SAMLAwareServlet
       Host List: <the ipaddress of greed.sun.com>
       POST URL: http://greed.sun.com:58080/amserver/SAMLPOSTProfileServlet
       SOAP URL: http://greed.sun.com:58080/amserver/SAMLSOAPReceiver
       Issuer: greed.sun.com:58080
       If machine B protocol is https, check "SSL" under "Authentication Type"Click on "Finish"
    Click on "Save"
    Click "New" under "Target URLs" to go to "Add New Post To Target URL"
          page.
          Set attributes like the following:
          
          Protocol: http
          Server Name: arth.red.iplanet.com
          Port: 58080
          Path: /demo/app_artifact.jsp
          Click on "OK"
    Click "New" under "Target URLs" to go to "Add New Post To Target URL"
          page.
          Set attributes like the following:
          
          Protocol: http
          Server Name: arth.red.iplanet.com
          Port: 58080
          Path: /demo/app_postprofile.jsp
          Click on "OK"
    Click on "Save"
    Click "edit" link of the only entry of "Site Identifiers" to go to
       "Edit Site Identifier" page. Make sure "Instance ID" has correct
       protocol and port if you changed Access Manager server protocol or port.
       Copy the Site IDvalue. This will be used at step 19. Click "Save" if you make any change or "Cancel" to go back to
       previous page.
    On machine B Click on "Federation" tab
    Click on "SAML" tab
    Click "New" under "Trusted Partners" to go to
       "Select trusted partner type and profile" page. Check "Artifact" and
       "Post" under both "Destination" and "Source" and click "Next" to go to
       "Add New Trusted Partner" page.
       Set attributes like the following:
       
       Source ID: <the one obtained from step 15>
       Target: arth.red.iplanet.com
       Site Attribute Mapper: com.iplanet.am.samples.saml.sso.TestSiteAttributeMapper
       SAML URL: http://arth.red.iplanet.com:58080/amserver/SAMLAwareServlet
       Host List: <the ipaddress of arth.red.iplanet.com>
       POST URL: http://arth.red.iplanet.com:58080/amserver/SAMLPOSTProfileServlet
       SOAP URL: http://arth.red.iplanet.com:58080/amserver/SAMLSOAPReceiver
       Issuer: arth.red.iplanet.com:58080
       If machine A protocol is https, check "SSL" under "Authentication Type"Click on "Finish"
    Click on "Save"
    Click "New" under "Target URLs" to go to "Add New Post To Target URL"
          page.
          Set attributes like the following:
          
          Protocol: http
          Server Name: greed.sun.com
          Port: 58080
          Path: /demo/app_artifact.jsp
          Click on "OK"
    Click "New" under "Target URLs" to go to "Add New Post To Target URL"
          page.
          Set attributes like the following:
          
          Protocol: http
          Server Name: greed.sun.com
          Port: 58080
          Path: /demo/app_postprofile.jsp
          Click on "OK"
    Click on "Save"
       
 The rest of the instructions need to be followed for both machines.
 
cd /<INSTALL_DIR>/SUNWam/samples/saml/sso/as root and rungmake. In the build environment its in/tools/ns/bin/gmake. For Windows
       machines go to where the product has been installedSunONE/SunONEISby
       default, so for default go to/SunONE/SunONEIS/samples/sso/and runmake.bat.cp SAMLSampleApp.jar/<INSTALL_DIR>/SUNWam/libfor Solaris.
       For Windows, this file gets copied automatically in the installation's
       lib directory.Change web server's classpath. In
       <WEB_SERVER_INSTALL_DIR>/https-<servername>/config/server.xmladd/<INSTALL_DIR>/SUNWam/lib/SAMLSampleApp.jarto theclasspathsuffixDeploy the application per the web container Access Manager is
       deployed on. For example on Sun Java System Web Server 6.1 the deploy
       location will be <WEB_SERVER_INSTALL_DIR>/docs.
       cp -r  <INSTALL_DIR>/SUNWam/samples/saml/sso/demo
          <WEB_SERVER_INSTALL_DIR>/docs/demo/.
       In case of Windows use the appropriate means available to copy
       directory recursively. Ensure that directory
       <WEB_SERVER_INSTALL_DIR>/docs/demo/ gets created and has following
       structure:
       <WEB_SERVER_INSTALL_DIR>/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
       cd <INSTALL_DIR>/docs/demo/. For Windows machines
       go to where the product has been installedSunONE/SunONEISby default,
       so for default go to/SunONE/SunONEIS/docs/demo/. As install user
       (root here for Solaris), in filedemo_artifact.jspanddemo_postprofile.jspon machine B replace
       PARTNER_PROT by machine A's protocol
       PARTNER_HOST by machine A's name
       PARTNER_PORT by machine A's port
       For example, indemo_artifact.jsp, in the lines
       looking like this:
       <td><a>PARTNER_HOST</a></td>
       <td><a href="<%= reqBase%>/amserver/SAMLAwareServlet?
       TARGET=PARTNER_PROT://PARTNER_HOST:PARTNER_PORT/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, indemo_postprofile.jsp, in the lines looking like this:
       <td><a>PARTNER_HOST</a></td>
       <td><a href="<%= reqBase%>/amserver/SAMLPOSTProfileServlet?
       TARGET=PARTNER_PROT://PARTNER_HOST:PARTNER_PORT/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 protocol, name and port for the above
       strings.cd <WEB_SERVER_INSTALL_DIR>/docs/demo/. For Windows machines go
       to where the product has been installedSunONE/SunONEISby default, so
       for default go to/SunONE/SunONEIS/docs/demo/. In filesreserve.htmlandcontact.htmlreplace
       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 Access Manager server is running on (58080
       in this sample).
       If the deployment URI is different fromamserverplease replaceamserverby the URI in these two files after editing them manually.To test web browser/post profile, the user has to set up an keyentryin akeystore. For details, please refer to<INSTALL_DIR>/SUNWam/samples/saml/xmlsig/keytool.txt(on Solaris) or<INSTALL_DIR>/samples/saml/xmlsig/keytool.txt(on Windows).Restart the Sun Java System web server.
    Log in as amadmin, to http://servername:port/amconsole
        Click root realm link.
    
        Click on "Subjects" tab.
    
        Click on "User" tab.
    
        Click "amadmin" link.
    
       Add "Email address" as amadmin@sun.comand "Home Address" as "gold" or
       "silver" or "bronze". (For sample purposes we are trying to use the
       attributepostaladdressto represent membership level of user.)
        Click "Save".
    
        Click on "Authentication" tab.
    Click "New" under "Instances" to go to
       "New Authentication Instance" page. Type "SAML" in "Name" textbox.
       Select "SAML" as "Type".
    
       Click "Create"
    Click "New" under "Configurations" to go to
       "New Authentication Configuration" page. Type "SAML" in "Name" textbox
       then click "Create" to go to "SAML - Edit Authentication Configuration"
       page.
    
        Click "Add" button under "(0 items)".
    
        Select "SAML" in the "Instance" drop down menu.
    
        Click "Save" and "LOG OUT".
     
    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 asamadmin, Click on "Sun Car Rental" next to thegreed.sun.comyou should be able toSSOto machine B as see the sample Application.
    Depending on the entry you specified in thepostaladdressattribute
    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 asamadmin, Click on "Sun Car Rental" next to thegreed.sun.comyou should be
    able toSSOto machine B as see the sample Application. Depending on the
    entry you specified in thepostaladdressattribute gold/silver/bronze you
    should see different pages. 
    Now can go the other way around, do SSOfrom B to A, after choosing
    "Visit Inter Site Service". 
    NOTE: if <INSTALL_DIR>/lib/AMConfig.propertieshasdebug=message, debug
    logs can be found at/var/opt/SUNWam/debug/samlSampleand/var/opt/SUNWam/debug/amSAMLfor Solaris and/SunONE/SunONEIS/debugdirectory on Windows. 
 
 5. Configure with SSL with client Authentication Enabled 
    If the Access Manager is running SSLwith 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. 
 
Assuming docs to turn SSLon from administration guide have been
       followed and the access manager is already runningSSLwith client
       authentication successfully.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.In the points 3 and 7 in the above section add one more attribute to
    the trusted partner configuration.
       
       authtype=SSL
       The point is that the server whose configuration is being defined in
       trusted partner list is running inSSLthen this attribute needs to be
       specified. If only one server is runningSSLand the other is not then
       this attribute will be set on the nonSSLserver for trusted partner
       info. of the server runningSSL.For machine A (arth) import the client certificate of machine B
       (greed) into thecertdbby running the following command as root.For Solaris
       setenv LD_LIBRARY_PATH <WEB_SERVER_INSTALL_DIR>/bin/https/lib
       cd <WEB_SERVER_INSTALL_DIR>/bin/https/admin/bin
       ./certutil  -A -n greed -t P -d <WEB_SERVER_INSTALL_DIR>/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
          <INSTALL_DIR>/SUNWam/lib/AMConfig.properties
       -P is the com.iplanet.am.admin.cli.certdb.prefix parameter from
          <INSTALL_DIR>/SUNWam/lib/AMConfig.properties
       -f is the com.iplanet.am.admin.cli.certdb.passfile parameter from
          <INSTALL_DIR>/SUNWam/lib/AMConfig.properties
       -i is the client certificate of B (greed).
       For WindowsAssuming product is installed inc:\sunone\sunoneisdirectory
       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.
       For machine B (greed) import the client certificate of machine A
       (arth) into thecertdbby running the following commandFor Solarisas user "root"
       setenv LD_LIBRARY_PATH <WEB_SERVER_INSTALL_DIR>/bin/https/lib
       cd <WEB_SERVER_INSTALL_DIR>/bin/https/admin/bin
          ./certutil  -A -n arth -t P -d <WEB_SERVER_INSTALL_DIR>/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
          <INSTALL_DIR>/SUNWam/lib/AMConfig.properties
       -P is the com.iplanet.am.admin.cli.certdb.prefix parameter from
          <INSTALL_DIR>/SUNWam/lib/AMConfig.properties
       -f is the com.iplanet.am.admin.cli.certdb.passfile parameter from
          <INSTALL_DIR>/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 WindowsAssuming product is installed inc:\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:
       -dg is the com.iplanet.am.admin.cli.certdb.dir parameter from
           c:\sunone\sunoneis\lib\AMConfig.propertiesg
       -Pg is the com.iplanet.am.admin.cli.certdb.prefix parameter from
           c:\sunone\sunoneis\lib\AMConfig.propertiesg
       -fg is the com.iplanet.am.admin.cli.certdb.passfile parameter from
           c:\sunone\sunoneis\lib\AMConfig.propertiesg. If this file does
	   not exist it needs to be created first and the password put there
	   in cleartext.
       -ig is the client certificate of B (greed).
       -ng is the nickname of the certificate.
       On machine A change the hostlistparameter in the partner configuration
       to include the nickname of machine B's clientcertso replacehostlist=192.12.12.34byhostlist = 192.12.12.34,greedin Service Management -> SAML-> trusted partner sites.On machine B change the hostlistparameter in the partner
       configuration to include the nickname of machine A's clientcertso
       replacehostlist=192.12.12.33byhostlist = 192.12.12.34,arthin Service Management -> SAML-> trusted partner sitesRestart server.
     |