Home | PDF | API | FAQ | Search | Feedback | History

SAML Sample Application

The samlinterop sample application demonstrates support for OASIS WSS SAML Token Profile 1.0 in XWS-Security. Security Assertion Markup Language (SAML) assertions are used as security tokens. SAML provides a means by which security assertions about messages can be exchanged between communicating service endpoints. SAML is also considered important for promoting interoperable Single-Sign-On (SSO) and Federated Identity. This release, JWSDP 1.6, adds partial support for SAML Token Profile 1.0.

This sample application was used as Sun's entry in a virtual interoperability demonstration sponsored by OASIS. This sample implements three out of the four interop scenarios required by the event and described in the WSS SAML Interop Scenarios document. The scenarios addressed in this interop are described in SAML Interop Scenarios. Read more about the SAML interop scenarios at the following URL: http://www.oasis-open.org/apps/org/workgroup/wss/download.php/7011/wss-saml-interop1-draft-11.doc.

The application prints out both the client and server request and response SOAP messages. The output from the server may be viewed in the appropriate container's log file. The output from the client is sent to stdout or whichever stream is used by the configured log handler. Messages are logged at the INFO level.

In this example, server-side code is found in the /swainterop/server/src/swainterop/ directory. Client-side code is found in the /swainterop/client/src/swainterop/ directory. The asant (or ant) targets build objects under the /build/server/ and /build/client/ directories.

SAML Interop Scenarios

All four SAML interop scenarios invoke the same, simple application. The Requester sends a Ping element with a value of a string. The value of the string should be the name of the organization that has developed the software and the number of the scenario, e.g. "Sun Microsystems - Scenario #1". The Responder returns a PingResponse element with a value of the same string. These scenarios use the Request/Response Message Exchange Pattern (MEP) with no intermediaries. All scenarios use SAML v1.1 Assertions.

To validate and process an assertion, the receiver needs to establish the relationship between the subject of each SAML subject statement and the entity providing the evidence to satisfy the confirmation method defined for the statements. The two methods for establishing this correspondence are Holder-of-Key (HOV) and Sender-Vouches (SV). For more information on these confirmation methods, read SAML Token Profile 1.0.

The following is a summary of each of the SAML interop scenarios.

Scenario #1 - Sender-Vouches: Unsigned

The request contains a minimal sender-vouches SAML assertion with no optional elements included. There are no signatures or certificates required. The response does not contain a security header.

In this scenario, there is no technical basis for trust because the messages are sent in the clear with no content or channel protection. This scenario is intended only to demonstrate message structure interoperability and is not intended for production use.

Scenario #2 - Sender-Vouches: Unsigned: SSL (sample not provided)

The request contains a sender-vouches SAML assertion. There are no signatures required. This scenario is tested over SSL, and certificates are required to support SSL at the transport layer. The response does not contain a security header.

In this scenario, the basis of trust is the Requester's client certificate used to establish the SSL link. The Responder relies on the Requester who vouches for the contents of the User message and the SAML Assertion.

This scenario is not demonstrated in this sample application.

Scenario #3 - Sender-Vouches: Signed

The request contains a sender-vouches SAML assertion. The Assertion and the Body elements are signed. A reference to the certificate used to verify the signature is provided in the header. The response does not contain a security header.

In this scenario, the basis of trust is the Requester's certificate. The Requester's private key is used to sign both the SAML Assertion and the message Body. The Responder relies on the Requester, who vouches for the contents of the User message and the SAML Assertion.

Scenario #4 - Holder-of-Key

The request contains a holder-of-key SAML assertion. The assertion is signed by the assertion issuer with an enveloped signature. The certificate used to verify the issuer signature is contained within the assertion signature. The message body is signed by the Requester. The certificate used to verify the Requester's signature is contained in the assertion SubjectConfirmation. The response does not contain a security header.

In this scenario, the basis of trust is the Assertion Issuer's certificate. The Assertion Issuer's private key is used to sign the SAML Assertion for the User. The Responder relies on the Assertion Issuer to have issued the assertion to an authorized User.

SAML Interop Sample Configuration Files

The following sections provide the example configuration files for SAML interop scenarios 1, 3, and 4:

Sender-Vouches Sample Configuration Files
Holder-Of-Key Sample Configuration Files

Sender-Vouches Sample Configuration Files

The security configuration pair sv-saml-client3.xml and sv-saml-server3.xml enable the following tasks, as required by Scenario #3:

Client contains a sender-vouches SAML assertion.
Client signs the assertion and the body elements.
Client includes a reference to the certificate used to verify the signature in the header.
Client sends the request body.
Server verifies that a SAML assertion is received.
Server verifies the signature.
Server sends the response, which does not contain a security header.

The sv-saml-client3.xml file looks like this:

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">
    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:SAMLAssertion type="SV" strId="SV-123"/>
            <xwss:Sign includeTimestamp="false">
                <xwss:X509Token certificateAlias="xws-security-
