View Source

The <PolicyRule> element configures a plugin used to enforce a security policy requirement or to provide for a particular kind of authentication technology.

In versions prior to 2.2, this element was named <Rule>, which conflicts with the identically-named element used in the access control syntax. For obscure schema design reasons, the elements co-existed, but this conflict has been corrected in subsequent versions.

During message processing, at least one rule must successfully authenticate a message or it will be rejected.

Common Attributes

type (string)
- Name of plugin type.

MessageFlow Rule

Identified by type="MessageFlow", this rule enforces replay detection and freshness requirements to prevent replay attacks.

<PolicyRule type="MessageFlow" checkReplay="true" expires="60"/>

Attributes

checkReplay (boolean) (defaults to true)
- Enables or disables use of a replay cache to prevent replay attacks. Do not turn off in production.

expires (time in seconds)
- Maxmimum time permitted between a message's timestamp and when it can be processed. Bounds the size of the replay cache.

ClientCertAuth Rule

Identified by type="ClientCertAuth", enables TLS/SSL client certificate authentication for back-channel SOAP communication to the SP.

<PolicyRule type="ClientCertAuth" errorFatal="true"/>

Attributes

errorFatal (boolean) (defaults to false)
- If true, failure to validate a supplied certificate is fatal during message processing. This is distinct from cases where a certificate isn't present.

XMLSigning Rule

Identified by type="XMLSigning", enables XML signature authentication of messages and assertions.

<PolicyRule type="XMLSigning" errorFatal="true"/>

Attributes

errorFatal (boolean) (defaults to false)
- If true, failure to validate a signature is fatal during message processing. This is distinct from cases where a signature isn't present.

SimpleSigning Rule

Identified by type="SimpleSigning", enables "simple" signature authentication of messages. A simple signature is a bulk signature over the raw content of a message, rather than embedded inside the message.

<PolicyRule type="SimpleSigning" errorFatal="true"/>

Attributes

errorFatal (boolean) (defaults to false)
- If true, failure to validate a signature is fatal during message processing. This is distinct from cases where a signature isn't present.

Conditions Rule (Version 2.2 and Above)

Identified by type="Conditions", processes SAML 1.x and 2.0 "condition" elements found in assertions, which control the circumstances under which they may be accepted by the SP for use. In the absence of this rule, any conditions found will result in rejection of an assertion.

This rule also enforces the NotBefore and NotOnOrAfter attributes accompanying the assertion, if any.

If no child elements are supplied, the plugin will install itself with a default set of rules equivalent to the following:

<PolicyRule type="Conditions" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">
    <PolicyRule type="Audience"/>
    <PolicyRule type="Ignore">saml:DoNotCacheCondition</PolicyRule>
    <PolicyRule type="Ignore">saml2:OneTimeUse</PolicyRule>
    <PolicyRule type="Ignore">saml2:ProxyRestriction</PolicyRule>
</PolicyRule>

Child Elements

<PolicyRule> (zero or more)
- Supplies one or more rules to apply to any conditions found in the assertion being evaluated. In the event that a condition is unrecognized by all of them, the surrounding rule will reject the assertion.

Audience Rule (Version 2.2 and Above)

Identified by type="Audience", processes SAML 1.x and 2.0 "AudienceRestriction" conditions. The set of allowed "audience" values are normally supplied within the rule configuration or can be supplied by unspecified means (e.g., the SP will normally ensure that its own entityID is an allowable value without special setup).

<PolicyRule type="Audience"/>

Child Elements

<saml:Audience> (zero or more)
- Supplies additional audience values to be allowed when evaluating conditions. This replaces the deprecated mechanism of including this element directly within an <ApplicationDefaults> or <ApplicationOverride> element. Rarely required during normal use.

Delegation Rule (Version 2.2 and Above)

Identified by type="Delegation", processes SAML 2.0 "DelegationRestriction" conditions. A rule can either generically permit delegation, or require specific delegates with a variety of matching options.

