Steps to configure Single Sign-On using SAML in WebLogic 9.2

by Vikrant Sawant
09/09/2006 ( my article originally posted on oracle.com )

Abstract

BEA WebLogic 9.2 provides out-of-the-box support for SAML (Security Assertion Markup Language) to build Single Sign-On solutions with minimum or no coding, depending upon your security requirements.Using WebLogic 9.2, the Single Sign-On capability can be easily added between the online applications running on trusted domains. The SAML (Security Assertion Markup Language) 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 article provides step by step instructions to configure Single Sign-On capability between the two simple J2EE web applications running on two different WebLogic domains. The SAML configuration for Single Sign-On (SSO) is performed using BEA WebLogic 9.2 Administration Console with no programming involved.  The article also briefly introduces the basic interactions between WebLogic containers, the security providers, and the security framework during the Single Sign-On process.

Introduction

A simple use case considered in this article demonstrates how two web applications;  appA as Identity Provider web application deployed on SAML source site and appB as Service Provider web application deployed on SAML destination site; can be configured using BEA WebLogic 9.2 Administration Console  to participate in a Single Sign-On process.

Figure 1. Interaction between Source Site and Destination Site, using SAML, during Single Sign-On

Figure 1 shows the basic interaction between source site and destination site during Single Sign-On process. The whole process works as follows

