XML processor AuthStates

Introduction and overview

XML processor AuthStates are used for processing XML documents or input strings and extracting information from these sources by applying XPath queries.

DocumentProcessor

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit the migration guide for additional information.

The document processor (DocumentProcessor AuthState) processes XML and has the ability to validate against an XML schema definition or to propagate variables that are queried with XPath from an XML DomProvider. Several DomProviders are available for fetching, parsing and processing XML. The supported DomProvider document sources include strings, URL resources (local files and plain HTTP resources), and WS Federation resources. The XPath query processor was extended to allow Nevis substitutions as XPath variables in the query.

Description

The following table and chapters describe the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.xml.DocumentProcessor
Logging	XML
Auditing	none
Marker	none
Methods	process

Properties

• documentSourceType (string, "STRING")

  The type of document we are processing. Currently, the types "RESOURCE", "STRING" and "WS_FEDERATION" are supported.

• documentSource (string, required)

  The source of the document. The format depends on the documentSourceType:

  • STRING: <doc><example /></doc>
  • RESOURCE: file://dir/example , http://www.example.org
  • WS_FEDERATION: file://dir/example , http://www.example.org

  Supported channels: file, http.

• validateAgainstSchema (boolean, false)

  Enables XML schema validation. In case the XML schema validation is enabled and fails, the transition validation-failed is triggered.

Expressions

• scope:var (string, required)

  The variable to which the XPath result will be propagated to.

  Example

  <property name="notes:var" value="xpath:/root/child/text()">
  info

  The value has to start with "xpath:".

• optional (list of xpath expressions, -)

  The name of the propagation variable that is optional. The AuthState will not report an error if the optional flag is set on a variable that is not found.

• concatResults (string or boolean, "false")

  This flag concatenates results if multiple nodes are found for one XPath query.

• delimiter (string, " ")

  The delimiter for the concatenation of results. If concatResults is false, this parameter is ignored. Otherwise, multiple query results are separated with this delimiter.

XML Parsing

• parser.namespaceAware (boolean, true)

  Configures the DOM parsers to be namespace-aware.

• parser.validating (boolean, true)

  Configures the DOM parsers to validate the schema.

• parser.coalescing (boolean, false)

  Configures the DOM parsers to be coalescing.

• namespace.<prefix> (string, -)

  Optional properties to configure custom XML namespaces.

• parser.schema (string, -)

  An additional schema can be configured to allow validation against it. If none is specified, a set of XML namespaces that the engine knows is used for the validation.

Document loading

• maxAge (int, 600)

  After this time (in seconds), a resource is considered outdated and attempts are made to update it. This is only relevant for CachedDomProviders (that includes UrlDomProviders and WsFedUrlDomProviders). maxAge= -1 indicates that updates are done according to the scheduler.interval, without regard to the document age.

• discardInterval (int, 60)

  If an update failed, the CachedDomProvider (that includes UrlDomProviders and WsFedUrlDomProviders) does not try to update again until this amount of seconds has passed. This is only relevant for CachedDomProvider (that includes UrlDomProviders and WsFedUrlDomProviders).

• failOnUpdateFailure (boolean, false)

  If this flag is enabled, the AuthState fails with an exception if an update failed for some reason. If set to "true", this guarantees that only up-to-date resources are used. If set to "false", the latest valid entry from the cache will be used. This is only relevant for CachedDomProvider (that includes UrlDomProviders and WsFedUrlDomProviders).

• scheduler.interval (int, 10000)

  The interval for attempting updates on the document. This is only relevant for CachedDomProvider (that includes UrlDomProviders and WsFedUrlDomProviders). scheduler.interval = "-1" indicates that the update should only be done once, therefore disabling the scheduler.

• scheduler.threads (int, " ")

  The pool size of the scheduled thread pool. The scheduled thread pool executes the update of a resource periodically. This is only relevant for CachedDomProvider (that includes UrlDomProviders and WsFedUrlDomProviders).

String provider

• encoding (string, " ")

  The encoding for parsing a string. This is only relevant for StringDomProviders.

WS-Federation provider

• wsfed.maxDepth (int, 10)

  The maximum allowed metadata reference depth. This is only relevant for WsFedUrlDomProviders.

• wsfed.targetScopesRestriction (boolean, true)

  If target scopes restriction is enabled, the AuthState fails if the referenced entity descriptor is not referenced in the target scopes of a web service federation metadata file.

HttpClient

• httpclient.* (String)

  When the documentSource is an URL, configure the outgoing HTTP communication towards it. For a list of valid HTTP properties, see HTTP Client.

Input

none (except over variable substitution)

Transitions

• ok

  Variable was successfully propagated.

• nomatch

  One of the XPath expressions does not match.

• validation-failed

  In case the XML schema validation is enabled and fails.

• default

  An error occured.

Output

Depending on the XPath propagation property name stored in session, notes, inargs or outargs.

Errors

none

Notes

none

Example

<AuthState name="MetadataFetchSTS" class="ch.nevis.esauth.auth.states.xml.DocumentProcessor" final="false" resumeState="false">
    <ResultCond name="ok" next="ConsumeIntAssertion"/>
    <Response value="AUTH_ERROR"/>
    <property name="documentSourceType" value="ws-federation"/>
    <property name="documentSource" value="file:/var/opt/nevisauth/default/conf/MetadataFederationZFSTest.xml"/>
    <!-- scheduler interval: 30 seconds -->
    <property name="scheduler.interval" value="30000"/>
    <property name="maxAge" value="-1"/>
    <property name="notes:wsfed.targetSTS" value="xpath://md:EntityDescriptor/md:RoleDescriptor[@xsi:type='fed:SecurityTokenServiceType' and fed:PassiveRequestorEndpoint/wsa:EndpointReference/wsa:Address/text()=$targetRP]/fed:SecurityTokenServiceEndpoint/wsa:EndpointReference/wsa:Address/text()"/>
