Single Sign On between WebLogic Server 9.2 and IIS using SAML

Implementing single sign on (SSO) for several sites is a problem that has a multitude of variations and quite a few solutions.  Security Assertion Markup Language (SAML) has emerged in the last five years to address this problem in a standard way, and BEA WebLogic Server 9 offers extensive support for it. Unfortunately, simple SAML configuration examples, especially for cross-platform scenarios, are hard to come by.

This tutorial describes a simple SAML SSO scenario between Microsoft Internet Information Services Server (IIS) and BEA WebLogic Server 9. The article assumes some knowledge of SAML and is accompanied by a fully functional example that includes ASP.NET code as well as a script to fully configure WebLogic Server.

Introduction

Recently, I did some work for a customer who decided to add WebLogic Portal 9 into a predominantly ASP.NET Web infrastructure. The old and new sites had to coexist as seamlessly as possible, and single sign on was a must.

In the past, that would have meant a lot of work—probably writing another clunky security provider. Luckily, WebLogic Server 9 offers SAML support out of the box.

SAML is an XML-based standard for communicating user authentication, entitlement, and attribute information. Harold Lockhart, in his article Demystifying SAML, and Beth Linker, in her Introduction to SAML, provide a good introduction to this technology.

Unlike WebLogic Server 9, IIS does not provide SAML support out of the box. For simple scenarios, handcrafting SAML assertions is fairly easy, and that is what I have done. In more complicated cases, try using Web Services Enhancements (WSE).

Solution

My customer had a solidly functioning IIS authentication solution that I decided to reuse. The .NET side was going to maintain responsibility for authentication and to produce SAML assertions for WebLogic Server to consume. The network setup made direct communication between the two servers impossible, leaving the POST SAML profile as the only option.

Figure 1. SAML-protected resource access sequence

Figure 1 depicts the POST SAML profile applied to my scenario. In SAML terminology, WebLogic Server is a resource provider, and IIS is the identity assertion provider.

We have a protected WebLogic Server application that a browser is attempting to access. Only the user weblogic is allowed to view this resource, http://localhost:7001/protected/secret.jsp. When accessed, we want IIS to expose a page that validates the user's identity and creates SAML assertions at http://localhost/SAMLdotNet/Login.aspx.

With this in mind, let's look at the typical security flow described in Figure 1:

1. The browser sends a GET /protected/secret.jsp to WebLogic Server.
2. WebLogic Server responds with "HTTP/1.1 302 Moved Temporarily," and redirects the browser to  http://localhost/SAMLdotNet/Login.aspx?RPID=rp_00001&APID=ap_00001&TARGET=//localhost:7001/protected/secret.jsp. The resource provider ID (RPID) identifies the protected resource provider. It is used by the assertion provider to distinguish between potential multiple resource providers it generates assertions for.  This ID allows IIS to return control to the WebLogic Server that requested the assertion and not to another system. The assertion party ID (APID) identifies the assertion party in the same way in which the RPID identifies the resource provider. WebLogic Server needs to know which assertion party created a particular assertion to properly validate it.
3. The browser sends a GET /SAMLdotNet/Login.aspx?RPID=rp_00001&APID=ap_00001&TARGET=//localhost:7001/protected/secret.jsp to IIS.
4. Login.aspx validates the user’s identity and generates a SAML assertion.
5. A form containing this newly generated assertion is returned to the browser.
6. The form received from IIS is posted to WebLogic Server at http://localhost:7001/samlacs/acs. The server is configured to perform SAML Identity assertions at this URL.
7. WebLogic Server validates the assertion and forwards the request to /protected/secret.jsp if successful.
8. The result is returned to the browser.

The rest of this tutorial describes how this result was accomplished.

Protecting a Web Application

The first step on the way to using SAML assertions is securing the protected Web application. This sample Web application is included in the example. There is nothing new here: The <security-constraint> XML tag and its association with a security role are configured in web.xml. The weblogic.xml configuration file defines how roles map to principals.

Protecting the application here simply means applying standard Java EE security constraints.

Key Pair

To establish trust between WebLogic Server and IIS you have to generate an asymmetric key pair and load these keys into the WebLogic Server and Windows key stores. For your convenience, a pair of keys is attached to this tutorial: saml_dsa.pfx contains a private key, and saml_dsa.cer contains its matching certificate.

You have to do two things to allow your ASP.NET application to use the private key:

1. The private key has to be loaded into the Windows key store. To do this, perform the following steps:
   1. Double-click LocalMachineKeyStore.msc.
   2. In the tree on your left, expand Certificates\Personal\Certificates.
   3. Right-click Certificates, and then, in All tasks, select Import.
   4. Click Next.
   5. Change file type to "Personal Information Exchange," and then select saml_dsa.pfx.
   6. Click Next.
   7. Do not enter a password; just click Next.
   8. Click Finish.

   User "ASPNET," that owns the ASP.NET process under IIS has to be granted privileges to access the private key. This can be done using the following command: winhttpcertcfg -g -c LOCAL_MACHINE\My -s "saml_dsa" -a ASPNET. This utility can be downloaded here.

