From 1256fe07ce0604084e79dada6eed7012ca057c50 Mon Sep 17 00:00:00 2001 From: Ivan Borshchov Date: Thu, 6 Feb 2025 14:46:28 +0200 Subject: [PATCH 1/6] Update README.md --- README.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 72b090ce..f0663921 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ Why AdminForth: * Define express APIs and call them from your components and pages * Use various modern back-office-must-have plugins like audit log, files/image upload, TOTP 2FA, I18N, Copilot-style AI writing and image generation +Your ⭐ is very important to us! + ## Project initialisation ``` @@ -56,19 +58,25 @@ npx adminforth create-app # For developers -``` +The most convenient way to add new features or fixes is using `dev-demo`. It imports the source code of the repository and plugins so you can edit them and see changes on the fly. + +Fork repo, pull it and do next: + + +```sh cd adminforth npm ci npm run build - # this will install all official plugins and link adminforth package, if plugin installed it will git pull and npm ci npm run install-plugins # same for official adapters npm run install-adapters +``` -# this is dev demo for development +To run dev demo: +```sh cd dev-demo cp .env.sample .env npm ci @@ -76,7 +84,9 @@ npm run migrate npm start ``` -Add some columns to a database. Open .prisma file, modify it, and run: +## Adding columns to a database in dev-demo + +Open `.prisma` file, modify it, and run: ``` npm run namemigration -- --name desctiption_of_changes From 6641e18bc8a29d0971edde558070cecb4529d7ba Mon Sep 17 00:00:00 2001 From: Ivan Borshchov Date: Tue, 11 Feb 2025 10:02:00 +0200 Subject: [PATCH 2/6] Update README.md --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index f0663921..231f8acb 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,6 @@ Why AdminForth: * Define express APIs and call them from your components and pages * Use various modern back-office-must-have plugins like audit log, files/image upload, TOTP 2FA, I18N, Copilot-style AI writing and image generation -Your ⭐ is very important to us! ## Project initialisation From 597d7ce171cd1d4622cf0bcb2b44f3f82d23b09f Mon Sep 17 00:00:00 2001 From: Vitalii Kulyk Date: Thu, 20 Feb 2025 17:17:23 +0200 Subject: [PATCH 3/6] docs: add OAuth authentication documentation for AdminForth --- .../docs/tutorial/05-Plugins/11-oauth.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 adminforth/documentation/docs/tutorial/05-Plugins/11-oauth.md diff --git a/adminforth/documentation/docs/tutorial/05-Plugins/11-oauth.md b/adminforth/documentation/docs/tutorial/05-Plugins/11-oauth.md new file mode 100644 index 00000000..519c3dd7 --- /dev/null +++ b/adminforth/documentation/docs/tutorial/05-Plugins/11-oauth.md @@ -0,0 +1,122 @@ +# OAuth Authentication + +The OAuth plugin enables OAuth2-based authentication in AdminForth, allowing users to sign in using their Google, GitHub, or other OAuth2 provider accounts. + +## Installation + +To install the plugin: + +```bash +npm install @adminforth/oauth --save +npm install @adminforth/google-oauth-adapter --save # for Google OAuth +``` + +## Configuration + +### 1. OAuth Provider Setup + +You need to get the client ID and client secret from your OAuth2 provider. + +For Google: +1. Go to the [Google Cloud Console](https://console.cloud.google.com) +2. Create a new project or select an existing one +3. Go to `APIs & Services` → `Credentials` +4. Create credentials for OAuth 2.0 client IDs +5. Select application type: "Web application" +6. Add your application's name and redirect URI +7. In "Authorized redirect URIs", add next URI: `https://your-domain/oauth/callback`, `http://localhost:3500/oauth/callback`. Please remember to include BASE_URL in the URI if you are using it in project e.g. `https://your-domain/base/oauth/callback` +8. Add the credentials to your `.env` file: + +```bash +GOOGLE_OAUTH_CLIENT_ID=your_google_client_id +GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret +``` + +### 2. Plugin Configuration + +Configure the plugin in your user resource file: + +```typescript title="./resources/adminuser.ts" +import OAuthPlugin from '@adminforth/oauth'; +import AdminForthAdapterGoogleOauth2 from '@adminforth/google-oauth-adapter'; + +// ... existing resource configuration ... + +plugins: [ + new OAuthPlugin({ + adapters: [ + new AdminForthAdapterGoogleOauth2({ + clientID: process.env.GOOGLE_OAUTH_CLIENT_ID, + clientSecret: process.env.GOOGLE_OAUTH_CLIENT_SECRET, + }), + ], + emailField: 'email', // Required: field that stores the user's email + }), +] +``` + +### 3. Email Confirmation + +The plugin supports automatic email confirmation for OAuth users. To enable this: + +1. Add the `email_confirmed` field to your database schema: + +```prisma title='./schema.prisma' +model adminuser { + // ... existing fields ... + email_confirmed Boolean @default(false) +} +``` + +2. Run the migration: + +```bash +npx prisma migrate dev --name add-email-confirmed-to-adminuser +``` + +3. Configure the plugin with `emailConfirmedField`: + +```typescript title="./resources/adminuser.ts" +new OAuth2Plugin({ + // ... adapters configuration ... + emailField: 'email', + emailConfirmedField: 'email_confirmed' // Enable email confirmation tracking +}), +``` + +When using OAuth: +- New users will have their email automatically confirmed (`email_confirmed = true`) +- Existing users will have their email marked as confirmed upon successful OAuth login +- The `email_confirmed` field must be a boolean type + +### 4. Open Signup + +By default, users must exist in the system before they can log in with OAuth. You can enable automatic user creation for new OAuth users with the `openSignup` option: + +```typescript title="./resources/adminuser.ts" +new OAuth2Plugin({ + // ... adapters configuration ... + openSignup: { + enabled: true, + defaultFieldValues: { // Set default values for new users + role: 'user', + }, + }, +}), +``` + +### 5. UI Customization + +You can customize the UI of the OAuth login buttons by using the `iconOnly` and `pill` options. + +```typescript title="./resources/adminuser.ts" +new OAuth2Plugin({ + // ... adapters configuration ... + iconOnly: true, // Show only provider icons without text + pill: true, // Use pill-shaped buttons instead of rectangular +}), +``` + + + + From c0dda2cecf0a96d066ebd25403a915b99eb385fa Mon Sep 17 00:00:00 2001 From: Vitalii Kulyk Date: Thu, 20 Feb 2025 17:17:43 +0200 Subject: [PATCH 4/6] fix: add OAuth2Adapter interface for authentication --- adminforth/types/Adapters.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/adminforth/types/Adapters.ts b/adminforth/types/Adapters.ts index 62a18bf2..bbdc671a 100644 --- a/adminforth/types/Adapters.ts +++ b/adminforth/types/Adapters.ts @@ -24,3 +24,9 @@ export interface CompletionAdapter { error?: string; }>; } + +export interface OAuth2Adapter { + getAuthUrl(): string; + getTokenFromCode(code: string, redirect_uri: string): Promise<{ email: string }>; + getIcon(): string; +} From ffd5b752d13910598787cb5e2dd9458d2213cfe1 Mon Sep 17 00:00:00 2001 From: Maksym Pipkun Date: Fri, 21 Feb 2025 15:41:51 +0200 Subject: [PATCH 5/6] fix: correct import statements for OAuth plugins in users resource --- dev-demo/resources/users.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/dev-demo/resources/users.ts b/dev-demo/resources/users.ts index 07113d9d..79c03576 100644 --- a/dev-demo/resources/users.ts +++ b/dev-demo/resources/users.ts @@ -11,9 +11,9 @@ import TwoFactorsAuthPlugin from "../../plugins/adminforth-two-factors-auth"; import EmailResetPasswordPlugin from "../../plugins/adminforth-email-password-reset/index.js"; import { v1 as uuid } from "uuid"; import EmailAdapterAwsSes from "../../adapters/adminforth-email-adapter-aws-ses/index.js"; -import { OAuthPlugin } from "../../plugins/adminforth-oauth"; -import { AdminForthAdapterGoogleOauth2 } from "../../adapters/adminforth-google-oauth-adapter"; -import { AdminForthAdapterGithubOauth2 } from "../../adapters/adminforth-github-oauth-adapter"; +import OAuthPlugin from "../../plugins/adminforth-oauth"; +import AdminForthAdapterGoogleOauth2 from "../../adapters/adminforth-google-oauth-adapter"; +import AdminForthAdapterGithubOauth2from "../../adapters/adminforth-github-oauth-adapter"; export default { dataSource: "maindb", table: "users", From 1f8cf2f37d7f11ef50a80529dfe2883a1d8403b2 Mon Sep 17 00:00:00 2001 From: Maksym Pipkun Date: Fri, 21 Feb 2025 15:45:25 +0200 Subject: [PATCH 6/6] fix: correct spacing in import statement for GitHub OAuth adapter --- dev-demo/resources/users.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-demo/resources/users.ts b/dev-demo/resources/users.ts index 79c03576..df100d71 100644 --- a/dev-demo/resources/users.ts +++ b/dev-demo/resources/users.ts @@ -13,7 +13,7 @@ import { v1 as uuid } from "uuid"; import EmailAdapterAwsSes from "../../adapters/adminforth-email-adapter-aws-ses/index.js"; import OAuthPlugin from "../../plugins/adminforth-oauth"; import AdminForthAdapterGoogleOauth2 from "../../adapters/adminforth-google-oauth-adapter"; -import AdminForthAdapterGithubOauth2from "../../adapters/adminforth-github-oauth-adapter"; +import AdminForthAdapterGithubOauth2 from "../../adapters/adminforth-github-oauth-adapter"; export default { dataSource: "maindb", table: "users",