SAML Module

Enterprise

Mule Enterprise offers support for the Security Assertion Markup Language (SAML), which is a standard for exchange of security information between federated systems. For more information on SAML, see http://saml.xml.org/wiki/saml-wiki-knowledgebase.

This module implements SAML 1.1.

Mule’s CXF Module includes WS-Security with a SAML option that supports SAML 2.0.

Using the SAML Module

This section describes how to configure the SAML module in your Mule configuration.

Adding the SAML Module JAR

The use the SAML module, the mule-module-saml JAR file must be in a location on the classpath of your application.

Configuring the Security Manager

To use the features of the SAML module, add the SAML module namespace to your Mule configuration file as follows:

<mule xmlns:saml="http://www.mulesoft.org/schema/mule/ee/saml"
      xsi:schemaLocation="http://www.mulesoft.org/schema/mule/ee/saml http://www.mulesoft.org/schema/mule/ee/saml/current/mule-saml-ee.xsd">
    <!-- Rest of your mule configuration -->

</mule>

Next, you configure the SAML security manager as shown below. The following example starts off with the definition of the SAML security manager and its accompanying security provider. The security provider specifies the default security realm to use by security filters if none is specified. This is especially useful in case you have only one security realm.

<saml:security-manager>
  <saml:saml-security-provider name="samlSecurityProvider" default-realm="senderVouches">
    <saml:keystore-provider name="default-key-provider"
      key-store-file="classpath:saml.ks"
      key-store-type="JKS"
      key-store-password="changeit"/>
    <saml:sender-vouches-realm name="senderVouches" sign-key-alias="mulesaml"
      sign-key-password="changeit" key-provider-ref="default-key-provider" resign-assertions="true"/>
    <saml:holder-of-key-realm name="holderOfKey" key-provider-ref="default-key-provider" />
  </saml:saml-security-provider>
</saml:security-manager>

Within the security provider, you define a key provider, which reads keys and certificates from a standard Java keystore file. You configure this file using the normal Spring options to define resources. In this case, the keystore is read from the classpath.

In this example, two security realms are defined. One uses the sender vouches SAML scheme and is also the default realm. The other is a holder of key realm. Both use the same key provider as defined above. For more information on these realms, see Choosing a SAML Profile below.

Configuring Security on an Connector

Once you’ve defined a security manager, you can configure security filters on CXF connectors as shown in the examples below. The first example does not specify a security realm, so the default realm is used. Both filters specify the same certificate that is used to verify the SAML assertions as issued by the assertion provider.

<saml:cxf-security-filter certificate-alias="mulesaml"/>

<saml:cxf-security-filter certificate-alias="mulesaml" security-realm="non-default"/>

Additionally, you must create specific configurations for the various transports to instruct them to support SAML. For example, CXF has to be instructed to configure WSS4j for usage of SAML as WS-Security profile.

Choosing a SAML Profile

SAML defines two different profiles: Sender-vouches (SV) and Holder-of-key (HOK).

The Sender Vouches profile means that the sender of a message is authorized to act for one of its users towards another system. In this case, the sender of the message vouches its correctness. If both systems trust each other, this profile is appropriate.
Holder-of-key means that the user himself is authorized to perform the actions. In this case, the owner (holder) of the key is acting. If your target system trusts the token issuer (and therefore the user) you’ll use Holder-of-key.

For a more detailed description of these profiles and the use cases when they’re appropriate, see the article in the SAP documentation here.

Example

Since SAML is used for single sign-on, authentication of the user is assumed to have already occurred, and the SAML token simply contains one or more subjects, which provide some information understood by other systems. In this case we configure our flow to require a SAML subject of AllowGreetingServices. To our inbound connector we add a SAMLVerifyInterceptor with a callback, which checks for the correct SAML subject:

<spring:bean class="org.mule.module.saml.cxf.SAMLVerifyInterceptor">
     <spring:property name="callback">
          <spring:bean class="org.mule.example.security.VerifyAuthorization">
               <spring:property name="subject" value="AllowGreetingServices" />
          </spring:bean>
     </spring:property>
</spring:bean>

public class VerifyAuthorization implements SAMLVerifyCallback
{
    private String subject;

    public SAMLAuthenticationAdapter verify(SAMLAuthenticationAdapter
samlAuthentication) throws SecurityException
    {
        SAMLSubject samlSubject = samlAuthentication.getSubject();
        if (!samlSubject.getNameIdentifier().getName().equals(subject))
        {
            throw new UnauthorisedException(...cut...

When the expected SAML token is added to the WS-Security header of the message, it looks like this:

<Assertion xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
AssertionID="_40082eadbf045476e26a107e4f37861d"
IssueInstant="2015-11-17T02:26:06.569Z" Issuer="self"
MajorVersion="1" MinorVersion="1">
  <AuthenticationStatement AuthenticationInstant="2015-11-17T02:26:06.569Z"
AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password">
    <Subject>
      <NameIdentifier>AllowGreetingServices</NameIdentifier>
      <SubjectConfirmation>
        <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches
</ConfirmationMethod>
      </SubjectConfirmation>
    </Subject>
  </AuthenticationStatement>
</Assertion>

To verify that the received SAML token is authentic, SAML offers two different modes of trust: Sender Vouches and Holder of Key. In this case, we are using Sender Vouches, which means that the sender of the message must be trusted (e.g., via a digital signature). In Holder of Key mode, the sender of the message does not matter, but the SAML token subject must contain a key from a trusted source (for example, an X.509 certificate from Verisign).

Configuration Reference

SAML Module

Mule enterprise offers support for the Security Assertion Markup Language (SAML), a standard for exchange of security information between federated systems.

Security manager

There are no attributes of security-manager.

Table 1. Child Elements of <security-manager…>
Name	Cardinality	Description
`saml-security-provider`	0..1	A security provider that delegates authorization to some other provider.

SAML Security Provider

A security provider that delegates authorization to some other provider.

Table 2. Attributes of <saml-security-provider…>
Name	Type	Required	Default
`saml-version`	samlVersion	no	1.1
`default-realm`	string	no

Table 3. Child Elements of <saml-security-provider…>
Name	Cardinality
`abstract-key-provider`	1..*
`abstract-security-realm`	1..*

Keystore Provider

There are no default values for these objects.

Table 4. Attributes of `keystore-provider`
Name	Type	Required
`name`	string	yes
`key-store-file`	string	yes
`key-store-type`	string	yes
`key-store-password`	string	yes

There are no child elements of keystore-provider.

Sender Vouches Realm

There are no default values for these objects.

Table 5. Attributes of `sender-vouches-realm`
Name	Type	Required
`name`	string	yes
`key-provider-ref`	name (no spaces)	yes
`sign-key-alias`	string	no
`sign-key-password`	string	no
`resign-assertions`	boolean	no

There are no child elements of sender-vouches-realm.

Holder of Key Realm

There are no default values for these objects.

Table 6. Attributes of `holder-of-key-realm`
Name	Type	Required
`name`	string	yes
`key-provider-ref`	name (no spaces)	yes

There are no child elements of holder-of-key-realm.