buffcleb/buffcleb-saml-sp

1. What this repo is

- This is a WordPress plugin that turns a site into a SAML 2.0 Service Provider (SP).

- It is not a standalone service: it runs inside WordPress, uses WordPress admin/UI hooks, and exposes SAML endpoints through query parameters on the normal site URL.

2. Top-level structure

- buffcleb-saml-sp.php is the plugin bootstrap entrypoint.

- includes/ contains the protocol, security, user, logging, CLI, and lifecycle classes.

- admin/ contains the WordPress admin tabs and list-table UI.

- docs/ is extensive operational and architectural documentation, which closely matches the plugin’s runtime responsibilities.

3. Request-routing and public endpoints

- The plugin exposes five main public endpoints via ?buffcleb_saml_sp=...:

- metadata for SP metadata output

- login to start SP-initiated SSO

- acs for the SAML Assertion Consumer Service callback

- sls for Single Logout

- attributes for per-user attribute display

- These endpoints are the main boundary between the browser/IdP and the plugin’s internal SAML engine.

4. SAML protocol core

- The core protocol implementation is split across classes such as:

- authn-request, response, logout, acs

- metadata, idp-metadata, metadata-refresh

- xml, xml-verifier, schema, crypto, decrypter

- request-store

- Together they handle request construction, XML parsing, signature verification, assertion decryption, replay protection, and logout message handling.

5. Security model is a first-class subsystem

- The plugin deliberately avoids third-party SAML libraries and implements XML signing/verification directly with PHP ext-dom and ext-openssl.

- Security-sensitive code enforces anti-wrapping checks, destination/audience/recipient/timing validation, XXE-safe XML loading, login-CSRF browser binding, and SSRF-safe metadata retrieval.

- The architecture is therefore “WordPress integration + custom SAML engine,” rather than “WordPress wrapper around a SAML SDK.”

6. Identity Provider lifecycle

- Identity Providers are managed as first-class configuration objects through the admin UI and metadata import.

- The plugin supports importing IdP metadata from URL, paste, or file, then refreshing it automatically later.

- It also supports certificate rollover by staging a primary and “next” signing certificate, which matters for zero-downtime IdP key rotation.

7. User resolution, provisioning, and access control

- After a successful SAML response, the plugin maps the assertion to a WordPress user via user, transform, and related access-control logic.

- It supports matching by email or username, optional auto-provisioning, attribute-to-field/meta mapping, role mapping, and per-IdP allow/deny rules.

- Access-denied handling is a distinct flow with customizable denial messages, so authorization is separate from authentication.

8. Login UX and WordPress integration points

- The plugin integrates into wp-login.php with a branded “Sign in with SSO” button and per-IdP buttons/logos.

- Shortcodes expose the same login entry points inside content, which makes the login UI reusable outside the default login screen.

- “Force SSO” changes the normal WordPress authentication boundary by disabling local passwords, with an emergency token as a recovery path.

9. Administration, monitoring, and operational controls

- admin/ contains tabbed screens for SP settings, IdPs, logs, maintenance, and users.

- The plugin extends the Users list with SSO-related columns and a per-user attributes view.

- Logging is a core subsystem: searchable/filterable activity logs, verbose SAML message capture, CSV export, retention controls, failure-spike alerts, and IP anonymization.

10. External integrations and operational outputs

- Beyond WordPress and IdPs, the main external operational sink is optional SIEM forwarding to a file in JSON Lines or CEF format.

- There is also certificate-expiry monitoring and metadata refresh automation, both of which behave like scheduled maintenance jobs inside WordPress.

11. Automation and lifecycle management

- includes/class-buffcleb-saml-sp-cli.php supports WP-CLI operations for maintenance and admin automation.

- uninstall.php indicates a clean teardown path, and the docs mention config export/import for moving settings between environments.

- This means the plugin has a full operational lifecycle: install, configure, observe, rotate keys, migrate config, and uninstall.

12. How the main data flow works

- Admin imports or refreshes IdP metadata → settings/certs are stored → SP publishes metadata to the IdP → user hits login → plugin sends AuthnRequest → IdP POSTs SAMLResponse to ACS → response is verified/decrypted → attributes are mapped → WordPress user is matched/provisioned → session/login state is established → logs/alerts/SIEM are updated.