humanmade · allysonsouza · Jan 22, 2025 · Jan 23, 2025 · Jan 23, 2025 · Jan 27, 2025
diff --git a/README.md b/README.md
@@ -1,69 +1,62 @@
+# WordPress Simple SAML
+
 <table width="100%">
 	<tr>
-		<td align="left" width="70">
-			<strong>WordPress Simple SAML</strong><br />
-			Easy to use Single-sign-on ( SSO ) SAML integration plugin for WordPress, with multi-site / multi-network support. 
-		</td>
-		<td align="right" width="20%">
-			<a href="https://travis-ci.org/humanmade/wp-simple-saml">
-				<img src="https://travis-ci.org/humanmade/wp-simple-saml.svg?branch=master" alt="Build status">
-			</a>
-		</td>
-	</tr>
-	<tr>
-		<td>
-			A <strong><a href="https://hmn.md/">Human Made</a></strong> project. Maintained by <a href="https://github.com/shadyvb">Shady Sharaf</a>.
+		<td align="left" width="70%">
+			Easy to use Single-sign-on ( SSO ) SAML integration plugin for WordPress, with multi-site / multi-network support.
 		</td>
 		<td align="center">
-			<img src="https://hmn.md/content/themes/hmnmd/assets/images/hm-logo.svg" width="100" />
+			<p style="font-size:small">Created by</p>
+			<img src="https://humanmade.com/content/themes/hmnmd/assets/images/hm-logo.svg" width="100" />
 		</td>
 	</tr>
 </table>
 
