diff --git a/README.md b/README.md index 715dc8e..216f84b 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,62 @@ +# 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 -- 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 Human Made -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 new file mode 100644 index 0000000..e69de29 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..cacae6b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,141 @@ +# WordPress Simple SAML + + + + + + +
+ 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. + +## 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 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/) diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 0000000..bb7107c --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/hooks.md b/docs/hooks.md new file mode 100644 index 0000000..e10fed8 --- /dev/null +++ b/docs/hooks.md @@ -0,0 +1,78 @@ +These are the currently available filters in WordPress Simple SAML plugin, which controls how the plugins works. + +## Filters + +- **`wpsimplesaml_idp_metadata_xml_path`** `() : string = ''` + +Use to pass a path to the XML file for IdP metadata. + +- **`wpsimplesaml_idp_metadata_xml`** `() : string = ''` + +Use to pass XML blob for IdP metadata. + +- **`wpsimplesaml_idp_metadata`** `() : string = ''` + +Use to pass/update IdP metadata. + +- **`wpsimplesaml_config`** `() : array = []` + +Use to pass/override IdP metadata. + +- **`wpsimplesaml_log_in_link`** `() : bool = true` + +Use to enable/disable/override displaying of log-in link in WordPress log-in form. + +- **`wpsimplesaml_log_in_text`** `() : string = __( 'SSO Login' )` + +Use to alter the log-in text of log-in form link. + +- **`wpsimplesaml_force`** `() : bool = false` + +Use to force SSO redirection via code, bypassing the log-in form completely, overrides the `SSO Status` option. Defaults to be disabled. + +- **`wpsimplesaml_add_users_to_site`** `( WP_User ) : bool = true` + +Use to enable/disable adding users to sites they've not been added to during SSO log-in process. Defaults to be enabled. + +- **`wpsimplesaml_match_user`** `( string $email, array $saml_attributes ) : WP_User = null` + +Use to match users from SAML responses to WordPress users using a different method, ie: a special attribute/meta key. Default to use the `user_login` mapped key/value (check `wpsimplesaml_attribute_mapping`). + +- **`wpsimplesaml_user_data`** `( array $saml_attributes ) : array` + +Use to update user data before passing to `wp_insert_user` for first-time log-ins. + +- **`wpsimplesaml_attribute_mapping`** `() : array` + +Use to map SAML response attribute fields to WordPress user fields, eg `[ 'user_login' => 'uid', 'user_email' => 'email' ]`. This is required for proper population of user data, based on your IdP of choice. + +- **`wpsimplesaml_manage_roles`** `() : bool = false` + +Use to enable management of users roles based on SAML attributes, requires use of `wpsimplesaml_map_role` to map attributes to roles. + +- **`wpsimplesaml_map_role`** `( array $saml_attribute, int $user_id, WP_User $user ) : string|array` + +Use to map SAML attributes to WordPress user roles. + +- **`wpsimplesaml_allowed_hosts`** `( string $host ) : array = []` + +Use to allow specific hosts/domains to use SSO delegation, ie: sharing the same service provider data. + +- **`wpsimplesaml_network_activated`** `() : bool = false` + +Use to override the standard WordPress plugin activation check, eg. when the plugin is activated via code. + +## Actions + +- **`wpsimplesaml_action_%ACTION%`** +- **`wpsimplesaml_invalid_endpoint`** `( string $action )` + +Can be used to use `https://my.site/sso/XXX` ( where XXX is `$action` in the above )custom URLs for various SSO related endpoints, ie checking validity of the session. + +- **`wpsimplesaml_user_created`** `( WP_User $user, array $saml_attributes )` + +Trigger custom login on creation of new users as a result of the SSO log-in process. + +- **`wpsimplesaml_cross_sso_form_inputs`** `()` + +Can be used to add more data to the delegated request form the main service provider to the delegating site, as a result of a SAML Response. diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..cd44250 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,23 @@ + + + + + Document + + + + + + +
+ + + + + diff --git a/docs/testing-locally.md b/docs/testing-locally.md new file mode 100644 index 0000000..12916e2 --- /dev/null +++ b/docs/testing-locally.md @@ -0,0 +1,44 @@ +# Testing locally + +Usually SSO systems are managed by external entities to the development team, and most times - at least in my experience - it has been a daunting experience asking for configuration changes back and forth to be able to test the SSO implementation, specially because SSO SPs ( service providers, which is our site in this case ) require a single URL to redirect to after authentication succeeds. + +Here is where kenchan0130 [docker-simplesaml](https://github.com/kenchan0130/docker-simplesamlphp) docker image comes to relieve some of the pressure, enabling you to test the SSO process with minimal changes required. + +## Steps: + +1. First we run the docker image, and pass some parameters to introduce our site's SP. Remember to update the parameters `SIMPLESAMLPHP_SP_ENTITY_ID`, `SIMPLESAMLPHP_SP_ASSERTION_CONSUMER_SERVICE` and `SIMPLESAMLPHP_SP_SINGLE_LOGOUT_SERVICE` to match your local WordPress address. On the example it's pointing to `localhost:8888`, default address of wp-env. + +```bash +docker run --name=idp \ + -p 8080:8080 \ + -e SIMPLESAMLPHP_SP_ENTITY_ID=http://localhost:8888/ \ + -e SIMPLESAMLPHP_SP_ASSERTION_CONSUMER_SERVICE=http://localhost:8888/sso/verify \ + -e SIMPLESAMLPHP_SP_SINGLE_LOGOUT_SERVICE=http://localhost:8888/sso/logout \ + -d kenchan0130/simplesamlphp +``` + +2. Second we need to configure the plugin using one of the two options, trough admin or trough code using filters. + +### Option 1: Admin + +- Go to `Settings \ General` if single installation, or `Network Settings` if multisite. +- In order to do that, we need to copy the IdP metadata XML from our dockerized IdP, which should live at http://localhost:8080/simplesaml/saml2/idp/metadata.php?output=xhtml, if you used the example above ), and save it locally where our site can read it. Let's assume it is under `ABSPATH . '/.private/sso/test.idp.xml'`. +- Create a new integration plugin / edit functions.php, and filter the plugin configuration as follows: + +``` +// SAML metadata XML file path +add_filter( 'wpsimplesaml_idp_metadata_xml', function(){ + return ABSPATH . '/.private/sso/test.idp.xml'; +} ); + +// Configure attribute mapping between WordPress and SSO IdP +add_filter( 'wpsimplesaml_attribute_mapping', function(){ + return [ + 'user_login' => 'uid', + 'user_email' => 'email', + ]; +} ); +``` +- Now you can start testing using the sample _static_ users provided by the [docker-simplesaml](https://hub.docker.com/r/kristophjunge/test-saml-idp/) + +**Note**: The docker command in the example removes the image automatically once the container is removed, as no state needs to be preserved, you just need to stop the container after you're finished, for the sake of your battery, using `docker stop idp`. \ No newline at end of file