saml: Add NameID generation filters.

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

docs/simplesamlphp-authproc.txt

@@ -142,6 +142,9 @@ The following filters are included in the simpleSAMLphp distribution:
 - [`core:TargetedID`](./core:authproc_targetedid): Generate the `eduPersonTargetedID` attribute.
 - [`core:WarnShortSSOInterval`](./core:authproc_warnshortssointerval): Give a warning if the user logs into the same SP twice within a few seconds.
 - [`preprodwarning:Warning`](./preprodwarning:warning): Warn the user about accessing a test IdP.
+- [`saml:AttributeNameID`](./saml:nameid): Generate custon NameID with the value of an attribute.
+- [`saml:PersistentNameID`](./saml:nameid): Generate persistent NameID from an attribute.
+- [`saml:TransientNameID`](./saml:nameid): Generate transient NameID.
 
 
 

modules/saml/docs/nameid.txt

+NameID generation filters
+=========================
+
+This document describes the NameID generation filters in the saml module.
+
+
+Common options
+--------------
+
+`NameQualifier`
+:   The NameQualifier attribute for the generated NameID.
+    This can be a string that is used as the value directly.
+    It can also be `TRUE`, in which case we use the IdP entity ID as the NameQualifier.
+    If it is `FALSE`, no NameQualifier will be included.
+
+:   The default is `FALSE`, which means that we will not include a NameQualifier by default.
+
+`SPNameQualifier`
+:   The SPNameQualifier attribute for the generated NameID.
+    This can be a string that is used as the value directly.
+    It can also be `TRUE`, in which case we use the SP entity ID as the SPNameQualifier.
+    If it is `FALSE`, no SPNameQualifier will be included.
+
+:   The default is `TRUE`, which means that we will use the SP entity ID.
+
+
+`saml:AttributeNameID`
+----------------------
+
+Uses the value of an attribute to generate a NameID.
+
+### Options
+
+`attribute`
+:   The name of the attribute we should use as the unique user ID.
+
+`Format`
+:   The `Format` attribute of the generated NameID.
+
+
+
+`saml:PersistentNameID`
+-----------------------
+
+Generates a persistent NameID with the format `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`.
+The filter will take the user ID from the attribute described in the `attribute` option, and hash it with the `secretsalt` from `config.php`, and the SP and IdP entity ID.
+The resulting hash is sent as the persistent NameID.
+
+### Options
+
+`attribute`
+:   The name of the attribute we should use as the unique user ID.
+
+
+`saml:TransientNameID`
+----------------------
+
+Generates a transient NameID with the format `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`.
+
+No extra options are available for this filter.
+
+
+Example
+-------
+
+This example makes three NameIDs available:
+
+    'authproc' => array(
+        1 => array(
+            'class' => 'saml:TransientNameID',
+        ),
+        2 => array(
+            'class' => 'saml:PersistentNameID',
+            'attribute' => 'eduPersonPrincipalName',
+        ),
+        3 => array(
+            'class' => 'saml:AttributeNameID',
+            'attribute' => 'eduPersonPrincipalName',
+            'Format' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
+        ),
+    ),

modules/saml/lib/Auth/Process/AttributeNameID.php

