Federated Portals Guide

Establishing WSRP Security with SAML

This chapter discusses how to configure the security realms of WebLogic Portal producers and consumers running in different domains. In the first part of this chapter, we explain the configuration that is required when both the producer and consumer are running in WebLogic Portal version 9.2 or later domains. In the second part of this chapter, the case of mixed domains is discussed, where the producer and consumer can be running in either WebLogic Portal 8.1x or 9.2 or later domains.

This chapter includes the following sections:

SAML Security Between WebLogic Portal Domains

This section explains the procedure for configuring WSRP security using custom SAML tokens when the producer and consumer are running in different WebLogic Portal version 9.2 or later domains. Use the procedure described in this section to configure security on production systems where custom SAML tokens are required.

This section includes these topics:

Overview

In a typical scenario, consumer and producer applications are running in separate WebLogic Portal 9.2 or later domains, as shown in Figure 15-1.

By default, WebLogic Portal specifies SAML as the default security token type for WSRP. If you are running in a demonstration or development environment, no further configuration is required. However, for a production environment it is recommended that you perform the SAML configuration described in this section.

Setting Up the SAML Configuration Example

This section describes an example federated portal application where the producer and consumer are running in different WebLogic Portal 9.2 or later domains. This example provides a basis for discussing how to configure SAML security between these domains.

The portal shown in Figure 15-2 includes a local portlet on the left and a remote (proxy) portlet on the right. The local portlet is a login portlet. When a user logs in successfully, the producer portlet displays the user’s name. As you will see, however, unless SAML security is properly configured, an error results when a user logs in to the portal.

As you can see in Figure 15-2, the proxy portlet renders without error before a user logs in. It isn’t until a user attempts to log in that a SAML message is sent, resulting in an error.

Checkpoint: This section described an example federated portal where the consumer and producer are running in separate WebLogic Portal domains. In the following sections, we explain how to configure the consumer and producer so that the SAML token sent from the consumer is accepted by the producer.

Configuring the Consumer

To correct the error shown in the previous section, you need to configure both the consumer and the producer. This section discusses the consumer configuration.

Generate a Key

This section explains how to generate a key on the consumer using the keytool utility, a Java utility distributed by Sun Microsystems that manages private keys and certificates. For detailed information on keytool, refer to the Sun Microsystems website.

Export the Key

Export the key from the consumer server. In the same command window that you used to generate the key, in the same directory, run the keytool command with the -export option, as shown in Figure 15-4. For example, the following command generates a key file called testalias.der.

keytool -export -keypass testkeypass -keystore DemoIdentity.jks -storepass DemoIdentityKeyStorePassPhrase -alias testalias -file testalias.der

Modify the Consumer’s Security Realm

This section explains the procedure for configuring the consumer to use the key that you generated.

Checkpoint: At this point, the SAML credential mapper provider on the consumer is configured to use the keystore you generated. If you were to try to log in to the login portlet, you would receive an error, as shown in Figure 15-15. This is because the producer does not yet recognize the new key sent from the consumer. In the next steps, you will configure the producer to accept the key sent from the consumer.

Configuring the Producer

This section explains how to configure the producer. To do this, you import the certificate into the SAML asserter, and configure the asserting party properties.

Import the Certificate

Configure the Asserting Party Properties

Testing the Configuration

SAML Security Between WebLogic Portal 8.1x and 9.2 or Later Versions

Producer and consumer applications developed with WebLogic Portal 9.2 or later versions are compatible with producers and consumers developed with WebLogic Portal 8.1x. That is, a portal developed with WebLogic Portal 9.2 or later versions can consume portlets deployed in a WebLogic Portal 8.1x domain. Similarly, portlets exposed in a WebLogic Portal 9.2 or later producer can be consumed by an 8.1x consumer. These two use cases are summarized in Figure 15-26.

This section discusses addresses both of these use cases. The following topics are discussed:

SAML Security Between 9.2 or Later Version Consumers and 8.1x Producers

This section explains how to achieve SAML-based security compatibility between a WebLogic Portal 9.2 or later version consumer and an 8.1x producer, as summarized in Figure 15-27.

