PHPackages                             import-ai/flarum-oauth-passport - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication &amp; Authorization](/categories/authentication)
4. /
5. import-ai/flarum-oauth-passport

ActiveFlarum-extension[Authentication &amp; Authorization](/categories/authentication)

import-ai/flarum-oauth-passport
===============================

Laravel Passport OAuth provider for Flarum - standalone implementation

v0.1.1(1mo ago)055↑931.3%Apache-2.0PHPCI passing

Since Feb 3Pushed 3w agoCompare

[ Source](https://github.com/import-ai/flarum-oauth-passport)[ Packagist](https://packagist.org/packages/import-ai/flarum-oauth-passport)[ RSS](/packages/import-ai-flarum-oauth-passport/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (2)Versions (3)Used By (0)

Flarum OAuth Passport
=====================

[](#flarum-oauth-passport)

[![License](https://camo.githubusercontent.com/a549a7a30bacba7bfceebdc207a8e86c3f2c02995a2527640dca30048fd2b64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d417061636865253230322e302d626c75652e737667)](https://camo.githubusercontent.com/a549a7a30bacba7bfceebdc207a8e86c3f2c02995a2527640dca30048fd2b64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d417061636865253230322e302d626c75652e737667) [![Latest Stable Version](https://camo.githubusercontent.com/fb2d988039b93c8abada68c4f8e32b9b7ce40ef88701844ebbbc6670badc73e7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696d706f72742d61692f666c6172756d2d6f617574682d70617373706f72742e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/fb2d988039b93c8abada68c4f8e32b9b7ce40ef88701844ebbbc6670badc73e7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696d706f72742d61692f666c6172756d2d6f617574682d70617373706f72742e7376673f7374796c653d666c61742d737175617265) [![Total Downloads](https://camo.githubusercontent.com/279541dc0a9ec418414a4a06a8506fd0a44fd51f318cf5f6b88e32e43d8033e8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696d706f72742d61692f666c6172756d2d6f617574682d70617373706f72742e7376673f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/279541dc0a9ec418414a4a06a8506fd0a44fd51f318cf5f6b88e32e43d8033e8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696d706f72742d61692f666c6172756d2d6f617574682d70617373706f72742e7376673f7374796c653d666c61742d737175617265) [![Flarum](https://camo.githubusercontent.com/a307fe6e496dbf8587a051efd9bbc46ea83426afe30e5e81f4830478da096b2a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f466c6172756d2d312e322532422d6f72616e67652e737667)](https://camo.githubusercontent.com/a307fe6e496dbf8587a051efd9bbc46ea83426afe30e5e81f4830478da096b2a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f466c6172756d2d312e322532422d6f72616e67652e737667)

English | [简体中文](./README_zh.md)

A standalone Flarum extension that enables OAuth2 authentication via Laravel Passport or any OAuth2-compatible server. No `fof/oauth` dependency required - full control over the OAuth flow with a custom callback route at `/auth/passport`.

[![screenshot](https://github.com/LucienShui/picx-images-hosting/raw/master/SCR-20260204-sqfk-3.1vz60p2wdq.webp)](https://github.com/LucienShui/picx-images-hosting/raw/master/SCR-20260204-sqfk-3.1vz60p2wdq.webp)

Features
--------

[](#features)

- **Standalone Implementation**: No dependency on `fof/oauth` - complete control over the OAuth flow
- **Universal OAuth2 Support**: Works with Laravel Passport, Keycloak, Auth0, or any standard OAuth2 server
- **Flexible User Data Mapping**: Configure field names for ID, display name, and email (supports dot notation for nested JSON)
- **Customizable Login Button**: Set custom title, icon (FontAwesome), background color, and text color
- **Account Linking**: Automatic account linking via OAuth provider ID
- **Profile Synchronization**: Optionally update display name and email on subsequent logins
- **Passwordless Option**: Hide default username/password fields for pure OAuth authentication
- **Popup Configuration**: Fullscreen popup or custom width/height for OAuth window
- **In-App Browser Support**: Built-in fallback for WeChat and other in-app browsers
- **Migration Support**: Seamless migration from `blt950/oauth-generic` and `fof/passport`

Installation
------------

[](#installation)

```
composer require import-ai/flarum-oauth-passport
```

Upgrade
-------

[](#upgrade)

```
composer update import-ai/flarum-oauth-passport
php flarum migrate
php flarum cache:clear
```

Configuration
-------------

[](#configuration)

1. Navigate to **Administration** &gt; **Extensions** &gt; **OAuth Passport**
2. Copy the **Redirect URL** to your OAuth server's allowed redirect URLs
3. Configure OAuth endpoints and credentials (see below)

### OAuth Server Settings

[](#oauth-server-settings)

SettingDescription**Client ID**Your OAuth application client ID**Client Secret**Your OAuth application client secret**Scopes**Comma-separated OAuth scopes (default: `read`)**Authorization Endpoint**OAuth authorize URL (e.g., `https://auth.example.com/oauth/authorize`)**Token Endpoint**OAuth token URL (e.g., `https://auth.example.com/oauth/token`)**User Information Endpoint**User info URL (e.g., `https://auth.example.com/api/user`)### User Data Mapping

[](#user-data-mapping)

Configure the field names from your OAuth server's user info response:

SettingDefaultDot Notation Support**User ID Field**`id`Yes (e.g., `data.user.id`)**Display Name Field**`name`Yes (e.g., `data.name`)**Email Address Field**`email`Yes (e.g., `data.email`)### User Registration Options

[](#user-registration-options)

SettingDescription**Force User ID as Username**Use OAuth user ID as Flarum username instead of allowing user to choose**Force Display Name**Use OAuth display name instead of allowing user to choose**Force Email Address**Use OAuth email and mark as verified**Update Display Name on Login**Sync display name from OAuth server on each login**Update Email on Login**Sync email from OAuth server on each login### Login Button Customization

[](#login-button-customization)

SettingDefaultDescription**Button Title**"Login with Passport"Text displayed on the login button**Button Icon**`fas fa-passport`FontAwesome icon class**Button Background Color**`#3B82F6`Hex color code**Button Text Color**`#ffffff`Hex color code### Popup Settings

[](#popup-settings)

SettingDefaultDescription**Fullscreen Popup**`false`Use fullscreen popup for OAuth (ignores width/height)**Popup Width**`580`OAuth popup window width in pixels**Popup Height**`400`OAuth popup window height in pixels### Advanced Options

[](#advanced-options)

- **Replace Login/Signup Buttons**: Hide default username/password fields and show only the OAuth button

OAuth Flow
----------

[](#oauth-flow)

1. User clicks "Login with Passport" button
2. Extension redirects to OAuth server with state parameter (CSRF protection)
3. User authenticates on OAuth server
4. OAuth server redirects back to `/auth/passport?code=xxx&state=xxx`
5. Extension validates state and exchanges code for access token
6. Extension fetches user info and creates/logs in Flarum user
7. Optional: Dispatches `OAuthLoginSuccessful` event for custom handling

Migration from Other Extensions
-------------------------------

[](#migration-from-other-extensions)

This extension includes built-in migrations for:

- `blt950/oauth-generic`
- `fof/passport`

Simply install this extension and existing OAuth-linked accounts will continue to work.

Events
------

[](#events)

The extension dispatches `FoF\Extend\Events\OAuthLoginSuccessful` after a successful OAuth login, allowing other extensions to perform custom actions:

```
use FoF\Extend\Events\OAuthLoginSuccessful;

$events->listen(OAuthLoginSuccessful::class, function (OAuthLoginSuccessful $event) {
    $token = $event->token;        // AccessToken from League\OAuth2\Client
    $user = $event->user;          // ResourceOwnerInterface
    $provider = $event->provider;  // 'passport'
    $providerId = $event->providerId;
    $actor = $event->actor;        // Current user (null if guest)
});
```

In-App Browser Support
----------------------

[](#in-app-browser-support)

For environments like WeChat where popups are blocked, the extension includes middleware that detects in-app browsers and provides a fallback mechanism for completing OAuth authentication.

Requirements
------------

[](#requirements)

- Flarum 1.2.0 or higher
- PHP 7.4 or higher
- An OAuth2-compatible authentication server

Links
-----

[](#links)

- [GitHub](https://github.com/import-ai/flarum-oauth-passport)
- [Packagist](https://packagist.org/packages/import-ai/flarum-oauth-passport)

###  Health Score

35

—

LowBetter than 81% of packages

Maintenance93

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity25

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

48d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1c6fa04ffefda5bef57e9401b6e723e2a56db702f5ea28b92e039febd0ea050f?d=identicon)[import-ai](/maintainers/import-ai)

---

Top Contributors

[![LucienShui](https://avatars.githubusercontent.com/u/30151093?v=4)](https://github.com/LucienShui "LucienShui (23 commits)")

---

Tags

laraveloauthpassportflarum

### Embed Badge

![Health badge](/badges/import-ai-flarum-oauth-passport/health.svg)

```
[![Health](https://phpackages.com/badges/import-ai-flarum-oauth-passport/health.svg)](https://phpackages.com/packages/import-ai-flarum-oauth-passport)
```

###  Alternatives

[fof/passport

The OAuth2 (and Laravel passport) compatible oauth extension

3013.0k](/packages/fof-passport)[mikemclin/passport-custom-request-grant

Custom Request Grant for Laravel Passport

343.6k](/packages/mikemclin-passport-custom-request-grant)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
