t('{core:frontpage:about_text}'); ?>
In this example, two translated terms are included: `about_header` and `about_text`. Both these terms are found in a dictionary file named `frontpage`, inside the module named `core`. **Note:** An important use-case here is that you can create your own module, that includes a new theme that overrides some of the default templates. You may in this template refer to both terms from the existing dictionary files, but you can also add new dictionary files in your new module that may introduce new alternative terms. ## The definition file When the template library is about to lookup the translation of a term, it will lookup * the definition file, for the English translation, and * the translation file, for translation to other languages. SimpleSAMLphp will always fallback to the English translation using the definition file, both: * when the term is not translated into the *current selected language*, and * when the translation file is not available at all. The name of the definition file is `BASENAME.definition.json`, where the term is referred to like this: `{MODULENAME:BASENAME:TERM}`. The file MUST be placed in the followng location: `modules/MODULENAME/dictionaries/BASENAME.definition.json`. The content of the defintion file is a *JSON encoded array* of `term => definition`, where definition is an array with an required `en` index for the english translation, and the value is the English text. Here is an example of a definition file with three terms: { "header": { "en": "Missing cookie" }, "description": { "en": "You appear to have disabled cookies in your browser. Please check the settings in your browser, and try again." }, "retry": { "en": "Retry" } } Note: you may not include other languages in the definition files, the `en` index is used in order to at a later point in time introduce more meta information for each term, like in example: "header": { "en": "Missing cookie", "_note": "This text shows up on the error page when the browser do not support cookies." }, To summarize the pattern of the definition file is as follows: { "TERM1": { "en": "English text 1" }, "TERM2": { "en": "English text 2" } } ## The translation file The translation file is similar to the definition file, but including translation to languages others than English. The structure of the file is identical to the definition files, except from the language index, which now is not `en`, but the actual langauge that is translated: { "TERM1": { "no": "Norsk tekst 1", "da": "Dansk tekst 1" }, "TERM2": { "no": "Norsk tekst 2", "da": "Dansk tekst 2" } } simplesamlphp-1.15.3/docs/simplesamlphp-hok-idp.md 0000644 0000000 0000000 00000007122 13245225037 020643 0 ustar root root Adding Holder-of-Key Web Browser SSO Profile support to the IdP =============================================================== This document describes the necessary steps to enable support for the [SAML V2.0 Holder-of-Key (HoK) Web Browser SSO Profile](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-holder-of-key-browser-sso.pdf) on a SimpleSAMLphp Identity Provider (IdP). The SAML V2.0 HoK Web Browser SSO Profile is an alternate version of the standard SAML Web Browser SSO Profile. Its primary benefit is the enhanced security of the SSO process while preserving maximum compatibility with existing deployments on client and server side. When using this profile the communication between the user and the IdP is required to be protected by the TLS protocol. Additionally, the user needs a TLS client certificate. This certificate is usually selfsigned and stored in the certificate store of the browser or the underlying operating system. Configuring Apache ------------------ The IdP requests a client certificate from the user agent during the TLS handshake. This behaviour is enabled with the following Apache webserver configuration: SSLEngine on SSLCertificateFile /etc/openssl/certs/server.crt SSLCertificateKeyFile /etc/openssl/private/server.key SSLVerifyClient optional_no_ca SSLOptions +ExportCertData If the user agent can successfully prove possession of the private key associated to the public key from the certificate, the received certificate is stored in the environment variable `SSL_CLIENT_CERT` of the webserver. The IdP embeds the client certificate into the created HoK assertion. Enabling HoK SSO Profile on the IdP ----------------------------------- To enable the IdP to send HoK assertions you must add the `saml20.hok.assertion` option to the `saml20-idp-hosted` metadata file: $metadata['__DYNAMIC:1__'] = array( [....] 'auth' => 'example-userpass', 'saml20.hok.assertion' => TRUE, ); Add new metadata to SPs ----------------------- After enabling the Holder-of-Key Web Browser SSO Profile your IdP metadata will change. An additional HoK `SingleSignOnService` endpoint is added. You therefore need to update the metadata for your IdP at your SPs. The `saml20-idp-remote` metadata for SimpleSAMLphp SPs should contain something like the following code: 'SingleSignOnService' => array ( array ( 'hoksso:ProtocolBinding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 'Binding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser', 'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php', ), array ( 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 'Location' => 'https://idp.example.org/simplesaml/saml2/idp/SSOService.php', ), ), SP metadata on the IdP ---------------------- A SP using the HoK Web Browser SSO Profile must have an `AssertionConsumerService` endpoint supporting that profile. This means that you have to use the complex endpoint format in `saml20-sp-remote` metadata. In general, this should look like the following code: 'AssertionConsumerService' => array ( array( 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', 'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp', 'index' => 0, ), array( 'Binding' => 'urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser', 'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp', 'index' => 4, ), ), (The specific values of the various fields will vary depending on the SP.) simplesamlphp-1.15.3/docs/simplesamlphp-artifact-idp.md 0000644 0000000 0000000 00000007321 13245225037 021660 0 ustar root root Adding HTTP-Artifact support to the IdP ======================================= This document describes the necessary steps to enable support for the HTTP-Artifact binding on a SimpleSAMLphp IdP: 1. Configure SimpleSAMLphp to use memcache to store the session. 2. Enable support for sending artifacts in `saml20-idp-hosted`. 3. Add the webserver certificate to the generated metadata. Memcache -------- To enable memcache, you must first install and configure memcache on the server hosting your IdP. You need both a memcache server and a the PHP memcached client (extension). How this is done depends on the distribution. If you are running Debian or Ubuntu, you can install this by running: apt install memcached php-memcached simpleSAMLphp also supports the legacy `php-memcache` (without `d`) variant. *Note*: For security, you must make sure that the memcache server is inaccessible to other hosts. The default configuration on Debian is for the memcache server to be accessible to only the local host. Once the memcache server is configured, you can configure simplesamlphp to use it to store sessions. You can do this by setting the `session.handler` option in `config.php` to `memcache`. If you are running memcache on a different server than the IdP, you must also change the `memcache_store.servers` option in `config.php`. Enabling artifact on the IdP ---------------------------- To enable the IdP to send artifacts, you must add the `saml20.sendartifact` option to the `saml20-idp-hosted` metadata file: $metadata['__DYNAMIC:1__'] = array( [....] 'auth' => 'example-userpass', 'saml20.sendartifact' => TRUE, ); Add new metadata to SPs ----------------------- After enabling the Artifact binding, your IdP metadata will change to add a ArtifactResolutionService endpoint. You therefore need to update the metadata for your IdP at your SPs. `saml20-idp-remote` metadata for SimpleSAMLphp SPs should contain something like: 'ArtifactResolutionService' => array( array( 'index' => 0, 'Location' => 'https://idp.example.org/simplesaml/saml2/idp/ArtifactResolutionService.php', 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:SOAP', ), ), SP metadata on the IdP ---------------------- An SP using the HTTP-Artifact binding must have an AssertionConsumerService endpoint supporting that binding. This means that you must use the complex endpoint format in `saml20-sp-remote` metadata. In general, that should look something like: 'AssertionConsumerService' => array ( array( 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', 'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp', 'index' => 0, ), array( 'Binding' => 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact', 'Location' => 'https://sp.example.org/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp', 'index' => 2, ), ), (The specific values of the various fields will vary depending on the SP.) Certificate in metadata ----------------------- Some SPs validates the SSL certificate on the ArtifactResolutionService using the certificates in the metadata. You may therefore have to add the webserver certificate to the metadata that your IdP generates. To do this, you need to set the `https.certificate` option in the `saml20-idp-hosted` metadata file. That option should refer to a file containing the webserver certificate. $metadata['__DYNAMIC:1__'] = array( [....] 'auth' => 'example-userpass', 'saml20.sendartifact' => TRUE, 'https.certificate' => '/etc/apache2/webserver.crt', ); simplesamlphp-1.15.3/docs/simplesamlphp-customauth.md 0000644 0000000 0000000 00000033117 13245225037 021507 0 ustar root root Implementing custom username/password authentication ==================================================== This is a step-by-step guide for creating a custom username/password [authentication source](./simplesamlphp-authsource) for SimpleSAMLphp. An authentication source is responsible for authenticating the user, typically by getting a username and password, and looking it up in some sort of database. Create a custom module ---------------------- All custom code for SimpleSAMLphp should be contained in a [module](./simplesamlphp-modules). This ensures that you can upgrade your SimpleSAMLphp installation without overwriting your own code. In this example, we will call the module `mymodule`. It will be located under `modules/mymodule`. First we need to create the module directory: cd modules mkdir mymodule Since this is a custom module, it should always be enabled. Therefore we create a `default-enable` file in the module. We do that by copying the `default-enable` file from the `core` module. cd mymodule cp ../core/default-enable . Now that we have our own module, we can move on to creating an authentication source. Creating a basic authentication source -------------------------------------- Authentication sources are implemented using PHP classes. We are going to create an authentication source named `mymodule:MyAuth`. It will be implemented in the file `modules/mymodule/lib/Auth/Source/MyAuth.php`. To begin with, we will create a very simple authentication source, where the username and password is hardcoded into the source code. Create the file `modules/mymodule/lib/Auth/Source/MyAuth.php` with the following contents: array('theusername'), 'displayName' => array('Some Random User'), 'eduPersonAffiliation' => array('member', 'employee'), ); } } Some things to note: - The classname is `sspmod_mymodule_Auth_Source_MyAuth`. This tells SimpleSAMLphp to look for the class in `modules/mymodule/lib/Auth/Source/MyAuth.php`. - Our authentication source subclassese `sspmod_core_Auth_UserPassBase`. This is a helper-class that implements much of the common code needed for username/password authentication. - The `login` function receives the username and password the user enters. It is expected to authenticate the user. If the username or password is correct, it must return a set of attributes for the user. Otherwise, it must throw the `SimpleSAML_Error_Error('WRONGUSERPASS');` exception. - Attributes are returned as an associative array of `name => values` pairs. All attributes can have multiple values, so the values are always stored in an array. Configuring our authentication source ------------------------------------- Before we can test our authentication source, we must add an entry for it in `config/authsources.php`. `config/authsources.php` contains an list of enabled authentication sources. The entry looks like this: 'myauthinstance' => array( 'mymodule:MyAuth', ), You can add it to the beginning of the list, so that the file looks something like this: array( 'mymodule:MyAuth', ), /* Other authentication sources follow. */ ); `myauthinstance` is the name of this instance of the authentication source. (You are allowed to have multiple instances of an authentication source with different configuration.) The instance name is used to refer to this authentication source in other configuration files. The first element of the configuration of the authentication source must be `'mymodule:MyAuth'`. This tells SimpleSAMLphp to look for the `sspmod_mymodule_Auth_Source_MyAuth` class. Testing our authentication source --------------------------------- Now that we have configured the authentication source, we can test it by accessing "authentication"-page of the SimpleSAMLphp web interface. By default, the web interface can be found on `http://yourhostname.com/simplesaml/`. (Obviously, "yourhostname.com" should be replaced with your real hostname.) Then select the "Authentication"-tab, and choose "Test configured authentication sources". You should then receive a list of authentication sources from `config/authsources.php`. Select `myauthinstance`, and log in using "theusername" as the username, and "thepassword" as the password. You should then arrive on a page listing the attributes we return from the `login` function. Next, you should log out by following the log out link. Using our authentication source in an IdP ----------------------------------------- To use our new authentication source in an IdP we just need to update the IdP configuration to use it. Open `metadata/saml20-idp-hosted.php`. In that file you should locate the `auth`-option for your IdP, and change it to `myauthinstance`: 'myauthinstance', /* ... */ ); You can then test logging in to the IdP. If you have logged in previously, you may need to log out first. Adding configuration to our authentication source ------------------------------------------------- Instead of hardcoding options in our authentication source, they should be configurable. We are now going to extend our authentication source to allow us to configure the username and password in `config/authsources.php`. First, we need to define the properties in the class that should hold our configuration: private $username; private $password; Next, we create a constructor for the class. The constructor is responsible for parsing the configuration and storing it in the properties. public function __construct($info, $config) { parent::__construct($info, $config); if (!is_string($config['username'])) { throw new Exception('Missing or invalid username option in config.'); } $this->username = $config['username']; if (!is_string($config['password'])) { throw new Exception('Missing or invalid password option in config.'); } $this->password = $config['password']; } We can then use the properties in the `login` function. The complete class file should look like this: username = $config['username']; if (!is_string($config['password'])) { throw new Exception('Missing or invalid password option in config.'); } $this->password = $config['password']; } protected function login($username, $password) { if ($username !== $this->username || $password !== $this->password) { throw new SimpleSAML_Error_Error('WRONGUSERPASS'); } return array( 'uid' => array($this->username), 'displayName' => array('Some Random User'), 'eduPersonAffiliation' => array('member', 'employee'), ); } } We can then update our entry in `config/authsources.php` with the configuration options: 'myauthinstance' => array( 'mymodule:MyAuth', 'username' => 'theconfigusername', 'password' => 'theconfigpassword', ), Next, you should go to the "Test configured authentication sources" page again, and test logging in. Note that we have updated the username & password to "theconfigusername" and "theconfigpassword". (You may need to log out first before you can log in again.) A more complete example - custom database authentication -------------------------------------------------------- The [sqlauth:SQL](./sqlauth:sql) authentication source can do simple authentication against SQL databases. However, in some cases it cannot be used, for example because the database layout is too complex, or because the password validation routines cannot be implemented in SQL. What follows is an example of an authentication source that fetches an user from a database, and validates the password using a custom function. This code assumes that the database contains a table that looks like this: CREATE TABLE userdb ( username VARCHAR(32) PRIMARY KEY NOT NULL, password_hash VARCHAR(64) NOT NULL, full_name TEXT NOT NULL); An example user (with password "secret"): INSERT INTO userdb (username, password_hash, full_name) VALUES('exampleuser', 'QwVYkvlrAMsXIgULyQ/pDDwDI3dF2aJD4XeVxg==', 'Example User'); In this example, the `password_hash` contains a base64 encoded SSHA password. A SSHA password is created like this: $password = 'secret'; $numSalt = 8; /* Number of bytes with salt. */ $salt = ''; for ($i = 0; $i < $numSalt; $i++) { $salt .= chr(mt_rand(0, 255)); } $digest = sha1($password . $salt, TRUE); $password_hash = base64_encode($digest . $salt); The class follows: dsn = $config['dsn']; if (!is_string($config['username'])) { throw new Exception('Missing or invalid username option in config.'); } $this->username = $config['username']; if (!is_string($config['password'])) { throw new Exception('Missing or invalid password option in config.'); } $this->password = $config['password']; } /** * A helper function for validating a password hash. * * In this example we check a SSHA-password, where the database * contains a base64 encoded byte string, where the first 20 bytes * from the byte string is the SHA1 sum, and the remaining bytes is * the salt. */ private function checkPassword($passwordHash, $password) { $passwordHash = base64_decode($passwordHash); $digest = substr($passwordHash, 0, 20); $salt = substr($passwordHash, 20); $checkDigest = sha1($password . $salt, TRUE); return $digest === $checkDigest; } protected function login($username, $password) { /* Connect to the database. */ $db = new PDO($this->dsn, $this->username, $this->password); $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); /* Ensure that we are operating with UTF-8 encoding. * This command is for MySQL. Other databases may need different commands. */ $db->exec("SET NAMES 'utf8'"); /* With PDO we use prepared statements. This saves us from having to escape * the username in the database query. */ $st = $db->prepare('SELECT username, password_hash, full_name FROM userdb WHERE username=:username'); if (!$st->execute(array('username' => $username))) { throw new Exception('Failed to query database for user.'); } /* Retrieve the row from the database. */ $row = $st->fetch(PDO::FETCH_ASSOC); if (!$row) { /* User not found. */ SimpleSAML\Logger::warning('MyAuth: Could not find user ' . var_export($username, TRUE) . '.'); throw new SimpleSAML_Error_Error('WRONGUSERPASS'); } /* Check the password. */ if (!$this->checkPassword($row['password_hash'], $password)) { /* Invalid password. */ SimpleSAML\Logger::warning('MyAuth: Wrong password for user ' . var_export($username, TRUE) . '.'); throw new SimpleSAML_Error_Error('WRONGUSERPASS'); } /* Create the attribute array of the user. */ $attributes = array( 'uid' => array($username), 'displayName' => array($row['full_name']), 'eduPersonAffiliation' => array('member', 'employee'), ); /* Return the attributes. */ return $attributes; } } And configured in `config/authsources.php`: 'myauthinstance' => array( 'mymodule:MyAuth', 'dsn' => 'mysql:host=sql.example.org;dbname=userdatabase', 'username' => 'db_username', 'password' => 'secret_db_password', ), simplesamlphp-1.15.3/docs/simplesamlphp-sp-api.md 0000644 0000000 0000000 00000016114 13245225037 020502 0 ustar root root SimpleSAMLphp SP API reference ============================== 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('Login'); } `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('Login'); ### 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=