Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
8 changes: 5 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ jobs:
[email protected] --skip-email
docker compose -p soca-ci --profile tools run -T --rm --no-deps cli wp plugin activate simple-oauth-cimd-access
docker compose -p soca-ci --profile tools run -T --rm --no-deps cli wp eval-file /tests/wordpress.php
docker compose -p soca-ci --profile tools run -T --rm --no-deps cli wp eval-file /tests/deployment.php
docker compose -p soca-ci --profile tools run -T --rm --no-deps cli wp eval-file /tests/emergency.php
docker compose -p soca-ci --profile tools run -T --rm --no-deps cli wp soca status
- name: Container logs on failure
if: failure()
Expand All @@ -79,11 +81,11 @@ jobs:
python3 tools/build.py
cd dist
sha256sum -c SHA256SUMS
unzip -t simple-oauth-cimd-access-0.2.0.zip
unzip -Z1 simple-oauth-cimd-access-0.2.0.zip | grep -Fx 'simple-oauth-cimd-access/simple-oauth-cimd-access.php'
unzip -t simple-oauth-cimd-access-0.3.0.zip
unzip -Z1 simple-oauth-cimd-access-0.3.0.zip | grep -Fx 'simple-oauth-cimd-access/simple-oauth-cimd-access.php'
- name: Upload installable plugin ZIP
uses: actions/upload-artifact@v7
with:
path: dist/simple-oauth-cimd-access-0.2.0.zip
path: dist/simple-oauth-cimd-access-0.3.0.zip
archive: false
if-no-files-found: error
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ SOCA adds single sign-on to WordPress through an OpenID Connect provider that su

- Publishes this site's client metadata and public signing keys through self-hosted URLs or a configurable HTTPS metadata proxy.
- Signs client assertions with encrypted, rotating P-256 keys and validates the provider's signed ID token.
- Applies email and domain admission rules to a **verified** provider email, then selects the matching local WordPress account. Optional creation is limited to Subscriber accounts.
- Applies email and domain admission rules to a **verified** provider email, then selects an account through its approved issuer/subject identity link. Optional creation is limited to Subscriber accounts.
- Provides a login button, a test-login flow, redacted diagnostics, WP-CLI maintenance commands, and a local-login recovery route.

**Security decision:** A provider that can verify an admitted administrator email can sign in as that administrator. Keep a local administrator login, review the admission rules, and test the provider before enabling automatic redirects. The browser's User-Agent is checked at callback, but it is not proof of the same browser.
**Upgrade to 0.3.0:** Existing users need administrator-approved issuer/subject links. Email alone no longer selects a local account. Ordinary SSO requires an admitted test login for the current configuration. Keep a working local administrator login during migration; see the [upgrade and configuration guide](docs/GUIDE.md). Callbacks require a short-lived secure browser cookie.

## Install and configure

Download the `simple-oauth-cimd-access-0.2.0.zip` release asset when published or build it with `python3 tools/build.py`. In WordPress, choose **Plugins → Add Plugin → Upload Plugin**, activate SOCA, then open **Settings → SOCA**. It requires WordPress 6.8+, PHP 8.1+, OpenSSL, cURL, and a public HTTPS site for self-hosted metadata. The installable ZIP contains its runtime dependency; Composer is not needed on the server.
Download the `simple-oauth-cimd-access-0.3.0.zip` release asset when published or build it with `python3 tools/build.py`. In WordPress, choose **Plugins → Add Plugin → Upload Plugin**, activate SOCA, then open **Settings → SOCA**. It requires WordPress 6.8+, PHP 8.1+, OpenSSL, cURL, and a public HTTPS site for self-hosted metadata. The installable ZIP contains its runtime dependency; Composer is not needed on the server.

