WP Subdomain Login

Seamlessly authenticate WordPress users across your main site and subdomain with separate databases. Simple, secure, and production-ready.

Get Started User Migration Guide

Overview

WP Subdomain Login allows you to create a login form on your main WordPress site that authenticates users and redirects them to a subdomain site, even when both sites use completely separate databases.

Separate Databases

Works with independent databases on different servers

Secure Authentication

HMAC-SHA256 encrypted tokens with 5-minute expiry

Easy Integration

Simple shortcode or PHP function implementation

Features

  • Cross-site authentication with separate databases
  • Secure token-based authentication (HMAC-SHA256)
  • Username-based matching (user IDs can differ)
  • Customizable redirect destinations
  • Remember me functionality
  • Professional, responsive login form design
  • Error message handling
  • CSRF protection with nonces

Getting Started

Prerequisites: WordPress 5.0+, PHP 7.4+, Both sites must have users with matching usernames and passwords.

Quick Start

  1. Install the plugin on both your main site and subdomain
  2. Configure the secret key in wp-config.php on both sites
  3. Add the shortcode to your main site's login page
  4. Test the login flow

Installation

Method 1: WordPress Admin (Recommended)

  1. Download wp-subdomain-login-v1.0.1.zip
  2. Go to WordPress Admin → Plugins → Add New → Upload Plugin
  3. Choose the zip file and click Install Now
  4. Click Activate Plugin
  5. Repeat on both sites (main site and subdomain)

Method 2: Manual Installation

  1. Extract the zip file
  2. Upload the wp-subdomain-login folder to /wp-content/plugins/
  3. Activate the plugin through the WordPress admin
  4. Repeat on both sites

Configuration

Step 1: Generate a Secret Key

Generate a random secret key for secure token encryption:

php -r "echo bin2hex(random_bytes(32));"

A quick alternative way to generate a secret key is to use a Secret Key Generator. Click the link and copy the key.

Step 2: Add Secret Key to wp-config.php

Add this line to wp-config.php on BOTH sites (before "That's all, stop editing!"):

define('SUBDOMAIN_AUTH_SECRET', 'your-generated-secret-key-here');
Important: Both sites must use the exact same secret key for authentication to work.

Shortcode Usage

Basic Usage

Add this shortcode to any page or post on your main site:

[wp_subdomain_login subdomain="https://subdomain.example.com" redirect="/dashboard"]

Parameters

Parameter Required Description Example
subdomain Required Full URL of the subdomain site https://app.example.com
redirect Optional Path to redirect after login (default: /) /dashboard

Examples

// Redirect to homepage
[wp_subdomain_login subdomain="https://app.example.com"]

// Redirect to specific page
[wp_subdomain_login subdomain="https://app.example.com" redirect="/welcome"]

// Redirect to user profile
[wp_subdomain_login subdomain="https://members.example.com" redirect="/profile"]

PHP Function

For theme developers, you can use the PHP function directly in your templates:

Function Signature

wp_subdomain_login_display_form( $subdomain_url, $redirect_path = '/' );

Parameters

Parameter Type Required Description
$subdomain_url string Required Full URL of the subdomain
$redirect_path string Optional Path to redirect after login (default: /)

Example Usage

<?php
// In your theme template
if ( function_exists( 'wp_subdomain_login_display_form' ) ) {
    wp_subdomain_login_display_form( 
        'https://app.example.com', 
        '/dashboard' 
    );
}
?>

Troubleshooting

Causes:
  • Secret keys don't match between sites
  • Server time synchronization issues
  • Token expired (5-minute limit)
Solutions:
  • Verify both sites have the exact same SUBDOMAIN_AUTH_SECRET
  • Check server time with date command on both servers
  • Ensure NTP is running for time synchronization

Causes:
  • User doesn't exist on subdomain
  • Username mismatch between sites
Solutions:
  • Ensure user exists on both sites with matching username
  • Run user migration (see Migration Guide)
  • Check username spelling and case sensitivity

Cause: Using plugin version 1.0.0 which had a bug using user IDs instead of usernames.

Solution: Update to version 1.0.1 or later, which correctly uses usernames for authentication.

Causes:
  • Plugin not activated
  • Shortcode syntax error
  • Theme conflicts
Solutions:
  • Verify plugin is activated on main site
  • Check shortcode parameters are correct
  • Try switching to a default WordPress theme temporarily
  • Check for JavaScript errors in browser console

Frequently Asked Questions

No! The plugin is specifically designed to work with separate databases. Your main site and subdomain can have completely independent databases on different servers. The only requirement is that usernames and passwords must match between the two sites.

This is completely fine! The plugin uses usernames for authentication, not user IDs. User 'john' might be ID 5 on the main site and ID 12 on the subdomain - the plugin will correctly match by username.

Yes, the plugin must be installed and activated on both your main site and subdomain. The main site handles the login form and token generation, while the subdomain validates tokens and logs users in.

Very secure! Tokens use HMAC-SHA256 encryption with your shared secret key, expire after 5 minutes, and can only be validated by a site with the matching secret key. The token contains only the username and timestamp - no passwords or sensitive data.

Yes, but with considerations. If your main site is Multisite, users are stored in a shared wp_users table. You'll need to specify the correct site_id when querying users and map multisite roles to single-site equivalents on the subdomain.

Ready to Get Started?

Download the plugin and start authenticating users across your WordPress sites today.

Download Plugin v1.0.1
View Migration Guide →