Securing WebLogic Server

Configuring Single Sign-On with Web Browsers and HTTP Clients

The following sections describe how to set up single sign-on (SSO) with Web browsers or other HTTP clients by using authentication based on the Security Assertion Markup Language 1.1 (SAML).

Overview of SAML-Based Single Sign-On

Security Assertion Markup Language (SAML) enables cross-platform authentication between Web applications or Web Services running in a WebLogic Server domain and Web browsers or other HTTP clients. WebLogic Server supports single sign-on (SSO) based on SAML. When users are authenticated at one site that participates in a single sign-on (SSO) configuration, they are automatically authenticated at other sites in the SSO configuration and do not need to log in separately.

SAML SSO works as follows:

A Web user authenticates to a SAML source site.

The user attempts to access a target resource at a destination site that is configured to accept authentications through SAML assertions.

Through one or more steps (for example, redirection), the user arrives at an Intersite Transfer Service (ITS) at the source site. The WebLogic Server SAML Credential Mapping provider can serve as an ITS. The ITS creates a security assertion authenticating the user.

Through a sequence of HTTP exchanges, the user browser is transferred to an Assertion Consumer Service (ACS) at the SAML destination site. The WebLogic Server SAML Identity Assertion provider can serve as an ACS.

Information about the SAML assertion provided by the source site and associated with the user and the desired target is conveyed from the source site to the destination site by the protocol exchange.

The ACS at the destination site examines both the assertion and the target information to determine whether to allow access to the target resource. If access is authorized, the user originating from a source site is accepted as an authenticated user by the destination site, thereby achieving Web-based SSO.

For a general overview of how WebLogic Server implements SAML, see Single Sign-On: Web Sites and Web Applications and Single Sign-On with the WebLogic Security Framework in Understanding WebLogic Security. For more information about adding security to Web Services, see Configuring Security in Programming WebLogic Web Services.

For more information about SAML, see http://www.oasis-open.org.

Single Sign-on with SAML: Main Steps

To enable single sign-on with SAML, configure WebLogic Server as a SAML source site and as a SAML destination site. The main steps are outlined in this section; they are described in detail in Configuring a SAML Source Site for Single Sign-On and Configuring a SAML Destination Site for Single Sign-On.

Create and configure a SAML Credential Mapping provider in your security realm. See Configuring a SAML Credential Mapping Provider.

Configure your server's source site federation services.

Create and configure SAML Relying Parties for which SAML assertions will be produced.

If you want to require SAML Relying Parties to use SSL certificates to connect to the Assertion Retrieval Service, add any such certificates to the SAML Credential Mapping provider's Certificate Registry.

Create and configure a SAML Identity Assertion provider in your security realm. See Configuring a SAML Identity Assertion Provider.

Configure your server's destination site federation services.

Create and configure SAML Asserting Parties from which SAML assertions will be consumed.

Establish trust by registering the source site's SSL certificate in the certificate registry maintained by the SAML Identity Assertion provider. See Certificate Registry.

Configuring a SAML Source Site for Single Sign-On

This section describes how to configure WebLogic Server as a SAML source site.

Configure SAML Credential Mapping Provider

In your security realm, create a SAML Credential Mapping Provider V2 instance. The SAML Credential Mapping provider is not part of the default security realm. See Configuring a SAML Credential Mapping Provider.

Configure the SAML Credential Mapping provider as a SAML authority, using the Issuer URI, Name Qualifier, and other attributes.

Configure Source Site Federation Services

Configuration of a WebLogic Server instance as a SAML source site is controlled by the FederationServicesMBean. Access the FederationServicesMBean with the WebLogic Scripting Tool or through the Administration Console, on the Environment: Servers: ServerName: Configuration: Federation Services: SAML 1.1 Source Site page. See Configure SAML source services in the Administration Console help.

Configure SAML source site attributes as follows:

Enable the SAML Source Site. Allow the WebLogic server instance to serve as a SAML source site by setting Source Site Enabled to true.
Set Source Site URL and Service URIs. Set the URL for the SAML source site. This is the URL that hosts the Intersite Transfer Service and Assertion Retrieval Service. The source site URL is encoded as a source ID in hex and Base64. When you configure a SAML Asserting Party for Browser/Artifact profile, you specify the encoded source ID.