2. The client certificate has to be loaded into WebLogic Server. This is done automatically by the WLST script setup_script.py. Postpone running this script until the next section.
3. This key pair will be used to verify the authenticity of assertions. IIS will sign produced assertions using the private key. WebLogic Server will use the certificate to validate the signature of IIS.

Configuring WebLogic Server

All of the steps required to configure WebLogic Server to use SAML for the purposes of this example are automated by the included WLST script: setup_script.py. Before going further, run wlst setup_script.py. This will create a SAML-enabled WebLogic Server domain. Start the resulting administration server and go to the console to observe how it is configured. No manual configuration steps are required.

To enable SAML, this script configures two major components: SAML Identity Asserter and SAML Destination Site

SAML Identity Asserter

The SAML Identity Asserter can be found in the administration console under Security Realms\myrealm\Providers. It is an authentication provider of type SAMLIdentityAsserterV2. All of its important properties are located under the Management tab, which has two sub tabs: Certificates and Assertion Parties.

The signature verification certificate is loaded under the Certificates tab.

The Assertion Parties tab is used to configure the assertion parties. In this example only one item was configured. It corresponds to IIS, the only partner of this site. Note the following properties of the assertion party:

The POST Signing Certificate Alias property is used during SAML Response signature validation. It references the certificate loaded through the Certificates tab. Without it there is no way to tell whether a message delivered from the partner has been tampered with.

The Source Site Redirect URIs property defines a list of URIs that trigger the SAML assertion sequence when someone tries to access them (Diagram 1, Step 2).

The Source Site ITS URL property defines the URL that has to be called on the partner's side. The request to this URL will contain the TARGET parameter and additional parameters defined in the Source Site ITS Parameters property. The TARGET parameter specifies the URI that the user is trying to access ( /protected/secret.jsp, in this example).

The Source Site ITS Parameters property identifies additional parameters that are passed during the call to the Source Site ITS URL. In this case, RPID=rp_00001 and APID=ap_00001 are specified.

RPID is used to indicate the party that initiated the assertion sequence. IIS uses this parameter to figure out what URL to use for the callback in Step 6 of the assertion sequence (Diagram 1). APID contains the assertion party ID by which WebLogic Server knows IIS. This parameter must be sent to WebLogic Server for the assertion to succeed.

The Issuer URI property is one of the components used to validate an assertion. It has to match the Issuer URI in the assertion XML.

Generally, all users trying to get access to protected resources not only have to have a valid assertion but they also have to "be known" to WebLogic Server. At least one of the authenticators has to be able to authenticate the user. Enabling the Allow Virtual Users property allows users "unknown" to WebLogic Server to get access to protected resources provided a valid assertion is present. This feature works in tandem with SAML Authenticator that has to be created for this approach to work. No configuration parameters are available for it.

SAML Destination Site

To make sure that there is a servlet waiting for SAML responses, a SAML Destination Site had to be configured. This configuration can be observed through the WebLogic Server console under Environment/Servers/<Server Name>/Federation Services/SAML 1.1 Destination Site.

The Assertion Consumer URIs property tells WebLogic Server which URIs to listen on for SAML responses. In this example, the default /samlacs/acs is used. A browser will post an assertion form to this URI (see Figure 1, Step 6).

The ACS requires SSL property can be enabled to avoid the risk of SAML assertion interceptions. In this example, it is turned off for simplicity. If you want to turn it on, you need to configure WebLogic Server to listen on the SSL port and make sure IIS performs callbacks using HTTPS, rather than HTTP.

This was not too hard, was it? I did not have to modify the application at all to support SAML. All required work was done by WebLogic Server configuration changes. If you wanted to slap SAML on top of your existing systems, you could do it without touching deployed applications.

Creating Assertions in .NET

For the purposes of this example, two .NET components were created.

Login.aspx receives assertion requests and generates forms with assertions created in response to those requests. SAMLAssertionCreator.cs encapsulates the assertion creation logic.

Example 1 shows a real SAML response generated by this ASP.NET application. It contains one assertion with an authentication statement. This assertion states that it has been issued on Nov 16, 2006 at 8:57 AM by https://aspsite.com and is valid between 8:57AM and 8:58AM. It confirms that the user weblogic was authenticated using password authentication.

