Shibboleth Service Provider Access Control

Table of contents

Introduction

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, based on the AAI attributes (see Shibboleth Wiki "Attributeaccess"), there are three methods how Shibboleth itself can perform access control with Apache or IIS.

Apache Webservers

Most web servers are operated with Apache. Shibboleth allows to use Apache directives to protect directories, files or locations. For Apache 2.4 and SP 2.5.1 or later, the syntax has slightly changed. Please select the Apache version you use to make the corresponding examples displayed.

Static configuration

The disadvantage of editing Apache's configuration files (e.g. httpd.conf) is that the web server has to be restarted if an access control rule was changed.
Configuration instructions: Apache Access Rules, Using XML Access Control together with Apache

Directory configuration (.htaccess) file

Apache supports the use of so-called .htaccess files, which can overwrite the static configuration if these files are placed in web server directories. The rules defined in this file are dynamicly processed. They are therefore reloaded without restarting the web server. This allows also dynamically changing Shibboleth access rules.
Ensure that the directory that contains an .htaccess file is configured with 'AllowOverride AuthConfig' in the Apache static configuration. This is a prerequisite for Apache to process .htaccess files.
The disadvantage of this method is that only existing files and directories can be protected but not arbitrary locations.
Configuration instructions: Apache Access Rules, Using XML Access Control together with Apache

IIS/Apache/other Webservers

XML Access rules in Shibboleth configuration
In IIS none of the above-two methods to define Shibboleth access control rules are supported. Therefore, access control rules can only be defined directly in the Shibboleth configuration, either inline or by using a reference to an external file. The inline access rules as well as the externally linked file are loaded dynamically by Shibboleth. Defining access control rules in Shibboleth is also possible with Apache.
Configuration instructions: XML Access Control

Apache Access Rules

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:

Apache 2.2 Configuration
# Force user to authenticate on protected-directory
<Location /protected-directory>
  AuthType shibboleth
  ShibCompatWith24 On
  ShibRequestSetting requireSession true
  Require shib-attr homeOrganizationType university uas
</Location>
Apache 2.4 Configuration
# Force user to authenticate on protected-directory
<Location /protected-directory>
  AuthType shibboleth
  ShibRequestSetting requireSession true
  Require shib-attr homeOrganizationType university uas
</Location>
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 shib-attr 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 should be protected with Shibboleth except for one specific location or sub directory, use the following directives:
Apache 2.2 Configuration
# First define a rule to enforce session on all pages
<Location />
  AuthType shibboleth
  ShibCompatWith24 On
  ShibRequestSetting requireSession true
  Require shib-attr homeOrganizationType university uas
</Location>


# Then list the exceptions
<Location /unprotected>
  AuthType shibboleth
  ShibRequestSetting requireSession false
  Require shibboleth
</Location>
Apache 2.4 Configuration
# First define a rule to enforce session on all pages
<Location />
  AuthType shibboleth
  ShibRequestSetting requireSession true
  Require shib-attr homeOrganizationType university uas
</Location>


# Then list the exceptions
<Location /unprotected>
  AuthType shibboleth
  ShibRequestSetting requireSession false
  Require shibboleth
</Location>

If there are multiple Require directives, it's sufficient that any of them matches by default, i.e. they are evaluated as OR conditions. Or use the tag <RequireAny> to make it explicit. 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 Onuse the tag <RequireAll>. In the following example, a user must be staff member and it's home organization must be uzh.ch.

All users from University of Zurich who are staff members
Apache 2.2 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
ShibCompatWith24 On
ShibRequireAll On
Require shib-attr affiliation staff
Require shib-attr homeOrganization uzh.ch
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
<RequireAll>
  Require shib-attr affiliation staff
  Require shib-attr homeOrganization uzh.ch
</RequireAll>

More information on Apache access control directives can be found on the Shibboleth Wiki "Apache" and Shibboleth Wiki "htaccess" pages.

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) of the <Attribute> elements 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.

All users from universities of applied sciences with an AAI login
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr homeOrganizationType uas
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
Require shib-attr homeOrganizationType uas
All users from University of Zurich and ETH Zurich
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr homeOrganization uzh.ch ethz.ch
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
Require shib-attr homeOrganization uzh.ch ethz.ch
Users whose email address match a regular expression (in this case all D-ITET users from ETHZ)
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr mail ~ .*@ee.ethz.ch$
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
Require shib-attr mail ~ .*@ee.ethz.ch$
All students from University of Zurich or ETH Zurich
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
ShibRequireAll On
Require shib-attr affiliation student
Require shib-attr homeOrganization uzh.ch ethz.ch
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
<RequireAll>
  Require shib-attr affiliation student
  Require shib-attr homeOrganization uzh.ch ethz.ch
