外掛說明
TWL SSO is a secure single sign-on plugin for WordPress that enables seamless authentication using RS256 JWT tokens from an external SSO application.
This plugin provides login security features and is designed for allowing Twelve Legs Marketing centralized authentication management.
Key Features
- Single Sign In: Agency employees can log into websites they manage from a central dashboard.
- Just-in-Time User Provisioning: Automatic user creation and role assignment
- JWT Validation: Full RS256 signature verification with JWKS endpoint integration
- Key Rotation: Support key rotation through JWKS endpoint
- Role Management: Flexible role assignment from JWT claims
- Referrer Validation: Enhanced security through referrer validation
- Audience Validation: Ensures tokens are valid for the specific WordPress site
- Token Expiration: Built-in token expiration and clock skew tolerance
- Email Validation: Comprehensive email validation with optional allowlist
- Caching: JWKS caching for improved performance
Security Features
- Referrer validation to prevent unauthorized access
- JWT signature verification using public key cryptography
- Issuer validation to ensure tokens come from trusted sources
- Audience validation to prevent token reuse across sites
- Token expiration validation with configurable leeway
- Email format validation and filtering via hook
Use Cases
- WordPress installations managed centrally by agency
- Organization using Google for external identity provider
Usage
Authentication Flow
- User clicks login link from SSO application (sso.twelvelegsmarketing.com or wpsso.twelvelegsmarketing.com)
- SSO application redirects to WordPress with JWT token:
/wp-login.php?action=twl_sso&token=JWT_TOKEN - Plugin validates the JWT token signature and claims
- Plugin extracts user information from JWT claims
- Plugin creates or retrieves WordPress user
- Plugin assigns appropriate role based on JWT claims
- User is logged into WordPress
JWT Claims
The plugin expects the following JWT claims:
emailorsub: User’s email addressiss: Issuer (must match allowed issuers)aud: Audience (must match WordPress site URL)exp: Expiration timenbf: Not before time (optional)wp_role: WordPress role to assign (optional)name: User’s display name (optional)given_name: User’s first name (optional)family_name: User’s last name (optional)
Configuration
The plugin automatically configures itself based on the WordPress environment:
- Production: Allows
https://sso.twelvelegsmarketing.comandhttps://wpsso.twelvelegsmarketing.comas issuers - Development/Staging: Also allows
https://localhost:8443as issuer
Customization
You can customize the plugin behavior using WordPress filters:
twl_sso_allow_email: Filter to control which email addresses are allowedtwl_sso_allowed_roles: Filter to control which roles can be assignedtwl_sso_allowed_issuers: Filter to control which issuers are allowed
Support
For support, please contact Twelve Legs Marketing at https://twelvelegsmarketing.com
Privacy Policy
This plugin does not collect, store, or transmit any personal data. All authentication is handled through secure JWT tokens from your configured SSO provider.
安裝方式
- Upload the plugin files to the
/wp-content/plugins/twelve-legs-marketing-sso/directory, or install the plugin through the WordPress plugins screen directly. - Activate the plugin through the ‘Plugins’ screen in WordPress
Manual Installation
- Download the plugin files
- Extract the files to your
/wp-content/plugins/twelve-legs-marketing-sso/directory
常見問題集
-
How does this plugin work?
-
The plugin intercepts login requests with a special action parameter and JWT token. It validates the JWT signature using public keys from a JWKS endpoint, extracts user information from the token claims, and creates or updates the WordPress user accordingly.
-
What JWT algorithm does this plugin support?
-
This plugin supports RS256 (RSA with SHA-256) JWT signatures only. This provides strong security through public key cryptography.
-
Can I use this with any SSO provider?
-
The plugin is designed to work with any SSO provider that can issue RS256 JWTs and provide a JWKS endpoint. You’ll need to configure your SSO provider to issue tokens with the correct audience and claims.
-
How do I configure the allowed issuers?
-
The plugin automatically configures allowed issuers based on the WordPress environment. In production,
https://sso.twelvelegsmarketing.comandhttps://wpsso.twelvelegsmarketing.comare allowed. In development/staging,https://localhost:8443is also allowed. -
What happens if a user doesn’t exist?
-
The plugin will automatically create a new WordPress user with the information from the JWT claims. The username is generated from the email address, and a random password is assigned.
-
How are user roles assigned?
-
User roles can be assigned in two ways:
1. Through thewp_roleclaim in the JWT token
2. Using the WordPress default role if no role is specified in the token -
Is this plugin secure?
-
Yes, the plugin implements multiple security layers including JWT signature verification, referrer validation, issuer validation, audience validation, and token expiration checking.
使用者評論
這個外掛目前沒有任何使用者評論。
參與者及開發者
變更記錄
2.1
- Add wpsso.twelvelegsmarketing.com as an allowed production SSO issuer
2.0
- Validate post-login redirects with allowed redirect hosts
- Build JWKS fetch URLs with add_query_arg for referrers that already have query parameters
- Reject replayed JWTs via transient jti tracking
- Generic SSO authentication failure message with detailed JSONL logging under uploads
- Rate limit failed SSO attempts (3 per minute, 5-minute lockout)
- Security audit logging (JSONL, daily files in uploads)
1.1
- Cache JWKS keys individually in wp_options (no expiration; keys are immutable)
1.0.2
- Version bump to sync plugin file with readme.txt
1.0.1
- Update install instructions
- Updated Required versions
1.0
- Initial release
- JWT validation with RS256 signature verification
- JWKS endpoint integration
- Environment-based issuer validation
- Just-in-time user provisioning
- Role assignment from JWT claims
- Referrer validation for security
- Comprehensive test suite with 39 tests