README.md

Headless Login for WPGraphQL

A WordPress plugin that provides headless login and authentication for WPGraphQL, supporting traditional passwords, OAuth2/OpenID Connect, JWT, and more.

• Join the WPGraphQL community on Slack.
• Documentation

---

Description

Headless Login for WPGraphQL is a flexible and extensible plugin that allows headless WordPress sites to login and authenticate users via WPGraphQL using a variety of authentication methods, including traditional WordPress credentials (username/password), OAuth 2.0 / OpenID Connect, JSON Web Tokens (JWT), and more.

This plugin is inspired by and aims to replace WPGraphQL JWT Authentication as more powerful, comprehensive, and flexible authentication solution for Headless WP.

System Requirements

• PHP 7.4-8.2+
• WordPress 6.2+
• WPGraphQL 1.14.0+

Quick Install

1. Install & activate WPGraphQL.
2. Download the latest release .zip file, upload it to your WordPress install, and activate the plugin.
3. Enable and configure the authentication providers you want to use in GraphQL > Settings > Headless Login.

With WP-CLI

wp plugin install https://github.com/AxeWP/wp-graphql-headless-login/releases/latest/download/wp-graphql-headless-login.zip --activate

With Composer

composer require axepress/wp-graphql-headless-login

Updating and Versioning

Until we hit v1.0, we're using a modified version of SemVer, where:

• v0.x: "Major" releases. These releases introduce new features, and may contain breaking changes to either the PHP API or the GraphQL schema
• v0.x.y: "Minor" releases. These releases introduce new features and enhancements and address bugs. They do not contain breaking changes.
• v0.x.y.z: "Patch" releases. These releases are reserved for addressing issue with the previous release only.

Development and Support

Development of Headless Login for WPGraphQL is provided by AxePress Development. Community contributions are welcome and encouraged.

Basic support is provided for free, both in this repo and in WPGraphQL Slack.

Priority support and custom development are available to our Sponsors.

Supported Features

The following functionality is currently supported:

• Authenticate with a WordPress username and password.
• Pass and validate OAuth 2.0 / OpenID Connect provider response from the frontend.
  Supported providers (out of the box):
  • Facebook
  • GitHub
  • Google
  • Instagram
  • LinkedIn
  • OAuth2 - Generic: Any other OAuth 2.0 provider.
  • SAML authentication and more coming soon!
• Use a special Site Token to support WordPress authentication with any externalaly authenticated user identity (e.g. Auth.js).
• Add your own Authentication Provider by extending the ProviderConfig class.
• Authenticate with JWT tokens using a HTTP Authorization header.
• Set CORS headers to allow or restrict access to the GraphQL endpoint.
• Generate short-term authTokens and long term refreshTokens for seamless reauthentication in your headless app.
• Link a user account to an authentication provider's resource owner, to allow users to authenticate with multiple providers.
• Query the enabled loginClient authorization urls, to use in your frontend's login buttons.
• Extensive WordPress actions and filters for customization of the plugin's behavior.
• Log out all sessions for a user by revoking or refreshing their tokens, in GraphQL or the WordPress backend Profile Page.
• Manage WooCommerce Sessions with WPGraphQL for WooCommerce.
• and more!

Usage

Getting Started ( 🎯 You are here! )

• System Requirements
• Installation

Core Concepts

• Terminology
• How it works

Reference

• Admin Settings
• GraphQL Queries
• GraphQL Mutations
• Javascript API
• WordPress Actions
• WordPress Filters

Recipes:

• Server-side Authentication flow with Next.js ( demo ).
• Client-side Authentication flow with NextAuth.js
• Adding custom ProviderConfigs

Testing

1. Copy .env.dist to .env, and update the file to match your local environment.
2. Run composer install to get the dev-dependencies.
3. Run composer install-test-env to create the test environment.
4. Run your test suite with Codeception. E.g. vendor/bin/codecept run wpunit will run all WPUnit tests.