</RequireAll>
All users from University of Zurich, ETH Zurich or two specific VHO groups
Apache 2.2 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
ShibCompatWith24 On
Require shib-attr homeOrganization uzh.ch ethz.ch
Require shib-attr entitlement ~ ^http://www.uzh.ch/phzh$ ^http://www.uzh.ch/cas$
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
<RequireAny>
  Require shib-attr homeOrganization uzh.ch ethz.ch
  <RequireAll>
    Require shib-attr homeOrganization vho-switchaai.ch
    Require shib-attr entitlement ~ ^http://www.uzh.ch/phzh$ ^http://www.uzh.ch/cas$
  </RequireAll>
</RequireAny>
Only users with the following e-Mail addresses
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr mail user-x@switch.ch user-y@switch.ch
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
Require shib-attr mail user-x@switch.ch user-y@switch.ch
Only users with the following uniqueIDs
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr uniqueID  000123@switch.ch 000455@switch.ch
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
Require shib-attr uniqueID  000123@switch.ch 000455@switch.ch
Only users from a specific VHO group with sub groups
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
ShibRequireAll On
Require shib-attr homeOrganization vho-switchaai.ch
Require shib-attr entitlement ~ ^http://www.olat.uzh.ch/.*$
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
<RequireAll>
  Require shib-attr homeOrganization vho-switchaai.ch
  Require shib-attr entitlement ~ ^http://www.olat.uzh.ch/.*$
</RequireAll>
Only members of a specific Toolbox group
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr isMemberOf https://toolbox.switch.ch/mygroup
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
Require shib-attr isMemberOf https://toolbox.switch.ch/mygroup
Only users from Swiss academic education (without library, upper secondary, professional education and training colleges)
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr homeOrganizationType university uas hospital others vho
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
Require shib-attr homeOrganizationType university uas hospital others vho
Only edu-ID users with at least one current organisation identity/affiliation
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
ShibRequireAll On
Require shib-attr homeOrganization eduid.ch
Require shib-attr swissEduIDLinkedAffiliation ~ .*@.*
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
<RequireAll>
  Require shib-attr homeOrganization eduid.ch
  Require shib-attr swissEduIDLinkedAffiliation ~ .*@.*
</RequireAll>
Only edu-ID users with at least one current staff organisation identity/affiliation
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
ShibRequireAll On
Require shib-attr homeOrganization eduid.ch
Require shib-attr swissEduIDLinkedAffiliation ~ staff@.*
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
<RequireAll>
  Require shib-attr homeOrganization eduid.ch
  Require shib-attr swissEduIDLinkedAffiliation ~ staff@.*
</RequireAll>
Only edu-ID users with a current identity/affiliation from a specific organisation (i.e. FHNW)
Apache 2.2 Configuration
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
ShibRequireAll On
Require shib-attr homeOrganization eduid.ch
Require shib-attr swissEduIDLinkedAffiliation ~ .*@fhnw.ch
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true
<RequireAll>
  Require shib-attr homeOrganization eduid.ch
  Require shib-attr swissEduIDLinkedAffiliation ~ .*@fhnw.ch
</RequireAll>
Only Shibboleth users or users from a specific domain/IP range
Apache 2.2 Configuration
AllowOverride All

# Use IP Authorisation or Shibboleth Authorisation
Satisfy Any

# IP Authorisation
Order Deny,Allow
Deny from all
Allow from switch.ch
Allow from 130.59.6.143
Allow from 2001:620::4:ca2a:14ff:fe2f:1b97

# Shibboleth Authorisation
AuthType shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr homeOrganization switch.ch
Apache 2.4 Configuration
AuthType shibboleth
ShibRequestSetting requireSession true

# Use IP Authorisation or Shibboleth Authorisation
<RequireAll>
  # IP Authorisation
  Require ip 130.59.16.0/22

  # Shibboleth Authorisation
  Require shib-attr homeOrganization switch.ch
</RequireAll>

XML Access Control

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.

Note:
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 should be active for a given location. This can be achieved by using the configuration directives:

Apache 2.2 Configuration
...
# Activate Shibboleth but don't enforce a session
<Location />
    AuthType shibboleth
    Require shibboleth
