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
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 describes the characteristics of the AuthState.
| Topic | Description |
|---|---|
| Class | ch.nevis.esauth.auth.states.xml.DocumentProcessor |
| Logging | XML |
| Auditing | none |
| Marker | none |
| Properties (general) | 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. This AuthState might use the HTTP or FTP protocol to fetch documents ". | |
| validateAgainstSchema (boolean, false)Enables XML schema validation. In case the XML schema validation is enabled and fails, the transition validation-failed is triggered. | |
| Properties (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()"> 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. | |
| Properties(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. | |
| Properties(document loading) | connectTimeout (int, " ")The time-out in milliseconds for connections to URL resources. |
| readTimeout (string, " ")The time-out in milliseconds for reading the input stream of a URL resource. | |
| 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). | |
| blockWhileUpdating (boolean, false)If set to "true", only the thread that is updating the resource is allowed to access it. If set to "false", all other threads will have access to the last valid DOM from the cache until an updated version is available. 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). | |
| Properties(String provider) | encoding (string, " ")The encoding for parsing a string. This is only relevant for StringDomProviders. |
| Properties(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. | |
| Methods | process |
| 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: error happened. | |
| Output | Depending on the XPath propagation property name stored in session, notes, inargs or outargs. |
| Errors | 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
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. However, the DOM has a specific form, for 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 ). 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 describes the characteristics of the AuthState.
| Topic | Description |
|---|---|
| Class | ch.nevis.esauth.auth.states.xml.ConditionalDocumentProcessor |
| Logging | XML |
| Auditing | none |
| Marker | none |
| 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. This AuthState might use the HTTP or FTP protocol to fetch documents (depending on what is configured in this property). It is thus potentially susceptible to HTTP and FTP proxies, as described in the chapter Configuring proxies. | |
| The ConditionalDocumentProcessor extends the AuthState DocumentProcessor and may be configured using the same properties. For a list of configurable properties, see. | |
| Methods | process |
| 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 |
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>