Skip to content

Commit 85ef8d0

Browse files
sourabpramaniksourabpramanik
authored
Merge pull request #157 from authsmith/feat/robolox-oauth
Feat/robolox oauth
2 parents aebc519 + d19bda2 commit 85ef8d0

58 files changed

Lines changed: 13610 additions & 3596 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎bun.lock‎

Lines changed: 178 additions & 131 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/README.md‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# payload-auth-plugin
2+
3+
> Authentication plugin for [Payload CMS](https://payloadcms.com) — OAuth 2.0, OIDC, Password, and Passkey support out of the box.
4+
5+
**Version:** 0.7.6 · **License:** MIT · **Payload:** >= 3.0.0
6+
7+
[![npm](https://img.shields.io/npm/v/payload-auth-plugin)](https://www.npmjs.com/package/payload-auth-plugin)
8+
[![license](https://img.shields.io/npm/l/payload-auth-plugin)](../LICENSE)
9+
10+
---
11+
12+
## Table of Contents
13+
14+
- [Overview](#overview)
15+
- [How It Works](#how-it-works)
16+
- [Architecture](#architecture)
17+
- [Collections](#collections)
18+
- [Endpoints](#endpoints)
19+
- [Session](#session)
20+
- [Supported Providers](#supported-providers)
21+
- [Package Exports](#package-exports)
22+
- [Documentation](#documentation)
23+
24+
---
25+
26+
## Overview
27+
28+
`payload-auth-plugin` extends Payload CMS's built-in authentication system to support multiple authentication strategies — OAuth 2.0, OIDC, Password, and Passkey — while staying true to Payload's own conventions and standards.
29+
30+
The plugin is designed for minimal configuration. Adding a new social login provider, for example, requires only a few lines of code in `payload.config.ts`. The same plugin instance handles **both admin panel authentication and any number of frontend applications**, each isolated by a unique `name`.
31+
32+
> **Requires Payload CMS >= 3.0**
33+
34+
---
35+
36+
## How It Works
37+
38+
```
39+
User → Provider (Google, GitHub, etc.)
40+
↓
41+
Payload Endpoint (/api/{name}/oauth/callback/{provider})
42+
↓
43+
Plugin Core (validate tokens, upsert account, create session)
44+
↓
45+
Payload Session Cookie (cookie-based, uses Payload's own session)
46+
↓
47+
Redirect → successRedirectPath / errorRedirectPath
48+
```
49+
50+
1. The plugin registers catch-all API endpoints in Payload for each enabled authentication strategy.
51+
2. Incoming requests are routed to the appropriate handler (OAuth, Password, Passkey, Session).
52+
3. After successful authentication the plugin upserts an **Account** document (linked to a **User**), then creates a Payload session cookie.
53+
4. The `AuthClient` class (client-side) provides typed helpers for triggering these flows from React/Next.js components.
54+
55+
---
56+
57+
## Architecture
58+
59+
### Collections
60+
61+
The plugin relies on two Payload collections:
62+
63+
| Collection | Purpose |
64+
|------------|---------|
65+
| **Users** | Stores user records. Managed via [`withUsersCollection`](./collections.md#withUserscollection). |
66+
| **Accounts** | Stores per-provider account data linked to a User. Managed via [`withAccountCollection`](./collections.md#withAccountcollection). |
67+
68+
A single user can own **multiple** accounts (one per provider). Each account belongs to **one** user.
69+
70+
Source: [`src/collection/index.ts`](../src/collection/index.ts)
71+
72+
### Endpoints
73+
74+
For every enabled authentication strategy, the plugin registers Payload API endpoints under the `/api/{name}/` namespace.
75+
76+
| Strategy | Path pattern |
77+
|----------|-------------|
78+
| OAuth (authorize) | `GET /api/{name}/oauth/authorize/:provider` |
79+
| OAuth (callback) | `GET /api/{name}/oauth/callback/:provider` |
80+
| Password sign-in | `POST /api/{name}/auth/signin` |
81+
| Password sign-up | `POST /api/{name}/auth/signup` |
82+
| Forgot password | `POST /api/{name}/auth/forgot-password?stage=init` |
83+
| Recover password | `POST /api/{name}/auth/forgot-password?stage=verify` |
84+
| Reset password | `POST /api/{name}/auth/reset-password` |
85+
| Passkey | `POST /api/{name}/passkey/:resource` |
86+
| Get session | `GET /api/{name}/session/user` |
87+
| Sign out | `GET /api/{name}/session/signout` |
88+
| Refresh session | `GET /api/{name}/session/refresh` |
89+
90+
Source: [`src/core/endpoints.ts`](../src/core/endpoints.ts)
91+
92+
### Session
93+
94+
The plugin uses **Payload's native cookie-based session** mechanism. No external session store is needed. Sessions are issued as signed cookies after successful authentication and are readable server-side (via request headers) or client-side (via the `AuthClient` helper).
95+
96+
---
97+
98+
## Supported Providers
99+
100+
### OAuth / OIDC
101+
102+
| Provider | Type | Import |
103+
|----------|------|--------|
104+
| [Google](./providers/google.md) | OIDC | `GoogleAuthProvider` |
105+
| [GitHub](./providers/github.md) | OAuth 2.0 | `GitHubAuthProvider` |
106+
| [GitLab](./providers/gitlab.md) | OIDC | `GitLabAuthProvider` |
107+
| [Apple (OIDC)](./providers/apple.md) | OIDC | `AppleOIDCAuthProvider` |
108+
| [Apple (OAuth2)](./providers/apple.md) | OAuth 2.0 | `AppleOAuth2Provider` |
109+
| [Auth0](./providers/auth0.md) | OAuth 2.0 | `Auth0AuthProvider` |
110+
| [AWS Cognito](./providers/cognito.md) | OIDC | `CognitoAuthProvider` |
111+
| [Microsoft Entra](./providers/microsoft-entra.md) | OIDC | `MicrosoftEntraAuthProvider` |
112+
| [Atlassian](./providers/atlassian.md) | OAuth 2.0 | `AtlassianAuthProvider` |
113+
| [Discord](./providers/discord.md) | OAuth 2.0 | `DiscordAuthProvider` |
114+
| [Facebook](./providers/facebook.md) | OAuth 2.0 | `FacebookAuthProvider` |
115+
| [Slack](./providers/slack.md) | OIDC | `SlackAuthProvider` |
116+
| [Keycloak](./providers/keycloak.md) | OIDC | `KeyCloakAuthProvider` |
117+
| [Okta](./providers/okta.md) | OIDC | `OktaAuthProvider` |
118+
| [Twitch](./providers/twitch.md) | OAuth 2.0 | `TwitchAuthProvider` |
119+
| [JumpCloud](./providers/jumpcloud.md) | OAuth 2.0 | `JumpCloudAuthProvider` |
120+
121+
### Credential-based
122+
123+
| Provider | Import |
124+
|----------|--------|
125+
| [Password](./providers/password.md) | `PasswordProvider` |
126+
| [Passkey ⚠️ experimental](./providers/passkey.md) | `PasskeyAuthProvider` |
127+
128+
All providers are imported from `payload-auth-plugin/providers`.
129+
130+
---
131+
132+
## Package Exports
133+
134+
```
135+
payload-auth-plugin → authPlugin (the Payload plugin function)
136+
payload-auth-plugin/providers → all provider factory functions
137+
payload-auth-plugin/client → AuthClient class
138+
payload-auth-plugin/collection → withUsersCollection, withAccountCollection
139+
payload-auth-plugin/collection/hooks → deleteLinkedAccounts hook
140+
```
141+
142+
Source: [`package.json` exports field](../package.json)
143+
144+
---
145+
146+
## Documentation
147+
148+
| Guide | Description |
149+
|-------|-------------|
150+
| [Installation](./installation.md) | How to install the package |
151+
| [Setup](./setup.md) | End-to-end setup walkthrough |
152+
| [Configuration](./configuration.md) | All `authPlugin()` options explained |
153+
| [Collections](./collections.md) | `withUsersCollection` and `withAccountCollection` API |
154+
| [Auth Client](./auth-client.md) | `AuthClient` class API reference |
155+
| [Session Management](./session-management.md) | Server-side and client-side session patterns |
156+
| [Providers](./providers/README.md) | All supported providers |
157+
| [Contributing](./contributing.md) | How to contribute to the plugin |
158+
159+
---
160+
161+
## Quick Start
162+
163+
```ts
164+
// payload.config.ts
165+
import { buildConfig } from 'payload'
166+
import { authPlugin } from 'payload-auth-plugin'
167+
import { GoogleAuthProvider, PasswordProvider } from 'payload-auth-plugin/providers'
168+
import { Users } from './collections/Users'
169+
import { Accounts } from './collections/Accounts'
170+
171+
export default buildConfig({
172+
serverURL: process.env.NEXT_PUBLIC_SERVER_URL,
173+
collections: [Users, Accounts],
174+
plugins: [
175+
authPlugin({
176+
name: 'admin',
177+
useAdmin: true,
178+
usersCollectionSlug: Users.slug,
179+
accountsCollectionSlug: Accounts.slug,
180+
successRedirectPath: '/admin',
181+
errorRedirectPath: '/admin/login',
182+
providers: [
183+
GoogleAuthProvider({
184+
client_id: process.env.GOOGLE_CLIENT_ID!,
185+
client_secret: process.env.GOOGLE_CLIENT_SECRET!,
186+
}),
187+
PasswordProvider({
188+
emailTemplates: { forgotPassword: myEmailTemplate },
189+
}),
190+
],
191+
}),
192+
],
193+
})
194+
```
195+
196+
See the full [Setup Guide](./setup.md) and the [example project](https://github.com/authsmith/payload-auth-plugin/tree/main/examples/with-website).
197+
198+
---
199+
200+
## Links
201+
202+
- [GitHub Repository](https://github.com/authsmith/payload-auth-plugin)
203+
- [npm Package](https://www.npmjs.com/package/payload-auth-plugin)
204+
- [Changelog](../CHANGELOG.md)
205+
- [License (MIT)](../LICENSE)
206+
- [Authsmith](https://authsmith.com)

0 commit comments

Comments
 (0)