1. The user's browser accesses the application appA, hosted on Identity Provider 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 welcome page of appA is displayed.
4. From the welcome page; the user then click on the link on the page to access a secured webpage of application appB, hosted on Service Provider domain, called domainB.This triggers a call to Inter-Site Transfer Service (ITS) servlet.
5. The ITS servlet calls the SAML Credential Mapper to request a caller assertion. SAML Credential Mapper returns the assertion. It also returns the URL of destination site application webpage (secured webpage 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 signed SAML response containing the generated assertion, signs it, base-64 encodes it, and 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 ACS (Assertion Consumer Service)
8. The assertion is validated. 
9.  If assertion is successful, the user is redirected to the target i.e. secured webpage of appB application.
10. The user is logged in into the destination site application appB, without having to re-authenticate at appB.

SAML Configuration using WebLogic Administrative Console

Before we actually start SAML configuration, in first few steps we will create and setup the server environment for our sample applications appA and appB. 

Step 1: Create SAML Source Site and Destination Site Domains and Application Servers

    Sample applications in this article are hosted on two domains on the localhost, so our first step is to create the domains and servers running on given ports as listed below in Table 1

	Host	Application Server	Application Name	Port	SSL Port
SAML Source Site Domain: domainA	localhost	AdminServer	appA	7001	7002
SAML  Destination Site Domain: domainB	localhost	AdminServer	appB	7003	7004

Table 1.  Sample application domains and application servers

Create domains, as shown in Table 1, using WebLogic BEA Domain Configuration Wizard. Update appropriate listen ports using WebLogic Administrative Console.

Step 2: Create user 

        For simplicity, this article uses the default security realm, myrealm, to configure security. However as a best practice, BEA recommends that you customize the default security configuration by creating an entirely new security realm. This preserves your ability to revert more easily to the default security configuration. A valid security realm requires an Authentication provider, an Authorization provider, an Adjudication provider, a Credential Mapping provider, a Role Mapping provider, and a CertPathBuilder.

	Realm	User/Password
SAML Source Site Domain: domainA	myrealm	ssouser/demosaml
SAML  Destination Site Domain: domainB	myrealm	ssouser/demosaml

Table 2.  The user participating in Single Sign-On
Create user, ssouser, as shown in Table 2, in both domains under default security realm, myrealm.

Step 3: Create and deploy J2EE Web applications - Identity Provider application (appA) and Service Provider application (appB) 

    Sample application source code for appA can be downloaded from here. Import the existing web application into WebLogic WorkShop Studio or any other IDE , such as Eclipse, you use. 

             

Figure 2. Application appA - Identity Provider application

   Application appA, is configured to use FORM based authentication. This application is deployed on SAML source site domain (domainA).
A jsp page, auth.jsp, under /admin folder (as shown in the Figure 2) is secured and require logged in user to have  'admin' role in order to access it. The role 'admin' is mapped to a principal called 'ssouser' in weblogic.xml (not shown in the Figure 2) When the user try to access /admin/auth.jsp page, a login page will be displayed asking user to supply credentials. When user supplies credentials and submit the login page, container authenticates user 'ssouser'. If authentication is successful, the auth.jsp will be displayed. Before we explore the webpage auth.jsp, let us create application appB on SAML destination site domain (domainB)
        
    Sample application source code for appB can be downloaded from here. Import the existing web application into WebLogic WorkShop Studio or any other IDE, such as Eclipse, you use. 

Figure 3. Application appB - Service Provider application

   Application appB, is configured to use CLIENT-CERT, so that it will use identity assertion for authentication. This application is deployed on SAML destination site domain (domainB). A jsp page, services.jsp, under /admin folder (as shown in the Figure 3) is secured and require user to have role 'admin' in order to access it. The role 'admin' is mapped to a principal called 'ssouser' in weblogic.xml (not shown in the Figure 3).  

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

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

Step 4: Generate and Register SSL Certificates

    Generate a key using keytool utility, distributed by Sun Microsystems that manages private keys and certificates.By default, a default keystore calledDemoIdentity.jks is already configured for domainA & domainB

Note:
    The keystores that are located in the WL_HOME\server\lib directory are used for testing and development purposes only. Do not use the demonstration keystores in a production environment. Because the digital certificates and trusted CA certificates in the demonstration keystores are signed by a WebLogic Server demonstration certificate authority, a WebLogic Server installation using the demonstration keystores will trust any WebLogic Server installation that also uses the demonstration keystores. You want to create a secure environment where only your installations trust each other

How to generate private key and certificate for test purpose?

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

    Keytool -genkey -keypass testkeypass -keystore DemoIdentity.jks -storepass DemoIdentityKeyStorePassPhrase -keyalg rsa -alias testalias
      Now run the keytool command with -export option, as shown in Figure below to generate key file called testalias.der

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

  
 Figure 4. Generate test SSL certificate Screen Shot

Note:
    In production environment you must follow the following steps

1. Obtain private keys and digital certificates from a reputable certificate authority such as Verisign, Inc. or Entrust.net.
2. Create identity and trust keystores.
3. Load the private keys and trusted CAs into the identity and trust keystores.
4. Use the WebLogic Server Administration Console to configure the identity and trust keystores.

    Make sure the SSL is configured and server is listening for SSL connections on SSL ports

SAML Configuration

Let us begin with the SAML Source Site configuration

Step 5: Configure domainA, Acting as a SAML Source Site 

1. Login 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 the Credential Mappings tab
5. If SAMLCredentialMapper doesn't exist then create a new SAMLCredentialMapper as shown in Figure 5. The SAML Credential Mapping provider acts as a producer of SAML security assertions, allowing WebLogic Server running in domainA to act as a source site for using SAML for Single Sign-On.

Figure 5. Create a new SAML Credential Mapping Provider

6. Select SAMLCredentialMapper,  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 allow it match with the key. Typically URL is used to guarantee the uniqueness.
9. Enter the Signing Key Alias(testalias) and Signing Key Pass Phrase(testkeypass), these are the values you used 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 6

Figure 6. 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 on source site (domainA) is configured to use the keystore you generated.We also need to configure the destination site(domainB) to accept the key sent from source site(domainA)

Step 6: Configure Relying Party Properties 

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

Figure 7. Relying Party Configuration

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

Parameter	Value
Enabled	Select the checkbox(true)
Target URL	http://localhost:7003/appB/admin/services.jsp
Assertion Consumer URL	https://localhost:7004/samlacs/acs
Assertion Consumer Parameters	APID=ap_00001
Signature Required	Select the checkbox(true)
Include Keyinfo	Select the checkbox(true)

    Table 3. Relying Party (rp_00001) Values

Step 7: Configure SAML 1.1 Source site 

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

Figure 8. Source Site Configuration

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

Parameter	Value
Source Site Enabled	Select the checkbox(true)
Signing Key Alias	testalias
Signing Key Passphrase	testkeypass
Intersite Transfer URIS	/samlits_cc/its (keep the other values)
ITS Requires SSL	Select the checkbox(true)
Assertion Retrieval URIs	/samlars/ars
ARS Requires SSL	Select the checkbox(true)

Table 4. Source Site Values

Step 8: Configure domainB, Acting as a SAML Destination Site

Now let us begin with the SAML Destination Site configuration

    Import the Certificate

1. Copy the key file (testalias.der) that you generated previously.
2. Login in to the WebLogic Server Administration Console on domainB
3. Select a security realm, myrealm.
4. Select the Providers tab and then the Authentication tab
5. If SAMLIdentityAsserter doesn't exist then create a new SAMLIdentityAsserter as shown in Figure 9. An Identity asserter allows WebLogic Server to establish trust by validating a user.

Figure 9. Create a new Identity Asserter

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

Figure 10. Create New Identity Asserter Certificate

8. In the Alias field, enter a name for the certificate. Good practice is to use the same name you use 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

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

Figure 11. Create a New Asserting Party

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

    

Parameter	Value
Enabled	Select the checkbox(true)
Target URL	http://localhost:7001/appA
POST Signing Certificate alias	testalias
Source Site Redirect URIs	/appB/admin/service.jsp
Source Site ITS URL	https://localhost:7001/samlits_cc/its
Source Site ITS Parameters	RPID=rp_00001
Issuer URI	http://www.bea.com/demoSAML
Signature Required	Select the checkbox(true)
Asserting Signing Certificate Alias	testalias

    Table 5. Asserting Party (ap_00001) Values
        

Step 10: Configure SAML 1.1 Destination site

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

Figure 12. SAML Destination Site Settings

3. Set the Destination site values, as listed in Table

Parameter	Value
Destination Site Enabled	Select the checkbox(true)
Assertion Consumer URIs	/samlacs/acs
ACS Requires SSL	Select the checkbox(true)
SSL Client Identity Alias	testalias
POST Recipient Check Enabled	Select the checkbox(true)
POST one Use Check Enabled	Select the checkbox(true)
Used Assertion Cache Properties	APID=ap_00001

Table 6. Destination Site Values

Test Single Sign-On

    Figure 13. Browser Showing appA Login
    

    Figure 14. Browser Showing appA Successful Login with Destination Site (appB on domainB) Link
    

    Figure 15. Browser Showing appB Successful Login with SSO

Debugging Note

    To enable SAML security debugging

1. In the administration console, select Environment and then Servers, in the Domain Structure window.
2. Select AdminServer and then in 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 weblogic > security > saml node. Select checkbox to enable SAML debugging as shown in the Figure 16 
5. In the Change Center Window, click Activate Changes.

    Figure 29. Showing WebLogic Console Enabling SAML Debug
   
   You can then view the AdminServer log file to debug the SAML related issues

    Figure 30. AdminServer Log showing SAML interactions

Conclusion

The article showed us how SAML source and destination sites can be configured to allow  identity provider and service provider applications in different domains to operate in a federation of trust based on successful Single Sign-On to identity provider application by a user.

References

• Technical Overview of the OASIS Security Assertion Markup Language (SAML) V1.1 - OASIS website on SAML
• saml_sso.zip - sample code for this article

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