The portal shown in Figure 15-28 includes a local portlet on the left and a remote (proxy) portlet on the right. The remote portlet is deployed in an 8.1x producer. The local portlet is a login portlet. Before SAML security is properly configured, when a user logs in, the name that is returned is null.

Configuring the Consumer

The following sections explain how to configure the consumer with a key that can sign the SAML assertion sent to the producer. The basic tasks include:

Generate a Key

This section explains how to generate a key on the consumer using the keytool utility, a Java utility distributed by Sun Microsystems that manages private keys and certificates. For detailed information on keytool, refer to the Sun Microsystems website.

Change the Consumer’s Name

Checkpoint: If you try to log in to the remote portlet again, you will receive an error, as shown in Figure 15-30. This error is caused by the fact that the producer cannot find the key that was sent from the consumer. The next step is to configure the security realm for the consumer domain.

Modify the Consumer’s Security Realm

Checkpoint: In the previous steps, you associated this consumer, consumer92, to a key to sign the SAML assertion. If you now try to log in to the remote portlet, the previously seen error does not appear. This means that the consumer is now properly associated with a key. However, now after logging in, the user name is null, as shown in Figure 15-34. This is because this consumer is not yet known to the producer. The next set of steps demonstrate how to configure the WebLogic Portal 8.1x producer to accept the WebLogic Portal 9.2 or later version consumer’s key.

Configure the WebLogic Portal 8.1x Producer

This section explains how to configure the WebLogic Portal 8.1x producer. To do this, you import the key into the producer’s keystore.

Import the Certificate

Test the Configuration

After the producer server is restarted, you can once again test the remote portlet in the consumer application. When you log into the portal, you will see that the remote portlet now recognizes the user as logged in, as shown in Figure 15-35.

Summary

The preceding example demonstrated how to configure SAML security between a WebLogic Portal 9.2 or later version consumer and a WebLogic Portal 8.1x producer. In the next example, you will see the reverse: configuring SAML security between a WebLogic Portal 8.1x consumer and a WebLogic Portal 9.2 or later version producer.

SAML Security Between 8.1x Consumers and 9.2 or Later Version Producers

This section explains how to achieve security compatibility between a WebLogic Portal 8.1x consumer and an 9.2 or later version producer, as summarized in Figure 15-36.

The basic steps include:

Configure the 8.1x Consumer

This section explains how to configure the 8.1x consumer. The basic steps include generating a key and configuring the WSRP Consumer Security Service in the WebLogic Administration Portal.

Generate a Key

This section explains how to use the keytool utility to generate a key on the consumer. Keytool, a Java utility distributed by Sun Microsystems, manages private keys and certificates. For detailed information on keytool, refer to the Sun Microsystems website.

Configure the 9.2 or Later Version Producer

This section explains how to configure the producer. To do this, you must configure the producer’s PKI credential mappings to include the consumer’s certificate.

Testing the Configuration

To test the configuration, log in to the consumer portal. As shown in Figure 15-45, the user name weblogic appears in the proxy portlet. This indicates success: the user was logged in successfully on the producer.

Using SAML Security with a Name Mapper

A name mapper is a class that maps one user name to another. Use a name mapper when the producer and consumer have different names for the same user. This section explains how to write and configure a name mapper class on both the consumer and the producer.

If you want to use a name mapping class on the producer or the consumer, the basic steps include:

Writing a Name Mapper Class

WebLogic Portal provides two user name mapping interfaces:

Implementing SAMLCredentialNameMapper on the Consumer

Implement SAMLCredentialNameMapper on the consumer to provide name mapping on the consumer. Listing 15-1 shows an example implementation of SAMLCredentialNameMapper.

The mapSubject() method gets a Subject (user) and returns a SAMLNameMapperInfo object. The method provides logic to test the user name and replace it with a new user name. This new user name is then returned in a SAMLNameMapperInfo object, which is then passed to the producer.

For detailed information on this interface, see the Javadoc.

package com.bea.wsrp.qa.security;

import java.util.Collection;
import java.util.Set;
import javax.security.auth.Subject;

import weblogic.security.SubjectUtils;
import weblogic.security.providers.saml.SAMLCredentialNameMapper;
import weblogic.security.providers.saml.SAMLNameMapperInfo;
import weblogic.security.service.ContextHandler;
import weblogic.security.spi.WLSGroup;

