Shibboleth access control using shibboleth2.xml

Authentication requirements and access control rules can be defined in the shibboleth2.xml configuration file. This is the only way that will work with IIS; with Apache it's also possible to configure rules in the Apache configuration files. Its actually possible to mix the two approaches (with the Apache files taking precedence) but that way madness lies - it's much simpler to use one or the other.

IIS Considerations

Under IIS the SP software needs some additional configuration information to allow it to obtain canonical scheme, host, and port information about an incoming request. This is achieved by a <ISAPI> element inside the <InProcess> element of the configuration file. See

 https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPISAPI

for more details.

Apache considerations

Under Apache, the SP software requires that the ServerName is correctly set to reflect the name of the site and that the UseCanonicalName directive is set to 'On'. Without this it may be possible to access the site using an alias and so bypass any access control implemented in shibboleth2.xml.

Further, Apache won't actually enforce access control unless an AuthType and Require directive are both in force for the protected content. Adding

 AuthType shibboleth
 Require shibboleth

to an appropriate <Location> or <Directory> block, or to a .htaccess file is sufficient. Most easily, adding

 <Location />
   AuthType shibboleth
   Require shibboleth
 </Location>

to the main configuration file should ensure that any access control in shibboleth2.xml will behave as expected.

Configuration examples

All of the following configuration examples should appear inside a <RequestMap> element in the <RequestMapper> element of the shibboleth2.xml configuration file. See editing XML for hints about editing XML files.

Note that the content of the <RequestMapper> is a reloadable resource, which means that the XML content can be supplied inline, in a local file, or a remote file, and can be monitored for changes and reloaded on the fly. The root of the XML instance MUST be a <RequestMap> element.

Any users

Require authentication but don't limit who can authenticate. Note, for SPs in the UK federation, that the authenticated user could be anyone with an identity in any SP in the federation.

 <Host name="mnementh.csi.cam.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="true">
     <AccessControl>
       <Rule require="valid-user"/>
     </AccessControl>
   </Path>
 </Host>

See <Host>, <Path>, <AccessControl> and <Rule>.

Particular users

 <Host name="mnementh.csi.cam.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="true">
     <AccessControl>
       <Rule require="user">jw35@cam.ac.uk fjc55@cam.ac.uk</Rule>
     </AccessControl>
   </Path>
 </Host>

Exactly which attributes Shibboleth uses for 'user' is controlled by the REMOTE_USER attribute of the <ApplicationDefaults> element in shibboleth2.xml. By default this is the first of the 'eppn', 'persistent-id', or 'targeted-id' attributes that has a value. When user is based on eppn it will have '@cam.ac.uk' on the end for University users.

Note that the content of the <Rule> element can be multiple values separated by space, making the rule an implicit <OR> - this rule could have been written

 <Host name="mnementh.csi.cam.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="true">
     <AccessControl>
       <OR>
         <Rule require="user">jw35@cam.ac.uk</Rule>
         <Rule require="user">fjc55@cam.ac.uk</Rule>
       </OR>
     </AccessControl>
   </Path>
 </Host>

See <AND>, <OR>, and <NOT>.

Cambridge user

Require authentication from someone in the University but don't otherwise limit who can authenticate. This is achieved with a pattern match on 'user'.

 <Host name="mnementh.csi.cam.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="true">
     <AccessControl>
       <RuleRegex require="user">@cam.ac.uk$</RuleRegex>
     </AccessControl>
   </Path>
 </Host>

See <RuleRegex>.

Group membership in lookup

 <Host name="mnementh.csi.cam.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="true">
     <AccessControl>
       <Rule require="groupID">100852</Rule>
     </AccessControl>
   </Path>
 </Host>

Institution membership in lookup

 <Host name="mnementh.csi.cam.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="true">
     <AccessControl>
       <Rule require="instID">CS</Rule>
     </AccessControl>
   </Path>
 </Host>

More complex combinations

This will grant access to the user jw35xx@idp.protectnetwork.org or to anyone in the Computing Service (instID=CS) who is also in lookup group 100852 (groupID=100852):

 <Host name="mnementh.csi.cam.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="true">
     <AccessControl>
       <OR>
         <Rule require="user">jw35xx@idp.protectnetwork.org</Rule>
         <AND>
           <Rule require="instID">CS</Rule>
           <Rule require="groupID">100852</Rule>
         </AND>
       </OR>  
     </AccessControl>
   </Path>
 </Host>

Require authentication only

This forces the user to authenticate, but doesn't impose any access control. This is useful when you want to delegate access control to a protected web application.

 <Host name="mnementh.csi.cam.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="true">
   </Path>
 </Host>

Optional authentication

With this configuration, the Shibboleth SP won't actually require users to authenticate:

 <Host name="mnementh.csi.cam.ac.uk">
   <Path name="secure" authType="shibboleth" requireSession="false">
   </Path>
 </Host>

However if they follow a link to https://<sitename>/Shibboleth.sso/Login then this _will_ trigger authentication, after which any attributes of the user will be available to web applications which can customise their behaviour accordingly. It's useful to provide a URL to link to after the user has authenticated - use a target= parameter and supply it with a URL-escaped URL.