client"/>
                <xwss:Target type="qname">
                      {http://schemas.xmlsoap.org/soap/
envelope/}Body
                </xwss:Target>
                <xwss:SignatureTarget type="uri" value="SV-123">
                    <xwss:Transform algorithm="http://docs.oasis-
open.org/wss/2004/01/
                          oasis-200401-wss-soap-message-
security-1.0#STR-Transform">
                        <xwss:AlgorithmParameter 
name="CanonicalizationMethod" 
                             value="http://www.w3.org/2001/10/
xml-exc-c14n#"/>
                    </xwss:Transform>
                </xwss:SignatureTarget>
            </xwss:Sign>
            <xwss:Timestamp />
        </xwss:SecurityConfiguration>
   </xwss:Service>
    <xwss:SecurityEnvironmentHandler>
        sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>
</xwss:JAXRPCSecurity> 

The sv-saml-server3.xml file looks like this:

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">
    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
         <xwss:RequireTimestamp />
         <xwss:RequireSAMLAssertion type="SV"/>
         <xwss:RequireSignature requireTimestamp="false">
         <xwss:X509Token />
         <xwss:Target type="qname">
               {http://schemas.xmlsoap.org/soap/envelope/}Body
         </xwss:Target>
         <xwss:SignatureTarget type="uri" value="SV-123"/>
        </xwss:RequireSignature>
        </xwss:SecurityConfiguration>
   </xwss:Service>
    <xwss:SecurityEnvironmentHandler>
        sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>
</xwss:JAXRPCSecurity> 

The other security configuration files in the /samlinterop/config/ directory that contain a sender-vouches type of assertion are those in support of Scenario #1, the sv-saml-client.xml and sv-saml-server.xml pair.

Holder-Of-Key Sample Configuration Files

The security configuration pair hok-saml-client.xml and hok-saml-server.xml enable the following tasks, as required by Scenario #4:

Client contains a holder-of-key SAML assertion.
Client has the assertion signed by the assertion issuer with an enveloped signature.
Client includes the certificate used to verify the issuer signature in the assertion signature.
Client signs the request body.
Server verifies that a SAML assertion is received.
Server verifies the signature.
Server sends the response, which does not contain a security header.

The hok-saml-client.xml file looks like this:

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">
    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
            <xwss:Sign includeTimestamp="false">
                <xwss:SAMLAssertion type="HOK"/>
                <xwss:Target type="qname">
                     {http://schemas.xmlsoap.org/soap/
envelope/}Body
                </xwss:Target>
            </xwss:Sign>
            <xwss:Timestamp />
        </xwss:SecurityConfiguration>
   </xwss:Service>
    <xwss:SecurityEnvironmentHandler>
        sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>
</xwss:JAXRPCSecurity> 

The hok-saml-server.xml file looks like this:

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">
    <xwss:Service>
        <xwss:SecurityConfiguration dumpMessages="true">
         <xwss:RequireTimestamp />
         <xwss:RequireSignature requireTimestamp="false">
         <xwss:SAMLAssertion type="HOK"/>
         <xwss:Target type="qname">
             {http://schemas.xmlsoap.org/soap/envelope/}Body
          </xwss:Target>
        </xwss:RequireSignature>
        </xwss:SecurityConfiguration>
   </xwss:Service>
    <xwss:SecurityEnvironmentHandler>
        sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>
</xwss:JAXRPCSecurity> 

Running the SAML Interop Sample

To run the samlinterop sample application, follow these steps:

Complete the tasks defined in the following sections of this addendum:
Setting System Properties
Configuring a JCE Provider
Setting Build Properties
Start the selected container and make sure the server is running. To start the Application Server,
From a Unix machine, enter the following command from a terminal window: asadmin start-domain domain1
From a Windows machine, choose StartProgramsSun MicrosystemsJ2EE 1.4Start Default Server.
Modify the build.properties file to set up the security configuration that you want to run for the client and/or server. To do this, remove the comment character (#) from beside the client and server configuration pair to be used, and make sure the other security configuration files have the comment character beside them. See SAML Interop Sample Configuration Files for more information on the security configurations options defined for this sample application.
Build and run the application from a terminal window or command prompt.
On the Application Server, the command to build and run the application is: asant run-sample
On the other containers, the command to build and run the application is: ant run-sample

---

Note: To run the sample against a remote server containing the deployed endpoint, use the run-remote-sample target in place of the run-sample target. In this situation, make sure that the endpoint.host, endpoint.port, http.proxyHost, http.proxyPort, and service.url properties are set correctly in the build.properties file (as discussed in Setting Build Properties) before running the sample.

---

If the application runs successfully, you will see a message similar to the following:

[echo] Running the client program....
     [java] ==== Sending Message Start ====
     ...
     [java] ==== Sending Message End ====
     [java] ==== Received Message Start ====
     ...
     [java] ==== Received Message End ====
     [java] Hello to Duke!  

You can view similar messages in the server logs:

<SJSAS_HOME>/domains/<domain-name>/logs/server.log 
<TOMCAT_HOME>/logs/launcher.server.log 
<SJSWS_HOME>/<Virtual-Server-Dir>/logs/errors  

All of the material in The Java(TM) Web Services Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.