diff options
Diffstat (limited to 'docs/simplesamlphp-sp-api.md')
| -rw-r--r-- | docs/simplesamlphp-sp-api.md | 270 |
1 files changed, 270 insertions, 0 deletions
diff --git a/docs/simplesamlphp-sp-api.md b/docs/simplesamlphp-sp-api.md new file mode 100644 index 0000000..fae5b14 --- /dev/null +++ b/docs/simplesamlphp-sp-api.md @@ -0,0 +1,270 @@ +SimpleSAMLphp SP API reference +============================== + +<!-- {{TOC}} --> + +This document describes the SimpleSAML_Auth_Simple API. +This is the preferred API for integrating SimpleSAMLphp with other applications. + +Constructor +----------- + + new SimpleSAML_Auth_Simple(string $authSource) + +The constructor initializes a SimpleSAML_Auth_Simple object. + +### Parameters + +It has a single parameter, which is the ID of the authentication source that should be used. +This authentication source must exist in `config/authsources.php`. + +### Example + + $auth = new SimpleSAML_Auth_Simple('default-sp'); + + +`isAuthenticated` +----------------- + + bool isAuthenticated() + +Check whether the user is authenticated with this authentication source. +`TRUE` is returned if the user is authenticated, `FALSE` if not. + +### Example + + if (!$auth->isAuthenticated()) { + /* Show login link. */ + print('<a href="/login">Login</a>'); + } + + +`requireAuth` +------------- + + void requireAuth(array $params = array()) + +Make sure that the user is authenticated. +This function will only return if the user is authenticated. +If the user isn't authenticated, this function will start the authentication process. + +### Parameters + +`$params` is an associative array with named parameters for this function. +See the documentation for the `login`-function for a description of the parameters. + + +### Example 1 + + $auth->requireAuth(); + print("Hello, authenticated user!"); + +### Example 2 + + /* + * Return the user to the frontpage after authentication, don't post + * the current POST data. + */ + $auth->requireAuth(array( + 'ReturnTo' => 'https://sp.example.org/', + 'KeepPost' => FALSE, + )); + print("Hello, authenticated user!"); + + +`login` +------------- + + void login(array $params = array()) + +Start a login operation. +This function will always start a new authentication process. + +### Parameters + +The following global parameters are supported: + +`ErrorURL` (`string`) + +: A URL to a page which will receive errors that may occur during authentication. + +`KeepPost` (`bool`) + +: If set to `TRUE`, the current POST data will be submitted again after authentication. + The default is `TRUE`. + +`ReturnTo` (`string`) + +: The URL the user should be returned to after authentication. + The default is to return the user to the current page. + +`ReturnCallback` (`array`) + +: The function we should call when the user finishes authentication. + +The [`saml:SP`](./saml:sp) authentication source also defines some parameters. + + +### Example + + # Send a passive authentication request. + $auth->login(array( + 'isPassive' => TRUE, + 'ErrorURL' => 'https://.../error_handler.php', + )); + + +`logout` +-------- + + void logout(mixed $params = NULL) + +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 + +`$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. + + 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'); + +### 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` +--------------- + + array getAttributes() + +Retrieve the attributes of the current user. +If the user isn't authenticated, an empty array will be returned. + +The attributes will be returned as an associative array with the name of the attribute as the key and the value as an array of one or more strings: + + array( + 'uid' => array('testuser'), + 'eduPersonAffiliation' => array('student', 'member'), + ) + + +### Example + + $attrs = $auth->getAttributes(); + if (!isset($attrs['displayName'][0])) { + throw new Exception('displayName attribute missing.'); + } + $name = $attrs['displayName'][0]; + + print('Hello, ' . htmlspecialchars($name)); + + +`getAuthData` +--------------- + + mixed getAuthData(string $name) + +Retrieve the specified authentication data for the current session. +NULL is returned if the user isn't authenticated. + +The available authentication data depends on the module used for authentication. +See the [`saml:SP`](./saml:sp) reference for information about available SAML authentication data. + +### Example + + $idp = $auth->getAuthData('saml:sp:IdP'); + print('You are logged in from: ' . htmlspecialchars($idp)); + + +`getLoginURL` +------------- + + string getLoginURL(string $returnTo = NULL) + +Retrieve a URL that can be used to start authentication. + +### Parameters + +`$returnTo` + +: The URL the user should be returned to after authentication. + The default is the current page. + +### Example + + $url = $auth->getLoginURL(); + + print('<a href="' . htmlspecialchars($url) . '">Login</a>'); + +### Note + +The URL returned by this function is static, and will not change. +You can easily create your own links without using this function. +The URL should be: + + .../simplesaml/module.php/core/as_login.php?AuthId=<authentication source>&ReturnTo=<return URL> + + +`getLogoutURL` +-------------- + + string getLogoutURL(string $returnTo = NULL) + +Retrieve a URL that can be used to trigger logout. + +### Parameters + +`$returnTo` + +: The URL the user should be returned to after logout. + The default is the current page. + +### Example + + $url = $auth->getLogoutURL(); + + print('<a href="' . htmlspecialchars($url) . '">Logout</a>'); + +### Note + +The URL returned by this function is static, and will not change. +You can easily create your own links without using this function. +The URL should be: + + .../simplesaml/module.php/core/as_logout.php?AuthId=<authentication source>&ReturnTo=<return URL> |