23 Configuring SAML 1.1 Services

Learn how to configure single sign-on in Oracle WebLogic Server with Web browsers and HTTP clients using SAML 1.1.

In addition to the topics described in these sections, see Creating Assertions for Non-WebLogic SAML 1.1 Relying Parties in Developing Applications with the WebLogic Security Service for information on how to create a custom SAML name mapper that maps Subjects to specific SAML 1.1 assertion attributes required by a third-party SAML Relying Party.

This chapter includes the following sections:

Enabling Single Sign-on with SAML 1.1: Main Steps

To enable single sign-on with SAML, configure WebLogic Server as either a source site or destination site.

Note:

In this release of WebLogic Server, the SAML 1.1 implementation is changed and no longer uses HttpServletResponse URL rewriting in SAML responses. Consequently, the JSESSIONID is no longer appended to SAML responses. However, this change means that SAML 1.1 cannot be used with browsers that do not support cookies.

To enable HttpServletResponse URL rewriting, set the Java system property weblogic.security.saml.enableURLRewriting to true. For example, you can do this by specifying the following option in the Java command that starts WebLogic Server:

-Dweblogic.security.saml.enableURLRewriting=true

Configuring a Source Site: Main Steps

To configure a WebLogic Server instance in the role of a source site, complete the following main steps:

  1. Create and configure a SAML Credential Mapping provider V2 in your security realm.
  2. Configure the federation services for the server instance in the realm that will serve as a source site.
  3. Create and configure the relying parties for which SAML assertions will be produced.
  4. If you want to require relying parties to use SSL certificates to connect to the source site, add any such certificates to the SAML credential mapping provider's Certificate Registry.

Configuring a Destination Site: Main Steps

To configure a WebLogic Server instance in the role of a destination site, complete the following main steps:

  1. Create and configure a SAML Identity Assertion provider V2 in your security realm.
  2. Configure the federation services for the server instance realm that will serve as a destination site.
  3. Create and configure the asserting parties from which SAML assertions will be consumed.
  4. Establish trust by registering the asserting parties' SSL certificates in the certificate registry maintained by the SAML Identity Assertion provider.

Configuring a SAML 1.1 Source Site for Single Sign-On

Learn how to configure a WebLogic Server instance as a SAML 1.1 source site.

Configure the SAML 1.1 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 for SAML 1.1.

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

Configure the Source Site Federation Services

Configuration of a WebLogic Server instance as a SAML 1.1 source site is controlled by the FederationServicesMBean. Access the FederationServicesMBean with the WebLogic Scripting Tool or through the WebLogic Server Administration Console, on the Environment > Servers > ServerName > Configuration > Federation Services > SAML 1.1 Source Site page. See Configure SAML 1.1 source services in the Oracle WebLogic Server Administration Console Online 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 the 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.

    Specify the URIs for the Intersite Transfer Service and (to support Browser/Artifact profile) the Assertion Retrieval Service. (You also specify the Intersite Transfer Service URI when you configure a Relying Party.)

    The default URI FederationServicesMBean.IntersiteTransferURIs values are shown in Table 23-1.

    Table 23-1 Intersite Transfer URIs

    Default URI Values Description

    /samlits_ba/its

    BASIC authentication, POST or Artifact profile

    /samlits_ba/its/post

    BASIC authentication, POST profile

    /samlits_ba/its/artifact

    BASIC authentication, Artifact profile

    /samlits_cc/its

    Client cert authentication, POST or Artifact profile

    /samlits_cc/its/post

    Client cert authentication, POST profile

    /samlits_cc/its/artifact

    Client cert authentication, Artifact profile

    The Intersite Transfer URI text box allows you to accept the default values as-is, or modify them as you choose. Each URI includes the application context, followed by /its, /its/post, or /its/artifact. The provided application contexts are /samlits_ba (BASIC authentication) or /samlits_cc (client certificate authentication). You could also specify an application-specific context if needed, for example /yourapplication/its, but in most cases the defaults provide the easiest configuration option.

    If you specify these URIs as /samlits_ba/its, if a redirect occurs and the user's session on the source site has timed out, a BASIC authentication dialog is presented. If you instead want to use a FORM dialog, the URI should point to a custom Web application that authenticates users and then forwards to the actual ITS URI.

  • 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 WebLogic Server Administration Console, on the Security Realms > RealmName > Providers > Credential Mapper > SAMLCredentialMapperName > Management > Relying Parties page. See Create a SAML 1.1 Relying Party and Configure a SAML 1.1 Relying Party in the Oracle WebLogic Server Administration Console Online Help.

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

