1. Administering Security for Oracle WebLogic Server
  2. Configuring Single Sign-On
  3. Configuring SAML 2.0 Services

23 Configuring SAML 2.0 Services

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

Configuring SAML 2.0 Services: Main Steps

Before you configure SAML 2.0 services, you must perform certain steps if you want to run this service in more than one WebLogic Server instance. You can then configure your WebLogic Server instance as either a Service Provider or Identity Provider.

A summary of the main steps you take to configure SAML 2.0 services is as follows:

  1. Determine whether you plan to have SAML 2.0 services running in more than one WebLogic Server instance in the domain. If so, do the following:

    1. Create a domain in which the RDBMS security store is configured.

      The RDBMS security store is required by the SAML 2.0 security providers in production environments so that the data they manage can be synchronized across all the WebLogic Server instances that share that data.

      Note that Oracle does not recommend upgrading an existing domain in place to use the RDBMS security store. If you want to use the RDBMS security store, you should configure the RDBMS security store at the time of domain creation. If you have an existing domain with which you want to use the RDBMS security store, create the new domain and migrate your existing security realm to it.

      See Managing the RDBMS Security Store.

    2. Ensure that all SAML 2.0 services are configured identically in each WebLogic Server instance. If you are configuring SAML 2.0 services in a cluster, each Managed Server in that cluster must be configured individually.

    3. Note the considerations described in Web Application Deployment Considerations for SAML 2.0.

  2. If you are configuring a SAML 2.0 Identity Provider site:

    1. Create and configure an instance of the SAML 2.0 Credential Mapping provider in the security realm.

    2. Configure the SAML 2.0 general services identically and individually in each WebLogic Server instance in the domain that will run SAML 2.0 services.

    3. Configure the SAML 2.0 Identity Provider services identically and individually in each WebLogic Server instance in the domain that will run SAML 2.0 services.

    4. Publish the metadata file describing your site, and manually distribute it to your Service Provider partners.

    5. Create and configure your Service Provider partners.

  3. If you are configuring a SAML 2.0 Service Provider site:

    1. Create and configure an instance of the SAML 2.0 Identity Assertion provider in the security realm.

      If you are allowing virtual users to log in via SAML, you need to create and configure an instance of the SAML Authentication provider. See Configuring the SAML Authentication Provider.

    2. Configure the SAML 2.0 general services identically and individually in each WebLogic Server instance in the domain that will run SAML 2.0 services.

    3. Configure the SAML 2.0 Service Provider services identically and individually in each WebLogic Server instance in the domain that will run SAML 2.0 services.

    4. Publish the metadata file describing your site, and manually distribute it to your Identity Provider partners.

    5. Create and configure your Identity Provider partners.

The sections that follow provide details about each set of main steps.

Note:

  • In this release of WebLogic Server, the SAML 2.0 implementation uses the SHA2 signature algorithm as the default for signing requests and responses. If required for backward compatibility, you can use the SHA1 signature algorithm by setting the Java system property com.bea.common.security.saml2.useSHA1SigAlgorithm to true. To do so, specify the following option in the Java command that starts WebLogic Server:

    -Dcom.bea.common.security.saml2.useSHA1SigAlgorithm=true

  • In this release of WebLogic Server, the SAML 2.0 implementation no longer uses certificates that are expired or not yet valid in SAML signing. To allow use of these certificates, set the Java system property com.bea.common.security.saml2.allowExpiredCerts to true. For example, specify the following option in the Java command that starts WebLogic Server:

    -Dcom.bea.common.security.saml2.allowExpiredCerts=true

  • The SAML 2.0 implementation does not use HttpServletResponse URL rewriting in SAML responses. Consequently, the JSESSIONID is not appended to SAML responses and, as a result, SAML 2.0 cannot be used with browsers that do not support cookies.

    To enable HttpServletResponse URL rewriting, set the Java system property com.bea.common.security.saml2.enableURLRewriting to true. For example, specify the following option in the Java command that starts WebLogic Server:

    -Dcom.bea.common.security.saml2.enableURLRewriting=true

Configuring SAML 2.0 General Services

