NativeSPhtaccess
When used with Apache, the SP includes an Access Control plugin implemented on top of the Apache Require
authorization command. The placement rules for this command are dictated by Apache, and include its <Directory>
, <File>
, and <Location>
blocks, as well as .htaccess
files. By default, any place you can apply the Require
command will trigger the Access Control implementation supplied with the SP's Apache module.
Make sure that any user will have already established a session, or require a session for the same path, or any access attempt will result in a 403.
Location Blocks Take Precedence
.htaccess directives are able to override <Directory>
blocks, but they cannot override <Location>
blocks. If your .htaccess rules appear not to be executing, check for conflicting directives in the rest of Apache's configuration.
General Syntax
The general syntax of a Require
rule is:
Require rule-type value1 value2
Some of the rule types support a regular expression mode:
Require rule ~ exp1 exp2
Rule Types
The SP supports the following rule "types" (the type is the first parameter of the command):
shibboleth
- This is a special "dummy" rule that allows a
Require
command to be inserted to satisfy Apache's requirements when using theAuthType
command. It takes no parameters and has no effect other than to ensure that the module sees and processes requests. It does not restrict access based on whether a user is logged in, and is therefore commonly used with the lazy session feature.
- This is a special "dummy" rule that allows a
shib-session
(Shibboleth V2.5.2 and Later) (Apache 2.4 and Later ORShibCompatWith24
)- A rule that requires an authenticated session, but nothing else. No information of any kind about the user is required in order to satisfy this rule and it should never be used in the absence of additional application logic to perform authorization. This is equivalent toÂ
valid-user
in older releases, or whenShibCompatValidUser
isÂOff
.
- A rule that requires an authenticated session, but nothing else. No information of any kind about the user is required in order to satisfy this rule and it should never be used in the absence of additional application logic to perform authorization. This is equivalent toÂ
valid-user
(Deprecated)- Prior to V2.5.2, and whenÂ
ShibCompatValidUser
isÂOff
(the default), this is equivalent to theÂshib-session
rule above. When theShibCompatValidUser
option is enabled, this rule is implemented compatibly with the rule implemented by Apache itself and requires a non-null REMOTE_USER value be set for the request. This restores the ability to deploy Shibboleth along with other modules and rules. A future version of the SP may remove the "special" definition and such rules should be changed to rely onshib-session
.
- Prior to V2.5.2, and whenÂ
shib-user
(Shibboleth V2.5.2 and Later) (Apache 2.4 and Later ORShibCompatWith24
)- A rule based on the REMOTE_USER value established for the request. The remaining parameters are the values to compare against. Regular expression and negation modifiers are supported (see below).
user
(Use of ~/! Modifiers Deprecated)- Prior to V2.5.2, and whenÂ
ShibCompatValidUser
isÂOff
(the default), this is equivalent to theÂshib-user
rule above. When theÂShibCompatValidUser
option is enabled, this rule is implemented compatibly with the rule implemented by Apache itself and does only standard string matching against REMOTE_USER. This restores the ability to deploy Shibboleth along with other modules and rules. A future version of the SP may remove the "special" definition that supports modifiers and such rules should be changed to rely onshib-user
.
- Prior to V2.5.2, and whenÂ
group
(Apache 2.2 and Earlier)- A rule to check membership of the REMOTE_USER value established for the request against a group membership file designated with the
AuthGroupFile
command. The remaining parameters are the names of groups to check membership against. Starting with Apache 2.4, support for this option is left up to other "out of the box" Apache module support for group-based rules, rather than reimplemented by the SP.
- A rule to check membership of the REMOTE_USER value established for the request against a group membership file designated with the
authnContextClassRef
- A rule based on the SAML authentication context class or method asserted by the IdP. The remaining parameters are the values to compare against.
authnContextDeclRef
- A rule based on the SAML authentication context declaration asserted by the IdP. The remaining parameters are the values to compare against.
shib-plugin
(Apache 2.4 and Later ORShibCompatWith24
)- Enables the use of XML Access Control rules for access control. The single parameter is the path to an access control configuration file. The plug-in is loaded on every request, which allows on-the-fly changes of access control rules (though is less efficient if large rulesets are used). This is equivalent to the olderÂ
ShibAccessControl
option and can be enabled for use with older Apache versions using theÂShibCompatWith24
option.
- Enables the use of XML Access Control rules for access control. The single parameter is the path to an access control configuration file. The plug-in is loaded on every request, which allows on-the-fly changes of access control rules (though is less efficient if large rulesets are used). This is equivalent to the olderÂ
shib-attr
(Apache 2.4 and Later ORShibCompatWith24
)- The Apache 2.4 authorization API does not allow for "extensible" rule types within a single module, so to accomodate rules based on attributes, a new rule type is used. The first parameter to the rule specifies the attribute ID to check, and the rest of the parameters are used as values to check for. This rule type can be enabled for use with older Apache versions using theÂ
ShibCompatWith24
option. Note that for literal comparisons, the case sensitivity of the match is dependent on thecaseSensitive
property applied when the attribute is decoded.
- The Apache 2.4 authorization API does not allow for "extensible" rule types within a single module, so to accomodate rules based on attributes, a new rule type is used. The first parameter to the rule specifies the attribute ID to check, and the rest of the parameters are used as values to check for. This rule type can be enabled for use with older Apache versions using theÂ
- any string value (Apache 2.2 and Earlier, Deprecated)
- Prior to Apache 2.4, any other rule type is matched against the set of attribute ID values available in the session associated with the request, and the value(s) of the corresponding attribute(s) are compared to the rest of the rule parameters. A future version of the SP may remove this feature and such rules should be changed to rely on
shib-attr
.
- Prior to Apache 2.4, any other rule type is matched against the set of attribute ID values available in the session associated with the request, and the value(s) of the corresponding attribute(s) are compared to the rest of the rule parameters. A future version of the SP may remove this feature and such rules should be changed to rely on
Rule Modifiers
A pair of rule modifiers are supported to affect the processing of the rule types that accept parameters (all but the first two above). Modifiers are placed after the rule type but before any comparison values.
- ~ (tilde)
- The tilde modifier causes the rest of the parameters to be interpreted as regular expressions rather than literal values. The
group
rule does not support this modifier.
- The tilde modifier causes the rest of the parameters to be interpreted as regular expressions rather than literal values. The
- ! (bang)
- The bang modifier inverts the rule such that a non-match satisfies the rule. This does not apply to rules based on arbitrary attributes (the ones identified by an arbitrary string).
The two modifiers can be combined, so as to enforce a regular expression that must NOT match. When using both modifiers, be sure to separate them with a space (see examples).
Rule and Module Combinations
Apache 2.4
As of Apache V2.4, authorization rules are designed to be handled by specific modules that register for them. With this change, the notion of combining rules from different modules is a first-order concept using a feature called authorization containers. This renders the commands described below obsolete and they are no longer supported.
Apache 1.3 - 2.2
Prior to Apache V2.4. the server functions by allowing access if any rule is satisfied. This allows rules recognized by different modules to appear, since modules can ignore rules they don't understand and simply grant access on their own, but limits the kinds of combinations possible.
The SP module includes a ShibRequireAll
command that changes this semantic and requires that all rules present be satisfied before granting access. This is straightforward as long as all the rules are known to the SP module, but becomes complex if other modules are involved.
To control this behavior, the AuthzShibAuthoritative
command is supplied. The following matrix describes how the options interact when an unrecogized rule is found:
 |
|
|
---|---|---|
| Access Denied | Decision Left to Other Modules |
| Ignored | Ignored |
Recommended Practices for Compatibility
The following are suggested steps to take to avoid work in the future:
- Upgrade to V2.5.2 or later of the SP.
- Prior to Apache 2.4, turn onÂ
ShibCompatWith24
to enable the newer versions of various rules. Make sure you have no existing rules by those names referring to custom attributes. - Avoid Shibboleth-style use of theÂ
valid-user
andÂuser
rules, and replace them withÂshib-session
andÂshib-user
respectively (if needed). Of course, if all you need is the existing Apache semantics, feel free to use them. On Apache 2.4, turn onÂShibCompatValidUser
.
The soonest changes would be made to remove deprecated options is in a V3.0 release of the SP, and there are no current plans for that. However the various combinations and issues are quite complex due to the software's age, so avoiding all this is the best option.
Examples
# Direct comparison Require shib-attr affiliation student@osu.edu student@psu.edu # Using an expression Require shib-attr affiliation ~ ^student@(osu|psu)\.edu$
Require shib-user ! ~ ^.+@(osu|psu)\.edu$