Shibboleth Service Provider Access Rules
It is the resource administrator's responsibility to configure the correct access rules for a protected resource. A resource either can be protected with acces rules defined in the web server configuration or by the application itself by checking certain Shibboleth attributes. In both cases, a Shibboleth session must be enforced on the file, location or directory to protect. Second, there must be an authorization rule based on attributes that determines how access is granted.
When using web server access rules, there are three ways to define rules:
- Web Server config file
- E.g. you can directly set rules for a directory, file or loacation in the httpd.conf of Apache.
The downside of this method is that the web server has to be restarted each time the configuration file is changed. - Directory config file
- In Apache you can use so-called '.htaccess' files in directories to overwrite the web server static configuration settings. The rules defined in that file are dynamic, which means that they can be changed without restarting the web server. This also can be used to set Shibboleth access rules.
Be sure to check that the directory you use a '.htaccess' file is configured with 'AllowOverride AuthConfig' file to allow usage of '.htaccess' files.
The downside of this method that you cannot protect locations but only existing files and directories. - XML Access rules in Shibboleth config (for IIS)
- Especially needed for the IIS web server, there is a way to define access rules directly within the Shibboleth configuration file or in a linked external file that contains access rules which are define using a special XML syntax. The inline access rules as well as the externally linked file are loaded dynamically by Shibboleth and thus are also suitable to protect locations for Apache.
Once your resource is ready for use, you have to configure access rules which properly protect your resource.
Examples of Apache Access Rules
For first testing purposes (in Apache) it is OK to start with the most simple access
rule that grants access to any user with a valid AAI login and redirects all non-ssl http requets to https before processing by Shibboleth, which is recommended:
AuthType shibboleth
ShibRequireSession On
ShibRedirectToSSL 443
require valid-user
In the following some common rules (based on an
example page by University of Zurich) are shown together with a description of what effect they have.
More information on this topic can also be found in the corresponding Shibboleth Wiki page.
- All users with an AAI login
AuthType shibboleth ShibRequireSession On require valid-user- All university users with an AAI login
AuthType shibboleth ShibRequireSession On require homeOrganizationType university- All users from university of Zurich
AuthType shibboleth ShibRequireSession On require homeOrganization unizh.ch- All staff members from university of Zurich (with regular expression example)
AuthType shibboleth ShibRequireSession On ShibRequireAll On require affiliation staff require homeOrganization ~ ^unizh.ch$- People whose email address match a regular expression (in this case all D-ITET students from ETHZ)
AuthType shibboleth ShibRequireSession On ShibRequireAll On require affiliation staff require homeOrganization ~ .*@ee.ethz.ch$- All users from university of Zurich or ETH Zurich
AuthType shibboleth ShibRequireSession On require homeOrganization unizh.ch ethz.ch- All students from university of Zurich or ETH Zurich
AuthType shibboleth ShibRequireSession On ShibRequireAll On require affiliation student require homeOrganization unizh.ch ethz.ch- All users from university of Zurich, ETH Zurich, two specific VHO groups
AuthType shibboleth ShibRequireSession On require homeOrganization unizh.ch ethz.ch require entitlement http://www.olat.uzh.ch/phzh http://www.olat.uzh.ch/cas_bgm- Only users with the following e-Mail addresses
AuthType shibboleth ShibRequireSession On require mail user-x@switch.ch user-y@switch.ch- Only users with the following uniqueIDs
AuthType shibboleth ShibRequireSession On require uniqueID 000123@switch.ch 000455@switch.ch- Only users with the following uniqueIDs or from a certain VHO group with sub groups
AuthType shibboleth ShibRequireSession On require uniqueID 000123@switch.ch 000455@switch.ch require entitlement ~ ^http://www.olat.uzh.ch/.*$
XML access control
XML access rules are defined either directly in the Shibboleth configuration file ('shibboleth.xml' within the Host element) or in an externally linked and dynamically loaded XML file.
If you plan to use the XML access control rules with Apache (e.g. in order to dynamically protect a location), you first have to make sure that the Shibboleth module actually is active for the specific location or the whole web server. This can be done by using a rule in the Apache configuration like the following:
...
<Location />
AuthType shibboleth
Require shibboleth
</Location>
...
A simple inline example could look like this:
...
<Host name="sp.example.org">
<Path name="secure" authType="shibboleth" requireSession="true">
<AccessControl>
<AND>
<Rule require="affiliation">student</Rule>
<OR>
<Rule require="homeOrganization">ethz.ch</Rule>
<Rule require="homeOrganization">unizh.ch</Rule>
</OR>
<NOT>
<Rule require="homeOrganization">vho-switchaai.ch</Rule>
</NOT>
</AND>
</AccessControl>
</Path>
</Host>
...
The allowed boolean operations are AND, OR and NOT.
An example of a linked XML access control file is given below. This method has the advantage that changes to the file don't require Shibboleth to be restarted to take effect.
...
<Host name="sp.example.org">
<Path name="secure" authType="shibboleth" requireSession="true">
<AccessControlProvider uri="/var/www/secure/.shibacl.xml"
type="edu.internet2.middleware.shibboleth.sp.provider.XMLAccessControl"
/>
</Path>
</Host>
...
The syntax in .shibacl.xml looks like (similar to inline but note the required xml namespace definition):
<?xml version="1.0" encoding="UTF-8"?>
<AccessControl xmlns="urn:mace:shibboleth:target:config:1.0">
<AND>
<Rule require="affiliation">student</Rule>
<OR>
<Rule require="homeOrganization">ethz.ch</Rule>
<Rule require="homeOrganization">unizh.ch</Rule>
</OR>
<NOT>
<Rule require="homeOrganization">vho-switchaai.ch</Rule>
</NOT>
</AND>
</AccessControl>
More information on XML access control can be found on the official SP XML Access Control (Shibboleth Wiki).
Attribute Names
If you wonder what the names are of the attributes you can check for, have a look at the AAP.switchaai.xml (Shibboleth 1.3.x) file (Attribute Acceptance Policy) or the attribute-map.xml (Shibboleth 2.x) file, which usually is located in /etc/shibboleth/ or /etc/shibboleth2/. That file lists all attributes that have an alias name, which can be used for the access rules.
VHO Users
Be aware, that also users from the Virtual Home Organization can authenticate via AAI. However, it is easy to distinguish them from users from real home organizations a with this rule:
or with XML access rulesAuthType shibboleth ShibRequireSession On require homeOrganizationType ~ ^[^vV][^hH][^oO]
...
<NOT>
<Rule require="homeOrganizationType">vho</Rule>
</NOT>
...
Other ways to authorize users
There may be use-case that involve protecting certain documents, web applications or just certain functions of a web application in a way where you only want to grant access very specific users of one or more Home Organizations (see graphic below). In such a case, the users that shall get access most probably don't share a common attribute that would allow setting rules like the one above.
Therefore, you either have to make sure that all the users share a common attribute, e.g. by setting an entitlement attribute for all of them, or you have to collect their uniqueIDs and use them to create an access rule like:
AuthType shibboleth
ShibRequireSession On
ShibRedirectToSSL 443
require 234023480@unizh.ch 32489234@ethz.ch 435kjsm95s4we3ssdfsd5@unige.ch [...]
However, setting entitlement attributes for users from many different Home Organizations is something that only the user directory administrator from these Home Organizations can accomplish. Of course, they won't be very keen on doing that and also maintaining the entitlement values for you in case you want to add more users or revoke the entitlement form users.The second solution where you collect all unique IDs shifts the control (and the work) to your side as Service Provider administrator. Although the solution works as assumed, it may be hard to get all user unique IDs from the people that shall be granted access. However, there is an easy solution that you might consider looking at. It's called Group Management Tool and it allows you to easily get the uniqueIDs for you. It's a web application that basically faciliates the mangement of users and groups in order to do authorization.
Java Applications
In case you want to protect Java Applications with Shibboleth 2.x and if the applications also shall be able to read Shibboleth attributes, you have to do one of the following things:
- Use the old Shibboleth 1.3 behaviour where attributes are stored in the web server environment as header variables. This can be done using an Apache directive called ShibUseHeaders On
- Tell mod_jk, which is the bridge between Apache and your servlet container, to forward certain environment variables. Here is Apache configuration to pass particular environment variables:
JkEnvVar Shib-Application-ID JkEnvVar Shib-Session-ID JkEnvVar Shib-Identity-Provider JkEnvVar Shib-Authentication-Instant JkEnvVar Shib-SwissEP-UniqueID JkEnvVar Shib-InetOrgPerson-givenName JkEnvVar Shib-Person-surname [...]