Twelve Legs Marketing SSO

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

1. User clicks login link from SSO application sso.twelvelegsmarketing.com
2. SSO application redirects to WordPress with JWT token: /wp-login.php?action=twl_sso&token=JWT_TOKEN
3. Plugin validates the JWT token signature and claims
4. Plugin extracts user information from JWT claims
5. Plugin creates or retrieves WordPress user
6. Plugin assigns appropriate role based on JWT claims
7. User is logged into WordPress

JWT Claims

The plugin expects the following JWT claims:

• email or sub: User’s email address
• iss: Issuer (must match allowed issuers)
• aud: Audience (must match WordPress site URL)
• exp: Expiration time
• nbf: 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: Only allows https://sso.twelvelegsmarketing.com as issuer
• Development/Staging: Also allows https://localhost:8443 as issuer

Customization

You can customize the plugin behavior using WordPress filters:

• twl_sso_allow_email: Filter to control which email addresses are allowed
• twl_sso_allowed_roles: Filter to control which roles can be assigned
• twl_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.

1. Upload the plugin files to the /wp-content/plugins/twelve-legs-marketing-sso/ directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the ‘Plugins’ screen in WordPress

Manual Installation

1. Download the plugin files
2. Extract the files to your /wp-content/plugins/twelve-legs-marketing-sso/ directory

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