AttributeFilterScript

Namespace: urn:mace:shibboleth:2.0:metadata
Schema: http://shibboleth.net/schema/idp/shibboleth-metadata.xsd

Overview

The <AttributeFilterScript> element contains a script (or a reference to a script) that ultimately applies an implementation of Predicate<Attribute> to a given entity attribute. The containing filter implicitly iterates over all entity attributes in the metadata pipeline. For each entity attribute, the entity attribute is removed from the input stream if (and only if) the predicate evaluates to false.

Reference

The <AttributeFilterScript> element is a configuration element of type ScriptType.

Various custom configuration elements support a common content model used to supply JSR-223 scripts inside other object configurations. Where applicable, the specific configuration elements that share this content model will include this material. These include the following documentation pages:

Namespace and Schema

Configuration elements that contain scripts are of type ScriptType, which is a type used across a number of namespaces. The specific namespace will depend on where the element shows up in your configuration.

The following sections describe the attributes and child elements of an element of type ScriptType.

XML Attributes

Name	Type	Default	Description
language	String	javascript	Defines the JSR-223 language to use
customObjectRef	Bean ID		Any bean defined elsewhere in the configuration

If the customObjectRef attribute is present, the result of the referenced Spring bean is made available to the script in a variable named custom. This is in addition to the normal script context discussed below

XML Elements

Name	Cardinality	Description
<Script>	Exactly One	An inline script
<ScriptFile>	Exactly One	Path to a local file or classpath resource containing the script

The script may be stored in a local file (with <ScriptFile>) or written inline (with <Script>). An inline script should be wrapped with a CDATA section to prevent interpretation of any special XML characters that may be included in the script.

Always wrap inline scripts with a CDATA section

Always wrap inline scripts with a CDATA section, even if the script contains no special XML characters. This will future-proof your script.

Script Context

Each element of type ScriptType provides the relevant script context, that is, one or more input objects (in the general sense) to be utilized by the script. For specific details, consult the individual configuration element pages listed above.

Examples

The following example illustrates the use of a CDATA section

A script wrapped with a CDATA section

<Script>
<![CDATA[
    // script goes here
]]>
</Script>

For additional examples of scripts, consult the individual configuration element pages listed above.

Scripting Language

The default scripting language is JavaScript (language=”javascript”). Therefore all of the sample scripts are written in JavaScript, which is based on the ECMAScript standard. The following table illustrates the relationship between JRE version and ECMAScript version:

Java Version	Default Script Engine	ECMAScript Version
Java 11+	Nashorn	ECMAScript 5.1 (plus some features of ECMAScript 2015 aka ECMAScript 6)
Java 15+	None	Java versions from JDK15 on do not support the Nashorn or the Rhino Language. This will be mitigated started with IdP Version 4.1, but for now it suffices to note that the SystemRequirements only specify Java 11 variants (and as such JDK15 is unsupported).

Nashorn documentation from Oracle

An introduction to Nashorn from Oracle:

Part 1: Introducing JavaScript, ECMAScript, and Nashorn
Part 2: The Java in JavaScript
Part 3: Database Scripting

If you’re still using Rhino via manual addition to the IdP classpath, many of the sample scripts (which are quite simple) will run under both Rhino and Nashorn.

Still using Rhino?

Consult the Rhino Migration Guide for helpful advice. Alternatively consider using the Rhino Scripting plugin (IdP Versions 4.1 and later)

Since Nashorn is included with Java 8 (and later), the sample scripts aim to conform to ECMAScript 5.1. In particular, the scripts avoid features introduced in ECMAScript 6 (also known as ECMAScript 2015) for compatibility.

ECMAScript 2015 is not supported

Language features introduced in ECMAScript 2015 (aka ECMAScript 6) are intentionally not used in the sample scripts for compatibility reasons. This includes let, const, and the so-called fat arrow function notation.

Many of the sample scripts are written in Strict Mode. Such a script will include an explicit “use strict” directive, which intentionally precludes the use of certain (error-prone) JavaScript features. Although Strict Mode was introduced in ECMAScript 5, the “use strict” directive is a harmless addition to any script. In particular, it has no effect (positive or negative) when used in scripts under Rhino. That said, you may disable Strict Mode at any time simply by removing (or commenting out) the “use strict” directive.

Follow best coding practices

Write all your scripts in Strict Mode. Moreover, check all your scripts against JSLint. Both practices will help you write better JavaScript code that is more easily debugged and maintained.

Using the JSLint tool

The JSLint tool cannot tell that the JavaScript is being run within the environment of the IdP, with the implied inputs and outputs that that infers. This manifests itself in two ways:

JSLint does not like the input object and customobjects that seem to magically appear from nowhere. From a Shibboleth perspective, this is a feature, not a bug. You can safely ignore this warning issued by the JSLint tool.
Equally it does not like the "last value is the implied return" paradigm. Should this grate you can fool JSLint by using a closure as the last line, for instance replacing
```
var retVal;
retVal = false;
//
// arbitrary code to set up retVal, consulting input and customref
//
retVal;
```
with
```
var retVal;
retVal = false;
//
// arbitrary code to set up retVal, consulting input and customref
//
(function (val) {
    return val;
}(retVal));
```
Only you can decide whether this will help maintainabilty. For clarity and didactic purpose the examples omit this paradigm.

Script Context

Name	Type	Description
input	Attribute	The Attribute to evaluate for exclusion
customObjectRef	any	A custom object to inject into the script

Examples

The following trivial implementation of Predicate<Attribute> always returns false regardless of the input argument:

A trivial implementation of Predicate<Attribute>

<AttributeFilterScript>
    <Script>
    <![CDATA[
        false;
    ]]>
    </Script>
</AttributeFilterScript>

A more complex example might use the custom object to help the operation.

<AttributeFilterScript>
    <Script>
    <![CDATA[
        "use strict";
        var someCondition = function(attributeValueCount) {
            // Good stuff
        }
         
        var result;
        // CustomObjectRef points to a <util:map> where the key is a string and the value is an 'interesting bean'
        if (someCondition(input.getValues.size()) {
            result = custom["myAttributePredicate"].someFunction(input);
        } else {
            result = custom["myOtherAttributePredicate"].someOtherFunction(input);
        }
        result;
    ]]>
	</Script>
</AttributeFilterScript>