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 won’t adapt itself to Spring very well, and 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. Likely 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 |
|---|---|---|
applicationId | string | This tied the requests back to the Application layer and probably will continue to be needed, but it’s likely the values will have to change in cases where multiple agents are running against one hub. Notionally, each deployment would have some kind of unique prefix, so possible the prefix could be set separately and then combined with the existing values. |
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. 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. I think this should probably be removed and redesigned, but it won’t end up being a whole lot better for the application, just hopefully not a mechanism that really requires this much extra cruft to achieve. |
exportStdVars | boolean | This was intended to eventually default on and suppress the “standard” variables the SP originally used for a bunch of things. I’d ideally like to carry that through and just require that people configure the resolver to populate attributes with the information they want, and just make sure all the existing ones can be handled. We can ship things with it all set up for that out of the box. |
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. |
entityIDSelf | URI | Similarly, this is the big “avoid overrides for vhosting” feature that overrides the SP name. |
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 |
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 or centrally managed.
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”, clearly will need to change. |
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 sense is we end up leveraging this for compatibility but newer configs would delegate the entityID to the hub. |
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. |
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. I don’t know if we can just drop it, I should have added a deprecation warning I suspect. If we need it, we need it, the idea was just that a particular SAML Attribute might be about the IdP and not the subject. |
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 I hope we can do. |
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 good 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. Another of those “probably something the agent should be able to influence” things. |
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 in part |
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 | Probably needs agent control but could be debated |
redirectAllow | list of URIs | Application | |
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 | ||
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 | Seriously doubt we will bother supporting outbound artifact binding. |
chunkedEncoding | boolean | Application, RelyingParty | SOAP related, definitely gone |
connectTimeout | seconds | Application, RelyingParty | SOAP related, definitely gone |
timeout | seconds | ||
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 |