</Location>
...
Apache 2.4 Configuration
...
# Activate Shibboleth but don't enforce a session
<Location />
    AuthType shibboleth
    Require shibboleth
</Location>
...

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:

Shibboleth Configuration: shibboleth2.xml
...
<Host name="sp.example.org">
    <Path name="protected-directory" authType="shibboleth" requireSession="true">
        <AccessControl>
            <AND>
                <Rule require="affiliation">student</Rule>
                <OR>
                    <Rule require="homeOrganization">ethz.ch</Rule>
                    <Rule require="homeOrganization">uzh.ch</Rule>
                </OR>
                <NOT>
                    <Rule require="homeOrganization">vho-switchaai.ch</Rule>
                </NOT>
            </AND>
        </AccessControl>
        <Path name="unprotected" authType="shibboleth" requireSession="false" />
    </Path>
</Host>
...

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.

Shibboleth Configuration: shibboleth2.xml
...
<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):

Shibboleth Access Control: shibacl.xml
<?xml version="1.0" encoding="UTF-8"?>
<AccessControl type="edu.internet2.middleware.shibboleth.sp.provider.XMLAccessControl">
    <AND>
        <Rule require="affiliation">student</Rule>
        <OR>
            <Rule require="homeOrganization">ethz.ch</Rule>
            <Rule require="homeOrganization">uzh.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 Shibboleth Wiki "XML Access Control" page.

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 refer to the Shibboleth Wiki "Prepping Apache" page for further details.

Access Control Wizard

Create access control rules for Apache or Shibboleth by selecting users, organisations and privileges below to automatically compose a matching set of rules.

Access Control Type

Chose if the access control is created for an Apache web server or for Shibboleth directly.

   

Apache Version

Provide the Apache version that you are using.

   

Apache Access Control Mechanism

Decide whether to protect a <Location>, <directory> or a .htaccess file.

       
Hostname:
Location:

Select Organisations and Users

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
University of Applied Sciences
Hospital
Library
Professional education and training college
Institution on the upper secondary level
Virtual Home Organization
Other
► Show Home Organizations:
► Show Affiliations:

Consider first reading the detail information on the Affiliation attribute.

faculty
student
staff
alum
member
affiliate
library-walk-in
► Show Entitlement:

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 gets often 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.



► Show Email:
► Show Unique ID:


Boolean Operator

Select with which boolean operator the rules should be connected.

   

Note:
Insert this <RequestMapper> element in shibboleth2.xml before the element <ApplicationDefaults>

Access Control Rule

Using XML Access Control together with Apache

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:

Apache 2.2 Configuration
AuthType Shibboleth
ShibRequestSetting requireSession true
ShibRequireAll On
Require Shibboleth
ShibAccessControl /var/www/aai/shibacl.xml


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:

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:

Apache 2.4 Configuration
AuthType Shibboleth
ShibRequestSetting requireSession true
Require shib-plugin /var/www/aai/shibacl.xml


Add an absolute file path after Require shib-plugin. This file (e.g. /var/www/aai/shibacl.xml) then must contain an XML Access Control rule. For example:

Shibboleth Access Control: shibacl.xml
<AccessControl
 type="edu.internet2.middleware.shibboleth.sp.provider.XMLAccessControl">
    <OR>
        <AND>
            <Rule require="homeOrganization">ethz.ch</Rule>
            <Rule require="affiliation">staff</Rule>
            <Rule require="staffCategory">102</Rule>
        </AND>
        <AND>
            <Rule require="affiliation">student</Rule>
            <OR>
                <Rule require="homeOrganization">ethz.ch</Rule>
                <Rule require="homeOrganization">epfl.ch</Rule>
            </OR>
        </AND>
    </OR>
</AccessControl>

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:

Apache 2.4 Configuration
AuthType Shibboleth
ShibRequestSetting requireSession true
<RequireAny>
  <RequireAll>
    Require shib-attr homeOrganization ethz.ch
    Require shib-attr affiliation staff
    Require shib-attr staffCategory 102
  </RequireAll>
  <RequireAll>
    Require shib-attr affiliation student
    <RequireAny>
      Require shib-attr homeOrganization epfl.ch
      Require shib-attr homeOrganization ethz.ch
    </RequireAny>
  </RequireAll>
</RequireAny>

Attribute Check

