Skip to main content

OAuth Authentication

The OAuth plugin enables OAuth2-based authentication in AdminForth, allowing users to sign in using their Google, GitHub, Facebook or other OAuth2 provider accounts.

Installation​

To install the plugin:

npm install @adminforth/oauth --save
npm install @adminforth/google-oauth-adapter --save  # for Google OAuth

Configuration​

This section provides a step-by-step guide to configure the OAuth plugin for Google authentication. See OAuth2 Providers for other providers.

1. OAuth Provider Setup (Google Example)​

You need to get the client ID and client secret from your OAuth2 provider.

  1. Go to the Google Cloud Console and log in.
  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:
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:

./resources/adminuser.ts
import OAuthPlugin from '@adminforth/oauth';
import AdminForthAdapterGoogleOauth2 from '@adminforth/google-oauth-adapter';

declare global {
  namespace NodeJS {
    interface ProcessEnv {
      GOOGLE_OAUTH_CLIENT_ID: string;
      GOOGLE_OAUTH_CLIENT_SECRET: string;
    }
  }
}

// ... 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:
./schema.prisma
model adminuser {
  // ... existing fields ...
  email_confirmed Boolean @default(false)
}
  1. Run the migration:
npx prisma migrate dev --name add-email-confirmed-to-adminuser
  1. Configure the plugin with emailConfirmedField:
./resources/adminuser.ts
new OAuthPlugin({
  // ... 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:

./resources/adminuser.ts
new OAuthPlugin({
  // ... 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.

./resources/adminuser.ts
new OAuthPlugin({
  // ... adapters configuration ...
  iconOnly: true, // Show only provider icons without text
  pill: true, // Use pill-shaped buttons instead of rectangular
}),

OAuth2 Providers​

Facebook Adapter​

Install Adapter:

npm install @adminforth/facebook-oauth-adapter --save
  1. Go to the Facebook Developers
  2. Go to My apps
  3. Create a new project or select an existing one (choose Authenticate and request data from users with Facebook Login)
  4. Go to Use Cases - Authenticate and request data from users with Facebook Login -> Customize and add email permissions
  5. Go to App Settings -> Basic
  6. Get App ID and App secret
  7. Add the credentials to your .env file:
FACEBOOK_OAUTH_CLIENT_ID=your_facebook_client_id
FACEBOOK_OAUTH_CLIENT_SECRET=your_facebook_client_secret

Add the adapter to your plugin configuration:

./resources/adminuser.ts
import AdminForthAdapterFacebookOauth2 from '@adminforth/facebook-oauth-adapter';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapterFacebookOauth2({
        clientID: process.env.FACEBOOK_OAUTH_CLIENT_ID,
        clientSecret: process.env.FACEBOOK_OAUTH_CLIENT_SECRET,
      }),
    ],
  }),
]

GitHub Adapter​

Install Adapter:

npm install @adminforth/github-oauth-adapter --save
  1. Go to the GitHub Apps
  2. Create a new app or select an existing one
  3. Go to the Permisiions & events -> Account permissions -> Email addresses and change to Read-only
  4. Go to the General and click to Generate a new client secret button and copy secret
  5. Add the credentials to your .env file:
GITHUB_OAUTH_CLIENT_ID=your_facebook_client_id
GITHUB_OAUTH_CLIENT_SECRET=your_facebook_client_secret

Add the adapter to your plugin configuration:

./resources/adminuser.ts
import AdminForthAdapterGithubOauth2 from '@adminforth/github-oauth-adapter';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapterGithubOauth2({
        clientID: process.env.GITHUB_OAUTH_CLIENT_ID,
        clientSecret: process.env.GITHUB_OAUTH_CLIENT_SECRET,
      }),
    ],
  }),
]

Kaycloack Adapter​

Install Adapter:

npm install @adminforth/keycloak-oauth-adapter --save

If you need a basic Keycloak setup which tested with AdminForth, you can follow this minimal KeyClock setup example.

  1. Update your .env file with the following Keycloak configuration:
KEYCLOAK_CLIENT_ID=adminforth-client
KEYCLOAK_CLIENT_SECRET=1234567890
KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=AdminforthRealm
  1. Create a new user from the back office with the same email as the test user (by default: testuser@example.com)

Add the adapter to your plugin configuration:

./resources/adminuser.ts
import AdminForthAdapterKeycloakOauth2 from '@adminforth/keycloak-oauth-adapter';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapterKeycloakOauth2({
          clientID: process.env.KEYCLOAK_CLIENT_ID,
          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
          keycloakUrl: process.env.KEYCLOAK_URL,
          realm: process.env.KEYCLOAK_REALM,
          useOpenID: true,
      }),
    ],
  }),
]

If you want to create a new user:

  1. Access Keycloak Admin Panel Open a browser and go to: http://localhost:8080 Log in with the default Keycloak admin credentials: Username: admin Password: admin

  2. Navigate to the "Users" Section Click on "Users" in the left-hand menu. Click "Add user" in the top-right corner.

  3. Enter User Information Username: username Email: username@example.com Email Verified: ✅ (Check this box) Enabled: ✅ (Check this box) Click "Save"

  4. Set a Password for the User Go to the "Credentials" tab. Enter a password (e.g., testpassword). Uncheck "Temporary" (so the user doesn't have to reset the password). Click "Set Password".

Microsoft Adapter​

Install Adapter:

npm install @adminforth/microsoft-oauth-adapter --save
  1. In the Microsoft Azure Portal, search for and click App registrations, then New registration.
  2. Give your application a name. This name will be visible to your users.
  3. Set the audience for the app to Accounts in my organizational directory and personal Microsoft accounts. This allows your user to log in using any Microsoft account.
  4. Set the Redirect URI platform to Web and enter your project's redirect URI.
  5. Go to your app and search API permissions, click Add a permission, select Microsoft Graph, select Delegated permissions, enable permissions: offline_access, openid, profile, User.Read, click Add permissions.
  6. Serch Certificates & secrets, click New client secret and create client secret.
  7. Get Application ID and Client Secret.
  8. Add the credentials to your .env file:
MICROSOFT_OAUTH_CLIENT_ID=your_application_id
MICROSOFT_OAUTH_CLIENT_SECRET=your_microsoft_client_secret

Add the adapter to your plugin configuration:

./resources/adminuser.ts
import AdminForthAdapterMicrosoftOauth2 from '@adminforth/microsoft-oauth-adapter';

// ... existing resource configuration ...
plugins: [
  new OAuthPlugin({
    adapters: [
      ...
      new AdminForthAdapterMicrosoftOauth2({
        clientID: process.env.MICROSOFT_CLIENT_ID,
        clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
        useOpenID: true,
      }),
    ],
  }),
]

Need custom provider?​

Just fork any existing adapter e.g. Google and adjust it to your needs.

This is really easy, you have to change less then 10 lines of code in this file

Then just publish it to npm and install it in your project.

Links to adapters: Google GitHub Facebook Keycloak