Auth_Simple: Logout improvements

- Support for callbacks after logout instead of redirects.
- Support for passing the state array to the logout page.

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

docs/simplesamlphp-sp-api.txt

@@ -117,22 +117,55 @@ The [`saml:SP`](./saml:sp) authentication source also defines some parameters.
 `logout`
 --------
 
-    void logout(string $url = NULL)
+    void logout(mixed $params = NULL)
 
-Log the user out, and return to the given URL.
-If the user isn't authenticated, the user will be redirected to the URL.
-If the user is authenticated with an IdP, the user will be sent to the IdP for logout.
+Log the user out.
+After logging out, the user will either be redirected to another page, or a function will be called.
 This function never returns.
 
 ### Parameters
 
-`$url`
-:   The URL the user should be sent to after logout.
-    The default is the URL of the current page.
+`$params`
+:   Parameters for the logout operation.
+    This can either be a simple string, in which case it is interpreted as the URL the user should be redirected to after logout, or an associative array with logout parameters.
+    If this parameter isn't specified, we will redirect the user to the current URL after logout.
 
-### Example
+    If the parameter is an an array, it can have the following options:
+
+    - `ReturnTo`: The URL the user should be returned to after logout.
+    - `ReturnCallback`: The function that should be called after logout.
+    - `ReturnStateParam`: The parameter we should return the state in when redirecting.
+    - `ReturnStateStage`: The stage the state array should be saved with.
+
+    The `ReturnState` parameters allow access to the result of the logout operation after it completes.
+
+### Example 1
+
+Logout, and redirect to the specified URL.
+
+    $auth->logout('https://sp.example.org/logged_out.php');
 
-    $auth->logout('https://sp.example.org/');
+### Example 2
+
+Same as the previous, but check the result of the logout operation afterwards.
+
+    $auth->logout(array(
+        'ReturnTo' => 'https://sp.example.org/logged_out.php',
+        'ReturnStateParam' => 'LogoutState',
+        'ReturnStateStage' => 'MyLogoutState',
+    ));
+
+And in logged_out.php:
+
+    $state = SimpleSAML_Auth_State::loadState((string)$_REQUEST['LogoutState'], 'MyLogoutState');
+    $ls = $state['saml:sp:LogoutStatus']; /* Only works for SAML SP */
+    if ($ls['Code'] === 'urn:oasis:names:tc:SAML:2.0:status:Success' && !isset($ls['SubCode'])) {
+        /* Successful logout. */
+        echo("You have been logged out.");
+    } else {
+        /* Logout failed. Tell the user to close the browser. */
+        echo("We were unable to log you out of all your sessions. To be completely sure that you are logged out, you need to close your web browser.");
+    }
 
 
 `getAttributes`

lib/SimpleSAML/Auth/Simple.php

@@ -134,26 +134,83 @@ class SimpleSAML_Auth_Simple {
 	 *
 	 * This function logs the user out. It will never return. By default,
 	 * it will cause a redirect to the current page after logging the user
-	 * out, but a different URL can be given with the $url parameter.
+	 * out, but a different URL can be given with the $params parameter.
 	 *
-	 * @param string|NULL $url  The url the user should be redirected to after logging out.
-	 *                          Defaults to the current page.
+	 * Generic parameters are:
+	 *  - 'ReturnTo': The URL the user should be returned to after logout.
+	 *  - 'ReturnCallback': The function that should be called after logout.
+	 *  - 'ReturnStateParam': The parameter we should return the state in when redirecting.
+	 *  - 'ReturnStateStage': The stage the state array should be saved with.
+	 *
+	 * @param string|array|NULL $params  Either the url the user should be redirected to after logging out,
+	 *                                   or an array with parameters for the logout. If this parameter is
+	 *                                   NULL, we will return to the current page.
 	 */
-	public function logout($url = NULL) {
-		assert('is_string($url) || is_null($url)');
+	public function logout($params = NULL) {
+		assert('is_array($params) || is_string($params) || is_null($params)');
+
+		if ($params === NULL) {
+			$params = SimpleSAML_Utilities::selfURL();
+		}
+
+		if (is_string($params)) {
+			$params = array(
+				'ReturnTo' => $params,
+			);
+		}
+
+		assert('is_array($params)');
+		assert('isset($params["ReturnTo"]) || isset($params["ReturnCallback"])');
 
-		if ($url === NULL) {
-			$url = SimpleSAML_Utilities::selfURL();
+		if (isset($params['ReturnStateParam']) || isset($params['ReturnStateStage'])) {
+			assert('isset($params["ReturnStateParam"]) && isset($params["ReturnStateStage"])');
 		}
 
 		$session = SimpleSAML_Session::getInstance();
-		if (!$session->isValid($this->authSource)) {
-			/* Not authenticated to this authentication source. */
-			SimpleSAML_Utilities::redirect($url);
-			assert('FALSE');
+		if ($session->isValid($this->authSource)) {
+			$state = $session->getAuthData($this->authSource, 'LogoutState');
+			if ($state !== NULL) {
+				$params = array_merge($state, $params);
+			}
+
+			$session->doLogout($this->authSource);
+
+			$params['LogoutCompletedHandler'] = array(get_class(), 'logoutCompleted');
+
+			$as = SimpleSAML_Auth_Source::getById($this->authSource);
+			if ($as !== NULL) {
+				$as->logout($params);
+			}
 		}
 
-		SimpleSAML_Auth_Default::initLogout($url, $this->authSource);
+		self::logoutCompleted($params);
+	}
+
+
+	/**
+	 * Called when logout operation completes.
+	 *
+	 * This function never returns.
+	 *
+	 * @param array $state  The state after the logout.
+	 */
+	public static function logoutCompleted($state) {
+		assert('is_array($state)');
+		assert('isset($state["ReturnTo"]) || isset($state["ReturnCallback"])');
+
+		if (isset($state['ReturnCallback'])) {
+			call_user_func($state['ReturnCallback'], $state);
+			assert('FALSE');
+		} else {
+			$params = array();
+			if (isset($state['ReturnStateParam']) || isset($state['ReturnStateStage'])) {
+				assert('isset($state["ReturnStateParam"]) && isset($state["ReturnStateStage"])');
+				$stateID = SimpleSAML_Auth_State::saveState($state, $state['ReturnStateStage']);
+				$params[$state['ReturnStateParam']] = $stateID;
+			}
+
+			SimpleSAML_Utilities::redirect($state['ReturnTo'], $params);
+		}
 	}