RFC: Authentication

[theodesp]

Status: WIP

Current Version: 0.1.0

Owner: TBD

Target Version: 1.0.0

Contributors: TBD

PRD: N/A

This RFC proposes a simple yet effective authentication solution for headless WordPress implementations using FaustWP Toolkit. The goal is to establish secure, flexible, and developer-friendly authentication mechanisms that work seamlessly in a decoupled WordPress architectures.

Background

Headless WordPress architectures present unique authentication challenges that differ from traditional WordPress implementations. In a traditional WordPress setup, authentication is handled through cookies and sessions, with WordPress managing the entire user experience.

However, in a headless architecture:

• The frontend application is decoupled from WordPress, typically running on a different domain
• Traditional cookie-based authentication becomes problematic due to CORS restrictions
• Server-side rendering (SSR) requires different authentication approaches than client-side rendering.
• WordPress's native authentication mechanisms aren't designed for headless architectures.

The current state of authentication in headless WordPress implementations often involves custom solutions, leading to:

• Inconsistent security practices via custom authentication implementations.
• Poor developer experience. No modularity
• Limited support for modern authentication standards since they are harder to maintain.
• Difficulty implementing features like password reset and social login since this requires federation and other features that are very custom-made.

Proposal

We propose creating a flexible authentication framework for FaustWP that supports multiple authentication providers, with WPGraphQL Headless Login (https://github.com/AxeWP/wp-graphql-headless-login) serving as the recommended plugin. However, developers could also use a compatible plugin that followers similar principles and feature sets without any obstructions.

Abandoned Ideas (Optional)

NA

Documentation and Examples

Basic Authentication Flow - Fetch API

import {LOGIN_MUTATION} from './#.queries.graphql';
const login = async (username: string, password: string) => {
    try {
      const response = await fetch(process.env.NEXT_PUBLIC_WORDPRESS_API_URL!, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          query: LOGIN_MUTATION,
          variables: { username, password },
        }),
      });

      const { data } = await response.json();

      if (data.errors) {
        throw new Error(data.errors[0]?.message || "Authentication failed");
      }

      const { user, ...tokens } = data.login;

      // Update state
      storage.setItem("authTokens", JSON.stringify(tokens));
      storage.setItem("user", JSON.stringify(user));
      setAuthState({
        user,
        tokens,
        isLoading: false,
      });

      // Navigate to protected dashboard page
      navigation.push("/dashboard");
	 return data.login;
    } catch (error) {
      console.error("Error during login:", error);
      throw error;
    }
  };

Basic Authentication Flow - Apollo

import {LOGIN_MUTATION} from './#.queries.graphql';
// Assume apollo client was configured
const [loginMutation] = useMutation(LOGIN_MUTATION);
const login = async (username: string, password: string) => {
    try {
      const { data } = await loginMutation({
        variables: { username, password },
      });

      if (!data?.login) {
        throw new Error('Login failed');
      }

      const { user, ...tokens } = data.login;

      // Update state
      storage.setItem('authTokens', JSON.stringify(tokens));
      storage.setItem('user', JSON.stringify(user));
      setAuthState({
        user,
        tokens,
        isLoading: false,
      });

      // Navigate to protected dashboard page
      navigation.push('/dashboard');

      return data.login;
    } catch (error) {
      console.error('Error during login:', error);
      throw error;
    }
  };

Plugin Agnosticism

The authentication framework can remain plugin-agnostic while providing clear integration patterns. This is achieved through the following suggestions:

Interface Definitions

export interface StorageInterface<T> {
 getItem(key: string): T | null;
 setItem(key: string, value: T): void;
 removeItem(key: string): void;
}

Local storage integration

export const useLocalStorage: StorageInterface<string> = {
 getItem: (key: string) => localStorage.getItem(key),
 setItem: (key: string, value: string) => localStorage.setItem(key, value),
 removeItem: (key: string) => localStorage.removeItem(key),
};

Next.js integration

import { useRouter } from 'next/navigation';
export interface NavigationInterface {
 push(path: string): void;
}
export const useNextNavigation = (): NavigationInterface => {
 const router = useRouter();
 return {
   push: (path: string) => router.push(path),
 };
};

Application Passwords

WordPress application passwords can be used for authenticating API requests, including WPGraphQL queries, without exposing user passwords. This is useful for:

• Automated scripts interacting with WPGraphQL.
• Backend services that require API access.
• Secure authentication for headless WordPress setups.

Example: Using Application Passwords for WPGraphQL Authentication

To authenticate using an application password, a user must have an account with an application password created. The credentials are then used in a Basic authentication header:

curl -X POST https://myexample.local/graphql \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic $(echo -n 'service-account-user-1:qV3oGuUE1SfzoewwCFhNjmgJ' | base64)" \
    -d '{"query": "query __schema {__typename}"}'

This could be used for graphql-codegen to download the schema at build time over HTTPS.

Starter Templates / scripts

We will need to provide the following artifacts as part of the example projects:

1. Basic Authentication Template
   • Login/Logout components
   • Protected route wrapper
   • Token management utilities - refresh token
   • Error boundary components
2. Next.js Authentication Template with Next-auth.js
   • Next-Auth.js config that uses Credentials Provider
3. graphql-codegen config for authenticated queries using application passwords
   • Include steps to add a new application password
   • How to inspect and revoke access to application passwords
   • Security best practices