Also specify the URIs for the Intersite Transfer Service and (to support Browser/Artifact profile) the Assertion Retrieval Service. These URIs are also specified in the configuration of an Asserting Party.

Add signing certificate. The SAML source site requires a trusted certificate with which to sign assertions. Add this certificate to the keystore and enter the credentials (alias and passphrase) to be used to access the certificate. The server's SSL identity key/certificates will be used by default if a signing alias and passphrase are not supplied.
Configure SSL for the Assertion Retrieval Service. You can require all access to the Assertion Retrieval Service to use SSL by setting FederationServicesMBean.arsRequiresSSL to true. You can require two-way SSL authentication for the Assertion Retrieval Service by setting both arsRequiresSSL and ARSRequiresTwoWaySSL to true.

Configure Relying Parties

A SAML Relying Party is an entity that relies on the information in a SAML assertion produced by the SAML source site. You can configure how WebLogic Server produces SAML assertions separately for each Relying Party or use the defaults established by the Federation Services source site configuration for producing assertion.

You configure a Relying Party in the Administration Console, on the Security Realms: RealmName: Providers: Credential Mapper: SAMLCredentialMapperName: Management: Relying Parties page. See Create a SAML Relying Party and Configure a SAML Relying Party in the Administration Console help.

You can also configure a Relying Party with the WebLogic Scripting Tool. See Configuring Relying and Asserting Parties with WLST.

Configure Supported Profiles

When you configure a SAML Relying Party, you can specify support for Artifact profile or POST profile, for the purposes of SAML SSO. As an alternative configure a Relying Party to support WSS/Holder-of-Key or WSS/Sender-Vouches profiles for Web Services Security purposes. Be sure to configure support for the profiles that the SAML destination sites support.

If you support the POST profile, optionally create a form to use in POST profile assertions for the Relying Party and set the pathname of that form in the POST Form attribute.

Assertion Consumer Parameters

For each SAML Relying Party, you can configure one or more optional query parameters (such as a partner ID) that will be added to the ACS URL when redirecting to the destination site. In the case of POST profile, these parameters will be included as form variables when using the default POST form. If a custom POST form is in use, the parameters will be made available as a Map of names and values, but the form may or may not constructed to include the parameters in the POSTed data.

Replacing the Default Assertion Store

WebLogic Server uses a simple assertion store to maintain persistence for produced assertions. You can replace this assertion store with a custom assertion store class that implements weblogic.security.providers.saml.AssertionStoreV2. Configure WebLogic Server to use your custom assertion store class, rather than the default class, using the FederationServicesMBean.AssertionStoreClassName attribute. You can configure properties to be passed to the initStore() method of your custom assertion store class by using the FederationServicesMBean.AssertionStoreProperties attribute. Configure these attributes in the Administration Console on the Environment: Servers: ServerName: Configuration: Federation Services: SAML 1.1 Source Site page.

Configuring a SAML Destination Site for Single Sign-On

This section describes how to configure WebLogic Server as a SAML destination site.

Configure SAML Identity Assertion Provider

In your security realm, create and configure a SAML Identity Assertion Provider V2 instance. The SAML Identity Assertion provider is not part of the default security realm. See Configuring a SAML Identity Assertion Provider.

Configure Destination Site Federation Services

Before you configure WebLogic as a SAML destination site, you must first create a SAML Identity Assertion Provider V2 instance in your security realm. Configuration of a WebLogic Server instance as a SAML destination site is controlled by the FederationServicesMBean. You can access the FederationServicesMBean using the WebLogic Scripting Tool or through the Administration Console, using the Environment: Servers: ServerName: Configuration: Federation Services: SAML 1.1 Destination Site page.

Configure the SAML destination site attributes as follows.

Enable the SAML Destination Site

Allow the WebLogic Server instance to serve as a SAML destination site by setting Destination Site Enabled to true.

Set Assertion Consumer URIs

Set the URIs for the SAML Assertion Consumer Service. This is the URL that receives assertions from source sites, so that the destination site can use the assertions to authenticate users. The Assertion Consumer URI is also specified in the configuration of a Relying Party.

Configure SSL for the Assertion Consumer Service

You can require all access to the Assertion Consumer Service to use SSL by setting FederationServicesMBean.acsRequiresSSL to true.

