Skip to content

README updates #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

README updates #102

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
30a0d94
Cleanup sections and improvements on README
allysonsouza Jan 22, 2025
28ca0ff
README improvements and cleanup
allysonsouza Jan 23, 2025
36b5af5
Merge branch 'master' into documentation
allysonsouza Jan 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 59 additions & 59 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).

Expand All @@ -82,13 +75,21 @@ 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
```

This plugin can be tested or developed within any local WordPress environment.

## Contribute
**TL;DR**
Expand All @@ -99,9 +100,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.

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).

### Setting up
### Developing

To get development dependencies, install composer and npm dependencies via:

Expand All @@ -112,26 +117,21 @@ 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

## Next

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).

Interested in joining in on the fun? [Join us, and become human!](https://hmn.md/is/hiring/)
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).

## Changelog

Expand Down
Loading