...
The actual content settings in the RequestMap are likely to be altered, but it’s likely more will be aded than removed, as most of the settings that used to exist in other places will be migrated into the RequestMap (if they continue to exist).
Many settings below are defaulted and likely would never be used or seen, but are there for compatibility or to allow unusual tuning of behavior. Generally if a setting doesn’t look familiar, it’s either new or it was there all along and just isn’t needed much.
Master Configuraton
The top-level “master” file will be an INI file (conventionally in shibboleth.ini). So far the following sections have been sketched out or implemented:
...
Whether to try and catch all C++ runtime exceptions or only “known” exceptions. Failure to catch an exception terminates a process with prejudice.
IISConfigPath = iis-config.ini
Pointer to IIS-specific agent settings (this is a separate file because of how the Site mappings are defined). The file extension may be “ini” or “xml”, and the latter implies the format used by the older SP software’s <ISAPI> element.
[extensions]
<pathname> = true | false
...
Basic means of overriding logging level for specific categories, but notably this isn’t hierarchical as with more full-featured logging libraries. We expect to flatten out some of the nesting of categories to reduce the impact of that.
[remoting]
type =
...
CurlHTTP | WinHTTP
Controls the agent/hub remoting service to use, this is the only type expected to be implemented. Generally defaulted as appropriate for the platform.
baseURL = http://localhost/idp/profile/
Used to connect to operations implemented by the agent’s hub.
agentID = <string>
Identifies agent to hub for configuraton/authentication purposes.
userAgent = <string>
If set, overrides default User-Agent header sent with requests to hub.
authMethod = basic
Type of authentication used by agent when connecting to hub, will be extended with additional options as supported/warranted.
authCachingCookie = <string>
Enables capture of a named cookie to support caching of authentication with the hub.
tlsCipherList = <platform-specofoc cipher string>
Sets a non-defaulted cipher string to inject into a TLS implementation to limit ciphers or protocols used. The format will depend on the type of remoting service and the TLS library in use (most commonly OpenSSL’s format when not using Windows).
tlsCAFile = trustlist.pem
Specifies file to use as a CA list when connecting over TLS to hub. For the CurlHTTP type, this must be a file with PEM-encoded CA certificates.
chunkedEncoding = true | false
Flag controlling use of chunked content encoding. When false, the request is buffered to determine a content length to supply instead of using a read callback to pull data to send.
connectTimeout = 3
Connection timeout in seconds.
timeout = 10
Overall timeout in seconds.
secretSourceType = File | Env
Source of agent secret for shared secret authentication to hub.
secretFile = <path>
Used with secretSourceType=File, path to file containing secret. Trailing linefeeds/etc. are omitted.
secretEnv = <envname>
Used with secretSourceType=Env, name of environment variable to extract secret from.
[session-cache]
type = filesystem | storage | cookie
...
Whether to monitor the file for reloads, which occur in the foregrund foreground after taking a read lock, based on file modification time. C++-14 support is required for this code to be active and doing so introduces shared locking to the use of the component.
...
...
[handlers]
This section contains one or more key/value pairs mapping a “handler configuration ID” to a file defining the handlers that are active for a request that maps to that ID. This section can be omitted in most cases, in which case the default handler configuration will be found in handlers.ini. If this section is defined, then no default mappings are created or assumed.
IIS
The old <ISAPI> material from the configuration will be replaced by an INI file (name TBD, iis.ini for now), , but the exact name can be controlled from the setting pointing to it in the master file. We could also possibly end up supporting both INI and XML formats, with the XML more or less matching the original <ISAPI> element to make migration simplerOptionally the older XML syntax can also be reused.
[global]
authenticatedRole = ShibbolethAuthnN
...
Default matches the status of the useHeaders flag. Causes all non-alphanumeric characters to be removed from the names of all SP-controlled headers, as their presence makes header smuggling much harder to guard against due to IIS implementation choices (bad ones, that is).
handlerPrefix = /Shibboleth.sso
Optimizes ignoring non-handler requests when a default or static handlerURL is used, as is generally the case.
[<site-id>]
Every other section in the file represents a Site in IIS, with the Site ID used as the section key. The equivalent of Apache’s ServerName command to virtualize the settings for a site, but with each component separated into a discrete property to avoid the need to parse a URL.
...
Whitespace-delimited list of alternative hostnames that should be accepted as valid if requested by a client.
Handlers
Each handler configuration file contains 1 or more sections. The section names are the relative paths to the handlers they define/mount into the agent. The paths are relative to whatever the handlerURL setting in the Request Mapper is for a given request (defaulting to “/Shibboleth.sso” for now for compatibility, TBD).
Each section must contain a type property indicating what type of handler is being defined, and the rest of the properties will depend on the handler itself.
Status Handler
type = Status
acl = 127.0.0.1 ::1
Space-delimited list of CIDR expressions to match against the client address to authorize access to the handler.
Session Handler
type = Session
acl = 127.0.0.1 ::1
Space-delimited list of CIDR expressions to match against the client address to authorize access to the handler.
Session Initiator
type = SessionInitiator
requestMapperSettings = <setting1> <setting2> <setting3>
Space-delimited list of settings to pull from the RequestMapper based on the request that should be passed to the hub for processing the session request. This allows an arbitrarily extensible set of protocol options to be signalled without awareness by the agent code. The default will be determined closer to completion of SAML and OIDC support but will include the legacy SAML options (e.g., ForceAuthn).
At present, we have also retained support for defining “defaults” for these settings within this section itself, with the RequestMapper overriding them.
querySettings = <setting1> <setting2> <setting3>
Same as above but for query string parameters to the handler directly. These can be independently controlled for security purposes to limit what can be passed from the client to the handler (and thus be under insecure control).
Examples
| Code Block |
|---|
; shibboleth.ini [global] regexMatching = partial [logging] type = syslog openSyslog = false defaultLevel = INFO [logging-categories] Shibboleth.AgentConfig = DEBUG Shibboleth.Agent = DEBUG [remoting] baseURL = https://localhost/idp/profile/sp agentID = sp.example.org authMethod = basic authCachingCookie = __Host-JSESSIONID ; tlsCAFile = trustfile.pem secretSourceType = Env secretEnv = SHIBSP_AGENT_SECRET [session-cache] ... [request-mapper] type = XML path = request-map.xml reloadChanges = true |
| Code Block |
|---|
; handlers.ini
[Status]
type = Status
acl = 127.0.0.1 ::1
[Login]
type = SessionInitiator
[Validate]
type = TokenConsumer |