meta data for this page
  •  

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
plugin:simplesaml [2024/05/20 00:00] – external edit 127.0.0.1plugin:simplesaml [2025/05/03 11:39] (current) – [Keycloak] tatevik
Line 1: Line 1:
-# SIMPLESAMLPHP PLUGIN+====== SIMPLESAMLPHP ======
  
-—- plugin —-  +---- plugin ----
 Description: This plugin provides Single Sign-on, `SSO` for `phpList` via the [`SIMPLESAMLPHP`](https://simplesamlphp.org/).   Description: This plugin provides Single Sign-on, `SSO` for `phpList` via the [`SIMPLESAMLPHP`](https://simplesamlphp.org/).  
 author : Fon E. Noel Nfebe <github.com/fenn-cs> author : Fon E. Noel Nfebe <github.com/fenn-cs>
-type :   +type : plugin 
-compatible : phpList 3.6.8 and above, PHP 7.4 and above +compatible : phpList 3.6.8 and above, PHP 7.4 and above  
-depends :   +similar :  https://github.com/TatevikGr/phplist-plugin-oidc
-conflicts :   +
-similar :  +
 tags : authentication tags : authentication
  
-Source Repository :  [https://github.com/phpList/phplist-plugin-simplesaml](https://github.com/phpList/phplist-plugin-simplesaml)+Source Repository : (https://github.com/phpList/phplist-plugin-simplesaml)
  
 ---------- ----------
  
-# Installation+===== Installation =====
  
-### Plugin download+=== Plugin download ===
  
-To easiest way to setup this plugin is through the plugins page (menu Config > Manage plugins) using the package URL https://github.com/phpList/phplist-plugin-simplesaml/archive/refs/heads/main.zip+The easiest way to setup this plugin is through the plugins page (menu Config > Manage plugins) using the package URL https://github.com/phpList/phplist-plugin-simplesaml/archive/refs/heads/main.zip
  
 The plugin may be enabled at this point or after the `SimpleSAMLPHP` config described below. The plugin may be enabled at this point or after the `SimpleSAMLPHP` config described below.
  
-### SimpleSAMLPHP Installation+=== SimpleSAMLPHP Installation ===
  
-This plugin requires an installation of [`SIMPLESAMLPHP`](https://simplesamlphp.org/) to work. So the puglin comes with a ready to use build of `SIMPLESAMLPHP`. However, it is required that the server on which the `phpList` instance is running is configured to point to the `simplesamlphp` folder that comes in the plugin.+Plugin comes with a ready to use build of [`SIMPLESAMLPHP`](https://simplesamlphp.org/) (source code is slightly updated to work with phplist session logic). However, it is required that the server on which the `phpList` instance is running is configured to point to the `simplesamlphp` folder that comes in the plugin.
  
 Essentially, `your-phplist-domain.ext/simplesamlphp` should point to the folder in `main/simplesaml/simplesamlphp` of the extension or a copy of it on your server. Essentially, `your-phplist-domain.ext/simplesamlphp` should point to the folder in `main/simplesaml/simplesamlphp` of the extension or a copy of it on your server.
  
-*Advanced User: See [simplesaml config section](https://github.com/phpList/phplist-plugin-simplesaml#ways-to-configure-2-above) in the read me for more detailed information*+== Advanced User: See [simplesaml config section](https://github.com/phpList/phplist-plugin-simplesaml#ways-to-configure-2-above) in the read me for more detailed information ==
  
  
-### SimpleSAMLPHP Custom Configuration+===== Configuration =====
  
 By default, this plugin is configured to work with the `phpList`'s `Keyclaok` server. If you wish to change the identity provider, more configuration would be required. As described below. By default, this plugin is configured to work with the `phpList`'s `Keyclaok` server. If you wish to change the identity provider, more configuration would be required. As described below.
Line 38: Line 36:
 In `main/simplesaml/simplesamlphp/config/authsources.php` the following parameters have to be set: In `main/simplesaml/simplesamlphp/config/authsources.php` the following parameters have to be set:
  
-* **entityID**: The entityID is essentially the client ID which is specified in Keycloak or IDP + * **entityID**: The entityID is essentially the client ID which is specified in Keycloak or IDP 
-* **idp**: The IDP is the identifier for the IdP (Keycloak) which simplesaml would connect to. + * **idp**: The IDP is the identifier for the IdP (Keycloak) which simplesaml would connect to. 
-* **RelayState**: The RelayState specifies where simplesamlphp should redirect to after a successful authentication. Basically it's like a callback url. This should simply be the URL from which the authentication started. Hence, a 'redirect back'. + * **RelayState**: The RelayState specifies where simplesamlphp should redirect to after a successful authentication. Basically it's like a callback url. This should simply be the URL from which the authentication started. Hence, a 'redirect back'. 
-* **NameIDPolicy**: The IdP is expected to return a NameID every successful auth session, this name ID is what identifies the user. Depending on the IdP this NameID might change every session. That makes it impossible to tract the user across session. So we have to said the NameIDPolicy to persistent essentially telling the IdP to send the same NameID all the time for the same user.+ * **NameIDPolicy**: The IdP is expected to return a NameID every successful auth session, this name ID is what identifies the user. Depending on the IdP this NameID might change every session. That makes it impossible to tract the user across session. So we have to said the NameIDPolicy to persistent essentially telling the IdP to send the same NameID all the time for the same user.
  
  
Line 48: Line 46:
 * **`baseurlpath`**: The `baseurlpath` refers to the base url the running `SimpleSAML` configuration. Depending on where simplesaml was installed, it could be a separate domain such as `phplist.com/simplesamlphp/www` or a path like `phplist.com/admin/simplesamlphp/www`. * **`baseurlpath`**: The `baseurlpath` refers to the base url the running `SimpleSAML` configuration. Depending on where simplesaml was installed, it could be a separate domain such as `phplist.com/simplesamlphp/www` or a path like `phplist.com/admin/simplesamlphp/www`.
  
-_**NB:** The baseurlpath (which is essentially the simplesamlphp  installation URI) is where the IdP returns the SAML response after a successful login. The SAML request would then be parsed and simplesamlphp would redirect back to the phplist url that sent the request or the one set via the `RelayState` property in the config array of `authsources.php`_ within the config dir.+_**NB:** The baseurlpath (which is essentially the simplesamlphp  installation URI) is where the IdP returns the SAML response after a successful login. The SAML request would then be parsed and simplesamlphp would redirect back to the phplist URL that sent the request or the one set via the `RelayState` property in the config array of `authsources.php`_ within the config dir.
  
 For more information about the custom configuration see [Readme config section](https://github.com/phpList/phplist-plugin-simplesaml#configuration)) For more information about the custom configuration see [Readme config section](https://github.com/phpList/phplist-plugin-simplesaml#configuration))
  
-#### Installation for advanced users (git & terminal)+==== Installation for advanced users (git & terminal) ====
  
 See the README file on the GitHub page  [https://github.com/phpList/phplist-plugin-simplesaml](https://github.com/phpList/phplist-plugin-simplesaml) See the README file on the GitHub page  [https://github.com/phpList/phplist-plugin-simplesaml](https://github.com/phpList/phplist-plugin-simplesaml)
  
-## Plugin Activation+== Plugin Activation ==
  
 It is recommended to only enable the plugin only after the `SIMPLESAMLPHP` configs are set in the various configuration files described above and or in the [README](https://github.com/phpList/phplist-plugin-simplesaml#readme). It is recommended to only enable the plugin only after the `SIMPLESAMLPHP` configs are set in the various configuration files described above and or in the [README](https://github.com/phpList/phplist-plugin-simplesaml#readme).
  
-## Important Checks+== Important Checks ===
  
-### `SimpleSAMLPHP` Installation check+==== Keycloak ==== 
 + 
 +Configure Keycloak using this guide: https://resources.phplist.com/system/keycloak 
 +Documentation: https://www.keycloak.org/documentation 
 + 
 +=== `SimpleSAMLPHP` Installation check ===
 You should verify that `yourdomain.com/simplesamlphp` for example `phplist.com/simplesamlphp` loads the `simplesamlphp` files correctly and that `phplist.com/simplesamlphp/www` loads the `simplesamlphp` UI like the one shown below. You should verify that `yourdomain.com/simplesamlphp` for example `phplist.com/simplesamlphp` loads the `simplesamlphp` files correctly and that `phplist.com/simplesamlphp/www` loads the `simplesamlphp` UI like the one shown below.
  
 ![enter image description here](https://i.ibb.co/9pxM33T/simplesamlphp-success-install.png) ![enter image description here](https://i.ibb.co/9pxM33T/simplesamlphp-success-install.png)
  
 +You should have saml-certificate.pem and saml-private-key.pem files in main/simplesaml/simplesamlphp/cert directory and certificate from IDP (keycloak) in saml-remote-idp.crt file
 +Certificate keys of keycloak client can be generated with openssl commands:
 +- openssl genpkey -algorithm RSA -out saml-private-key.pem -pkeyopt rsa_keygen_bits:2048
 +- openssl req -new -x509 -key saml-private-key.pem -out saml-crtificate.pem)
 +Remote idp certificate can be fetched from keycloak metadata descriptor (https://sso.phplist.com:8443/realms/master/protocol/saml/descriptor)
  
-### Testing 
-#### Activation  
  
-After cloning the plugin in your plugin directory, you should login normally using your admin credentials and activate the plugin from the plugin management tab.+==== Activation ====
  
-#### Identity Provider Redirect  +After cloning the plugin in your plugin directory, you should login normally using your admin credentials and activate the plugin from the plugin management tab.
-  +
-Once the plugin is activated, if you logout the plugin should automatically redirect you the the Identity provider.+
  
-![Keycloak View](https://i.ibb.co/wdmnxmF/keycloak.png)+==== Plugin has option to disable default login which can be done from phplist Menu->config->settings  ====
  
  
-# Support +== Support == 
-Report any issues or questions in the support forum  [https://discuss.phplist.org/](https://discuss.phplist.org/ "https://discuss.phplist.org/")+Report any issues or questions in the support forum  [https://discuss.phplist.org/]