Table of contents
One of the great advantages of Shibboleth are its capabilities to easily define secure access control rules. Find below many useful examples and explanations of common access control rules and how they can be used effectively.
A resource can be protected with acces rules defined in the web server configuration, in Shibboleth or by the application itself. In all cases a Shibboleth session must be enforced first. This ensures that the user's attributes are available and can be used for access control. A user is then only granted access if his attributes match the defined access control rules.
Unless one implements access control within the application itself by access the AAI attributes, there are three methods how Shibboleth itself can perform access control with Apache or IIS.
Apache Version 2.4 in combination with SP 2.5.1 (or greater)
Apache Version 2.2 in combination with SP 2.5.1 (or greater)
Since Apache is the most popular web server in the Internet, let's see how easily access rules can be defined in Apache. For Apache 2.2, you can set the option ShibCompatWith24 On to be compatible with the new syntax. A very simple access control rule that could be defined in the Apache configuration looks like this:
This will enforce a Shibboleth session, i.e. users have to authenticate first in order to access the content of the directory "protected-directory" and all its sub directories. The three lines between the <Location> element are the Shibboleth access control directives. The same lines could also be used in an .htaccess file. In this example, the directive Require homeOrganizationType university uas enforces that users must be members of a university or federal institute of technology (homeOrganizationType "university") or a university of applied sciences or university of teacher education (homeOrganizationType "uas").
The directive ShibRequestSetting requireSession true is equivalent to the old directive ShibRequireSession On, which is not recommended to use anymore.
In case the whole Apache web server shall be protected with Shibboleth except for one specific location or sub directory, use the following directives:
If there are multiple Require directives, it's sufficient that any of them matches by default, i.e. they are evaluated as OR conditions. If you want to force that all Require directives must match, i.e. they are evaluated as AND conditions, you need to add the directive ShibRequireAll On. In the following example, a user must be staff member and it's home organization must be uzh.ch.
Also have a look at the AAI Attribute Specification in order to see which attributes one can use in order to create fine-grained access control rules. The attribute names of these access control rules are defined as id (and before SP 2.5 aliases) in the attribute-map.xml of the Shibboleth configuration.
Also have a look at the Expert Home Organisation page for more information about the homeOrganization and homeOrganizationType values of the SWITCHaai Home Organisations.
XML access rules are defined either directly in the Shibboleth configuration file (e.g. shibboleth2.xml within a <Host> element in the <RequestMap>) or in an externally referenced and dynamically loaded XML file.
In order to use XML access control rules with Apache (e.g. in order to dynamically protect a location), Apache first has to be made aware that Shibboleth shall be active for a given location. This can be achieved by using the configuration directives:
Inline access control rule
An example of an inline access control rule that protects the directory protected-directory but won't enforce an AAI session on the sub directory unprotected then looks like this:
As can be seen in the example above, the allowed boolean operators are AND, OR and NOT.
Linked access control file
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. The name of the file can be chosen arbitrarily.
The syntax in
shibacl.xml looks like (similar to inline but note the required xml namespace definition):
More information on XML access control can be found on the official SP XML Access Control (Shibboleth Wiki).
Note about Apache, XML based access control and security:
You should set the directive UseCanonicalName On in your Apache configuration (it's off by default), especially if you have configured multiple hostnames in your virtual host in Apache. Else, the configured XML access control rules might be bypassed.
Background: By default, Apache "trusts" the user’s web browser about what the requested hostname is and reports that value internally. Shibboleth chooses the access control rules in a <Host> element based on this hostname. This means that if a virtual host is accessible by multiple hostnames and a browser sends a different hostname than given in the <Host> element, the XML based access control rules might not be applied and thus access control would be bypassed. The directive UseCanonicalName On forces Apache to pass the hostname configured in the directive ServerName to Shibboleth instead of using the hostname sent by the browser.
Please refere to the Shibboleth documentation, "Prepping Apache" for details about this.
Create access control rules for Apache or Shibboleth by selecting users, organisations and privileges below to automatically compose a matching set of rules.
Chose if the access control is created for an Apache web server or for Shibboleth directly.
Apache Access Rule Shibboleth XML Access Control (needed for IIS)
Provide the Apache version that you are using.
Apache Version 2.4 and with SP 2.5.1 (or newer) Apache Version 2.2 and SP 2.5.1 (or newer)
Decide whether to protect a <Location>, <directory> or a .htaccess file.Location Directory .htaccess
Choose in below the types of organisation, individual organisations and/or the types of users that you want to allow access to.► Show Home Organization Types:
Consider first reading the detail information on the Home Organisation Type attribute and which organisations belongs to which type.University
Consider first reading the detail information on the Affiliation attribute.Faculty
Provide here one or more (space-separated) entitlement values that a user must have. A typical entitlement value is urn:mace:dir:entitlement:common-lib-terms, which often is used by publishers to determine if a user is eligible to access e-journals.
If only one value is provided, a regular expression can be provided.
Select with which boolean operator the rules should be connected.
Evaluate conditions with boolean OR Evaluation conditions with boolean AND
Insert this <RequestMapper> element in shibboleth2.xml before the element <ApplicationDefaults>
Using .htaccess files has the advantage that access control rules are dynamically processed without restarting the web server. In addition, .htaccess files can be set by any user with write privileges for a web server directory. However, one drawback of .htaccess files is the lack of flexibility when it comes to create access control rules.
Compared to the XML Access Control rules, the Apache 2.2 access control
directives can only be connected with simple boolean OR and AND
operators on one single level. This may not be sufficient for more
advanced access control use cases.
Since Shibboleth Service Provider version 2.4, there is also way to
combine the advantages of .htaccess files or httpd.conf and XML Access Control rules.
This looks like:
For Apache 2.4 (and SP 2.4 or greater), you have different options to implement more complex rules. Either you combine the httpd.conf and the XML Access Control rules like this:
Add an absolute file path after ShibAccessControl. This file (e.g. /var/www/aai/shibacl.xml) then must contain an XML Access Control rule. For example:
This would grant access only to students of ETHZ and EPFL or to lecturers of ETHZ.
Or you use the following new directives introduced by Apache 2.4 to create boolean access control rules with OR and AND operators: <RequireAll>, <RequireAny> and <RequireNone>. The new directives can be used in the Apache configuration or in .htaccess files. The above example can therefore also be implemented in Apache 2.4 and the Service Provider version 2.5.1 or newer like this:
For some applications with high security requirements it might be beneficial to break the Single-Sign On feature of AAI and require a reauthentication of the user. This can be achieved by using a SAML2 SessionInitiator with the content parameter forceAuth.
This SAML2 SessionInitiator parameter will force the user to authenticate at the Identity Provider, even if he still has a valid Single-Sign On session. In combination with a Service Provider's logout handler, this feature is especially useful for applications often used at public terminals/kiosks. It allows logged in users to log out from a web application.
To use the forceAuthn parameter, replace the simplified SSO and Logout elements in shibboleth2.xml with:
If you wonder what the names of the attributes in a web application (e.g. PHP, Perl, ...), they are defined in the file /etc/shibboleth/attribute-map.xml file (the attribute names correspond to the "id=" and "aliases" values of the <Attribute> elements) for Shibboleth 2.x. Alternatively, one can access the Shibboleth session handler after a successful authentication at '/Shibboleth.sso/Session'. This handler also shows the available attributes and their names in the web server environment.
If the Apache directive 'ShibUseHeaders On' is used as described below, the attributes will not only be available in the web server environment in form of web server environment variables but also in form of HTTP header variables. However, the names of HTTP header variables will be transformed by Apache so that they look differently than defined in the attribute-map.xml file. For instance, the attribute whose 'id' in attribute-map.xml is 'Shib-EP-Entitlement' will be transformed (name in uppercase letters, prepended by 'HTTP_' and all '-' are replaced by '_') to 'HTTP_SHIB_EP_ENTITLEMENT' by Apache.
Remember that users from the Virtual Home Organization or Swiss edu-ID users can also authenticate via AAI and, therefore, may access all resource that don't enforce access control rules. If your service should not be accessible for these users, you can block the access for VHO and Swiss edu-ID users like this:
For Apache 2.2
or more elegant with an XML Access Control rule:
As an XML Access Control rule:
or for Apache 2.4 and SP 2.5.1 or later
There are use-cases that involve protecting certain documents, web applications or just certain functions of a web application in a way where only access shall be granted to 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, it's necessary to set a common attribute for all these users. This can be done using the SWITCHtoolbox, which allows creating groups and subgroups that the can be given access to various tools (wikis, mailing lists, document storage, etc). Adding a tool to the toolbox would allow using a simple access control rule like:
Although this solution works as assumed, it may be hard to get and maintain all user unique IDs from the people that shall be granted access. The Group Management Tool (GMT) facilitates this process because it allows to easily collect all the uniqueIDs. The GMT is a web application that one has to download and deploy locally.
In case a Java application shall be protected with Shibboleth 2.x and if the applications also shall be able to read Shibboleth attributes, choose one of the following options in order to make Apache forward Shibboleth attributes to the Java application:
The underlying reason why one has to adapt the configuration with one of the above options is that Shibboleth attributes are not forwaded to a Java application by default. Shibboleth 2.x in its default configuration doesn't store the attributes as header variables in the web server environment but as environment variables. The effect of this that mod_proxy_ajp and mod_jk won't forward the attributes anymore to the servlet container unless one uses either of the above solutions. More information on this topic can be found on the pages NativeSPhtaccess of the Shibboleth Wiki.
Note: Due to a bug in some servlet containers it may not be possible to read the Shibboleth attributes directly using a loop like:
Instead, one has to access the header names directly using something like:
This of course implies that one knows the attribute names. These are defined in the attribute-map.xml as id and aliases of the Attribute elements.