The following topics explain how to configure Relying Parties:

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 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.

For WebLogic Server browser SSO configurations that communicate with another WebLogic Server instance, set the ID of the SAML Asserting Party (APID) in the relying party ACS parameters.

This parameter is required with the V2 providers in order for the browser profile configurations to work. That is, the ACS looks for an asserting party ID (APID) as a form parameter of the incoming request, and uses this to look up the configuration before performing any other processing.

The APID parameter also removes the need for you to specify a Target URL parameter for browser SSO. The Target URL is used for Web service configurations.

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 WebLogic Server Administration Console on the Environment: Servers > ServerName > Configuration > Federation Services > SAML 1.1 Source Site page.

Configuring a SAML 1.1 Destination Site for Single Sign-On

Learn 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 for SAML 1.1.

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 WebLogic Server Administration Console, using the Environment: Servers > ServerName > Configuration > Federation Services > SAML 1.1 Destination Site page.

Configure the SAML destination site attributes 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.

Specify Allowed Target Hosts

Specify the list of allowed destination hosts where the target URL may be redirected by using the FederationServicesMBean.AllowedTargetHosts attribute. If no allowed target hosts are specified and the list is empty, then the target redirect URL will not be checked.

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 SSL client identity is used to contact the ARS at the source site for Artifact profile. 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 WebLogic Server 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 WebLogic Server Administration Console, using the Security Realms > RealmName > Providers > Authentication > SAMLIdentityAsserterV2 > Management: Asserting Parties page. See Create a SAML 1.1 Asserting Party and Configure a SAML 1.1 Asserting Party in the Oracle WebLogic Server Administration Console Online Help.

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

The following topics explain key details about configuring an Asserting Party:

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 that will be added when redirecting to the source site.

For WebLogic Server browser SSO configurations that communicate with another WebLogic Server instance, you must set the ID of the SAML Relying Party (RPID) in the Asserting Party ITS parameters.

This parameter is required with the V2 providers in order for the browser profile configurations to work. That is, the ITS looks for the RPID as a form parameter of the incoming request, and uses this to look up the configuration before performing any other processing.

The RPID parameter also removes the need for you to specify a Target URL parameter for WebLogic Server-to-WebLogic Server browser SSO configurations only. The Target URL is used for Web service configurations.

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 Server Administration Console or using WebLogic Scripting Tool.

The following example shows how you might configure two Relying Parties using WLST in online mode. Note that the example sets the ID of the SAML Asserting Party (APID) in the relying party Assertion Consumer Service parameters. For WebLogic Server browser SSO configurations that communicate with another WebLogic Server instance, you must set the ID of the SAML Asserting Party (APID) in the relying party ACS parameters. (You would also set the ID of the SAML Relying Party (RPID) in the asserting party ITS parameters.)

The demoidentity certificate alias referenced in the example comes from the source site's demo SSL identity for the domain.

The APID is required for WebLogic Server-to-WebLogic Server browser SSO configurations only. This parameter is required with the V2 providers in order for the browser profile configurations to work.

Example 23-1 Creating Relying Parties with WLST

connect('','','t3://host:port')
Please enter your username :
Please enter your password :
...
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('password')
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.

Example 23-2 Editing an Asserting Party with WLST

connect('','','t3://host:port')
Please enter your username :adminuser
Please enter your password :
...
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()