Whether you configure a WebLogic Server instance as a SAML 2.0 Service Provider or as a SAML 2.0 Identity Provider, you must configure the server's general SAML 2.0 services using either the WebLogic Scripting Tool or the WebLogic Server Administration Console. Configuration of the SAML 2.0 general services for a WebLogic Server instance is controlled by the SingleSignOnServicesMBean.

You can access the SingleSignOnServicesMBean with the WebLogic Scripting Tool or through the WebLogic Server Administration Console, on the Environment > Servers > ServerName > Configuration > Federation Services > SAML 2.0 General page.

Note:

You cannot configure SAML 2.0 general services in a WebLogic Server instance until you have first configured either the SAML 2.0 Identity Assertion or SAML 2.0 Credential Mapping provider and restarted the server instance.

The following sections describe SAML 2.0 general services:

About SAML 2.0 General Services

The general SAML 2.0 services you configure include the following:

  • Whether you wish to enable the replicated cache

    Enabling the replicated cache is required if you are configuring SAML 2.0 services on two or more WebLogic Server instances in a domain, such as in a cluster. The replicated cache enables server instances to share and be synchronized with the data that is managed by the SAML 2.0 security providers; that is, either or both the SAML 2.0 Identity Assertion provider and the SAML 2.0 Credential Mapping provider.

    The RDBMS security store is required by the SAML 2.0 security providers in production environments so that the data they manage can be synchronized across all the WebLogic Server instances that share that data. (Use LDAP as the security store with the SAML 2.0 security providers only in development environments.)

    Therefore, prior to configuring SAML 2.0 services, the preferred approach is first to create a domain that is configured to use the RDBMS security store. See Managing the RDBMS Security Store.

  • Information about the local site

    The site information you enter is primarily for the benefit of the business partners in the SAML federation with whom you share it. Site information includes details about the local contact person who is your partners' point of contact, your organization name, and your organization's URL.

  • Published site URL

    This URL specifies the base URL that is used to construct endpoint URLs for the various SAML 2.0 services. The published site URL should specify the host name and port at which the server is visible externally, which might not be the same at which the server is accessed locally. For example, if SAML 2.0 services are configured in a cluster, the host name and port may correspond to the load balancer or proxy server that distributes client requests to the Managed Servers in that cluster.

    The published site URL should be appended with /saml2. For example:

    https://www.avitek.com:7001/avitek-domain/aviserver/saml2

  • Entity ID

    The entity ID is a human-readable string that uniquely distinguishes your site from the other partner sites in your federation. When your partners need to generate or consume an assertion, the SAML 2.0 services use the entity ID as part of the process of identifying the partner that corresponds with that assertion.

  • Whether recipient check is enabled

    If enabled, the recipient of the authentication request or response must match the URL in the HTTP Request.

  • Whether TLS/SSL client authentication is required for invocations on the Artifact Resolution Service. If enabled, SAML artifacts are encrypted when transmitted to partners.

  • Transport Layer Security keystore alias and passphrase, the values used for securing outgoing communications with partners.

  • Whether Basic authentication client authentication is required when your partners invoke the HTTPS bindings of the local site.

    If you enable this setting, you also specify the client username and password to be used. These credentials are then included in the published metadata file that you share with your federated partners.

  • Whether requests for SAML artifacts received from your partners must be signed.

  • Configuration settings for the SAML artifact cache.

  • Keystore alias and passphrase for the key to be used when signing documents sent to your federated partners, such as authentication requests or responses.

For information about the steps for configuring SAML 2.0 general services, see Configure SAML 2.0 general services in the Oracle WebLogic Server Administration Console Online Help.

Publishing and Distributing the Metadata File

The local site information that is needed by your federated partners — such as the local site contact information, entity ID, published site URL, whether TLS/SSL client authentication is required, and so on — is published to a metadata file by clicking Publish Meta Data in the SAML 2.0 General console page.

When you publish the metadata file, you specify an existing directory on the local machine in which the file can be created. The process of distributing the metadata file to your federated partners is a detail that is not implemented by WebLogic Server. However, you may send this file via a number of commonly used mechanisms suitable for securely transferring electronic documents, such as encrypted email or secure FTP.