public class CustomSAMLNameMapperImpl implements SAMLCredentialNameMapper {

	private String nameQualifier = null;
	
	public CustomSAMLNameMapperImpl (){ }
	
	/************ SAMLCredentialNameMapper implementation**************/
	
	public synchronized void setNameQualifier(String nameQualifier) 
	{
		this.nameQualifier = nameQualifier;
	}
	
	public SAMLNameMapperInfo mapName (String name, ContextHandler handler)
	{
		return new SAMLNameMapperInfo(nameQualifier, name, null);
	}
	
	public SAMLNameMapperInfo mapSubject (Subject subject, ContextHandler handler)
	{
		// Provider checks for null Subject...
		Set groups = subject.getPrincipals(WLSGroup.class);
		String userName = null;
		
		userName = SubjectUtils.getUsername(subject);
		if (userName == null || userName.equals("")) {
			System.out.println("mapSubject: Username string is null or
                      empty, returning null");
			return null;
		}
		
		if (userName.equals("testUser"))
		{
			userName = "testUser_Mapped";
		}
		
		// Return mapping information...
		return new SAMLNameMapperInfo(nameQualifier, userName, groups);
	}
}

Implementing SAMLIdentityAssertionNameMapper on the Producer

Implement SAMLIdentityAssertionNameMapper on the producer to provide name mapping. Listing 15-2 shows an example implementation of SAMLIdentityAssertionNameMapper. In this example, if you log in on the consumer as testUser_Mapped, the name mapper class retrieves that user name on the producer and logs you in as testUser_Producer.

The mapNameInfo() method gets a SAMLNameMapperInfo object from the consumer. This object contains the name with which the user logged in on the consumer. The method provides logic to test the user name from the consumer and replace it with a user name on the producer.

For detailed information on this interface, see the Javadoc.

package com.bea.wsrp.qa.security;

import java.util.Collection;
import java.util.Set;
import javax.security.auth.Subject;

import weblogic.security.SubjectUtils;
import weblogic.security.providers.saml.SAMLIdentityAssertionNameMapper;
import weblogic.security.providers.saml.SAMLNameMapperInfo;
import weblogic.security.service.ContextHandler;
import weblogic.security.spi.WLSGroup;

public class CustomSAMLNameMapperImpl implements SAMLIdentityAssertionNameMapper
{
	private String nameQualifier = null;
	
	public CustomSAMLNameMapperImpl (){ }
	
	
	/************ SAMLIdentityAssertionNameMapper implementation**************/
	
	public String getGroupAttrName ()
	{
		return SAMLNameMapperInfo.BEA_GROUP_ATTR_NAME;
	}
	
	public String getGroupAttrNamespace ()
	{
		return SAMLNameMapperInfo.BEA_GROUP_ATTR_NAMESPACE;
	}
	
	public Collection mapGroupInfo(SAMLNameMapperInfo info, ContextHandler handlr)
	{
		return info.getGroups();
	}
	
	public String mapNameInfo(SAMLNameMapperInfo info, ContextHandler handler)
	{
		String userName = info.getName();
		
		if (userName == null || userName.equals("")) {
			System.out.println("mapNameInfo: Username string is null or
                       empty, returning null");
			return null;
		}
		
		if (userName.equals("testUser_Mapped"))
		{
			userName = "testUser_Producer";
		}
		
		return userName;
	}
}

Deploying the Mapper Classes

Whether you are implementing a mapper class on the producer or the consumer, the class must be in the server’s classpath. For information on adding classes to the server classpath, refer to the WebLogic Server topic “Adding Startup and Shutdown Classes to the Classpath.”

Configuring the Mapper Classes

You need to use the WebLogic Server Administration Console add the mapper classes to the security realm of the producer and/or consumer.

Adding a Mapper Class to the Producer

To add a mapper class to the producer:

Adding a Mapper Class to the Consumer

To add a mapper class to the producer:

Allowing Virtual Users

You can configure the producer to automatically create a new user if it does not recognize the user name sent from the consumer. This feature is useful if you do not want to manually create a unique user name on the producer for every user who might log in from a consumer application. You can use this feature as long as the producer is configured to recognize the consumer’s SAML token, as explained previously in this chapter.

To configure the producer to allow virtual users: