SP Configuration Settings

Background

The SP configuration is a pretty severe case of scope creep, with settings being added constantly over many years of development and only partly having a consistent sense of design around where they ended up. This was partly due to the SP implementing a very generic DOM-based configuration API allowing settings to be added more or less all the time without major API changes and being accessed by string name and not via concrete APIs. This has a lot of pros and cons but the lack of rigor makes the overall system worse over time, which is where it’s ended up. It’s a mess of different buckets of settings and not all of them are likely in the best places.

Broadly speaking, there are two major elements of the core configuration likely to transfer over in some form: RequestMapper and ApplicationDefaults. At a high level, these are sort of split along the lines of “agent” and “service hub”, but that’s not 100% accurate and lots of settings in each case are either not limited to one or the other, or are in the wrong place, or are really protocol-specific settings that are better handled via the kind of ProfileConfiguration abstraction the IdP uses. The complication is in trying to maintain some compatibility, particularly with, e.g., Apache settings that might be heavily threaded throughout a complex deployment.

Roughly, the idea has been that the SP agents would be able to feed the RequestMapper section up to the service hub to parse and return in a structured way so that much of the behavior at the content level could be configured at the agent end without having to update the service hub’s view of the world, but this may be difficult to do in cases where the settings are actually protocol-specific options that have more to do with SAML. There will be cases where settings the agent sees have to be fed back into the service hub to change how it performs some remoted SAML processing, but we want to limit this as much as we can.

As a starting point, progress means going through all of the settings and putting them into appropriate categories or identifying them as overtaken by changes or in light of the new design. That will inform the API design for now.

Content Settings

The term “content settings” is used in the old design to reflect anything meant to apply at a content level, i.e., per request down to the path, file, etc. More or less anything that fit into the Apache command model. The trick with these settings is that anything plausibly wanting to be content-driven almost has to be left here because to do anything else would couple the hub configuration with the content model too tightly. In other words, the last thing you ever want is to have to centrally change a Spring config because a path changes. That’s just out of the question.

It may be a middle ground to imagine some settings packaged into groups representing collective behavior though, and only referencing the package of settings by some label in the agent config. That’s coupled, but it abstracts things in such a way that it provides more oversight over the options without having to actually put the options themselves out into agent configs.

Name	Type	Notes

Name	Type	Notes
applicationId	string	This tied the requests back to the Application layer and will continue to be needed. Since Applications are now contained and scoped by Agents, we should not need to force any new unique-ing convention for this.
authType	string	This is really meant to be Apache’s AuthType concept, but I don’t think it fits into the RequestMapper all that well and it ultimately become more of an on/off switch. Removing it may be more hassle than it’s worth though.
requireSession	boolean	The big Kahuna, activates active session protection for content, obviously staying.
requireSessionWith	string	This was a special case of the previous that tied into how to issue requests for a login. Keeping it is plausible, but I would ideally prefer to wait on that pending a review of the SessionInitiator settings and where they really fit. Could be that the need is more to package up those settings as a stand-alone object/API and this would maybe reference those objects, but it may also be just time to dump the idea and move solely to the use of protocol-specific settings that ultimately overtook this concept.
requireLogoutWith	URI	Hook for triggering content-specific logout code after the SP logout completes. This isn’t inherently non-functional in a world where the IdP ends up with control since it should be runnable in an IdP-hosted frame (aside from the TPC issues).
exportAssertion	boolean	This was a SAML-specific as a hack to expose the information needed to get at the assertion. In this form, it likely disappears because it governed the creation of special headers for figuring out how to access assertions and that mechanism won’t be retained in that form.
exportStdVars	boolean	This was intended to eventually default on and suppress the “standard” variables the SP originally used for a bunch of things. This will become a hub consideration and can be removed.
exportCookie	boolean	Exposes the cookie name in a standard way to allow manipulation. Was never a fan of this but will have to think on it, and whether this really needs to be content-specific vs. application layer.
exportDuplicateValues	boolean	Only exists because the current design requires a fair amount of per-request work to do. If we can redesign this to function more sanely up front once, won’t need it, since there’s no value to dups.
redirectToSSL	unsignedInt	Hacky trick for IIS to support http to https redirects to a specific port. I’d like to hope IIS 7 handles this by now? If not, jeesh.
entityID	URI	This is a discovery hook, it specifies the IdP to use based on content. Hesitation is that it’s somewhat SAML-specific, at least the name is, but can rename and deprecate.
entityIDSelf	URI	Similarly, this is the big “avoid overrides for vhosting” feature that overrides the SP name, and should be moved to the hub as an option for computation of the issuer value.
discoveryURL	URI	Another discovery hook, overrides DS location by content rule.
discoveryPolicy	string	Likely unused but is a thing the SAML DS spec allows for setting.
isPassive	boolean	These are all SAML (2) specific settings that override what were originally SessionInitiator options, and came along with the move away from multiple SessionInitiators and the requireSessionWith concept. The question is really whether to go back to that model once the old “chains” of SessionInitiators really just become profile configurations but it’s not entirely clear whether that old model was ever workable. Not all settings are really specific to the IdP you choose, which is where profile configuration becomes workable. If this sticks, clearly these kinds of options have to end up being less tightly controlled and more or less used as an arbitrary set of input options fed into the code for a given protocol that decides how to issue its requests, which is what the model really is now in the SP.
forceAuthn	boolean
authnContextClassRef	list of URIs
authnContextComparison	SAML enum
NameIDFormat	URI
SPNameQualifier	string
attributeIndex	string
returnOnError	boolean	This is not documented well, I think it was a way to tell a SessionInitiator to silently return in the event of an error, and is implicitly used when isPassive is. Probably needed I guess.
redirectErrors	URI	Bypasses SP error machinery but works pretty poorly in terms of communicating adequate error specifics. It’s possible if not likely this would just become a default way of handling errors if detailed information needs to be known.
sessionError	URI	These override the SP error template used for various cases. Error handling like is going to change a fair amount, so this is probably not surviving in this form, but OTOH…dunno. We don’t want error pages to have to be centrally controlled but I don’t know how safe it would be to feed in a Velocity template to the hub either….
metadataError	URI
accessError	URI
sslError	URI
target	URI	Very odd use case I never grasped, but basically overrides the RelayState-derived location to send the browser to
acsIndex	unsignedShort	This isn’t even documented anymore I suspect, and it’s going to go. Just a ridiculous idea, unworkable.
REMOTE_ADDR	string	This probably shouldn’t be a content setting but it ended up here due to being used during request processing. Again, a hack to compensate for IIS that I have to think would be unneeded by now? I hope? We just should not be in this business.
encoding	string	Allowed URL encoding of the variables to address Unicode problems, likely still needed but perhaps not at the content level
attributeValueDelimiter	string	Changes the multi-value delimiter, still needed but perhaps not at the content level
unset	list of strings	This was added to allow settings to be “cleared” lower in the tree, and Apache itself doesn’t really handle that well, so likely needed.

Application and Asserting (Relying) Party Settings

These overlap because the way the SP works now is that there are a package of settings you can override via RelyingParty elements (which should have been called AssertingParty) that apply when the IdP involved falls into a particular case by name or metadata tag/group. A few settings are (dubiously I guess) only settable at the Application level but most just get overridden at the RP level.

This includes some options that are located in e.g. the <Sessions> element, but that was always just a cosmetic/pointless difference.

Complicating this is the fact that a lot of these settings cross the agent/hub line now and I guess it will depend how many of them really need to be controllable at the agent side vs. centrally managed.

Name	Type	Location	Notes

Name	Type	Location	Notes
id	string	Application	Keys the override mechanism, hacky trick used currently that locks the root element to an id of “default”. With the subordination of Application to Agent in the hub, it doesn’t actually matter if there’s a fixed default or not.
entityID	URI	Application, RelyingParty, Content	This was the original way to specify the SP name, but it feels a lot like the original IdP mistake to put it as a RelyingParty setting and not a ProfileConfiguration item. My intent is to fully devolve determining the protocol issuer value to the hub in all cases.
homeURL	URI	Application	This is a default “if no RelayState” pointer to where to go and almost always just the root of the site but I’m sure people have used it. Definitely contaminates this area of the system with “content” awareness in some sense, creating a challenge to decouple things.
policyId	string	Application	Definitely dead since it ties into security processing, but the interesting note is that it never got included as an RP setting, possibly due to order of processing concerns knowing who the IdP is early enough. It does show up down at the individual protocol handler shortcut level. Either way, dead.
REMOTE_USER	list of strings	Application	Very odd that this shows up here, nowhere else, and REMOTE_ADDR was only a content setting. That’s due to the latter coming much later. Seems clear we would NOT have defined REMOTE_USER here originally and it likely needs to migrate out to a Content setting. Making it IdP-specific is an interesting idea but may be difficult to pull off.
unsetHeaders	list of strings	Application	Not used really at all, allows the set of headers to clear to be custom. The whole area is a problem of course since it was very hard to make headers even close to safe and it ended up tied very closely into the attribute processing layer, which will be…very hard to translate clearly, but we have to somehow. I believe this will simply be replaced by a new mechanism to control the namespace of headers being used and thus enumerate which ones to clear implicitly. This is to decouple the names produced by the hub with the ones used by the agent.
attributePrefix	string	Application	These allow the variable names to be adjusted on the fly. The basic one is pretty simple and helps out with things like AJP proxying, and is likely needed somewhere. The metadata one is just…odd, and had to do with the original support for sucking tags out of metadata and stuffing them into attributes. The hub would have to distinguish that I think.
metadataAttributePrefix	string	Application
requireAuthenticatedEncryption	boolean	Application	I don’t know why this ended up here. Clearly should have been a policy layer concept or handled in some better way, but I’m not sure it makes much sense really. Must have been some attempt to incentivize GCM support but no SP is going to care, it’s not their data.
handlerURL	URI	Application	This is certainly content-related, but it’s also tied pretty tightly up with the metadata needed to make things work if it’s actually changed, so might be better to divorce it from the agent and have it managed more as an IT “task” if it really has to be different (the agent would need to know it, but may not need to be able to change it on that end).
handlerSSL	boolean	Application	Probably more an agent consideration I suppose but then runs into security policy I guess.
exportLocation	URI	Application	Should both go away if we can shift to a different model for assertion access, which is the intent.
exportACL	list of IPs	Application
cookieName	string	Application	All sort of connected mostly to session cache handling, though the props apply to other cookies also. Will depend on session design I think. Lifetime is used to push cookies out across restarts.
cookieProps	string	Application
cookieLifetime	seconds	Application
sameSiteSession	Enum	Application	Another cookie property that more or less applies to all the cookies used.
sameSiteFallback	boolean	Application	The hack for old Mac and Android support. Might be a chance to just drop that.
idpHistory	boolean	Application	Dropping for sure
idpHistoryDays	days	Application
idpHistoryProps	string	Application
lifetime	seconds	Application	Session cache policy for the application, obviously needed but will depend on design there.
timeout	seconds	Application
maxTimeSinceAuthn	seconds	Application	This is only enforced at acceptance time, so this is really a security policy setting, but it may need to be agent-driven because it’s the only practical way to make ForceAuthn useful.
checkAddress	boolean	Application	This is the cross check with the assertion, so I suspect it will be sufficient to manage this at the hub. Kind of simplifies the problem really.
consistentAddress	boolean	Application	This is session cache policy so likely will be agent-driven.
postData	string	Application	The POST data preservation support, this only applies to the SSO boundary right now. Definitely more of a hub consideration I suspect and may have to be turned into something more general perhaps.
postLimit	bytes	Application
postTemplate	string	Application
postExpire	seconds	Application
relayState	string	Application	This will be a hub issue
redirectLimit	enum	Application	Likely still agent side
redirectAllow	list of URIs	Application	Likely still agent side
authType	enum	Application, RelyingParty	Not the same as the content setting, this was for SOAP communication, definitely gone (in this form)
authUsername	string	Application, RelyingParty	Used for some of the SOAP authType values, gone
authPassword	string	Application, RelyingParty	Used for some of the SOAP authType values, gone
signing	enum	Application, RelyingParty	Controls signing and encryption, definitely moving to hub and to a form consistent with IdP. I think most of the behavior was already modeled by the IdP when it comes to “conditional” signing or encryption but will need review
signingAlg	URI
digestAlg	URI
encryption	enum
encryptionAlg	URI
keyName	URI
artifactEndpointIndex	string	Application, RelyingParty	Not supporting outbound artifact binding, so gone.
chunkedEncoding	boolean	Application, RelyingParty	SOAP related, definitely gone
connectTimeout	seconds	Application, RelyingParty	SOAP related, definitely gone
timeout	seconds	Application, RelyingParty	SOAP related, definitely gone
cipherSuites	string		SOAP related, definitely gone
requireConfidentiality	boolean	Application, RelyingParty	SOAP related, but will have to review if this is addressed. The IdP doesn’t generally support outbound SOAP with protocols that receive data, so it’s less prone to the problem of using http but getting an unencrypted response. Of course, http isn’t too common anymore either.
requireTransportAuth	boolean	Application, RelyingParty	SOAP related, will need review to ensure semantics are handled.
requireSignedAssertions	boolean	Application, RelyingParty	Profile config option I imagine
sessionHook	URI	Application, RelyingParty	Definitely needed and probably has to be agent driven
artifactByFilesystem	boolean	Application, RelyingParty	Dead, part of old hacky trick in the SP for pluggable authn
requestDelegation	boolean	Application, RelyingParty	Already undocumented, part of the deprecated delegation work that’s pulled from V5
authnContextClassRef	URI	Application, RelyingParty	In this context they’re like profile config options, but they’re also content settings. Arguably the content setting part is how the agents override profile options set on the hub, but TBD.
authnContextComparison	SAML 2 enum
NameIDFormat	URI
SPNameQualifier	string
attributeIndex	string