Keep the following in mind regarding the metadata file:

  • Before you publish the metadata file, you should configure the Identity Provider and/or Service Provider services for the SAML 2.0 roles in which the WebLogic Server instances in your domain are enabled to function.

    The configuration data for the SAML 2.0 services your site offers that is needed by your federated partners is included in this metadata file, greatly simplifying the tasks your partners perform to import your signing certificates, identify your site's SAML 2.0 service endpoints, and use the correct binding types for connecting to your site's services, and so on.

  • You should have only a single version of the metadata file that you share with your federated partners, even if your site functions in the role of Service Provider with some partners and Identity Provider with others. By having only a single version of the metadata file, you reduce the likelihood that your configuration settings might become incompatible with those of a partner.

  • If you change the local site's SAML 2.0 configuration, you should update your metadata file. Because the metadata file is shared with your partners, it will be convenient to minimize the frequency with which you update your SAML 2.0 configuration so that your partners can minimize the need to make concomitant updates to their own partner registries.

  • When you receive a metadata file from a federated partner, place it in a location that can be accessed by all the nodes in your domain in which SAML 2.0 services are configured. At the time you create a partner, you bring the contents the partner's metadata file into the partner registry.

Operations on the metadata file are available via the com.bea.security.saml2.providers.registry.Partner Java interface.

Configuring an Identity Provider Site for SAML 2.0 Single Sign-On

Before you configure SAML 2.0 Identity Provider services for your WebLogic Server instance, you must first configure a SAML 2.0 Credential Mapping provider instance in the security realm, and then configure SAML 2.0 general services. After performing these prerequisites, configure SAML 2.0 Identity Provider Services using the WebLogic Scripting Tool (WLST), or through the WebLogic Server Administration Console.

Note:

When WebLogic Server is configured as an Identity Provider, it does not support SAML Single Logout.

This section presents the following topics:

Configure the SAML 2.0 Credential Mapping Provider

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

Configure the SAML 2.0 Credential Mapping provider as a SAML authority. Attributes you specify include the following:

  • Issuer URI

  • Name Qualifier

  • Life span attributes for generated SAML 2.0 assertions

  • Name mapper class name

  • Whether generated assertions should include attribute information, which specify the groups to which the identity contained in the assertion belongs

After you configure the SAML 2.0 Credential Mapping provider, configure SAML 2.0 general services, as described in Configuring SAML 2.0 General Services.

Configure SAML 2.0 Identity Provider Services

Configuration of a WebLogic Server instance as a SAML 2.0 Identity Provider site is controlled by the SingleSignOnServicesMBean. You can access the SingleSignOnServicesMBean using the WebLogic Scripting Tool (WLST), or through the WebLogic Server Administration Console by using the Environment > Servers > ServerName > Configuration > Federation Services > SAML 2.0 Identity Provider page.

The sections that follow summarize the configuration tasks. For more information about performing these tasks, see Configure SAML 2.0 Identity Provider services in the Oracle WebLogic Server Administration Console Online Help.

Enable the SAML 2.0 Identity Provider Site

From the SAML 2.0 Identity Provider page in the console, allow the WebLogic Server instance to serve as an Identity Provider site by setting the Enabled attribute to true.

Specify if Authentication Requests Must Be Signed

Enable or disable the Only Accept Signed Authentication Requests attribute that determines whether incoming authentication requests must be signed. If enabled, then the authentication requests that are not signed are not accepted.

Specify a Custom Login Web Application

Optionally, you may use a custom login web application to authenticate users into the Identity Provider site. To configure a custom login web application, enable the Login Customized attribute and specify the URL of the web application.

Enable Binding Types

Oracle recommends enabling all the available binding types for the endpoints of the Identity Provider services; namely, POST, Redirect, and Artifact. Optionally you may select a preferred binding type.

Configure Assertion Encryption
Set the following attributes to enable and configure encryption for SAML 2.0 assertions:
  • Select Assertion Encryption to enable encryption for SAML 2.0 assertions.
  • Optionally, update the default values of encryption algorithms in the Key Encryption Algorithm and the Data Encryption Algorithm fields.
Publish Your Site's Metadata File

After you have configured the SAML 2.0 general services and Identity Provider services, publish your site's metadata file and distribute it to your federated partners, as described in Publishing and Distributing the Metadata File.

Create and Configure Web Single Sign-On Service Provider Partners

