Adding a new auth proc filter: LanguageAdaptor reads and writes preferred language to attribute set

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

docs/source/simplesamlphp-authproc.txt

@@ -331,7 +331,51 @@ Example - generate from only the `eduPersonAffilitation` attribute:
 	),
 
 
+### Adopting preferred language from and to attributes (`core:LanguageAdaptor`)
 
+SimpleSAMLphp has built in lanugage support, and stores the preferred language in a cookie.
+
+Identity systems also often has a specific attribute that indicates what language is understood by the user. MACE defines an attribute with preferred language: `preferredLanguage`. [Read more about the preferredLanguage attribute defined by MACE](http://rnd.feide.no/node/1054).
+
+The LanguageAdaptor brings these two concepts together. If executed early at the IdP it will check if the `preferredLanguage` attribute is among the users attributes, and if it is, simpleSAMLphp will use that language in the user interface. **Notice that** the login page itself is to early to be influenced by the user attributes, because the IdP does not know any user attributes before the user logs in. In contrast, the consent module will be presented in the correct language based on user attribute.
+
+The LanguageAdaptor also works the other way around. If the user does not have the `preferredLanguage` attribute, the user interface for the user will be set to the default for the installation. If this language is not correct for the user, the user may click to switch language on the login page (or any other UI page in simpleSAMLphp). SimpleSAMLphp then stores the preferred language in a cookie. Now, the LanguageAdaptor will read the preferred language from the cookie and add a user attribute with the preferred language, that is sent to the service provider.
+
+
+Example 1:
+
+	'authproc' => array(
+ 		30 => 'core:LanguageAdaptor',
+	),
+
+Example 2: By default the filter will use the attribute name `preferredLanguage`. You can specify the name of the language attribute with an optional parameter:
+
+	'authproc' => array(
+ 		30 => array(
+ 			'class' => 'core:LanguageAdaptor',
+ 			'attributename' => 'lang',
+ 		),
+	),
+
+You can use the LanguageAdaptor both at the SP and the IdP. It may even make sense to run the LanguageAdaptor twice at the IdP if there is any other processing filters executed that includes a UI.
+
+Example 3: 
+
+	'authproc.idp' => array(
+ 		20 => 'core:TargetedID',
+ 		30 => 'core:LanguageAdaptor',
+		40 => 'core:AttributeRealm',
+		50 => 'core:AttributeLimit', 		
+		90 => array(
+			'class' 	=> 'consent:Consent', 
+			'store' 	=> 'consent:Cookie', 
+			'focus' 	=> 'yes', 
+			'checked' 	=> TRUE
+		),
+ 		99 => 'core:LanguageAdaptor',
+	),
+
+Here you can see that the LanguageAdaptor runs with priority 30. At this point the filter will check attributes and set the simpleSAMLphp language cookie if the preferredLanguage attribute was provided. Later, with priority 99, the filter is ran again. This time the LanguageAdaptor will discover if the user have selected preferred language in the consent module, and if the user has selected language, and if the user does not already have a preferredLanguage attribute, the LanguageAdaptor will set the `preferredLanguage` attribute reflecting the user's language choice in the consent UI.
 
 
 

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

+<?php
+
+/**
+ * Filter to set and get language settings from attributes.
+ * 
+ * @author Andreas Åkre Solberg, UNINETT AS.
+ * @package simpleSAMLphp
+ * @version $Id$
+ */
+class sspmod_core_Auth_Process_LanguageAdaptor extends SimpleSAML_Auth_ProcessingFilter {
+
+	private $langattr = 'preferredLanguage';
+
+
+	/**
+	 * Initialize this filter.
+	 *
+	 * @param array $config  Configuration information about this filter.
+	 * @param mixed $reserved  For future use.
+	 */
+	public function __construct($config, $reserved) {
+		parent::__construct($config, $reserved);
+		assert('is_array($config)');
+
+		if (array_key_exists('attributename', $config)) {
+			$this->langattr = $config['attributename'];
+		}
+	}
+
+
+	/**
+	 * Apply filter to add or replace attributes.
+	 *
+	 * Add or replace existing attributes with the configured values.
+	 *
+	 * @param array &$request  The current request
+	 */
+	public function process(&$request) {
+		assert('is_array($request)');
+		assert('array_key_exists("Attributes", $request)');
+
+		$attributes =& $request['Attributes'];
+		
+		$attrlang = NULL;
+		if (array_key_exists($this->langattr, $attributes)) 
+			$attrlang = $attributes[$this->langattr][0];
+		
+		$config = SimpleSAML_Configuration::getInstance();
+		$t = new SimpleSAML_XHTML_Template($config, 'frontpage');
+		$lang = $t->getLanguage(FALSE, FALSE);
+
+
+		if (isset($attrlang)) 
+			SimpleSAML_Logger::debug('LanguageAdaptor: Language in attribute was set [' . $attrlang . ']');
+		if (isset($lang))
+			SimpleSAML_Logger::debug('LanguageAdaptor: Language in session   was set [' . $lang . ']');
+
+		
+		if (isset($attrlang)) {
+
+			if (!isset($lang)) {
+				$t->setLanguage($attrlang);
+				$_GET['language'] = $attrlang;
+			} else {
+				// Language was set in both attributes and session.
+				
+				if ($lang !== $attrlang) {
+					// Different language set in attributes and session.
+
+				}
+			}
+			
+		} else {
+			
+			if (isset($lang)) {
+				$request['Attributes'][$this->langattr] = array($lang);
+			} else {
+				// Language was neighter set in attributes or in session
+			}
+			
+		}
+
+	}
+
+}
+
+?>
\ No newline at end of file