Download the PHP package burnthebook/craft-oauth without Composer

OAuth for Craft CMS

Adds OAuth Functionality to Craft CMS.

Requirements

This plugin requires Craft CMS 5.6.0 or later, and PHP 8.2 or later.

Installation

You can install this plugin from the Plugin Store or with Composer.

From the Plugin Store

Go to the Plugin Store in your project’s Control Panel and search for "OAuth for Craft CMS". Then press "Install".

With Composer

Open your terminal and run the following commands:

Go to the project directory

cd /path/to/my-project.test

Tell Composer to load the plugin

composer require burnthebook/craft-oauth

Tell Craft to install the plugin

php craft plugin/install craft-oauth

Usage

You can configure OAuth providers either:

• Through config/oauth.php, or
• Via the Craft Control Panel under Settings → OAuth.

The plugin currently supports connecting to:

For each provider, you can define:

• Scopes
• PKCE (Proof Key for Code Exchange) support
• Authorization URL, Token URL, and User Info URL (optional for custom providers)

When connecting a provider, the plugin will handle:

• Redirecting to the authorization URL
• Managing OAuth state
• Receiving and verifying the callback
• Fetching user profile information

After successful login, a user’s connected OAuth accounts will appear in the Craft Control Panel under: Admin → Users → {User} → OAuth Accounts as a table showing the linked providers and account IDs.

Adding a Custom Provider

If you need to connect to a non-standard OAuth2 provider, you can define a Custom Provider.

1. Create a Provider class extending League\OAuth2\Client\Provider\AbstractProvider.
2. (Optionally) Create a custom ResourceOwner class implementing ResourceOwnerInterface to handle user data. (This is only really necessary if you provide user data as a response to your access token request, and do not have a userInfo endpoint.)
3. Define your provider in config/oauth.php like so:

[!IMPORTANT] Custom providers must be configured in config/oauth.php (not via the Craft Settings UI). You must supply a valid providerClass which implements the necessary OAuth behavior.

The plugin will automatically use your custom provider when the user attempts to log in via OAuth.

Example: Custom Provider Class

Here’s a basic example of a custom OAuth provider and resource owner you could use.

[!NOTE] The below code is provided as an example only, will need tweaking to your implementation and we cannot assist with custom providers. This plugin uses league/oauth2-client under the hood and any custom provider must conform to their standards.

Provider Class

composer.json:

Provider Class:

Resource Owner Class:

[!NOTE] YourProvider must extend League\OAuth2\Client\Provider\AbstractProvider (or in most cases, GenericProvider). YourResourceOwner must implement ResourceOwnerInterface and provide the toArray() method.