Page tree
Skip to end of metadata
Go to start of metadata

Overview

The <Host> element is used to apply content settings to requests to specific virtual hosts and/or to act as a container for more specific rules based on path or query string.

Host matching is based on exact matching of the hostname in a request, and optionally based on scheme or port. For this matching to be reliable, the hostname must be canonical; that is, it must come from the web server's own virtual host configuration rather than a value in the Host header in an HTTP request. Otherwise any rule can be circumvented trivially.

Apache can support this via the UseCanonicalName directive, but this is normally unnecessary because there are better, more powerful ways of handling content settings in Apache itself.

IIS does not support this at all, and reports to applications only the value provided by the client. This is worked around by means of the <Site> element to provide a canonical site to host mapping independently of IIS.

Reference

Attributes

Content Specifiers

Names

Type

Req?

Description

name stringY

Required, specifies the hostname to match (see above for the issues with this)

scheme "http",
"https"

Optional scheme to match against. Used to match only requests using a specific protocol. If omitted, either protocol will match.
port integer
Optional port to match against. Used to match only requests using a specific port. If omitted, requests to the default port for the protocol scheme used (either 80 or 443) will match.

Content Settings

The element supports a large number of XML attributes corresponding to the content settings supported by the SP:

Name

Type

Default

Description

authTypestring

Analogous to Apache's AuthType command, just set this to "shibboleth" unless you want to bypass any processing by the SP.

applicationId (*)string
Overrides the application associated with the resource by matching the id attribute in an <ApplicationOverride> element.
requireSessionbooleanfalseMaster trigger that will require an authenticated session. If none exists, the SP will try to automatically establish one using the default SessionInitiator.
requireSessionWithstring
Same as requireSession, but uses the SessionInitiator with the specified id attribute instead of the default.
exportAssertionbooleanfalseIf true, special attributes are exported to provide applications with access to the underlying SAML assertions that are cached with the user's session. See the AssertionExport topic.
redirectToSSLinteger

A port to redirect non-SSL GET or HEAD requests to. Other HTTP methods like POST will result in an error. Used to automate the blocking of non-SSL requests in a portable way. Most servers can do this anyway, but some like IIS won't enforce the rule until it's too late to prevent problems with the Shibboleth filter.

entityIDURI
The name of a specific IdP to use when automatically requesting authentication because a session does not exist. Allows for resource-based selection of an IdP to use, and overrides the entityID attribute of a SessionInitiator.
entityIDSelf (*)URI
Overrides the SP's own name. If the string contains the pattern "$hostname", then the virtual hostname of the request is plugged into the value used. This is an alternative to the common pattern of defining minimal <ApplicationOverride> definitions with only an overridden entityID.
isPassivebooleanfalse

Sets the value of the IsPassive attribute of any SAML 2.0 AuthnRequest messages issued automatically as a result of accessing the resource. Has no effect for other SSO protocols. Overrides the isPassive attribute of a SessionInitiator. Also have a look at the page in order to see what isPassive can be used for.

forceAuthnbooleanfalseSets the value of the ForceAuthn attribute of any SAML 2.0 AuthnRequest messages issued automatically as a result of accessing the resource. This asks for forced reauthentication by the IdP (bypassing SSO). Has no effect for other SSO protocols. Overrides the forceAuthn attribute of a SessionInitiator.
authnContextClassRefwhitespace-delimited 
URI list

Specifies a SAML 2.0 AuthnContext class reference to request in any SAML 2.0 AuthnRequest messages issued automatically as a result of accessing the resource. Has no effect for other SSO protocols. Overrides the authnContextClassRef attribute of a SessionInitiator. This can be a whitespace-delimited list of classes to request.
authnContextComparison

"exact"
"better"
"minimum"
"maximum"



Specifies the SAML 2.0 AuthnContext comparison operator to use in any SAML 2.0 AuthnRequest messages issued automatically as a result of accessing the resource. Has no effect for other SSO protocols. Overrides the authnContextComparison attribute of a SessionInitiator.
redirectErrorsURL (relative or absolute)
Location to redirect to when errors occur, instead of using a generated HTML template. Particularly necessary when using passive SSO. Overrides the redirectErrors attribute of the <Errors> element.
sessionErrorlocal pathname
Error template to use for general processing errors. Overrides the session attribute of the <Errors> element.
metadataErrorlocal pathname
Error template to use for general processing errors. Overrides the metadata attribute of the <Errors> element.
accessErrorlocal pathname
Error template to use for general processing errors. Overrides the access attribute of the <Errors> element.
sslErrorlocal pathname
Error template to use for blocking non-SSL requests that could not be redirected.  Overrides the ssl attribute of the <Errors> element.
REMOTE_ADDRstring
Optional name of an HTTP request header to use for the IP address of the client. Used to divert this lookup from the REMOTE_ADDR variable to a header set by a proxy, such as "X-Forwarded-For". If you rely on this feature, you'd better ensure that the header can't be spoofed by a client.
targetURL
Allows the resources to return to after SSO to be "locked" to a specific value, even when running as a result of active protection of other resources. In other words, this value overrides the actual resource location when SSO redirection is automatic, including initial access and after a timeout.
encodingstring
Controls the encoding of attribute values exported to headers or environment variables. If omitted, the default is to encode the data as UTF8. The only supported value is "URL", which applies URL-encoding to the UTF8 data before export.

