URL: http://www.switch.ch/aai/docs/shibboleth/SWITCH/1.3/idp/update-arp.html Author: Lukas Haemmerle - SWITCH $Date: 2008/06/03 07:19:53 $ $Revision: 1.6 $
The Attribute Release Policy (ARP) file states which attributes are released to which Service Providers. Every Shibboleth Identity Provider 1.3 has one or several ARP files - one default arp.site.xml and optionally one for each user. In SWITCHaai it is recommended that the default ARP rule is to release no attributes to unknown Service Providers. However, this means that an Identity Provider needs to have listed each Service Provider it can communicate in the ARP file. So, if new Service Providers join the federation they potentially have to be added to the ARP files of each Identity Provider. To ease this procedure, SWITCH has developed a tool that securely downloads a custom-tailored ARP file from the Resource Registry via HTTPS, checks its validity, applies user defined transformation rules to this ARP file and optionally sends the Identity Provider administrator an email with the differences between the old ARP file and the new one that was installed.
It is recommended to run the updateARP script at least as often as the metadatarefresh scripts, at minimum once a day.
For the Shibboleth 2.0 Identity Provider, the updateARP script, curl, mailx and Perl are not needed anymore, because the IdP can periodically download attribute filter files itself. Custom rules still can be defined in the Resource Registry as Home Organization administrator. Notification mails about changes are then also sent by the Resource Registry.
The updateARP tool was developed in Perl in order to make it as platform independent as possible. It doesn't need any special Perl libraries installed but it needs curl (with OpenSSL >= 0.9.6) and mailx installed. The script was tested on Debian 3.1 Sarge, Mac OS X 10.4 Tiger and Solaris 9.
perlcurlmailxAfter an new ARP file was installed by the updateARP tool, an e-Mail that contains the changes is sent to the person specified in the config file:
Rules added:
------------
+ Resource 'AAI Attributes Viewer' (https://siufaaisp.unifr.ch/shibboleth)
+ 'swissEduPersonHomeOrganization' -> permit
+ 'givenName' -> permit
+ 'swissEduPersonHomeOrganizationType' -> permit
+ 'swissEduPersonUniqueID' -> permit
+ 'mail' -> permit
+ 'eduPersonAffiliation' -> permit
+ 'sn' -> permit
! Resource 'Development Resource' (https://ebulobo.switch.ch/shibboleth)
+ 'postalAddress' -> permit
Rules removed:
--------------
- Resource 'Wayfalizer' (https://tools.switch.ch/Shibboleth)
! Resource 'Development Resource' (https://ebulobo.switch.ch/shibboleth)
- 'postalAddress'
Legend:
------
+ Added - Removed ! Changed
Installation is straight forward provided you aready have installed curl and mailx.
https://aai-rr.switch.ch/download.php?file=updateARP.zip
$ unzip updateARP.zip
$ cp config.dist.txt config.txt
The script assumes that it is located /opt/updateARP and that the Shibboleth configuration directory is at /etc/shibboleth/.
Use your favourite text editor an open the config file /opt/updateARP/config.txt.
################################################################################# # updateARP config file ################################################################################# # # Copyright 2005 SWITCH - The Swiss Education & Research Network # # The updateARP script downloads files and/or customizes a Shibboleth Attribute # Request Policy (ARP) file according to rules in this configuration file. # Additionally, this script compares the previously used ARP file and informs # an administrator by email about the changes (if any) that occured. # # Requirements: # curl with SSL support (OpenSSL > 0.9.6) # mailx # # Use at own risk! Tested on: # Debian 3.1 Sarge # Mac OS X 10.4 Tiger # Solaris 9 ######## General configuration # Path to curl CurlPath /usr/local/bin/curl # Additional arguments that should be used for curl # E.g. you may specify the interface that it shall use or a proxy server CurlArguments -m 20 # Path to mailx MailxPath /usr/bin/mailx # Additional arguments that should be used for mailx # E.g. you may specify a from or a reply to address, consult man mailx MailxArguments ######## Notification configuration # Name of your Home Organization # This name is used in notification emails so that you know which # Home Organization's ARP was changed HomeOrganization #YOURHOMEORG# # Inform an admin in case that something changed # If no value is given, nobody will be informed # You need sendmail installed to make this work EmailNotification #YOUREMAILADDRESS# ######## ARP file configuration # Specify the ARP file that shall be analyzed and modified. # You can either modify a local file or download a remote file # ARP files may be downloaded from the Resource Registry with curl # over a secure SSL connection # Download ARP file for the SWITCHaai federation ARPIn https://aai-rr.switch.ch/gen_arp.php/switchaai/#YOURDOMAIN.CH#/arp.site.xml # Where should the file be saved, default path according to IdP install guide # Default location of ARP file according to IdP installation guide ARPOut /etc/shibboleth/arps/arp.site.xml # Pathname to the CA bundle file with the SwissSign Root CA to # assure proper SSL checking for the ARP download by curl # Default path if you install this file in /opt/updateARP CABundle /opt/updateARP/swisssign-ca.crt ######## ARP modification rules # Use the following syntax to modify the attribute release of a specific resource: # # ProviderID %Resource ProviderID% # %Attribute URN% %white space% %'permit' or 'deny' or ''% # # The ProviderID of the default rule is 'AnyTarget' # # 'permit' will release the attribute unless the user ARP file denies the release # 'deny' won't release the attribute, even not if the user ARP would allow it # '-' won't add a rule for the attribute which has the effect of not # releasing it unless the user ARP file allows it # # Example: Set some specific rules for the SWITCH eConferencing portal ProviderID https://panarea.switch.ch/shibboleth urn:mace:switch.ch:attribute-def:swissEduPersonUniqueID permit urn:mace:switch.ch:attribute-def:swissEduPersonDateOfBirth deny urn:mace:dir:attribute-def:postalAddress - # Use the following syntax to set all attributes of a resource to a specific value: # ProviderID %Resource ProviderID% # * %'permit' or 'deny' or '-'% # # This way you can set a default rule and then define exceptions # The position of the default rule is not important: # ProviderID https://vconf.switch.ch/aai/vconfres/reservation.php # * deny # urn:mace:switch.ch:attribute-def:swissEduPersonUniqueID permit # # Example: Set all attributes of SWITCH Attribute Viewer to 'permit' ProviderID https://aai-viewer.switch.ch/shibboleth * permit
You should at least adapt the red config settings to reflect your setup. Use the given example to define rules specific Attribute Release Policies for Service Providers. When done, run
$ /opt/updateARP/updateARP.pl /opt/updateARP/config.txt -vThis runs the script in the verbose mode so that you can see what it actually does and if it runs successfully.
Finally, you should install a cron job to run the updateARP script on a regular basis (at least daily) as it should be the case with the metadata refresh script.
As the examples in the config file show, the updateARP custom ARP rules can be used to deny the release of certain attributes to specific resources. The rules basically tell the updateARP script what should be changed. E.g. a rule like:
ProviderID https://panarea.switch.ch/shibboleth urn:mace:switch.ch:attribute-def:swissEduPersonUniqueID permit urn:mace:switch.ch:attribute-def:swissEduPersonDateOfBirth deny urn:mace:dir:attribute-def:postalAddress -takes the existing ARP policy for the resource https://panarea.switch.ch/shibboleth and adds rules to relaease attribute swissEduPersonUniqueID, to deny attribute swissEduPersonDateOfBirth and not to release attribute postalAddress. These rules are only applied if they differ with the rules in the ARP file that is processed. If there is a rule for this resource that allows the release of the attribute mail, this rule remains untouched.
With default rules all policies for a resource can be changed. E.g. if you want to deny release of all attribute to a specific resource, you could use something like:
ProviderID https://insecure.resource.ch/shibboleth * denyThis then sets all attributes for this resource to deny.
You can even add attributes that are not present in the ARP files that is processed. This can be useful if you have local attributes that are not specified in the SWITCHaai attribute specification.
ProviderID https://my.internal.resource.ch/shibboleth urn:mace:switch.ch:attribute-def:userPictureURL permitThis then creates a new rule to release the attribute urn:mace:switch.ch:attribute-def:userPictureURL.
-- $Id: update-arp.html,v 1.6 2008/06/03 07:19:53 haemmer Exp $