Page Comparison

Overview

The library was envisioned as a utility that makes the use of delegated SAML authentication easy for portlet developers. SAML designers realized that the authentication, attribute release, and federation of authentication services is very complex. That's why they have promoted the use of authentication and attribute release as "layers" removed from the Web application developers and administered by dedicated security experts.

...

The reader does not have to be an expert in any of these but should understand the concepts. The writer is not an expert in most of these, either.

Design

Background

There are myriad of ways that developers can write portlets. From the low-level servlet-like programming to rich Model-View-Controller (MVC) frameworks, portal developers can choose complexity vs. efficiency or performance vs. size to sample just a few of the choices available to portlet developers.

...

Recognizing that portlet developers may use this library to access a Web service, from RESTful, through SOAP to simple HTML, the design of the library concentrated on performing authentication and then relaying on the underlying transport to maintain a secure session with the Web Service Provider (WSP). Apache Commons HTTP Client supports "stateful" Web sessions much like browsers do, and the library makes such a session available to the portlet and steps out of the way.

XML Processing

SAML messages are complex XML documents using a multitude of namespaces. The library discussed here is mostly a proxy passing these messages to work within the SAML 2 Enhanced Client or Proxy (ECP) profile. To keep the XML processing efficient and keeping in mind the need to preserve the SAML assertions' integrity, the XML processing in the library relies on DOM and XPath. SAML assertions are digitally signed and even the most innocuous changes would break the assertions' digital signatures.

...

The DOM tree of each processed message is not kept. The only exception is the SAML assertion DOM because it is needed in several places.

Delegated SAML Authentication