<PolicyRule type="Delegation" match="oldest"
    xmlns:del="urn:oasis:names:tc:SAML:2.0:conditions:delegation"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
  <del:Delegate>
    <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://portal.example.org/shibboleth</saml:NameID>
  </del:Delegate>
  <del:Delegate ConfirmationMethod="urn:oasis:names:tc:SAML:2.0:cm:holder-of-key">
    <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://portal2.example.org/shibboleth</saml:NameID>
  </del:Delegate>
  <del:Delegate>
    <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://portal3.example.org/shibboleth</saml:NameID>
  </del:Delegate>
</PolicyRule>

Attributes

match (optional, one of "anyOrder", "oldest", "newest") (defaults to "anyOrder")
- Sets the matching policy for the rule, if there are child elements supplied. "anyOrder" means that every delegate in an assertion must be listed in the rule, in any order. "oldest" means that the delegates in the assertion must include the delegates listed in the rule, in order, starting from the beginning/top of the list. "newest" reverses the order of the matching process, starting from the bottom of the list in the assertion and working backward. With an ordered comparison, additional delegates may be in the assertion once the match is complete.
maxTimeSinceDelegation (optional) (time in seconds)
- If set, requires that any delegates include an associated time stamp indicating when delegation occurred and enforces a maximum period between the act and the current time.

Child Elements

<del:Delegate> (zero or more)
- Supplies delegates to match with the content of the assertion, using the policy specified in the match attribute. If none are included, any delegates found in the assertion will be accepted. Only delegates identified with <saml:NameID> elements are supported. An optional ConfirmationMethod attribute can be included, and if present, the same value must be found in the <del:Delegate> element in an assertion for a match to take place.

Ignore Rule (Version 2.2 and Above)

Identified by type="Ignore", signals to a containing Conditions rule (see above) that a condition has been understood and should not affect the processing of an assertion. Many condition types do not affect validity per se, but all SAML conditions require explicit acknowledgement and acceptance of their semantics.

The content of this element is an XML QName identifying the XML element or schema type of a SAML condition to ignore and treat as successfully processed.

<PolicyRule type="Ignore" xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">saml2:ProxyRestriction</PolicyRule>

SAML1BrowserSSO (Version 2.2 and Above)

Identified by type="SAML1BrowserSSO", enforces the general assertion requirements of the SAML 1.x Browser SSO profile. Normally not used explicitly, this rule is applied automatically to any policy running inside an AssertionConsumerService that implements the profile.

Bearer (Version 2.2 and Above)

Identified by type="Bearer", allows a SAML 2.0 assertion with the "bearer" subject confirmation method to be accepted when possible. Normally not used explicitly, this rule is applied automatically to any policy running inside an AssertionConsumerService that implements SAML 2.0 profiles that make use of this confirmation type.

Attributes

checkValidity (boolean) (defaults to true)
- When true, the enclosed <SubjectConfirmationData> element must include a NotOnOrAfter attribute, and both it and the optional NotBefore attribute are checked for validity.

checkRecipient (boolean) (defaults to true)
- When true, and the URL to which the assertion was submitted is available, the <SubjectConfirmationData> element's Recipient attribute is checked against that value. If no attribute is present, this setting has no affect.

checkCorrelation (boolean) (defaults to true)
- When true, and the identifier of a request to which the assertion was submitted as a response is available, the <SubjectConfirmationData> element's InResponseTo attribute is checked against that value. If no attribute is present, this setting has no affect.

missingFatal (boolean) (defaults to true)
- When true, the absence of an acceptable <SubjectConfirmation> element is treated as a fatal error. Otherwise, the rule signals nothing was found but does not fail. Can be set to allow for stacking of rules based on multiple confirmation methods.

NullSecurity Rule

Identified by type="NullSecurity", enables debugging by disabling security and permitting unauthenticated messages to pass successfully into higher layers.

<PolicyRule type="NullSecurity"/>

Do NOT use this rule in production, as it will leave your system vulnerable to attackers.