AttributeLimit: bugfix + proper documentation for the new functionality.

git-svn-id: http://simplesamlphp.googlecode.com/svn/trunk@3353 44740490-163a-0410-bde0-09ae8108e29a

modules/core/docs/authproc_attributelimit.txt

@@ -1,15 +1,18 @@
 `core:AttributeLimit`
 =====================
 
-Filter that limits the attributes that is sent to a user.
+A filter that limits the attributes (and their values) sent to a service provider.
 
-If the configuration is empty, the filter will use the attributes configured in the 'attributes' option in the SP metadata.
-
-The configuration is a list of which attributes should be allowed.
+If the configuration is empty, the filter will use the attributes configured in the `attributes` option in the SP
+metadata. The configuration is a list of attributes that should be allowed. In case you want to limit an attribute to
+release some specific values, make the name of the attribute the key of the array, and its value an array with all the
+different values allowed for it.
 
 Examples
 --------
 
+Here you will find a few examples on how to use this simple module:
+
 Limit to the `cn` and `mail` attribute:
 
     'authproc' => array(
@@ -19,35 +22,72 @@ Limit to the `cn` and `mail` attribute:
         ),
     ),
 
-Allow `eduPersonTargetedID` and `eduPersonAffiliation` by default, but allow metadata to override.
+Allow `eduPersonTargetedID` and `eduPersonAffiliation` by default, but allow the metadata to override the limitation.
 
     'authproc' => array(
         50 => array(
             'class' => 'core:AttributeLimit',
-	    'default' => TRUE,
+	        'default' => TRUE,
             'eduPersonTargetedID', 'eduPersonAffiliation',
         ),
     ),
 
-Don't allow any attributes by default, but allow metadata to override.
+Don't allow any attributes by default, but allow the metadata to override it.
 
     'authproc' => array(
         50 => array(
             'class' => 'core:AttributeLimit',
-	    'default' => TRUE,
+	        'default' => TRUE,
         ),
     ),
 
-An attribute list in metadata:
+In order to just use the list of attributes defined in the metadata for each service provider, configure the module
+like this:
 
     'authproc' => array(
         50 => 'core:AttributeLimit',
     ),
 
-And in saml20-sp-remote.php:
+Then, add the allowed attributes to each service provider metadata, in the `attributes` option:
 
     $metadata['https://saml2sp.example.org'] = array(
         'AssertionConsumerService' => 'https://saml2sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
         'SingleLogoutService' => 'https://saml2sp.example.org/simplesaml/module.php/saml/sp/saml2-logout.php/default-sp',
+        ...
         'attributes' => array('cn', 'mail'),
+        ...
     );
+
+Now, let's look to a couple of examples on how to filter out attribute values. First, allow only the entitlements known
+to be used by a service provider (among other attributes):
+
+    $metadata['https://saml2sp.example.org'] = array(
+        'AssertionConsumerService' => 'https://saml2sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp',
+        'SingleLogoutService' => 'https://saml2sp.example.org/simplesaml/module.php/saml/sp/saml2-logout.php/default-sp',
+        ...
+        'attributes' => array(
+            'uid',
+            'mail',
+            'eduPersonEntitlement' => array(
+                'urn:mace:example.org:admin',
+                'urn:mace:example.org:user',
+            ),
+        ),
+        ...
+    );
+
+Now, an example on how to normalize the affiliations sent from an identity provider, to make sure that no custom
+values ever reach the service providers. Bear in mind that this configuration can be overridden by metadata:
+
+    'authproc' => array(
+        50 => 'core:AttributeLimit',
+        'default' => TRUE,
+        'eduPersonAffiliation' => array(
+            'student',
+            'staff',
+            'member',
+            'faculty',
+            'employee',
+            'affiliate',
+        ),
+    ),

modules/core/lib/Auth/Process/AttributeLimit.php

@@ -110,7 +110,7 @@ class sspmod_core_Auth_Process_AttributeLimit extends SimpleSAML_Auth_Processing
                 // the attribute name is not in the array of allowed attributes
                 if (array_key_exists($name, $allowedAttributes)) {
                     // but it is an index of the array
-                    if (!is_array($values)) {
+                    if (!is_array($allowedAttributes[$name])) {
                         throw new SimpleSAML_Error_Exception('AttributeLimit: Values for ' . var_export($name, TRUE) .
                             ' must be specified in an array.');
                     }