attributeValueDelimiter  3.1

string;Optional alternative separator for multiple values when attributes are put into variables/headers, has no effect if the encoding option is set to "URL"
NameIDFormatURI
NameIDPolicy Format attribute to use in authentication request. Overrides the NameIDFormat attribute of a SessionInitiator.
SPNameQualifierstring

NameQualifier to use in authentication request. For instance, entityID of an EntityDescriptor with an AffiliationDescriptor.

exportStdVarsbooleantrueIf true, causes the SP to export a built-in set of standard variables based on the users' session. This set includes "Shib-Identity-Provider", "Shib-Authentication-Instant", "Shib-Authentication-Method", "Shib-AuthnContext-Class", "Shib-AuthnContext-Decl", and "Shib-Session-Index". 
A future version of the SP may remove these built-ins in favor of explicit configuration using the AttributeExtractor of type="Assertion".
exportCookiebooleanfalseIf true, causes the SP to export a variable called "Shib-Cookie-Name" with the algorithmically-generated portion of the implementation-specific cookies used by the SP to maintain sessions with users and track other state. Applications that want to unilaterally dispose of SP state and session information can delete any cookie whose name contains the value of this variable.
discoveryURLURL
Overrides the default location used by "discovery" SessionInitiators. Advanced option that can be used to direct the user to different discovery interfaces based on the resource accessed.
discoveryPolicystring
Used as input to some discovery protocols that take parameters modifying discovery behavior. In the case of the type="SAMLDS" SessionInitiator, this is passed as a policy parameter value.
requireLogoutWithURL
Used in conjunction with passive protection of a resource, this property will automate a redirect to the URL specified (usually the SP's logout handler) and then a return to the location being accessed, passing control to it. Assuming SP logout proceeds successfully, this will invoke that mechanism and pass control to this resource with the SP session disposed of, enabling application logout to proceed.
exportDuplicateValuesbooleantrueIf set to false, the export of attribute values to variables or headers will filter out duplicate values. This occurs per-header, so accounts for aliasing and multiply-sourced headers, but also adds some overhead to the processing of every request for larger attribute sets.
unsetwhitespace-delimited 
string list

Allows settings to be "unset" at a lower point in the hierarchy to deal with edge cases. For example, if the requireSessionWith property is set in a directory, this allows it to be cleared for a file within that directory.

(*) - It is recommended to cover whole vhost with this property. At least you must cover its own Shibboleth.sso handlers. See ApplicationOverride for details.

Child Elements

Access Control

One of the following child elements can be used to attach an access control policy to matching requests:
  • <htaccess>
    • Enables native Apache .htaccess support during Apache's authorization phase. This is automatic and implicitly plugged in for the Native RequestMapper, but can be enabled by hand if the XML RequestMapper is used. Note that this will fail for non-Apache servers.
  • <AccessControl>
    • Attaches an access control policy using the XML-based plugin provided with the SP. This is a short-hand for embedding the policy in the element above, if you want the policy inside the RequestMapper's configuration file anyway.

If no element is included (or inherited or implicitly enabled), any access control is left to the resource itself and the SP simply passes its session information along.

If an error occurs when processing this element, a dummy policy to deny access is installed to prevent accidental exposure.

Nested Content Specifiers

The following elements are supported to narrow the matching process:

Name

Cardinality

Description

<Path>0 or more

Matches requests whose first path component is an exact match

<PathRegex>0 or more

Matches requests whose remaining path as a whole matches a regular expression

<Query>0 or more

Matches requests containing a matching query string parameter

The further matching is done as follows:

  1. First, by examining <Path> elements in order.
  2. Then, by checking any <PathRegex> elements in order against the part of the path that was not matched in the first step.
  3. Finally, by examining any <Query> elements in order.

Once a matching child element is found, the process steps "into" that element and no other sibling elements will be tested for a match. Thus, sibling elements cannot overlap in the web space.

For more details on how the request mapping process works, see the HowTo.

  • No labels