A SAML 2.0 Service Provider partner is an entity that consumes the SAML 2.0 assertions generated by the Identity Provider site. The configuration of Service Provider partners is available from the WebLogic Server Administration Console, using the Security Realms > RealmName > Providers > Credential Mapper > SAML2CredentialMapperName > Management page.

The attributes that can be set on this console page can also be accessed programmatically via a set of Java interfaces, which are identified in the sections that follow.

See Create a SAML 2.0 Web Single Sign-on Service Provider partner in the Oracle WebLogic Server Administration Console Online Help for complete details about the specific steps for configuring a Service Provider partner. For a summary of the site information, signing certificates, and service endpoint information available when you configure a web single sign-on partner, see Viewing Partner Site, Certificate, and Service Endpoint Information.

This section includes the following topics:

Obtain Your Service Provider Partner's Metadata File

Before you configure a Service Provider partner for web single sign-on, you need to obtain the partner's SAML 2.0 metadata file via a trusted and secure mechanism, such as encrypted email or an SSL-enabled FTP site. Your partner's metadata file describes the partner site and binding support, includes the partner's certificates and keys, contains your partner's SAML 2.0 service endpoints, and more. Copy the partner's metadata file into a location that can be accessed by each node in your domain configured for SAML 2.0.

The SAML 2.0 metadata file is described in Publishing and Distributing the Metadata File.

Create Partner and Enable Interactions

To create and enable a Service Provider partner for web single sign-on:

  1. From the Management tab of the SAML 2.0 Credential Mapping provider page, specify the partner's name and metadata file.
  2. From the General tab of the partner configuration page, enable interactions between the partner and the WebLogic Server instance.

WebLogic Server provides the com.bea.security.saml2.providers.registry.Partner Java interface for configuring these attributes.

Configure How Assertions are Generated

Optionally from the General tab of the partner configuration page in the console, you can configure the following attributes of the SAML 2.0 assertions generated specifically for this Service Provider partner:

  • The Service Provider Name Mapper Class name

    This is the Java class that overrides the default username mapper class with which the SAML 2.0 Credential Mapping provider is configured in this security realm.

  • Time to Live attributes

    The Time to Live attributes specify the interval of time during which the assertions generated for this partner are valid. These attributes prevent expired assertions from being used.

  • Whether to generate attribute information that is included in assertions

    If enabled, the SAML 2.0 Credential Mapping provider adds, as attributes in the assertion, the groups to which the corresponding user belongs.

  • Whether the assertions sent to this partner must be disposed of immediately after use

  • Whether this server's signing certificate is included in assertions generated for this partner

WebLogic Server provides the com.bea.security.saml2.providers.registry.SPPartner Java interface for configuring these attributes.

Configure How Documents Are Signed

You can use the General tab of the Service Provider partner configuration page to determine how the following documents exchanged with this partner must be signed:

The attributes for specifying whether this partner accepts only signed assertions, or whether authentication requests must be signed, are read-only: they are derived from the partner's metadata file.

Configure Artifact Binding and Transport Settings

Optionally, you also use the General tab of the Service Provider partner configuration page to configure the following:

  • Whether SAML artifacts are delivered to this partner via the HTTP POST binding. If so, you may also specify the URI of a custom web application that generates the HTTP POST form for sending the SAML artifact.

  • The URI of a custom web application that generate the HTTP POST form for sending request or response messages via the POST binding.

Operations on these attributes are available via the com.bea.security.saml2.providers.registry.WebSSOPartner Java interface.

For added security in the exchange of documents with this partner, you can also specify a client user name and password to be used by the Service Provider partner when connecting to the local site's binding using Basic authentication. This attribute is available via the com.bea.security.saml2.providers.registry.BindingClientPartner Java interface.

Configuring a Service Provider Site for SAML 2.0 Single Sign-On

As a prerequisite to configuring a SAML 2.0 Service Provider site, you must configure a SAML 2.0 Identity Assertion provider instance in your security realm, and then configure SAML 2.0 general services. If you plan to enable virtual users, you can optionally configure the SAML Authentication provider. After fulfilling the prerequisites, configure SAML 2.0 Service Provider Services using the WebLogic Scripting Tool (WLST) or the WebLogic Server Administration Console.

Note:

As described in session-descriptor in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server, the cookie-path element defines the session tracking cookie path. If not set, this element defaults to / (slash), where the browser sends cookies to all URLs served by WebLogic Server.

The WebLogic Server SAML 2.0 Service Providers require that the cookie-path be / (slash). If you set any other value for cookie-path, SSO fails for the SAML 2.0 Service Providers.

This section presents the following topics:

Configure the SAML 2.0 Identity Assertion Provider

In your security realm, create an instance of the SAML 2.0 Identity Assertion provider. The SAML 2.0 Identity Assertion provider is not part of the default security realm. The attributes you specify for the SAML 2.0 Identity Assertion provider include the following:

  • Whether the replicated cache is enabled

    If you are configuring SAML 2.0 Identity Provider services in two or more server instances in the domain, this attribute must be enabled.

  • A custom name mapper class that overrides the default SAML 2.0 assertion name mapper class

For more information about this security provider, see Configuring a SAML 2.0 Identity Assertion Provider for SAML 2.0.

Configure the SAML Authentication Provider

If you plan to enable virtual users, or consume attribute statements contained in assertions that you receive from your Identity Provider partners, you need to create and configure an instance of the SAML Authentication provider. See Configuring the SAML Authentication Provider.

Configure SAML 2.0 General Services

After configuring the SAML 2.0 Identity Assertion provider, and optionally the SAML Authentication provider, configure the SAML 2.0 general services, as described in Configuring SAML 2.0 General Services.

Configure SAML 2.0 Service Provider Services

Configuration of a WebLogic Server instance as a SAML 2.0 Service Provider site is controlled by the SingleSignOnServicesMBean. You can access the SingleSignOnServicesMBean using the WebLogic Scripting Tool (WLST), or through the WebLogic Server Administration Console using the Environment > Servers > ServerName > Configuration > Federation Services > SAML 2.0 Service Provider page.

You configure the SAML 2.0 Service Provider site attributes as summarized in the sections that follow. For more information about these configuration tasks, see Configure SAML 2.0 Service Provider services in the Oracle WebLogic Server Administration Console Online Help.

This section includes the following topics:

Enable the SAML 2.0 Service Provider Site

From the Federation Services: SAML 2.0 Identity Provider page in the console, allow the WebLogic Server instance to serve as a Service Provider site by setting the Enabled attribute to true.

Specify How Documents Must Be Signed

Optionally, you may enable or disable the following attributes that set the document signing requirements:

  • Always Sign Authentication Requests that determines whether authentication requests sent to Identity Provider partners are signed.

  • Only Accept Signed Assertions that determines whether assertions received from Identity Provider partners are signed. Note that this option is enabled by default to ensure that all incoming SAML 2.0 assertions must be signed.

Specify How Authentication Requests Are Managed

Optionally you may enable the following attributes of the authentication request cache:

  • Maximum cache size

  • Time-out value for authentication requests, which establishes the time interval beyond which stored authentication requests are expired

Enable Binding Types

Oracle recommends enabling all the available binding types for the endpoints of the Service Provider services; namely, POST, and Artifact. Optionally you may specify a preferred binding type.

Set Default URL

Optionally, you may specify the URL to which unsolicited authentication responses are sent if they do not contain an accompanying target URL.

Configure Assertion Encryption Key
Specify values for the following attributes to configure assertion encryption key:
  • Assertion Key Pass Phrase that is required to retrieve the local site assertion key from the keystore
  • Assertion Key Alias that is an alias for the keystore that contains the certificate and private key used to encrypt and decrypt the SAML assertions
Optionally, update the default list of encryption algorithms in the Meta Data Encryption Algorithms field.
Configure SAML Single Logout

SAML Single Logout (SLO) complements SAML Single Sign On by logging users out of all of the applications in their current SSO session at once. SAML SLO decreases the number of connections that remain active but unused, therefore reducing the opportunity for unauthorized access.

You can configure the behavior of the SAML SLO. Use the SLO Redirect URI option to determine where users are sent after they log out of an application. If no SLO Redirect URI is set, users are directed to the Default URL. You can also change the binding of the SAML SLO requests, which is set to HTTP Redirect by default, but can also be set to HTTP POST.