+---
+
 WordPress Simple SAML is a flexible, extensible SAML integration plugin, which does most of the grunt work while keeping everything configurable through actions and filters throughout the plugin.
 
 The plugin supports multi-site networks, and cross-network SSO delegation as well. Can be installed on site-level, or on network-level.
 
 WordPress Simple SAML uses [OneLogin's PHP-SAML](https://github.com/onelogin/php-saml) toolkit for SAML API integration.
 
-## Getting Set Up
+## Installation
 
-
-- Copy the plugin files to your `wp-content/plugins` directory
-- Activate the plugin
-- Head over to [configuration screen](#Configuration).
-- Send Service Provider metadata URL ( or content ) to your Identity Provider authority (IdP) ( find the link in settings page ).
+-   Copy the plugin files to your `wp-content/plugins` directory
+-   Activate the plugin
+-   Head over to [configuration screen](#Configuration).
+-   Send Service Provider metadata URL (or content) to your Identity Provider authority (IdP), find the link in settings page.
 
 **Note**: If you're activating the plugin network-wide via code, you might need to use the filter `wpsimplesaml_network_activated` to override the standard WordPress check, something like this would be what you need:
 
 ```php
 add_filter( 'wpsimplesaml_network_activated', '__return_true' )
-```  
+```
 
-## Configuration
+### Configuration
 
 There is two ways to configure the plugin, either from the admin interface or using filters, both can be used interchangably as the project requires, usually filters prevail database settings though.
 
-### Admin configurations
+#### Option 1: Admin
 
-Depending on whether the plugin is network-activated or not, you will need to go to `Settings \ General` or `Network Settings` pages.
+Go to `Settings \ General` if single installation, or `Network Settings` if multisite.
 
-- `SSO Status`
-is how the plugin integrates with WordPress login process, available options are `Disable`, `Display login link` which only provides a link in the login form, `Force redirect` which overrides the login form altogether and directly goes to SSO login page.
-- `SSO Base URL` (optional)
-is the home URL of the WordPress site that serves as the delegate ( main service provider ) to which SAML responses will be posted, usually this is the main site of the network, and is the same value for `siteurl` option, eg `https://my.site/`
-- `SSO IdP Metadata` (required, if not filtered)
-Copy of the SSO IdP metadata XML file, which can also be passed via either `wpsimplesaml_idp_metadata_xml_path` for a path to the XML file, or `wpsimplesaml_idp_metadata_xml` for the contents of the XML, or `wpsimplesaml_idp_metadata` for the configuration array.
-- `SSO delegation whitelisted hosts`
-List of hosts to whitelist during delegation of SAML responses, ie: secondary domains that needs to use SSO as well from the same IdP. Local sites are allowed by default.  
-- `SSO Role Management`
-Enables developers to assign different roles to users based on SAML Responses, disabled by default, and is controlled via a few filters,  
-- `SSO Debug via Cookies`
-Allows developers to use a special cookie named `sso_debug` to override the `SSO Status` option during testing. Possible value of the cookie are `force` and `link`, which are self-explanatory.
-- `SSO Config validation`
-Shows information about IdP metadata and validity of its settings.
+-   `SSO Status`
+    is how the plugin integrates with WordPress login process, available options are `Disable`, `Display login link` which only provides a link in the login form, `Force redirect` which overrides the login form altogether and directly goes to SSO login page.
+-   `SSO Base URL` (optional)
+    is the home URL of the WordPress site that serves as the delegate ( main service provider ) to which SAML responses will be posted, usually this is the main site of the network, and is the same value for `siteurl` option, eg `https://my.site/`
+-   `SSO IdP Metadata` (required, if not filtered)
+    Copy of the SSO IdP metadata XML file, which can also be passed via either `wpsimplesaml_idp_metadata_xml_path` for a path to the XML file, or `wpsimplesaml_idp_metadata_xml` for the contents of the XML, or `wpsimplesaml_idp_metadata` for the configuration array.
+-   `SSO delegation whitelisted hosts`
+    List of hosts to whitelist during delegation of SAML responses, ie: secondary domains that needs to use SSO as well from the same IdP. Local sites are allowed by default.
+-   `SSO Role Management`
+    Enables developers to assign different roles to users based on SAML Responses, disabled by default, and is controlled via a few filters,
+-   `SSO Debug via Cookies`
+    Allows developers to use a special cookie named `sso_debug` to override the `SSO Status` option during testing. Possible value of the cookie are `force` and `link`, which are self-explanatory.
+-   `SSO Config validation`
+    Shows information about IdP metadata and validity of its settings.
 
-### Configuration via code
+#### Option 1: Code
 
 WordPress Simple SAML is built to be as extensible as possible, so most aspects of the login/validation process can be tweaked as needed by using the available well-documented [Hooks](https://github.com/humanmade/wp-simple-saml/wiki/Hooks).
 
@@ -82,15 +75,22 @@ add_filter( 'wpsimplesaml_attribute_mapping', function(){
 		'user_email' => 'email',
 	];
 } );
-```  
+```
 
-## Testing
+## Development
 
-This plugin can be tested or developed within any local WordPress environment. For convenience, a local WordPress server can also be run by executing `npm run dev`: this command will start a local server at http://localhost:8888/ (requires Docker). Run `npm run wp-env stop` to shut down the server when finished.
+### Testing
 
-As SSO authorities are usually a pain to change, and credentials take time to be configured, we've documented steps to get a sample SAML IdP ( Identity provider ) up and running using a test docker container. See more at [Testing SSO Locally](https://github.com/humanmade/wp-simple-saml/wiki/Testing-SSO-locally). 
+> **TL;DR**
+
+```
+# Make sure you have Docker installed, then run:
+npm install
+npm run dev
+```
 
 ## Contribute
+
 **TL;DR**
 
 ```bash
@@ -99,9 +99,13 @@ npm install
 npm run dev
 ```
 
-First, thanks for contributing!
+For convenience, you can use `@wordpress/env`, a local WordPress server can run by executing `npm run dev`: this command will start a local server at http://localhost:8888/ (requires Docker).
+
+Run `npm run wp-env stop` to shut down the server when finished.
 
-### Setting up
+As SSO authorities are usually a pain to change, and credentials take time to be configured, we've documented steps to get a sample SAML IdP ( Identity provider ) up and running using a test docker container. See more at [Testing SSO Locally](https://github.com/humanmade/wp-simple-saml/wiki/Testing-SSO-locally).
+
+### Developing
 
 To get development dependencies, install composer and npm dependencies via:
 
@@ -112,26 +116,23 @@ npm install
 
 This installs Human made's version of WordPress Coding Standards via PHP Code Sniffer, and symlinks a precommit hook to automatically check all commits for code quality concerns.
 
-### Workflow
-
-- Find an issue you'd like to help with, or create a new one for the change you'd like to introduce.
-- Fork the repo to your own account
-- Issue pull-requests from your fork to ours
-- Tag the issue you're trying to resolve in your pull-request for some context
-- Make sure the pull-request passed all Travis checks
-- Tag any of the contributors for a review.
+## Contributing
 
-## Next
+- Fork the repository
+- Create a feature branch (git checkout -b feature/amazing-feature)
+- Commit changes (git commit -m 'Add some amazing feature')
+- Push to branch (git push origin feature/amazing-feature)
+- Open a Pull Request
 
-Check [issues list](https://github.com/humanmade/wp-simple-saml/issues) for what's planned next.
+### Contribution Guidelines
 
 ## Credits
-Created by Human Made for network-wide SAML SSO Integrations, because of the lack of a well-written WordPress integration with the features/flexibility our clients require.
 
-Written and maintained by [Shady Sharaf](https://github.com/shadyvb). Thanks to all our [contributors](https://github.com/humanmade/wp-simple-saml/graphs/contributors).
+Created by <a href="https://hmn.md/"><img src="https://humanmade.com/content/themes/hmnmd/assets/images/hm-logo.svg" width="100" alt="Human Made" /></a>
 
-Interested in joining in on the fun? [Join us, and become human!](https://hmn.md/is/hiring/)
+Thanks to all our [contributors](https://github.com/humanmade/wp-simple-saml/graphs/contributors).
 
+=======
 
 ## Changelog
 

diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,141 @@
+# WordPress Simple SAML
+
+<table width="100%">
+	<tr>
+		<td align="left" width="70%">
+			Easy to use Single-sign-on ( SSO ) SAML integration plugin for WordPress, with multi-site / multi-network support.
+		</td>
+		<td align="center">
+			<p style="font-size:small">Created by</p>
+			<img src="https://humanmade.com/content/themes/hmnmd/assets/images/hm-logo.svg" width="100" />
+		</td>
+	</tr>
+</table>
+
+---
+
+WordPress Simple SAML is a flexible, extensible SAML integration plugin, which does most of the grunt work while keeping everything configurable through actions and filters throughout the plugin.
+
+The plugin supports multi-site networks, and cross-network SSO delegation as well. Can be installed on site-level, or on network-level.
+
+WordPress Simple SAML uses [OneLogin's PHP-SAML](https://github.com/onelogin/php-saml) toolkit for SAML API integration.
+
+## Installation
+
+-   Copy the plugin files to your `wp-content/plugins` directory
+-   Activate the plugin
+-   Head over to [configuration screen](#Configuration).
+-   Send Service Provider metadata URL (or content) to your Identity Provider authority (IdP), find the link in settings page.
+
+**Note**: If you're activating the plugin network-wide via code, you might need to use the filter `wpsimplesaml_network_activated` to override the standard WordPress check, something like this would be what you need:
+
+```php
+add_filter( 'wpsimplesaml_network_activated', '__return_true' )
+```
+
+### Configuration
+
+There is two ways to configure the plugin, either from the admin interface or using filters, both can be used interchangably as the project requires, usually filters prevail database settings though.
+
+#### Option 1: Admin
+
+Go to `Settings \ General` if single installation, or `Network Settings` if multisite.
+
+-   `SSO Status`
+    is how the plugin integrates with WordPress login process, available options are `Disable`, `Display login link` which only provides a link in the login form, `Force redirect` which overrides the login form altogether and directly goes to SSO login page.
+-   `SSO Base URL` (optional)
+    is the home URL of the WordPress site that serves as the delegate ( main service provider ) to which SAML responses will be posted, usually this is the main site of the network, and is the same value for `siteurl` option, eg `https://my.site/`
+-   `SSO IdP Metadata` (required, if not filtered)
+    Copy of the SSO IdP metadata XML file, which can also be passed via either `wpsimplesaml_idp_metadata_xml_path` for a path to the XML file, or `wpsimplesaml_idp_metadata_xml` for the contents of the XML, or `wpsimplesaml_idp_metadata` for the configuration array.
+-   `SSO delegation whitelisted hosts`
+    List of hosts to whitelist during delegation of SAML responses, ie: secondary domains that needs to use SSO as well from the same IdP. Local sites are allowed by default.
+-   `SSO Role Management`
+    Enables developers to assign different roles to users based on SAML Responses, disabled by default, and is controlled via a few filters,
+-   `SSO Debug via Cookies`
+    Allows developers to use a special cookie named `sso_debug` to override the `SSO Status` option during testing. Possible value of the cookie are `force` and `link`, which are self-explanatory.
+-   `SSO Config validation`
+    Shows information about IdP metadata and validity of its settings.
+
+#### Option 1: Code
+
+WordPress Simple SAML is built to be as extensible as possible, so most aspects of the login/validation process can be tweaked as needed by using the available well-documented [Hooks](https://github.com/humanmade/wp-simple-saml/wiki/Hooks).
+
+TL;DR; This is the basic minimum filters you'd need to get an implementation working with the default options.
+
+```php
+// SAML metadata XML file path
+add_filter( 'wpsimplesaml_idp_metadata_xml_path', function(){
+	return ABSPATH . '/.private/sso/test.idp.xml';
+} );
+
+// Configure attribute mapping between WordPress and SSO IdP SAML attributes
+add_filter( 'wpsimplesaml_attribute_mapping', function(){
+	return [
+		'user_login' => 'uid',
+		'user_email' => 'email',
+	];
+} );
+```
+
+## Development
+
+### Testing
+
+**TL;DR**
+
+```bash
+# Make sure you have Docker installed, then run:
+npm install
+npm run dev
+```
+
+This plugin can be tested or developed within any local WordPress environment.
+
+For convenience, you can use `@wordpress/env`, a local WordPress server can run by executing `npm run dev`: this command will start a local server at http://localhost:8888/ (requires Docker).
+
+Run `npm run wp-env stop` to shut down the server when finished.
+
+As SSO authorities are usually a pain to change, and credentials take time to be configured, we've documented steps to get a sample SAML IdP ( Identity provider ) up and running using a test docker container. See more at [Testing SSO Locally](https://github.com/humanmade/wp-simple-saml/wiki/Testing-SSO-locally).
+
+### Developing
+
+To get development dependencies, install composer and npm dependencies via:
+
+```bash
+composer install
+npm install
+```
+
+This installs Human made's version of WordPress Coding Standards via PHP Code Sniffer, and symlinks a precommit hook to automatically check all commits for code quality concerns.
+
+## Contributing
+
+- Fork the repository
+- Create a feature branch (git checkout -b feature/amazing-feature)
+- Commit changes (git commit -m 'Add some amazing feature')
+- Push to branch (git push origin feature/amazing-feature)
+- Open a Pull Request
+
+### Contribution Guidelines
+
+
+
+## Changelog
+
+-   0.3
+    -   Fix compatibilty with WordPress single site (no multisite).
+    -   Fix error caused by using WordPress dashboard function outside the dashboard.
+-   0.2.1
+    -   Fix missing composer dependency and updated .gitignore
+-   0.2
+    -   Updating PHP SAML library to 3.0 to support PHP 7.x
+-   0.1
+    -   Stable version
+
+## Credits
+
+Created by <a href="https://hmn.md/"><img src="https://humanmade.com/content/themes/hmnmd/assets/images/hm-logo.svg" width="100" alt="Human Made" /></a>
+
+Thanks to all our [contributors](https://github.com/humanmade/wp-simple-saml/graphs/contributors).
+
+Interested in joining in on the fun? [Join us, and become human!](https://hmn.md/is/hiring/)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,15 @@
+- WordPress Simple SAML
+
+	- [Installation](#Installation)
+	- Configuration
+		- Option 1: Admin
+		- Option 1: Code
+	- Development
+		- Testing
+		- Developing
+	- Contributing
+		- Contribution Guidelines
+	- Changelog
+	- Credits
+
+- [Hooks](Hooks.md)