<samlp:Response


   xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"

   MajorVersion="1" MinorVersion="1" 

   ResponseID="b8049e0c9e99f6a270ac05ad70f7384d" 

   IssueInstant="2006-11-16T18:57:59.59Z" 

   Recipient="//localhost:7001/samlacs/acs">

  <samlp:Status>

    <samlp:StatusCode Value="samlp:Success"/>

  </samlp:Status>

  <saml:Assertion 

     xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" 

     AssertionID="ccde3775286167a3bd1c9f5dec4f153a" 

     IssueInstant="2006-11-16T18:57:59.59Z" 

     Issuer="https://aspsite.com" 

     MajorVersion="1" MinorVersion="1">

    <saml:Conditions 

      NotBefore="2006-11-16T18:57:59.59Z" 

      NotOnOrAfter="2006-11-16T18:58:59.59Z"/>

      <saml:AuthenticationStatement 

        AuthenticationInstant="2006-11-16T18:57:59.59Z" 

        AuthenticationMethod=

         "urn:oasis:names:tc:SAML:1.0:am:password">

        <saml:Subject>

          <saml:NameIdentifier>weblogic</saml:NameIdentifier>

          <saml:SubjectConfirmation>

            <saml:ConfirmationMethod>

                urn:oasis:names:tc:SAML:1.0:cm:bearer

            </saml:ConfirmationMethod>

          </saml:SubjectConfirmation>

        </saml:Subject>

      </saml:AuthenticationStatement>

   </saml:Assertion>

</samlp:Response>

While I don't intend to provide a detailed explanation of SAML message structure, two key points need to be highlighted:

• It is not a coincidence that the SAML assertion issuer matches the Issuer URI specified in the WebLogic Server assertion party configuration. If they did not match, the assertion validation would fail.
• The NotBefore and especially the NotOnOrAfter assertion conditions are extremely important. They effectively specify an expiration date, therefore limiting the use of intercepted assertions. If IIS and WebLogic Server are running on separate physical machines, it is important to make sure their times are synchronized and their time zones are set correctly.

Once the assertion is created, it has to be put into a form and returned to the client. Three fields get populated, as shown in Example 2:

1. The TARGET field in this form contains the URI of the protected resource. It is received by IIS as part of the redirect from WebLogic Server.
2. The SAMLResponse field contains a base64-encoded SAML response.
3. The APID field contains the assertion party identifier associated with IIS.

The form gets automatically submitted to the WebLogic Server URL (stored in redirectURL in this example), configured in the WebLogic Federation Service tab. In this case, it is http://localhost:7001/samlacs/acs.

<%


saml.SAMLAssertionCreator assertionCreator = new saml.SAMLAssertionCreator();

/*

 * For purposes of this example, no authentication is performed at any level.

 * In a real scenario this HAS TO BE FIXED. 

 * 

 */

String assertionResponse = 

      assertionCreator.createAssertion("weblogic",

                                       "https://oldsite.com", 

                                       redirectURL, 

                                       "saml_dsa");

String base64 =Convert.ToBase64String(

                       Encoding.UTF8.GetBytes(assertionResponse))

%>      

      <form name="GoToWLS" 

            action="<%=redirectURL%>" 

            method="post">

        <input type="hidden" name="TARGET" 

               value="<%=target%>" />

        <input type="hidden" name="SAMLResponse" 

               value="<%=base64%>"/>

        <input type="hidden" name="APID" 

               value="<%=apid%>" />

        >                        

    </form>

    <SCRIPT language="JavaScript">

      document.GoToWLS.submit()

    </SCRIPT>

Configuring Internet Information Services

To configure IIS Server, use the Administrative Tools in your Windows Control Panel. Assuming that IIS has already been installed and the private key has been imported and is ready for use, you need to perform only three steps:

1. Make sure that IIS runs on port 80 as shown in Figure 2.

2. 

   Figure 2. IIS Web site configuration

3. Configure the SAMLdotNet Virtual Directory to point to the location of the SAMLdotNet application, as shown in Figure 3.

4. 

   Figure 3. Virtual Directory configuration steps

Trying It Out

Assuming your WebLogic Server is running locally on port 7001, go to http://localhost:7001/protected/secret.jsp. You will see your principal name, which should be weblogic. For the purposes of this example, your credentials do not get validated; ASP just creates an assertion for the user, signs it, and passes it back. Obviously, this approach is not sufficient for secure environments.

Download

• Sample code and configuration for this tutorial

Summary

WebLogic Server 9 makes single sign on implementation fairly simple. Once you are comfortable configuring a SAML security provider, the thought of creating a custom security solution when SAML is an option will never cross your mind. SAML provides a standard and extensible way of implementing single sign on, which makes it a perfect fit for deploying cross-platform solutions.

Alex Rykov has built his career as a software architect and engineer in several software and consulting companies. He has over a decade experience designing, building and deploying complex distributed systems.