SAML SLO is enabled by default on WebLogic Server instances that act as Service Providers but you can choose to disable it if you want users to log out of each application separately.

Create and Configure Web Single Sign-On Identity Provider Partners

A SAML 2.0 Identity Provider partner is an entity that generates SAML 2.0 assertions consumed by the Service Provider site. The configuration of Identity Provider partners is available from the WebLogic Server Administration Console, using the Security Realms > RealmName > Providers > Authentication > SAML2IdentityAsserterName > Management page.

The attributes that can be set on this console page can also be accessed programmatically via a set of Java interfaces, which are identified in the sections that follow.

See Create a SAML 2.0 Web Single Sign-on Identity Provider partner in the Oracle WebLogic Server Administration Console Online Help for complete details about the specific steps for configuring a Service Provider partner.

For a summary of the site information, signing certificates, and service endpoint information available when you configure a web single sign-on partner, see Viewing Partner Site, Certificate, and Service Endpoint Information.

The following sections summarize tasks for configuring an Identity Provider partner:

Obtain Your Identity Provider Partner's Metadata File

Before you configure an Identity Provider partner for web single sign-on, you need to obtain the partner's SAML 2.0 metadata file via a trusted and secure mechanism, such as encrypted email or an SSL-enabled FTP site. Your partner's metadata file describes that partner site and binding support, includes the partner's certificates and keys, and so on. Copy the partner's metadata file into a location that can be accessed by each node in your domain configured for SAML 2.0.

The SAML 2.0 metadata file is described in Publishing and Distributing the Metadata File.

Create Partner and Enable Interactions

To create an Identity Provider partner and enable interactions for web single sign-on:

  • From the Management tab of the SAML 2.0 Identity Assertion configuration page, specify the partner's name and metadata file.

  • From the General tab of the partner configuration page, enable interactions between the partner and the WebLogic Server instance.

WebLogic Server provides the com.bea.security.saml2.providers.registry.Partner Java interface for configuring these attributes.

Configure Authentication Requests and Assertions

Optionally, you can configure the following attributes of the authentication requests generated for, and assertions received from, this Identity Provider partner:

  • The Identity Provider Name Mapper Class name

    This is the custom Java class that overrides the default username mapper class with which the SAML 2.0 Identity Assertion provider is configured in this security realm. The custom class you specify is used only for identities contained in assertions received from this particular partner.

    Operations on this attribute are available in the com.bea.security.saml2.providers.registry.IdPPartner Java interface.

  • Whether the identities contained in assertions received from this partner are mapped to virtual users in the security realm

    Note:

    To use this attribute, you must have a SAML Authentication provider configured in the realm.

    Operations on this attribute are available in the com.bea.security.saml2.providers.registry.IdPPartner Java interface.

  • Whether to consume attribute information contained in assertions received from this partner

    If enabled, the SAML 2.0 Identity Assertion provider extracts attribute information from the assertion, which it uses in conjunction with the SAML Authentication provider (which must be configured in the security realm) to determine the groups in the security realm to which the corresponding user belongs.

    Operations on this attribute are available in the com.bea.security.saml2.providers.registry.IdPPartner Java interface.

  • Whether authentication requests sent to this Identity Provider partner must be signed. This is a read-only attribute that is derived from the partner's metadata file.

    Operations on this attribute are available in the com.bea.security.saml2.providers.registry.WebSSOIdPPartner Java interface.

  • Whether SAML artifact requests received from this Identity Provider partner must be signed.

    Operations on this attribute are available in the com.bea.security.saml2.providers.registry.WebSSOIdPPartner Java interface.

Configure Redirect URIs

You can configure a set of URIs that, if invoked by an unauthenticated user, cause the user request to be redirected to the Identity Provider partner where the user can be authenticated.

Note:

If you configure one or more redirect URIs, remember to set a security policies on them as well; otherwise the web container will not attempt to authenticate the user and, consequently, not redirect the user's request to the Identity Provider partner.

WebLogic Server provides the com.bea.security.saml2.providers.registry.WebSSOIdPPartner Java interface for configuring this attribute.

Configure Binding and Transport Settings

