This chapter explains how to configure single sign-on with Web browsers and HTTP clients using SAML 1.1. WebLogic Server 12.1.3 supports single sign-on (SSO) based on SAML
This chapter includes the following sections:
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.
To enable single sign-on with SAML, configure WebLogic Server as either a source site or destination site as described in the sections that follow.
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
To configure a WebLogic Server instance in the role of a source site, complete the following main steps:
Create and configure a SAML Credential Mapping provider V2 in your security realm.
Configure the federation services for the server instance in the realm that will serve as a source site.
Create and configure the relying parties for which SAML assertions will be produced.
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.
To configure a WebLogic Server instance in the role of a destination site, complete the following main steps:
Create and configure a SAML Identity Assertion provider V2 in your security realm.
Configure the federation services for the server instance realm that will serve as a destination site.
Create and configure the asserting parties from which SAML assertions will be consumed.
Establish trust by registering the asserting parties' SSL certificates in the certificate registry maintained by the SAML Identity Assertion provider.
The following topics explain how to configure a WebLogic Server instance as a SAML 1.1 source site:
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.
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.
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.
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.
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.
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.
The following topics describe how to configure WebLogic Server as a SAML destination site:
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.
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 as follows.
Allow the WebLogic Server instance to serve as a SAML destination site by setting Destination Site Enabled to true.
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.
You can require all access to the Assertion Consumer Service to use SSL by setting FederationServicesMBean.acsRequiresSSL to true.
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.
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.
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.
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.
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.
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('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('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('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()