Some web applications require that certain attributes (or rather their valeus) must be presents to work. Either these applications can check on their own if the attribute and values are present for a user and then display a meaningful error message if this is not the case. Or, Shibboleth can check this and display an error message. The feature needed to configure this is called the Attribute Checker. To e.g. ensure that the mail, uniqueID, given name and surname attributes are present, the following changes need to be applied to the shibboleth2.xml file:

  1. In the element ApplicationDefaults add the following XML attribute after the entityID attribute:
    sessionHook="/Shibboleth.sso/AttrChecker"
    The element will then look something like this:
    <ApplicationDefaults
      entityID="https://www.coursereg.ethz.ch/shibboleth"
      sessionHook="/Shibboleth.sso/AttrChecker"
      metadataAttributePrefix="Meta-"
      ...
  2. Within the Sessions element at at the end (where there are the Handler elements) of this element the following handler configuration:
    <Handler type="AttributeChecker"
         Location="/AttrChecker"
         template="attrChecker.html"
         flushSession="true"
         attributes="mail uniqueID givenName surname" />
    The names in attributes correspond to the id values in the file attribute-map.xml.
  3. Create and customize the template file attrChecker.html (relative to /etc/shibboleth/) that will be shown when not all the required attributes are present. This template file can contain certain macros that Shibboleth will replace with the actual values. Typically, one would list the attributes that are missing. This could be achieved with a snippet like:
    The following attributes are missing for your user account:
    <ul>
      <shibmlpifnot givenName><li>Given Name</li></shibmlpifnot>
      <shibmlpifnot surname><li>Surname</li></shibmlpifnot>
      <shibmlpifnot uniqueID><li>Unique Identifier
    (uniqueID)</li></shibmlpifnot>
      <shibmlpifnot mail><li>E-Mail Address</li></shibmlpifnot>
    </shibmlpifnot>
    </ul>
    Please contact the helpdesk of your organisation and ask them to add the above attributes
    to your user account or to make sure that these attributes are released to this service.
    
  4. Check the Shibboleth configuration with the command (as root): shibd -t
    The output should be "overall configuration is loadable, check console or log for non-fatal problems".
  5. Restart the Shibboleth daemon for te changes to take effect. I.e. with: service shibd restart

The Attribute Checker can also be configured to look if either given name and surname are present or the display name. More details on these boolean check options are documented on the Shibboleth Wiki "Attribute Checker" page.

Forced re-authentication

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 forceAuthn="true".
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:

Shibboleth Configuration: shibboleth2.xml
<SessionInitiator
    id="Login"
    type="Chaining"
    Location="/Login"
    isDefault="true">
    <SessionInitiator
        type="SAML2"
        acsByIndex="false"
        acsIndex="1"
        template="bindingTemplate.html"
        forceAuthn="true"/>
    <SessionInitiator
        type="SAMLDS"
        URL="https://wayf.switch.ch/SWITCHaai/WAYF"/>
</SessionInitiator>

<md:AssertionConsumerService
    Location="/SAML2/POST"
    index="1"
    Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>

<LogoutInitiator
    type="Local"
    Location="/Logout" />

Attribute Names

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 before SP 2.5 "aliases") values of the <Attribute> elements) for the Shibboleth SP. 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.

Note:
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.

Block VHO and SWITCH edu-ID Users

Remember that users from the Virtual Home Organization or SWITCH 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 SWITCH edu-ID users like this:

For Apache 2.2

Apache 2.2 Configuration
AuthType Shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
ShibRequireAll On
Require shib-attr homeOrganizationType ~ ^[^v][^h][^o]
Require shib-attr homeOrganization ~ ^[^e][^d][^u][^i][^d][^.][^c][^h]

or more elegant with an XML Access Control rule:

As an XML Access Control rule:

Shibboleth Access Control: shibacl.xml
...
     <NOT>
         <Rule require="homeOrganizationType">vho</Rule>
         <Rule require="homeOrganization">eduid.ch</Rule>
     </NOT>
...

or for Apache 2.4 and SP 2.5.1 or later

Apache 2.4 Configuration
AuthType Shibboleth
ShibRequestSetting requireSession true
<RequireAll>
  require shibboleth
  <RequireNone>
    Require shib-attr homeOrganizationType vho
    Require shib-attr homeOrganization eduid.ch
  </RequireNone>
</RequireAll>

Alternative Ways to Authorize Users

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 should be granted to very specific users of one or more Home Organizations (see graphic below). In such a case, the users that should get access most probably don't share a common attribute that would allow setting rules like the one above.

Group Management Tool use case

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:

