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

• 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:

• 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: Allows https://sso.twelvelegsmarketing.com and https://wpsso.twelvelegsmarketing.com as issuers

• 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

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.