+<?php
+
+/**
+ * Authproc filter to create a NameID from an attribute.
+ *
+ * @package simpleSAMLphp
+ * @version $Id$
+ */
+class sspmod_saml_Auth_Process_AttributeNameID extends sspmod_saml_BaseNameIDGenerator {
+
+	/**
+	 * The attribute we should use as the NameID.
+	 *
+	 * @var string
+	 */
+	private $attribute;
+
+
+	/**
+	 * Initialize this filter, parse configuration.
+	 *
+	 * @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 (!isset($config['Format'])) {
+			throw new SimpleSAML_Error_Exception('AttributeNameID: Missing required option \'Format\'.');
+		}
+		$this->format = (string)$config['Format'];
+
+		if (!isset($config['attribute'])) {
+			throw new SimpleSAML_Error_Exception('AttributeNameID: Missing required option \'attribute\'.');
+		}
+		$this->attribute = (string)$config['attribute'];
+	}
+
+
+	/**
+	 * Get the NameID value.
+	 *
+	 * @return string|NULL  The NameID value.
+	 */
+	protected function getValue(array &$state) {
+
+		if (!isset($state['Attributes'][$this->attribute]) || count($state['Attributes'][$this->attribute]) === 0) {
+			SimpleSAML_Logger::warning('Missing attribute ' . var_export($this->attribute, TRUE) . ' on user - not generating attribute NameID.');
+			return NULL;
+		}
+		if (count($state['Attributes'][$this->attribute]) > 1) {
+			SimpleSAML_Logger::warning('More than one value in attribute ' . var_export($this->attribute, TRUE) . ' on user - not generating attribute NameID.');
+		}
+		$value = array_values($state['Attributes'][$this->attribute]); /* Just in case the first index is no longer 0. */
+		$value = $value[0];
+		return $value;
+	}
+
+}

modules/saml/lib/Auth/Process/PersistentNameID.php

+<?php
+
+/**
+ * Authproc filter to generate a persistent NameID.
+ *
+ * @package simpleSAMLphp
+ * @version $Id$
+ */
+class sspmod_saml_Auth_Process_PersistentNameID extends sspmod_saml_BaseNameIDGenerator {
+
+	/**
+	 * Which attribute contains the unique identifier of the user.
+	 *
+	 * @var string
+	 */
+	private $attribute;
+
+
+	/**
+	 * Initialize this filter, parse configuration.
+	 *
+	 * @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)');
+
+		$this->format = SAML2_Const::NAMEID_PERSISTENT;
+
+		if (!isset($config['attribute'])) {
+			throw new SimpleSAML_Error_Exception('PersistentNameID: Missing required option \'attribute\'.');
+		}
+		$this->attribute = $config['attribute'];
+	}
+
+
+	/**
+	 * Get the NameID value.
+	 *
+	 * @return string|NULL  The NameID value.
+	 */
+	protected function getValue(array &$state) {
+
+		if (!isset($state['SPMetadata']['entityid'])) {
+			SimpleSAML_Logger::warning('No SP entity ID - not generating persistent NameID.');
+			return NULL;
+		}
+		$spEntityId = $state['SPMetadata']['entityid'];
+
+		if (!isset($state['IdPMetadata']['entityid'])) {
+			SimpleSAML_Logger::warning('No IdP entity ID - not generating persistent NameID.');
+			return NULL;
+		}
+		$idpEntityId = $state['IdPMetadata']['entityid'];
+
+		if (!isset($state['Attributes'][$this->attribute]) || count($state['Attributes'][$this->attribute]) === 0) {
+			SimpleSAML_Logger::warning('Missing attribute ' . var_export($this->attribute, TRUE) . ' on user - not generating persistent NameID.');
+			return NULL;
+		}
+		if (count($state['Attributes'][$this->attribute]) > 1) {
+			SimpleSAML_Logger::warning('More than one value in attribute ' . var_export($this->attribute, TRUE) . ' on user - not generating persistent NameID.');
+		}
+		$uid = array_values($state['Attributes'][$this->attribute]); /* Just in case the first index is no longer 0. */
+		$uid = $uid[0];
+
+		$secretSalt = SimpleSAML_Utilities::getSecretSalt();
+
+		$uidData = 'saml:PersistentNameID:' . $secretSalt;
+		$uidData .= strlen($idpEntityId) . ':' . $idpEntityId;
+		$uidData .= strlen($spEntityId) . ':' . $spEntityId;
+		$uidData .= strlen($uid) . ':' . $uid;
+		$uidData .= $secretSalt;
+
+		return sha1($uidData);
+	}
+
+}

modules/saml/lib/Auth/Process/TransientNameID.php

