Sun Java System Access Manager version 7 2005Q4
Sample
 

Main Page

SAML Client Sample


1. Introduction

This Sample serves as a basis for using SAMLClient API. There are two machines which installed Access Manager. One is called machine #1. The other is machine #2. The AssertionArtifactSample servlet is running on machine #1 generates an AssertionArtifact and sends it to SAMLClientSample servlet on machine #2. SAMLClientSample will retrieve the Assertion by passing the Artifact to machine #1.


2. Instructions For Solaris

Instructions to set up the sample servlets on Machine #1

  1. cd to <INSTALL_DIR>/SUNWam/samples/saml/client
  2. Edit the Makefile. Modify the environment variables. These environment variables will be used to run the make command.
           BASE - Set this Variable to install directory
           CLASSPATH - Get this from the web container the Access Manager instance
              is running in. For example, in Sun Web Server, use the value of
    	  classpathsuffix in
    	  <WEB_SERVER-INSTALL_DIR>/https-<servername>/config/server.xml.
           JAVA_HOME - Set this variable to your installation of JDK. It should be
              newer than JDK 1.3.1
           BASE_CLASS_DIR - Directory where all the Sample compiled classes will
              be kept.
           JAR_DIR - Directory where the jar of the sample classes will be created.
           
  3. Run gmake
  4. Deploy this example to web container. For example, in Sun Web Server:
           Add <INSTALL_DIR>/SUNWam/lib/SAMLSample.jar to web server's
           server.xml file classpathsuffix
           Add <servlet> and <servlet-mapping> to file
           <WEB_SERVER_INSTALL_DIR>/https-<servername>/is-web-apps/services/WEB-INF/web.xml
    
              <servlet>
              <servlet-name>AssertionArtifactSample</servlet-name>
              <description>AssertionArtifactSample</description>
              <servlet-class>AssertionArtifactSample</servlet-class>
              </servlet>
              <servlet-mapping>
              <servlet-name>AssertionArtifactSample</servlet-name>
              <url-pattern>/AssertionArtifactSample</url-pattern>
              </servlet-mapping>
           
  5. 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
  6. Restart the Access Manager
  7. Login in to the Administration Console, http://<machine#1 host>:<machine #1 port>/amserver/UI/Login
  8. Click on "Federation" tab
  9. Click on "SAML" tab
  10. 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 ID value. It will be used in machine #2 setup.
  11. Click "Save" if you make any change or "Cancel" to go back to previous page.
  12. Click "New" under "Trusted Partners" to go to "Select trusted partner type and profile" page. Check "artifact" under "Destination" and click "Next" to go to "Add New Trusted Partner" page. Set attributes like the following:
           Source ID: <Site ID of machine #2>
           Target: <machine #2 host>:<machine #2 port>
           SAML URL: <machine #2 protocol>://<machine #2 host>:<machine #2 port>/amserver/SAMLAwareServlet
           Host List: <machine #2 host IP>
           
    For example,
           Source ID: 5SwAdEHiwXYg+Oho40ppcB+NLnM=
           Target: machine#2.abc.com:80
           SAML URL: http://machine#2.abc.com:80/amserver/SAMLAwareServlet
           Host List: 192.12.148.102
           
  13. Click on "Finish"
  14. Click on "Save"

Instructions to set up the sample servlets on Machine #2"

  1. cp the SAMLSample.jar from <INSTALL_DIR>SUNWam/lib/ on the machine #1 to <INSTALL_DIR>/SUNWam/lib/ on the machine #2
  2. Deploy this sample to the web container where Access Manager is running in. For example, on Sun Web Server:
           Add <INSTALL_DIR>/SUNWam/lib/SAMLSample.jar to web server's
           server.xml file classpathsuffix
           Add <servlet> and <servlet-mapping> to file
           <WEB_SERVER_INSTALL_DIR>/https-<servername>/is-web-apps/services/WEB-INF/web.xml
    
              <servlet>
              <servlet-name>SAMLClientSample</servlet-name>
              <description>SAMLClientSample</description>
              <servlet-class>SAMLClientSample</servlet-class>
              </servlet>
              <servlet-mapping>
              <servlet-name>SAMLClientSample</servlet-name>
              <url-pattern>/SAMLClientSample</url-pattern>
              </servlet-mapping>
           
  3. Restart the Access Manager
  4. Login in to the Administration Console
    <machine #2 protocol>://<machine #2 host>:<machine #2 port>/amserver/UI/Login
  5. Click on "Federation" tab
  6. Click on "SAML" tab
  7. 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 ID value. This will be used in machine #1 setup.
  8. Click "Save" if you make any change or "Cancel" to go back to previous page.
  9. Click "New" under "Trusted Partners" to go to "Select trusted partner type and profile" page. Check "artifact" under "Source" and click "Next" to go to "Add New Trusted Partner" page. Set attributes like the following:
           Source ID: <machine #1 siteid>
           SOAP URL: <machine #1 protocol>://<machine #1 host>:<machine #1 port>/amserver/SAMLSOAPReceiver
    For example,
           Source ID: 6zLPS96EshDhTrDJddH5ZAa8yeQ=
           SOAP URL: http://machine#1.xyz.com:58080/amserver/SAMLSOAPReceiver
    If machine #1 protocol is https, check "SSL" under "Authentication Type"
  10. Click on "Finish"
  11. Click on "Save"
  12. Open a browser.
  13. Login into the Administration Console on machine #1 if has not logged in
  14. Invoke the servlet
           <machine #1 protocol>://<machine #1 host>:<machine #1 port>/
           <service_deploy_URI>/AssertionArtifactSample?
           target=<machine #2 protocol>://<machine #2 host>:<machine #2 port>/
           <service_deploy_URI>/SAMLClientSample
           &sourceid=<URLEncoded site id of machine #2>
           
    Note: machine #2 source id can be obtained from Administration Console. It should be URL Encoded before entering in the above URL. To URL encode the sourceid one can use the SAMLURLEncoder provided along with this sample as follows:
           java -classpath <INSTALL_DIR>/SUNWam/lib/SAMLSample.jar:<INSTALL_DIR>/SUNWam/lib/am_sdk.jar SAMLURLEncoder <sourceid>
           
    Also the query parameters target and sourceid are case sensitive, so TARGET or SOURCEID will not work. For instance:
           http://neuhome.red.iplanet.com:58080/amserver/AssertionArtifactSample?
           target=http://dsame.sun.com:58080/amserver/SAMLClientSample
           &sourceid=6zLPS96EshDhTrDJddH5ZAa8yeQ%3D
           
    You should see servlet response output (see the last section for example)