Apache 2.2 Configuration
AuthType Shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr isMemberOf https://toolbox.switch.ch/phy101

Apache 2.4 Configuration
AuthType Shibboleth
ShibRequestSetting requireSession true
Require shib-attr isMemberOf https://toolbox.switch.ch/phy101

An alternative, would be to collect all uniqueIDs/emails/persistentId values or the users that should be granted access. This then would allow using an access control rule like:

Apache 2.2 Configuration
AuthType Shibboleth
ShibCompatWith24 On
ShibRequestSetting requireSession true
Require shib-attr uniqueID 234023480@uzh.ch 32489@ethz.ch 435kjsmfsd5@unige.ch

Apache 2.4 Configuration
AuthType Shibboleth
ShibRequestSetting requireSession true
Require shib-attr uniqueID 234023480@uzh.ch 32489@ethz.ch 435kjsmfsd5@unige.ch

Although this solution works as assumed, it may be hard to get and maintain all user unique IDs from the people that should 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.

Shibboleth Attribute in Applications

Web applications running within Apache or Microsoft IIS get access to the user attributes provided by Shibboleth. Therefore, the user attributes can be used to identify/authenticate a user, to auto-provision user accounts or to perform access control directly within the application. Basically, for a web application to use user attributes, they just have to read them from the web server environment. No library or API is required for that. Attributes thus can be read the same way as an application would read the REMOTE_USER or the REMOTE_ADDR web server environment variables. This works for any programming language whose program runs with Apache or IIS.

For a simple PHP Web Application, reading and using Shibboleth attributes could look like in the following snippet:
<?php
if (isset($_SERVER['Shib-Identity-Provider'])){
  // User has Shibboleth session
  if (isset($_SERVER['persistent-id'])){
     echo 'Hello '.$_SERVER['givenName'].' '.$_SERVER['surname'];
     // Check if user with given persistent-id exists in web application database
     // If not, use the attributes to auto-provision user accounts
   } else {
     echo "No persistent-id attribute found, which is needed for identification";
   }
} else {
  echo "User has no Shibboleth session and thus is not authenticated";
}
?>

In order to know the attribute names that Shibboleth uses to populate the attributes in the web server environment, have a look at the attribute-map.xml in the Shibboleth configuration directly. The attribute names used in the web server environment correspond to the 'id' of each attribute definition. Alternatively, you can also just access the Shibboleth Session handler (/Shibboleth.sso/Session) to see how the attributes are called.

Java Applications

In case a Java application should be protected with a Shibboleth SP and if the applications also should be able to read Shibboleth attributes, choose one of the following options in order to make Apache forward Shibboleth attributes to the Java application:

  • pass attributes in environment variables (recommended method)
    If mod_proxy_ajp is used to make Apache forward requests via AJP to a servlet container the following method can be used: In shibboleth2.xml add attributePrefix="AJP_" to the <ApplicationDefaults> (or an appropriate <ApplicationOverride>) element. This is necessary because environment variables are only included in the request by mod_proxy_ajp if they have AJP_ prefixes. You can find more information about setting up Apache httpd to forward requests over AJP on the Shibboleth Wiki "Java Howo" page.
    Shibboleth Configuration: shibboleth2.xml
    <ApplicationDefaults id="default" policyId="default"
        [...]
        attributePrefix="AJP_" >
    
  • pass attributes in HTTP headers (less secure)
    Apache 2.2 Configuration
    AuthType Shibboleth
    ShibRequestSetting requireSession true
    ShibUseHeaders On
    Require shib-attr homeOrganizationType university uas
    
    Apache 2.4 Configuration
    AuthType Shibboleth
    ShibRequestSetting requireSession true
    ShibUseHeaders On
    Require shib-attr homeOrganizationType university uas
    
    This option is less secure than the other because headers are easier to spoof in web browsers (particularily IIS).

The underlying reason why one has to adapt the configuration with one of the above options is that Shibboleth attributes are not forwarded to a Java application by default. The Shibboleth SP in its default configuration doesn't store the attributes as header variables in the web server environment but as environment variables. More information on this topic can be found on the Shibboleth Wiki "htaccess" page.

Java Code Example
request.getAttribute("affiliation");

This of course implies that one knows the attribute names. These are defined as id (and before SP 2.5 aliases) of the <Attribute> elements in the attribute-map.xml of the Shibboleth configuration.

You find examples for other applications on the Shibboleth Wiki "Attribute Access" pgae.