Published on dev2dev (http://dev2dev.bea.com/)
 http://dev2dev.bea.com/pub/a/2006/12/sso-with-saml.html
 See this if you're having trouble printing code examples

Configuring Single Sign-On using SAML in WebLogic Server 9.2

by Vikrant Sawant
01/04/2007

Abstract

BEA WebLogic Server 9.2 provides out-of-the-box support for Security Assertion Markup Language (SAML) to build single sign-on (SSO) solutions with minimum or no coding, depending on your security requirements. Using WebLogic Server 9.2, the single sign-on capability can be easily added between multiple online applications running on trusted domains. The SAML standard defines a framework for exchanging security information between the federation of trusted servers. The primary function of the security framework is to provide configuration tools and APIs to secure your applications.

This tutorial provides step by step instructions to configure the single sign-on capability between two simple Java EE Web applications running on two different WebLogic domains. The SAML configuration for single sign-on is performed using the WebLogic Server 9.2 Administration Console with no programming involved. The tutorial also briefly introduces the basic interactions between WebLogic containers, the security providers, and the security framework during the single sign-on process.

Introduction

The SAML standard defines a framework for exchanging security information within the federation of trusted servers. For some background, read Introduction to SAML by Beth Linker (Dev2Dev, 2006). This tutorial shows how to set up SAML authorization between two Web applications. The source for these applications is provided here.

This tutorial looks at a simple example involving two Web applications; appA deployed on the source (local) site, and appB deployed on the destination (remote) site. You'll learn how to configure these applications using the WebLogic Server 9.2 Administration Console and participate in a SSO process using SAML.

The source site provides an authentication service and securely passes the authentication details using SAML Inter-site Transfer Service (ITS) when requested by the destination site. The server on the source site includes an ITS servlet, which is an addressable component that provides SAML processing functionality such as artifact generation and the ability to redirect a user to the destination site.

Figure 1 shows the basic interaction between source site and destination site during the SSO process.

Figure 1. Interaction between source site and destination site, using SAML, during single sign-on

1. The user's browser accesses the application appA(source site), hosted on a WebLogic Server domain, called domainA, by supplying user credentials.
2. The application appA passes the user credentials to the authentication service provider.
3. If authentication is successful, the authenticated session is established, and a welcome page of appA is displayed.
4. From the welcome page, the user then clicks on a link on the page to access a secured Web page of application appB (destination site), hosted on a different WebLogic Server domain, called domainB. This triggers a call to the Inter-Site Transfer Service (ITS) servlet.
5. The ITS servlet calls the SAML Credential Mapper to request a caller assertion. The SAML Credential Mapper returns the assertion. It also returns the URL of the destination site application Web page (a secured Web page of appB) and path to the appropriate POST form (if the source site is configured to use the POST profile).
6. The SAML ITS servlet generates a SAML response containing the generated assertion, signs it, base-64 encodes it, embeds it in the HTML form, and returns the form to the user's browser.
7. The user's browser POSTs the form to the destination site's Assertion Consumer Service (ACS).
8. The assertion is validated.
9. If the assertion is successful, the user is redirected to the target—that is, the secured Web page of the appB application.
10. The user is logged in on the destination site application appB, without having to reauthenticate at appB.

The whole single sign-on process listed above requires no coding by the developer (except for the coding of applications appA and appB, of course) and can be easily configured using the Administration Console.

SAML Configuration Using the WebLogic Administrative Console

Before starting the SAML configuration, in the first few steps you'll create and set up the server environment for the sample applications appA and appB.

Step 1: Create SAML source site and destination site domains and application servers

The sample applications in this tutorial are hosted on two domains on the local host, so the first step is to create the domains and servers running on given ports, as listed below in Table 1.

Table 1. Sample application domains and application servers

Create domains, as shown in Table 1, using the Domain Configuration Wizard. Update the appropriate listen ports using the WebLogic Server 9.2 Administration Console.

Step 2: Create users

For simplicity, this tutorial uses the default security realms on each domain, each named with the same default realm name, that is, myrealm. Create a user ssouser in each domain separately under the myrealm realm. Alternatively, you could create this user in a centralized external LDAP store and configure both domains to use this common store for authentication.

The user ssouser created here will authenticate with application appA hosted on domainA, and then access application appB hosted on domainB directly using SSO.

Table 2. The user participating in single sign-on

Create the user, ssouser, as shown in Table 2, in both domains under the default security realms, each called myrealm.

Step 3: Create and deploy the Java EE Web applications appA and appB

The sample application source code for appA can be downloaded here. Import the existing Web application into WebLogic WorkShop Studio or any other IDE, such as Eclipse.

Application appA is configured to use FORM-based authentication. This application is deployed on the SAML source site domain (domainA). A JSP page of appA called auth.jsp, under the admin folder, requires the authenticated user to have an admin role in order to access it. The admin role is mapped to a principal called ssouser in weblogic.xml. Figure 2 shows the configuration of the security in web.xml.

<display-name>Saml Source Site Application</display-name>
<security-constraint>
	<web-resource-collection>
		<web-resource-name>SecurePages</web-resource-name>
		<description>These pages are only accessible by authorized users.</description>
		<url-pattern>/admin/*</url-pattern>
		<http-method>GET</http-method>
	</web-resource-collection>
	<auth-constraint>
		<description>These are the roles who have access.</description>
		<role-name>admin</role-name>
	</auth-constraint>
	<user-data-constraint>
		<description>This is how the user data must be transmitted.</description>
		<transport-guarantee>NONE</transport-guarantee>
	</user-data-constraint>
</security-constraint>
<login-config>
	<auth-method>FORM</auth-method>
	<realm-name>myrealm</realm-name>
	<form-login-config>
		<form-login-page>/login.jsp</form-login-page>
		<form-error-page>/fail_login.htm</form-error-page>
	</form-login-config>
</login-config>
<security-role>
	<description>These are the roles who have access</description>
	<role-name>admin</role-name>
</security-role>

Example 1. Application appA - web.xml snippet

When the user tries to access the /admin/auth.jsp page, a configured login page, login.jsp, will be displayed, asking the user to supply credentials. After submitting the details, the container will authenticate the user ssouser. If authentication is successful, the auth.jsp will be displayed. Before going on to explore the Web page auth.jsp, I'll create the application appB on the SAML destination site domain (domainB).

Sample application source code for appB can be downloaded from the Download section. Application appB is configured to use CLIENT-CERT, so that it will use identity assertion for authentication. This application should be deployed on the SAML destination site domain (domainB). A JSP page of appB, called services.jsp and located in the /admin folder, requires the authenticated user to have the admin role in order to access it. This role is mapped to a principal called ssouser in weblogic.xml. Figure 3 shows an excerpt from appB's web.xml configuration:

<display-name>SAML Destination Site Application</display-name>
 <!-- ... -->
<security-constraint>
	<web-resource-collection>
		<web-resource-name>SecurePages</web-resource-name>
		<description>These pages are only accessible by authorized users.</description>
		<url-pattern>/admin/*</url-pattern>
		<http-method>GET</http-method>
	</web-resource-collection>
	<auth-constraint>
		<description>These are the roles who have access.</description>
		<role-name>admin</role-name>
	</auth-constraint>
	<user-data-constraint>
		<description>This is how the user data must be transmitted.</description>
		<transport-guarantee>NONE</transport-guarantee>
	</user-data-constraint>
</security-constraint>
<login-config>
	<auth-method>CLIENT-CERT</auth-method>
	<realm-name>myrealm</realm-name>
</login-config>
<security-role>
	<description>These are the roles who have access.</description>
	<role-name>admin</role-name>
</security-role>

Example 2. Application appB - web.xml snippet

Compile and build the WAR files (appA.war,appB.war) for each application. To deploy, copy appA.war and appB.war files into the autodeploy folders of the domainA and domainB domains respectively. Restart the application servers and test to see how the applications behave without SSO.

When the SAML configuration has been completed, as described in the steps to follow, the user ssouser, authenticated at appA (SAML source site), will be able to directly access the services.jsp page of appB (SAML destination site) without being asked to supply the credentials again.

Step 4: Generate and register SSL certificates

To secure communication between the SAML source and destination sites, communication between the source site and destination site should be encrypted. Additionally, certificates should be used to verify the identity of the other party during SAML interaction. In this step I'll create and register certificates that will be used in the communication between the source site and the destination site.

Generate a key using the keytool utility (part of your JDK). By default, a keystore called DemoIdentity.jks will already be configured for domainA and domainB.

Now I'll show how to generate a private key and certificate for test purposes:

1. Open the DOS command window and change the directory to WEBLOGIC_HOME/server/lib directory.
2. Run the keytool command to generate the key, as shown below.

keytool -genkey -keypass testkeypass -keystore DemoIdentity.jks -storepass DemoIdentityKeyStorePassPhrase -keyalg rsa -alias testalias

Figure 2. Generate test SSL certificate screen shot

Now run the keytool command with -export option, as shown in Figure 2, to generate a key file called testalias.der:

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

SAML Configuration

I'll begin with the SAML source site configuration.

Step 5: Configure domainA, acting as a SAML source site

In this step I will create and configure a SAML Credential Mapper V2 instance. The SAML Credential Mapper acts as a producer of SAML security assertions, allowing domainA to act as a source site for using SAML for SSO.
A SAML security assertion is a package of information that supplies one or more statements made by a SAML authority (meaning an asserting party). The statements made are of the following types; authentication statements, attribute statements, and authorization decision statements.

I'll start by configuring a SAML Credential Mapper V2 instance (note that the SAML Credential Mapper V1 is deprecated as of BEA WebLogic Server 9.2):

1. Log in to the WebLogic Server Administration Console on domainA(http://localhost:7001/console).
2. In the administration console, select Security Realms in the Domain Structure window
3. Select a security realm. The default realm used is myrealm.
4. Select the Providers tab, and then select the Credential Mappings tab.
5. If SAMLCredentialMapper doesn't exist, then create a new SAMLCredentialMapper, as shown in Figure 3.

Figure 3. Create a new SAML credential mapping provider

6. Select SAMLCredentialMapper, and then select Provider Specific.
7. In the Change Center window, select Lock and Edit; this will allow you to edit the SAMLCredentialMapper settings.
8. Edit the issuer URI, http://www.bea.com/demoSAML. This unique URI tells the destination site (domainB/appB) the origin of the SAML message and allows it to match with the key. Typically, the URL is used to guarantee uniqueness.
9. Enter the Signing Key Alias (testalias) and the Signing Key Pass Phrase (testkeypass). You used these values when you generated the keystore.
10. Set the Default time to Live and Cred Cache Min Viable TTL and other values, as shown in Figure 4.

Figure 4. SAML credential mapping provider settings

11. Click Save.
12. In the Change Center window, click Activate Changes.

At this point the SAML credential mapper provider is configured to allow domainA to act as a source site (source of SAML security assertions) and also it is configured to use the keystore you generated in Step 4.

Step 6: Configure relying party properties

In this step I'll create and configure a relying party. When you configure WebLogic Server to act as a source of SAML security assertions, you need to register the parties that may request SAML assertions that will be accepted. For a SAML relying party, you can specify: the SAML profile used, details about the relying party, and the attributes expected in assertions for the relying party.

The relying party determines whether it trusts the assertions provided to it by the asserting party. SAML defines a number of mechanisms that enable the relying party to trust the assertions provided to it.

1. On the Management tab, click Relying Parties.
2. In the Relying Parties table, click New.
3. In the Profile pull-down menu, select Browser/POST. In the Description field, enter the name demoSAML to identify the relying party, as shown in Figure 5.

Figure 5. Relying party configuration

4. Set the relying party values, as listed in Table 3.

Table 3. Relying Party (rp_00001) Values

Although a relying party may trust the assertions provided to it for user ssouser, the local access policy on the destination site application appB on domainB defines whether the subject (ssouser) may access local resources.

Step 7: Configure SAML on the source site

In this step I'll configure various federation services source site settings for the server instance running the application appA. These settings enable server instances running on domainA to serve as a SAML source site, define the source site URIs and service URIs, add certificate to sign assertions, and configure SSL for retrieving assertions.

1. In the administration console, in the Domain Structure window, select Environment and then Servers.
2. Select AdminServer, and then in the Settings for AdminServer, click Federation Services on the SAML 1.1 Source Site tab, as shown in Figure 6.

Figure 6. Source site configuration

3. Set the source site values, as listed in Table 4.

Table 4. Source Site Values

Step 8: Configure domainB, acting as a SAML destination site

I'm ready to begin the SAML destination site configuration. In this step I'll create and configure a SAML Identity Assertion Provider V2 instance. The SAML Identity Assertion provider acts as a consumer of SAML security assertions, allowing WebLogic Server to act as a destination site for using SAML for single sign-on. The SAML Identity Assertion provider validates SAML assertions by checking the signature and validating the certificate for trust in the certificate registry maintained by the provider. The first thing I need to do here is to create a SAML Identity Assertion Provider V2 instance and import the certificate generated in step 4 into the provider's certificate registry.

Import the certificate:

1. Copy the key file (testalias.der) that you generated previously to the D:\bea\weblogic92\server\lib directory.
2. Log in to the WebLogic Server Administration Console on domainB.
3. Select a security realm, myrealm.
4. Select the Providers tab, and then select the Authentication tab.
5. If a SAMLIdentityAsserter doesn't exist, then create a new SAMLIdentityAsserter, as shown in Figure 7. An identity asserter allows WebLogic Server to establish trust by validating a user.

Figure 7. Create a new Identity asserter

6. Select SAMLIdentityAsserter, click the Management tab, and then click Certificates.
7. In the Certificates dialog, click New, as shown in Figure 8.

Figure 8. Create a new identity asserter certificate

8. In the Alias field, enter a name for the certificate. Good practice is to use the same name you used when you created the certificate.
9. Enter the path to the certificate file in the Certificate File Name field.
10. Click Finish. If there are no problems, the message "The certificate has been successfully registered." is displayed.

Step 9: Configure asserting party properties

In this step I'll create and configure an asserting party. When you configure WebLogic Server to act as a consumer of SAML security assertions, you need to register the parties whose SAML assertions will be accepted. For a SAML asserting party, you can specify the SAML profile used, details about the asserting party, and the attributes expected in assertions received from the asserting party.

The asserting party asserts that a user has been authenticated and given associated attributes. For example, there is a user ssouser, and he/she is authenticated to this domain using a password mechanism. Asserting parties are also known as SAML authorities.

1. On the Management tab, click Asserting Parties.
2. In the Asserting Parties table, click New.
3. In the Profile pull-down menu, select Browser/POST. In the Description field, enter the name demoSAML to identify the asserting party, as shown in Figure 9.

Figure 9. Create a new asserting party

4. Set the asserting party values, as listed in Table 5.

Table 5. Asserting Party (ap_00001) Values

Step 10: Configure the SAML 1.1 destination site

In this step I'll configure various destination site settings for the server instance running application appB. These settings enable a server instance running on domainB to serve as a SAML destination site, define service URIs (for example, Assertion Consumer Service URI), add a certificate to sign POST profile responses, and configure SSL for the Assertion Consumer Service.

1. In the administration console, select Environment, and then select Servers in the Domain Structure window.
2. Select AdminServer, and then in the Settings for AdminServer, click Federation Services, and then the SAML 1.1 Destination Site tab, as shown in Figure 10.

Figure 10. SAML destination site settings

3. Set the destination site values, as listed in Table 6.

Table 6. Destination Site Values

Test Single Sign-On

To test single sign-on, open a browser and point to the URL http://localhost:7001/appA/. The FORM-based authentication configured for appA will display the login.jsp page, as shown in Figure 11. Enter ssouser and demosaml as the values (created in step 2).

Figure 11. Browser showing appA login

This will authenticate the user using the default authenticator configured for domainA.

The auth.jsp page will now be displayed. This page shows a link to appB (http://localhost:7003/appB/admin/services.jsp), as shown in Figure 12. Clicking this link will trigger a call to the ITS servlet and cause the assertion to be generated and the control to be transferred to the destination site.

Figure 12. Browser showing appA successful login with destination site (appB on domainB) link

Once the assertion is validated on the destination site, the ssouser is allowed to access the services.jsp page, as shown in Figure 13.

Figure 13. Browser showing appB successful login with SSO

What if ssouser visits the destination site first? In Step 9, when the asserting party was configured, the Source Site Redirect URI was set to URI /appB/admin/services.jsp. This is the URI from which the unauthenticated user will be redirected to the ITS URL, https://localhost:7001/samlits_ba/its, of the source site. This is done to support the destination site first scenario, whereby a user tries to access a destination site URL prior to being authenticated and is redirected to the source site to be authenticated and then obtain a SAML assertion. The ITS servlet at the source site will challenge the user to supply a username and password. Upon successful authentication, the redirection to the destination site is issued, and the /appB/admin/services.jsp page is displayed.

Debugging Notes

You can enable SAML security debugging to see how the source and destination site interact using the SAML SSO process. To enable SAML security debugging:

1. In the administration console, select Environment, and then select Servers, in the Domain Structure window.
2. Select AdminServer and then the Debug tab.
3. In the Change Center window, select Lock and Edit; this will allow you to edit the debug settings.
4. In the Debug Scope and Attributes, click to open the weblogic > security > saml node. Select the checkbox to enable SAML debugging, as shown in the Figure 14.
5. In the Change Center window, click Activate Changes.

Figure 14. Showing WebLogic console enabling SAML debug

You can then view the AdminServer log file on domainA (source) and domainB (destination) to debug the SAML-related issues (Figure 15).

Figure 15. AdminServer log showing SAML interactions

Download

• Sample code for this tutorial

Summary

The tutorial shows how SAML source and destination site domains can be configured to allow Web applications on these domains to operate in a federation of trust based on successful single sign-on to the SAML source site Web application. This is a powerful paradigm, completely configured using the administration console, providing immediate benefit to users of your many applications.

References

• Introduction to SAML by Beth Linker (Dev2Dev, 2006)
• Demystifying SAML by Harold Lockhart (Dev2Dev, 2006)
• Using PFX and PEM Certificate Formats with Keystores by Arvind Tiwari (Dev2Dev, 2006) - provides more background on setting up certificates and keystores
• Configuring Single Sign-On with Web Browsers and HTTP Clients - product documentation, WebLogic Server
• Technical Overview of the OASIS Security Assertion Markup Language (SAML) V1.1 - OASIS Web site on SAML

Vikrant Sawant is Senior IT Specialist at the Legislative Counsel Bureau, California. He has over 14 years of experience in software development and has worked extensively in Java and Java EE based projects

Return to dev2dev.