3. Instructions For Windows

Instructions to set up the sample servlets on Machine #1

  1. cd to <INSTALL_DIR>\samples\saml\client
  2. Edit the Makefile. Modify the environment variables. These environment variables will be used to run the make command.
           BASE - Set this Variable to install directory <INSTALL_DIR>
           CLASSPATH - Get this from the web container the Access Manager instance
              is running in.  For example, in Sun Web Server, use the value of
    	  classpathsuffix in <ws-INSTALL_DIR>\https-<servername>\config\server.xml.
           JAVA_HOME - Set this variable to your installation of JDK. It should be
              newer than JDK 1.3.1.
           BASE_CLASS_DIR - Directory where all the Sample compiled classes will
              be kept.
           JAR_DIR - Directory where the jar of the sample classes will be created.
           
  3. Run make
  4. Deploy this sample to the web container where Access Manager is running in. For example, on Sun Web Server:
           Add <INSTALL_DIR>\lib\SAMLSample.jar to web server's server.xml file
           classpathsuffix
           Add <servlet> and <servlet-mapping> to file
           <ws-INSTALL_DIR>\https-<servername>\is-web-apps\services\WEB-INF\web.xml.
           For example,
              <servlet>
              <servlet-name>AssertionArtifactSample</servlet-name>
              <description>AssertionArtifactSample</description>
              <servlet-class>AssertionartifactSample</servlet-class>
              </servlet>
              <servlet-mapping>
              <servlet-name>AssertionArtifactSample</servlet-name>
              <url-pattern>/AssertionArtifactSample</url-pattern>
              </servlet-mapping>
           
  5. Restart the Access Manager
  6. Login in to the Administrator Console
    http://<machine #1 host>:<machine #1 port>/amserver/UI/Login
  7. Click on "Federation" tab
  8. Click on "SAML" tab
  9. 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 ID value. It will be used in machine #2 setup.
  10. Click "Save" if you make any change or "Cancel" to go back to previous page.
  11. Click "New" under "Trusted Partners" to go to "Select trusted partner type and profile" page. Check "artifact" under "Destination" and click "Next" to go to "Add New Trusted Partner" page. Set attributes like the following:
           Source ID: <Site ID of machine #2>
           Target: <machine #2 host>:<machine #2 port>
           SAML URL: <machine #2 protocol>://<machine #2 host>:<machine #2 port>/amserver/SAMLAwareServlet
           Host List: <machine #2 host IP>
           
    For example,
           Source ID: 5SwAdEHiwXYg+Oho40ppcB+NLnM=
           Target: machine#2.abc.com:80
           SAML URL: http://machine#2.abc.com:80/amserver/SAMLAwareServlet
           Host List: 192.12.148.102
           
  12. Click on "Finish"
  13. Click on "Save"

Instructions to set up the sample servlets on Machine #2

  1. cp the SAMLSample.jar from <INSTALL_DIR>\lib on the machine #1 to <INSTALL_DIR>\lib on the machine #2.
  2. Deploy this sample to web container. For example, on Sun Web Server:
           Add <INSTALL_DIR>\lib\SAMLSample.jar to web server's server.xml
           file classpathsuffix
           Add <servlet> and <servlet-mapping> to file
           <ws-INSTALL_DIR>\https-<servername>\is-web-apps\services\WEB-INF\web.xml.
           
    For example,
           <servlet>
           <servlet-name>SAMLClientSample</servlet-name>
           <description>SAMLClientSample</description>
           <servlet-class>SAMLClientSample</servlet-class>
           </servlet>
           <servlet-mapping>
           <servlet-name>SAMLClientSample</servlet-name>
           <url-pattern>/SAMLClientSample</url-pattern>
           </servlet-mapping>
           
  3. Restart the Access Manager
  4. Login in to the Administration Console
           <machine #2 protocol>://<machine #2 host>:<machine #2 port>/amserver/UI/Login
           
  5. Click on "Federation" tab
  6. Click on "SAML" tab
  7. 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 ID value. This will be used in machine #1 setup.
  8. Click "Save" if you make any change or "Cancel" to go back to previous page.
  9. Click "New" under "Trusted Partners" to go to "Select trusted partner type and profile" page. Check "artifact" under "Source" and click "Next" to go to "Add New Trusted Partner" page. Set attributes like the following:
           Source ID: <machine #1 siteid>
           SOAP URL: <machine #1 protocol>://<machine #1 host>:<machine #1 port>/amserver/SAMLSOAPReceiver
    For example,
           Source ID: 6zLPS96EshDhTrDJddH5ZAa8yeQ=
           SOAP URL: http://machine#1.xyz.com:58080/amserver/SAMLSOAPReceiver
    If machine #1 protocol is https, check "SSL" under "Authentication Type"
  10. Click on "Finish"
  11. Click on "Save"
  12. Bring up a browser.
  13. Login into the Administration Console on machine #1 if has not logged in.
  14. Invoke the servlet
           <machine #1 protocol>://<machine #1 host>:<machine #1 port>/
           <service_deploy_URI>/AssertionArtifactSample?
           target=<machine #2 protocol>://<machine #2 host>:<
           machine #2 port>/<service_deploy_URI>/SAMLClientSample
           &sourceid=<URLEncoded site id of machine #2>
           
    Note: machine #2 source id can be obtained from Administration Console. It is in base64 encoded format. It should be URL encoded before entering in the above URL. To URL encode the sourceid, one can use the SAMLURLEncoder provided along with this sample as follows:
           java -classpath <INSTALL_DIR>\lib\SAMLSample.jar:<INSTALL_DIR>\lib\am_sdk.jar SAMLURLEncoder <sourceid>
           
    Also the query parameters target and sourceid are case sensitive, so TARGET or SOURCEID will not work. For instance:
           http://neuhome.red.iplanet.com:58080/amserver/AssertionArtifactSample?
           target=http://dsame.sun.com:58080/amserver/SAMLClientSample
           &sourceid=6zLPS96EshDhTrDJddH5ZAa8yeQ%3D
           
    You should see servlet response output (see the last section for example)


4. Servlet response output for Assertion Artifact

The Assertion related to AssertionArtifact AAE1U3dBZEVIaXdYWWcrT2hvNDBwcE5zTzYyUEgwUmt6WlNsOUFLL2gr:

    <saml:Assertion MajorVersion="1" MinorVersion="0"
    AssertionID="udue+oAHA8MPK3W3A4sHGpre6iM=" Issuer="wsun-unix.red.iplanet.com:58080"
    IssueInstant="2002-08-07T02:11:26Z" >
    <saml:Conditions NotBefore="2002-08-07T02:06:26Z" NotOnOrAfter="2002-08-07T02:13:26Z" >
    </saml:Conditions>
    <saml:AuthenticationStatement AuthenticationMethod="urn:sun.com:sunone:ims:LDAP"
    AuthenticationInstant="2002-08-07T01:42:01Z">
    <saml:Subject >
    <saml:NameIdentifier NameQualifier="dc=example,dc=com"
    >uid=amAdmin,ou=People,dc=example,dc=com</saml:NameIdentifier>
    <saml:SubjectConfirmation >
    <saml:ConfirmationMethod
    >urn:oasis:names:tc:SAML:1.0:cm:artifact-01</saml:ConfirmationMethod>
    </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:SubjectLocality IPAddress="192.18.120.114" /></saml:AuthenticationStatement>
    <saml:AttributeStatement >
    <saml:Subject >
    <saml:NameIdentifier NameQualifier="dc=example,dc=com"
    >uid=amAdmin,ou=People,dc=example,dc=com</saml:NameIdentifier>
    <saml:SubjectConfirmation >
    <saml:ConfirmationMethod
    >urn:oasis:names:tc:SAML:1.0:cm:artifact-01</saml:ConfirmationMethod>
    </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Attribute AttributeName="attName1" AttributeNamespace="attNamespace1">
    <saml:AttributeValue xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">first
    example of
    AttributeValue</saml:AttributeValue>
    </saml:Attribute>
    <saml:Attribute AttributeName="attName2" AttributeNamespace="attNamespace2">
    <saml:AttributeValue
    xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"><Name>Oasis</Name></saml:AttributeValue>
    </saml:Attribute>
    </saml:AttributeStatement>
    </saml:Assertion>
    


End of Sample