Add SSL Client Identity Certificate

The SAML destination site uses a trusted certificate with which to sign POST profile responses. Add this certificate to the keystore and enter the credentials (alias and passphrase) to be used to access the certificate.

Configure Single-Use Policy and the Used Assertion Cache or Custom Assertion Cache

Optionally, you can require that each POST profile assertion be used no more than once. WebLogic Server maintains a cache of used assertions so that it can support a single-use policy for assertions. You can replace this assertion cache with a custom assertion cache class that implements weblogic.security.providers.saml.SAMLUsedAssertionCache. Configure WebLogic Server to use your custom assertion cache class, rather than the default class, using the FederationServicesMBean.SAMLUsedAssertionCache attribute. You can configure properties to be passed to the initCache() method of your custom assertion cache class using the FederationServicesMBean.UsedAssertionCacheProperties attribute. You can configure these attributes in the Administration Console on the Environment: Servers: ServerName: Configuration: Federation Services: SAML 1.1 Destination Site page.

Configure Recipient Check for POST Profile

Optionally, you can require that the recipient of the SAML Response must match the URL in the HTTP Request. Do this by setting the POST Recipient Check Enabled attribute.

Configuring Asserting Parties

A SAML Asserting Party is a trusted SAML Authority (an entity that can authoritatively assert security information in the form of SAML Assertions).Configure an Asserting Party in the Administration Console, using the Security Realms: RealmName: Providers: Credential Mapper: SAMLCredentialMapperName: Management: Asserting Parties page. See Create a SAML Asserting Party and Configure a SAML Asserting Party in the Administration Console help.

You can also configure an Asserting Party with the WebLogic Scripting Tool. See Configuring Relying and Asserting Parties with WLST.

Configure Supported Profiles

When you configure a SAML Asserting Party, you can specify support for Artifact profile or POST profile, for the purposes of SAML SSO. Alternatively, configure an Asserting Party to support WSS/Holder-of-Key or WSS/Sender-Vouches profiles for Web Services Security purposes.

Configure Source Site ITS Parameters

For each SAML Asserting Party, configure zero or more optional query parameters (such as a partner ID) that will be added to the ITS URL when redirecting to the source site.

Configuring Relying and Asserting Parties with WLST

SAML partners (Relying Parties and Asserting Parties) are maintained in a registry. You can configure SAML partners using the WebLogic Administration Console or using WebLogic Scripting Tool. The following example shows how you might configure two Relying Parties using WLST in online mode.

Listing 7-1 Creating Relying Parties with WLST

connect('weblogic','weblogic','t3://localhost:7001')

rlm=cmo.getSecurityConfiguration().getDefaultRealm()

cm=rlm.lookupCredentialMapper('samlv2cm')

rp=cm.newRelyingParty()

rp.setDescription('test post profile')

rp.setProfile('Browser/POST')

rp.setAssertionConsumerURL('http://domain.example.com:7001/saml_destination/acs')

rp.setAssertionConsumerParams(array(['APID=ap_00001'],String))

rp.setSignedAssertions(true)

rp.setEnabled(true)

cm.addRelyingParty(rp)

rp=cm.newRelyingParty()

rp.setDescription('test artifact profile')

rp.setProfile('Browser/Artifact')

rp.setAssertionConsumerURL('http://domain.example.com:7001/saml_destination/acs')

rp.setAssertionConsumerParams(array(['APID=ap_00002'],String))

rp.setARSUsername('foo')

rp.setARSPassword('bar')

rp.setSSLClientCertAlias('demoidentity')

rp.setEnabled(true)

cm.addRelyingParty(rp)

disconnect()

exit()

The following example shows how you might edit an existing Asserting Party. The example gets the Asserting Party, using its Asserting Party ID, and sets the Assertion Retrieval URL.

Listing 7-2 Editing an Asserting Party with WLST

connect('weblogic','weblogic','t3://localhost:7001')

rlm=cmo.getSecurityConfiguration().getDefaultRealm()

ia=rlm.lookupAuthenticationProvider('samlv2ia')

ap=ia.getAssertingParty('ap_00002')

ap.setAssertionRetrievalURL('https://hostname:7002/samlars/ars')

ia.updateAssertingParty(ap)

disconnect()

exit()