To accomplish delegated SAML authentication, there are several interactions that all the involved players (user, IdP, portal, portal's SP, portlet, WSP) must perform. These interactions are best illustrated in this diagram from the Shibboleth Web site.

...

Steps 9-14 are initiated by the portlet, but most of the work is performed on portlet's behalf in the library documented here.

Security

The security of the SAML assertion is protected by all involved parties. Its integrity is protected with digital signatures, and the IdP signs the assertion using its private key. The portal's SP and the WSP examine the digital signature when receiving the assertion. The library retrieves elements from the SAML assertion, but it cannot modify anything within the assertion, as that would invalidate the assertion's digital signature. The portlet should treat the assertion the same way. It may be authorized to examine the contents of the assertion, but it may not modify it in any way.

...

The library also supports server authentication. Either the IdP or the WSP can be authenticated using a TrustStore, which is basically a standard Java KeyStore containing server certificates to trust. Obviously, different TrustStores can be used for IdP and WSP authentication. The portal's SP may also convey the IdP public key to the portal and the portlet. This public key may be used to authenticate the IdP, and in this case the library does not examine the IdP's certificate(s) but only the public keys within the IdP's X.509 certificate(s).

Installation

Overview

This library uses Maven for building and installation. A portlet developer in a need to retrieve resources from a SAML-protected Web Service will need to perform two steps to take advantage of this library:

1. Build the library from sources to make it available as a local Maven resource
2. Add the library to the developer's portlet project, presumably a Maven project itself

Building the Library

The library is built using Maven. In the future the library may be published to a public Maven repository, and this step will not be necessary. As of this writing, however, this is not available.

...

mvn javadoc:javadoc

Adding the Library to a Portlet Project

To add this library to a Maven portlet project, a developer must add the following dependency to the portlet's pom.xml file:

...

The names used in this dependency element match the names used in the library's own pom.xml and this matching is what allows Maven to locate the library in the local Maven repository.

Usage

Introduction

The reason this library exists is to facilitate delegated SAML authentication for portlets that act on behalf of the logged on user. It is not the library's responsibility, nor was it its requirement, to retrieve any resources from the SAML-protected WSP. The library uses Apache HttpClient component. The only difference from using HttpClient directly is that instead of creating an instance of HttpClient, a developer obtains it from the library. The initial testing of this library was performed with only HTTP GET as the initial request to retrieve a protected resource. This is because that was the only method that would handle SAML authentication "as-needed." Support to preserve HTTP POST form post elements was recently added to the Shibboleth SP, but this will need to be tested in the future.

...

• This resource in the initial HTTP GET can exist only for the purpose of completing authentication, and it could be ignored by the portlet.
• Upon successful authentication, the portlet may use the Apache Commons HTTP Client API and will not be limited to HTTP GET.

Simple Example

With SAML assertion and resource URL available, the portlet is ready to start a delegated SAML authentication session. It first creates a new copy of the SAMLSession class and passes the SAML assertion as the constructor parameter. From the instance of SAMLSession, the portlet obtains an instance of HttpClient and uses the API of the Apache HttpClient from then on.

...

In this simplest of examples, assuming that SAML protects a RESTful Web Service, at the end of this sequence the portlet may call resource.getResource(), which will return a String representation of what came back from the WSP. Since the data encapsulating classes are stateful, SAMLSession and Resource should not be considered thread-safe.

IdP Resolution

While the example above shows how the WSP is identified with the resource URL, it would be a valid question to ask how the library locates the IdP. After all, only an IdP may issue an assertion that is suitable for the WSP. While it would be possible to require that the portlet identify the IdP, it should not be necessary. Not in all cases, anyway.

...

"EPR" in IdPEPRResolver stands for End Point Reference. The implementation of this interface delivered with this library assumes that Shibboleth IdP was used to issue the SAML assertion, and Shibboleth IdP includes an EPR in the assertions it issues. When working with other SAML IdP, portlet developers should write their own implementation of the above interface and set it with a authnState.setIdpResolver method call. SAMLSession defaults to using the included implementation, so at installations using Shibboleth IdP there is no need to instantiate or sent the IdP resolver in the SAMLSession object.

Reusing SAMLSession

SAMLSession encapsulates a great deal of properties. Most of them may not even be useful to portlet developers, but many are. One of the properties is the HttpClient instance that can be reused for "stateful" communications with the WSP. HttpClient from Apache Commons has the default behavior like that of a browser. This means that once a client is set up, it will continue operating in a "stateful" way, including sending cookies that were previously set by the server. These cookies may represent the SAML session and some sort of WSP-specific session. Maintaining these sessions is critical to efficiently communicating with the WSP and not performing authentications unnecessarily.

To reuse the stateful HttpClient, a portlet developer needs to make sure to use the samlSession.getHttpClient method.

Authenticating the IdP

While the library does not enforce it, communicating with the IdP should always be performed over a secure connection, most commonly utilizing TLS. In addition to encrypting all of the information between the IdP and its client, TLS also supports methods of authenticating the server. This can go a long way to assuring that there client, in this case the delegated SAML authentication library, is not a victim of a man-in-the-middle attack. The library supports two different methods of authenticating the IdP:

...

At this time the library only supports a single public key to trust. Internally, the library decodes the key, retrieves all the X.509 certificates presented by the IdP, and looks for a matching public key in one of those certificates. A secure connection to the IdP will only be allowed if a matching public key is found.

Authenticating to the IdP

Just as the IdP client needs to authenticate the IdP it is about to communicate with, the IdP may want to restrict the clients authorized to obtain delegated SAML authentication. This is supported by the library, and it also uses TLS as the means of IdP client authentication. The IdP authenticates its clients by examining the client X.509 certificate. By presenting to the TLS/SSL layer a certificate and private key, the client's certificate with the public key is presented to the IdP. Since, as far as the IdP is concerned, the library/portlet/portal are synonymous with their corresponding SP, the library must use the SP's certificate and private key. There are two methods by which a portlet developer may convey the private key and certificate to the TLS layer:

...

The library will use the keys and/or certificates in its communications with the IdP.

Authenticating the WSP

Just as with the IdP, communications with the WSP may need to be secured using TLS. The WSP will present its certificate to the client, and the client must trust the certificate to allow the connection to proceed. The default behavior is to trust servers whose X.509 certificates have been signed by a recognized CA. Institutions wishing to issue their own certificates, either signed by their own CA or even self-signed certificates, may override the default behavior of Java and Apache HTTP Client. This can be done by providing an alternate TrustStore for communications with the WSP. The following call specifies the TrustStore to use:

...

where trustStore is a file name of a Java KeyStore containing certificates to trust and trustStorePass is the password that was used to secure the KeyStore. The TrustStore may contain certificates of CA, if the WSP has a CA-signed certificate or a certificate of the WSP, if the WSP uses a self-signed certificate. Please note that with this authentication the use of the Resource class becomes a requirement. The Resource class encapsulates the state specific to the WSP, while SAMLSession's state is IdP-specific.

Authenticating to the WSP

As with the IdP, the WSP may require a client TLS certificate to authenticate and trust its clients. The library supports that with TLS client certificates. This is virtually identical to the TLS client certificates that can be presented to the IdP, so rather than repeat that section verbosely, here are the two different method calls to convey the client certificate location to the library:

...

resource = new Resource();
resource.setResourceUrl(url);  //obtained elsewhere
resource.setWSPClientPrivateKeyAndCert (pkFile, certFile);  //one of the methods to authenticate the client to the WSP
resource.setupWSPClientConnection(samlSession);  // This looks for "https" in the Resource URL and the optional port number to use
HttpClient client = samlSession.getHttpClient();

Error Handling

This library acts as a part of security infrastructure. It normally works "behind the scenes" as a communication conduit between the portal, portlet, WSP, and IdP. The errors encountered and produced by this library will virtually always be of "infrastructural" nature, and neither the portlet nor portlet's user will be able to do much to correct them. For example, the portlet may be misconfigured, the IdP may be down, or the portal may keep its session active even after the SAML session has expired. Because of this, the portlet sets all of its error conditions using a runtime exception, DelegatedAuthenticationRuntimeException. This means that no explicit error handling is required to handle this exception. The portlet container will catch these exceptions and deal with them in its own standard manner.

...