From 30a0d9428195bfcafd9b774b844402899345cfeb Mon Sep 17 00:00:00 2001 From: Allyson Souza <2000638+allysonsouza@users.noreply.github.com> Date: Wed, 22 Jan 2025 19:32:53 -0300 Subject: [PATCH 1/2] Cleanup sections and improvements on README --- README.md | 103 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 54 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 0559546..475ed78 100644 --- a/README.md +++ b/README.md @@ -28,42 +28,41 @@ WordPress Simple SAML uses [OneLogin's PHP-SAML](https://github.com/onelogin/php ## Getting Set Up - -- 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 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,19 +81,25 @@ add_filter( 'wpsimplesaml_attribute_mapping', function(){ 'user_email' => 'email', ]; } ); -``` +``` ## Testing -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. +> **TL;DR** +> +> - Make sure you have Docker installed +> - `npm install` +> - `npm run dev` -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). +This plugin can be tested or developed within any local WordPress environment. -## Contribute +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). -First, thanks for contributing! +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: @@ -107,35 +112,35 @@ This installs Human made's version of WordPress Coding Standards via PHP Code Sn ### 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. - -## Next - -Check [issues list](https://github.com/humanmade/wp-simple-saml/issues) for what's planned next. +- 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. ## 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). +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/) ## Changelog -- 0.3 - - Fix compatibilty with WordPress single site (no multisite). - - Fix error caused by using WordPress dashboard function outside the dashboard. +- 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.1 - - Fix missing composer dependency and updated .gitignore +- 0.2 -- 0.2 - - Updating PHP SAML library to 3.0 to support PHP 7.x + - Updating PHP SAML library to 3.0 to support PHP 7.x -- 0.1 - - Stable version +- 0.1 + - Stable version From 28ca0ff01e2305eb7ed20b39d396ae4762ae0d4d Mon Sep 17 00:00:00 2001 From: Allyson Souza <2000638+allysonsouza@users.noreply.github.com> Date: Thu, 23 Jan 2025 15:31:45 -0300 Subject: [PATCH 2/2] README improvements and cleanup --- README.md | 74 +++++++++++++++++++++++++++---------------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 475ed78..ca9fe74 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,26 @@ +# WordPress Simple SAML + - - - - -
- WordPress Simple SAML
- Easy to use Single-sign-on ( SSO ) SAML integration plugin for WordPress, with multi-site / multi-network support. - 		- - Build status - -
- A Human Made project. Maintained by Shady Sharaf. + + Easy to use Single-sign-on ( SSO ) SAML integration plugin for WordPress, with multi-site / multi-network support. - +

Created by

+
+--- + 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 @@ -39,11 +33,11 @@ WordPress Simple SAML uses [OneLogin's PHP-SAML](https://github.com/onelogin/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. -### Option 1: Admin +#### Option 1: Admin Go to `Settings \ General` if single installation, or `Network Settings` if multisite. @@ -62,7 +56,7 @@ Go to `Settings \ General` if single installation, or `Network Settings` if mult - `SSO Config validation` Shows information about IdP metadata and validity of its settings. -### Option 1: 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). @@ -83,13 +77,17 @@ add_filter( 'wpsimplesaml_attribute_mapping', function(){ } ); ``` -## Testing +## Development + +### Testing > **TL;DR** -> -> - Make sure you have Docker installed -> - `npm install` -> - `npm run dev` + +``` +# 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. @@ -99,7 +97,7 @@ 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 +### Developing To get development dependencies, install composer and npm dependencies via: @@ -110,22 +108,16 @@ 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 +## Contributing -- 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. +- 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 -## Credits +### Contribution Guidelines -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. - -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/) ## Changelog @@ -144,3 +136,11 @@ Interested in joining in on the fun? [Join us, and become human!](https://hmn.md - 0.1 - Stable version + +## Credits + +Created by Human Made + +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/)