+<?php
+
+/**
+ * Authproc filter to generate a transient NameID.
+ *
+ * @package simpleSAMLphp
+ * @version $Id$
+ */
+class sspmod_saml_Auth_Process_TransientNameID extends sspmod_saml_BaseNameIDGenerator {
+
+	/**
+	 * Initialize this filter, parse configuration
+	 *
+	 * @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)');
+
+		$this->format = SAML2_Const::NAMEID_TRANSIENT;
+	}
+
+
+	/**
+	 * Get the NameID value.
+	 *
+	 * @return string|NULL  The NameID value.
+	 */
+	protected function getValue(array &$state) {
+
+		return SimpleSAML_Utilities::generateID();
+	}
+
+}

modules/saml/lib/BaseNameIDGenerator.php

+<?php
+
+/**
+ * Base filter for generating NameID values.
+ *
+ * @package simpleSAMLphp
+ * @version $Id$
+ */
+abstract class sspmod_saml_BaseNameIDGenerator extends SimpleSAML_Auth_ProcessingFilter {
+
+	/**
+	 * What NameQualifier should be used.
+	 * Can be one of:
+	 *  - a string: The qualifier to use.
+	 *  - FALSE: Do not include a NameQualifier. This is the default.
+	 *  - TRUE: Use the IdP entity ID.
+	 *
+	 * @var string|bool
+	 */
+	private $nameQualifier;
+
+
+	/**
+	 * What SPNameQualifier should be used.
+	 * Can be one of:
+	 *  - a string: The qualifier to use.
+	 *  - FALSE: Do not include a SPNameQualifier.
+	 *  - TRUE: Use the SP entity ID. This is the default.
+	 *
+	 * @var string|bool
+	 */
+	private $spNameQualifier;
+
+
+	/**
+	 * The format of this NameID.
+	 *
+	 * This property must be initialized the subclass.
+	 *
+	 * @var string
+	 */
+	protected $format;
+
+
+	/**
+	 * Initialize this filter, parse configuration.
+	 *
+	 * @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 (isset($config['NameQualifier'])) {
+			$this->nameQualifier = $config['NameQualifier'];
+		} else {
+			$this->nameQualifier = FALSE;
+		}
+
+		if (isset($config['SPNameQualifier'])) {
+			$this->spNameQualifier = $config['SPNameQualifier'];
+		} else {
+			$this->spNameQualifier = TRUE;
+		}
+	}
+
+
+	/**
+	 * Get the NameID value.
+	 *
+	 * @return string|NULL  The NameID value.
+	 */
+	abstract protected function getValue(array &$state);
+
+
+	/**
+	 * Generate transient NameID.
+	 *
+	 * @param array &$state  The request state.
+	 */
+	public function process(&$state) {
+		assert('is_array($state)');
+		assert('is_string($this->format)');
+
+		$value = $this->getValue($state);
+		if ($value === NULL) {
+			return;
+		}
+
+		$nameId = array('Value' => $value);
+
+		if ($this->nameQualifier === TRUE) {
+			if (isset($state['IdPMetadata']['entityid'])) {
+				$nameId['NameQualifier'] = $state['IdPMetadata']['entityid'];
+			} else {
+				SimpleSAML_Logger::warning('No IdP entity ID, unable to set NameQualifier.');
+			}
+		} elseif (is_string($this->nameQualifier)) {
+			$nameId['NameQualifier'] = $this->nameQualifier;
+		}
+
+		if ($this->spNameQualifier === TRUE) {
+			if (isset($state['SPMetadata']['entityid'])) {
+				$nameId['SPNameQualifier'] = $state['SPMetadata']['entityid'];
+			} else {
+				SimpleSAML_Logger::warning('No SP entity ID, unable to set SPNameQualifier.');
+			}
+		} elseif (is_string($this->spNameQualifier)) {
+			$nameId['SPNameQualifier'] = $this->spNameQualifier;
+		}
+
+		$state['saml:NameID'][$this->format] = $nameId;
+	}
+
+}