Optionally, you also use the General tab of the Service Provider partner configuration page to configure the following:

  • Whether SAML artifacts are delivered to this partner via the HTTP POST method. If so, you may also specify the URI of a custom web application that generates the HTTP POST form for sending the SAML artifact.

  • The URL of the custom web application that generates the POST form for carrying the SAML response for POST bindings to this Identity Provider partner.

  • The URL of the custom web application that generates the POST form for carrying the SAML response for Artifact bindings to this Identity Provider partner.

Operations on these attributes are available via the com.bea.security.saml2.providers.registry.WebSSOPartner Java interface.

For added security in the exchange of documents with this partner, you can also specify a client user name and password to be used by this Identity Provider partner when connecting to the local site's binding using Basic authentication. This attribute is available via the com.bea.security.saml2.providers.registry.BindingClientPartner Java interface.

Configuring SAML Encryption Using WLST

You can configure encryption for SAML 2.0 assertions using WLST scripts that perform operations on the SingleSignOnServicesMBean. Example 23-1 shows the use of WLST to enable encryption of SAML 2.0 assertions, and set the preferred key encryption and data encryption algorithms.

Example 23-1 Configure SAML Encryption Settings

edit()
startEdit()
srvr = cmo.lookupServer('myadmin')
realm = cmo.getSecurityConfiguration().getDefaultRealm()
 
################################################################################
# SAML2 SSO Service Settings
################################################################################
ssoSvc = srvr.getSingleSignOnServices()
ssoSvc.setAssertionEncryptionEnabled(true)
ssoSvc.setDataEncryptionAlgorithm('aes192-cbc')
ssoSvc.setKeyEncryptionAlgorithm('rsa-oaep')

Viewing Partner Site, Certificate, and Service Endpoint Information

When you configure SAML 2.0 partners, the partner configuration pages displayed by the WebLogic Server Administration Console include tabs for viewing and configuring additional information about the partner.

  • The Site tab displays information about the Service Provider partner, which is derived from the partner's metadata file. The data in this tab is read-only.

    WebLogic Server provides the com.bea.security.saml2.providers.registry.MetadataPartner Java interface for partner site information.

  • The Single Sign-On Signing Certificate tab displays details about the partner's signing certificate, which are also derived from the partner's metadata file. The data in this tab is read-only.

    Operations on these attributes are available from the com.bea.security.saml2.providers.registry.WebSSOPartner Java interface.

  • The Transport Layer Client Certificate tab displays partner's transport layer client certificate. You can optionally import this certificate by clicking Import Certificate from File.

    Operations on this attribute are available from the com.bea.security.saml2.providers.registry.BindingClientPartner Java interface.

  • When configuring Service Provider partners, the Assertion Consumer Service Endpoints tab is available, which displays the Service Provider partner's ACS endpoints. This data is also available from the com.bea.security.saml2.providers.registry.WebSSOSPPartner Java interface.

  • When configuring Identity Provider partners, the Single Sign-On Service Endpoints tab is available, which displays the Identity Provider partner's single sign-on service endpoints. If the IdP partner supports SAML Single Logout, the Single Logout Endpoints tab is also available, which displays the Identity Provider partner's single logout service endpoints. This data is also available from the com.bea.security.saml2.providers.registry.WebSSOIdPPartner Java interface.

  • The Artifact Resolution Service Endpoints tab displays the partner's ARS endpoints. This data is also available from the com.bea.security.saml2.providers.registry.WebSSOPartner Java interface.

Web Application Deployment Considerations for SAML 2.0

When deploying web applications for SAML-based SSO in a clustered environment, you must keep in mind certain considerations for preventing SAML-based single sign-on from failing.

Deployment Descriptor Recommendations

Note the following recommendations regarding the use of the following elements in deployment descriptor files:

  • relogin-enabled

  • cookie-name

This section includes the following topics:

Use of relogin-enabled with CLIENT-CERT Authentication

If a user logs in to a web application and tries to access a resource for which that user is not authorized, an HTTP FORBIDDEN (403) response is generated. This is standard web application behavior. However, for backwards compatibility with earlier releases, WebLogic Server permits web applications to use the relogin-enabled element in the weblogic.xml deployment descriptor file, so that the response to an access failure results in a request to authenticate. In certain circumstances, it can cause SAML 2.0 based web single sign-on to fail.