</AuthState>

ConditionalDocumentProcessor

nevisAuth 4.38.x HTTP client changes

The new HTTP client shipped with nevisAuth 4.38.0.12 will likely require changes in this auth state configuration, specifically in the area of certificate configuration and handling.

Visit the migration guide for additional information.

The conditional document processor (ConditionalDocumentProcessor AuthState) processes and propagates variables that are queried with XPath from an XML DomProvider, similar to the document processor (see Document processor. However, the DOM has a specific form, for example:

ConditionalDocumentProcessor example

<?xml version="1.0" encoding="UTF-8"?>
<cond:Clauses xmlns:cond="http://nevis.ch/nevisauth/xsd/conditionalDocument"
    <cond:Clause name="whr_in_req"> <!-- name: whr in request -->
        <cond:Condition match="any">
            <cond:isSet value="${sess:wsfed.in.whr}" />
        </cond:Condition>
    </cond:Clause>
    <cond:Clause name="whr_selected"> <!-- name: whr selected -->
        <cond:Condition match="any">
            <cond:isSet value="${inargs:whr}" />
        </cond:Condition>
        <set var="sess:wsfed.in.whr" value="${inargs:whr}" />
    </cond:Clause>
    <cond:Clause name="intern">
        <cond:Condition match="any">
            <cond:notSet value="${inctx:connection.HttpHeader.extern}" />
        </cond:Condition>
        <set var="sess:wsfed.in.whr" value="https://adnovum.zh.adnovum.ch/realmidp/?login" />
    </cond:Clause>
    <cond:Clause name="extern">
        <cond:Condition match="any">
            <cond:equals left="${inctx:connection.HttpHeader.extern}" right="extern" />
        </cond:Condition>
        <set var="sess:wsfed.in.whr" value="https://adnovum.zh.adnovum.ch/realmidp2/?login" />
    </cond:Clause>
    <cond:Clause name="select">
        <Gui name="chooseMethod" label="login.choose.label">
            <GuiElem name="info" type="info" label="Select your Home Realm"/>
            <GuiElem name="whr" type="radio" label="Home Realm 1" value="https://adnovum.zh.adnovum.ch/realmidp/?login"/>
            <GuiElem name="whr" type="radio" label="Home Realm 2" value="https://adnovum.zh.adnovum.ch/realmidp2/?login"/>
            <GuiElem name="submit" type="button" label="submit.button.label"/>
            <GuiElem name="wreply" type="hidden" value="${sess:wsfed.in.wreply}"/>
            <GuiElem name="wtrealm" type="hidden" value="${sess:wsfed.in.wtrealm}"/>
            <GuiElem name="wa" type="hidden" value="${sess:wsfed.in.wa}"/>
        </Gui>
    </cond:Clause>
</cond:Clauses>

The schema for conditional documents can be found in the appendix (see Appendix Conditional document schema)). The idea of the conditional document processor is to set variables or process GUIs described in the conditional document, but only if the condition of the clause holds. In the above example, the session variable wsfed.in.whr would only be set if the clause extern can be positively evaluated by checking whether its condition holds. Possible condition operations are:

* *<cond:set value="${scope:var}">*
* *<cond:notSet value="${scope:var}">*
* *<cond:equals left="${scope:var1}" right="${scope:var2}">*
* *<cond:notEquals left="${scope:var1}" right="${scope:var2}"*>

The names of the clauses are also the names of the transitions from the current AuthState to the next AuthState. Whenever a GUI is found, the transition is set internally to the same AuthState, so that the GUI is processed and displayed.

Description

The following table and chapters describe the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.xml.ConditionalDocumentProcessor
Logging	XML
Auditing	none
Marker	none
Methods	process

Properties

• documentSourceType (string, "RESOURCE")

  The type of document we are processing. The types "RESOURCE" and "STRING" are supported.

• documentSource (string, required)

  The source of the document. The format depends on the documentSourceType:

  • STRING: <doc><example /></doc>
  • RESOURCE: file://dir/example , http://www.example.org

  Supported channels: file, http.

HttpClient

• httpclient.* (String)

  When the documentSource is an URL, configure the outgoing HTTP communication towards it. For a list of valid HTTP properties, see HTTP Client.

Input

none (except over variable substitution)

Transitions

• <name of the clause>

  The variable was successfully propagated.

• default

  An error happened.

Output

Depending on the XPath propagation property name either stored in session, notes, inargs or outargs.

Errors

none

Notes

none

Example

<AuthState name="RPIdP_HomeRealmDiscoveryService" class="ch.nevis.esauth.auth.states.xml.ConditionalDocumentProcessor" final="false" resumeState="false">
    <ResultCond name="whr_in_req" next="RPIdP_wsfedClient" />
    <ResultCond name="whr_selected" next="RPIdP_wsfedClient" />
    <ResultCond name="intern" next="RPIdP_wsfedClient" />
    <ResultCond name="extern" next="RPIdP_wsfedClient" />
    <Response value="AUTH_CONTINUE" />
    <property name="documentSourceType" value="resource"/>
    <property name="documentSource" value="file:/var/opt/nevisauth/default/conf/hrds.xml"/>
    <!-- scheduler interval: 30 seconds -->
    <property name="scheduler.interval" value="30000"/>
    <property name="maxAge" value="-1"/>
</AuthState>