1. Keep a working local administrator password and bookmark `/wp-login.php?soca_local=1`.
2. Review the configured issuer, provider name, client metadata mode, and exact admission rules. Defaults use `https://auth.resoauth.cloud`.
Expand All @@ -24,6 +24,7 @@ The initial identity provider is the [RESOAuth hosted Smart Access Gateway](http

## Documentation and support

- [Shared requirements review and remaining gaps](docs/REQUIREMENTS.md)
- [Operator guide](docs/GUIDE.md)
- [Local development and build](docs/DEVELOPMENT.md)
- [Security and protocol decisions](docs/SECURITY.md)
Expand Down
9 changes: 9 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,14 @@
# Release history

## 0.3.0 (unreleased)

- Bind each ten-minute transaction to its initiating browser using an independent Secure, HttpOnly, SameSite=Lax cookie; retain encrypted WordPress transients and atomic replay checks.
- Replace email-based account selection with encrypted, unique issuer/subject associations. Add explicit administrator linking/revocation and conservative provisioning rollback. Existing users require approved links.
- Require an admitted, fresh test login before ordinary SSO becomes available. Bind evidence to candidate configuration and metadata; preserve the operator session and prevent test-side account writes.
- Add deployment overrides and locks for every supported setting, shared validation, stale form rejection, WP-CLI configuration and operator-bound test URLs. Emergency disable and deactivation invalidate pending flows and activation evidence.
- Support exact and leading `*.` domain rules, platform branding/privacy defaults, public metadata overrides and explicit proxy payload/URL limits.
- Publish a per-ID shared requirements review with remaining security, interoperability and operational gaps.

## 0.2.0

- Standardized the PHP and vendored JWT namespaces, hooks, options, transients and configuration constants under SOCA, and removed pre-release compatibility paths.
Expand Down
114 changes: 114 additions & 0 deletions docs/CONFIGURATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Deployment configuration

SOCA 0.3.0 uses one validation path for deployment values, WP-CLI and the existing
WordPress settings screen. No settings form must be saved to apply deployment
configuration. Effective precedence is **defaults < saved site settings <
SOCA_CONFIG**. A key present in SOCA_CONFIG is locked in the GUI; crafted form
posts and CLI writes cannot replace it. Removing an override reveals the previous
saved value or the default. Multisite applies the constant on each site; use
conditional deployment code when sites need different values.

Provision keys/salts through the host's secret-management process. Before loading
WordPress, set SOCA_ENCRYPTION_KEY to a stable secret of at least 32 random bytes
when using a separate encryption root. Otherwise the plugin derives its root from
the WordPress authentication keys/salts. Do not put private keys or secrets in
SOCA_CONFIG or the database configuration JSON.

```php
// wp-config.php, before WordPress loads.
define('SOCA_CONFIG', [
'issuer' => 'https://auth.resoauth.cloud',
'enabled' => true,
'automatic' => false,
'mode' => 'self',
'key_mode' => 'uri',
'allow_domains' => ['example.com', '*.example.com'],
'deny_domains' => ['blocked.example.com', '*.blocked.example.com'],
'create_users' => false,
'tos_uri' => 'https://www.example.com/terms/',
]);
```

`enabled=true` requests activation; ordinary SSO remains unavailable until an
admitted operator test login succeeds for the effective candidate. Candidate
metadata is published while ordinary login is disabled. A real test validates
provider signatures, fresh authentication and admission without creating/linking
accounts, writing profiles/roles or replacing the operator's session.

Use the CLI for setup and maintenance:

```sh
wp plugin activate simple-oauth-cimd-access
wp soca config
wp soca configure /secure/deployment/soca.json
wp soca check
wp soca test-url --user=localadmin
wp soca status
wp soca link --user=localadmin 42 'https://auth.resoauth.cloud' 'exact-provider-subject'
wp soca unlink --user=localadmin 42 'https://auth.resoauth.cloud' 'exact-provider-subject'
wp soca maintain
wp soca disable
```

Identity approval and revocation require `--user=<administrator>`; audit entries record the local actor and target IDs.

`configure` accepts a JSON object containing any supported setting, with booleans,
integers, strings and string-array rule lists. Unknown names are rejected. Changes
to unlocked settings merge with previous values, so repeat deployments preserve
omitted fields. An unchanged configuration is a no-op and preserves in-flight revisions. `config` shows effective values and deployment locks, including
admission lists; restrict its output to operators. This is separate from the
redacted health/status export. The supported names are listed below.

Open the one-use `test-url` in a browser authenticated locally as the selected
administrator. It expires after ten minutes and requires that same operator and
configuration revision. Ordinary WordPress login suffices; no settings page or
form save is needed. Interactive authentication at the provider remains necessary.
The test result and activation status are available with `wp soca status`.
Enabling automatic redirects or the button preserves an otherwise unchanged
candidate test; changing issuer, callback, admission rules, metadata or inline keys
requires a fresh test. Any settings save invalidates existing in-flight flows.

| Setting | Default and validation |
| --- | --- |
| enabled, automatic, create_users, unrestricted | false. JSON/PHP booleans preferred; 0/1 accepted. Unrestricted bypasses allowlists, never denylists. Provisioning is fixed to Subscriber. |
| provider, button | RESOAuth; Continue with SSO. Plain text, 1–120 bytes. |
| issuer | https://auth.resoauth.cloud. Exact public HTTPS issuer, no query/userinfo/fragment. |
| scopes | openid email profile. Space-separated OAuth scope syntax, <=500 bytes; openid and email required. Request only necessary scopes. |
| mode, key_mode | Public host: self/uri; local host: proxy/inline. Allowed values self or proxy; uri or inline. |
| proxy | https://dynamic-cimd.resoauth.cloud/cimd/%s. Exactly one literal %s in an HTTPS path. Set this value to reset to the default. |
| jwks_url | Empty, deriving the site's public JWKS endpoint. Override must be public HTTPS. |
| id_alg | ES256. Explicit RS256 alternative for ID tokens; assertions remain ES256. |
| assertion_audience | issuer. Alternative token_endpoint uses its exact discovered URL. |
| cache_hours | 24; integer 1–168 hours. Confirm the provider's actual maximum cache lifetime. |
| allow_domains, deny_domains | Suggested exact site hostname in allow_domains; empty deny list. Arrays or separated text, <=200 entries and <=32000 bytes per list. Exact domains or one leading *. followed by a dotted domain. |
| allow_emails, deny_emails | Empty. Arrays or separated text, <=200 ASCII emails per list; verified email required. |
| client_name | Empty override uses the WordPress site name. Plain text <=120 bytes. |
| client_uri | Empty override uses the WordPress home URL. Explicit overrides require public HTTPS. |
| logo_uri | Empty override uses the WordPress Site Icon URL when public HTTPS; otherwise omitted. |
| policy_uri | Empty override uses WordPress's published privacy-policy URL when public HTTPS; otherwise omitted. |
| tos_uri | Empty by default, omitted. WordPress has no core terms-page API; set a published public HTTPS terms URL explicitly. |

Metadata uses application identity, not the identity provider's branding or legal
pages. Optional unavailable/unsafe platform URLs are omitted. Explicit overrides
must pass validation. Hosted and proxy metadata share the same generation path.

Emergency disable is independent of deployment locks:

```php
define('SOCA_DISABLED', true);
```

Roll it out to every PHP worker and run `wp soca status` with the flag present.
The first observation changes the persisted security epoch, invalidating pending
ordinary/test flows and activation evidence even after the flag is removed. PHP
opcode-cache/deployment propagation is the host's responsibility. `wp soca disable`
clears unlocked enablement and invalidates the same evidence; if enabled is locked
true, the emergency constant provides durable disablement. Existing WordPress
sessions survive disable/deactivation; unlinking an identity ends all sessions for
its local account. Retest after recovery.

Forms include a revision check and reject stale writes. Keep configuration JSON
and deployment revisions in your normal version-controlled deployment process for
rollback, excluding secrets. No automatic settings history or database rollback
engine is provided. Restoring old database backups can restore old links/evidence;
reconcile revocations and run emergency disable before restoring service.
Loading
Loading