Normally, the SAML 2.0 Assertion Consumer Service (ACS) logs the user into the application and redirects the user request to the target web application. However, if that web application is enabled for SAML 2.0 single sign-on, is protected by CLIENT-CERT authentication, and has the relogin-enabled deployment descriptor element set to true, an infinite loop can occur in which a request to authenticate a user is issued repeatedly. This loop can occur when a user is logged in to the web application and attempts to access a resource for which the user is not permitted: instead of generating a FORBIDDEN message, a new authentication request is generated that triggers another SAML 2.0 based web single sign-on attempt.

To prevent this situation from occurring in a web application that is protected by CLIENT-CERT authentication, either remove the relogin-enabled deployment descriptor element for the web application, or set the element to false. This enables standard web application authentication behavior.

Use of Non-default Cookie Name

When the Assertion Consumer Service logs in the Subject contained in an assertion, an HTTP servlet session is created using the default cookie name JSESSIONID. After successfully processing the assertion, the ACS redirects the user's request to the target web application. If the target web application uses a cookie name other than JSESSIONID, the Subject's identity is not propagated to the target web application. As a result, the servlet container treats the user as if unauthenticated, and consequently issues an authentication request.

To avoid this situation, do not change the default cookie name when deploying web applications in a domain that are intended to be accessed by SAML 2.0 based single sign-on.

Login Application Considerations for Clustered Environments

Note the following two login limitations that are rare in clustered environments, but if they occur, they may prevent a single sign-on session from succeeding.

  • When an Identity Provider's single sign-on service receives an authentication request, it redirects that request to the login application to authenticate the user. The login application must execute on the same cluster node as that single sign-on service. If not, the Identity Provider is unable to produce a SAML 2.0 assertion even if the authentication succeeds.

    Under normal circumstances, the login application executes on the same node as the single sign-on service, so likelihood of the authentication request being redirected to a login application executing on a different node in the domain is very small. However, it may happen if an authentication request is redirected by a cluster node different than the one hosting the login application. You can almost always prevent this situation from occurring if you configure the Identity Provider to use the default login URI with Basic authentication.

  • When the SAML 2.0 Assertion Consumer Service (ACS) successfully consumes an assertion, it logs in the Subject represented by the assertion. The ACS then redirects the user request to the target application. Normally, the target application executes on the same node as the ACS. However, in rare circumstances, the target application to which is the user request is redirected executes on a cluster node other than the one hosting the ACS on which the login occurred. When this circumstance occurs, the identity represented by the assertion is not propagated to the target application node. The result is either another attempt at the single sign-on process, or denied access.

    Because the target application executes on the same node as the ACS, this situation is expected to occur very rarely.

Enabling Force Authentication and Passive Attributes is Invalid

When configuring SAML 2.0 Service Provider services, enabling both the Force Authentication and Passive attributes is an invalid configuration that WebLogic Server is unable to detect. If both these attributes are enabled, and an unauthenticated user attempts to access a resource that is hosted at the Service Provider site, an exception is generated and the single sign-on session fails.

Even if the user is already authenticated at the Identity Provider site and Force Authentication is enabled, the user is forced to authenticate again at the Identity Provider site.

Enabling SAML SLO on Web Applications

You can enable SAML SLO on a target web application deployed in a WebLogic Server instance acting as a Service Provider.

There are two ways to configure SAML SLO on a web application:

  • Expose the SP SAML SLO init endpoint URL to authenticated SSO users. When authenticated SSO users access the URL, it triggers the SAML SLO process. You can also include the optional slo_redirect_uri parameter to specify where users are sent after logging out. For example, /saml2/sp/slo/init[?slo_redirect_uri=<URI>].
  • Configure the application's logout page to redirect to the SAML SLO init endpoint.

    Do not invoke the logout() method of the javax.servlet.http.HttpServletRequest object on the logout page to sign out users. The SLO init service will perform that step.

You can find the SAML SLO endpoint URL in the WebLogic Server published metadata file. For example:

<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://<hostname>:<port>/saml2/sp/slo"/>
# or
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<hostname>:<port>/saml2/sp/slo"/>

If the third-party SAML IdP does not support importing an SP partner's metadata, you must enter the WebLogic Server SLO endpoint URL manually and select one of the two supported bindings.