GITBOOK-110: Firebase Auth

Author: Rafał Dzięgielewski

.gitbook/assets/Screenshot 2023-11-14 at 12.54.56.png

@@ -15,7 +15,7 @@ AdminJS also generates it's own REST API which you can use outside of the admin
 ![AdminJS Demo](.gitbook/assets/anim.gif)
 
 {% hint style="info" %}
-Visit [our demo](https://adminjs-demo.herokuapp.com/admin/login) for a live preview.\
+Visit our [demo](https://demo.adminjs.co) for a live preview.\
 \
  `Email: [email protected]`\
  `Password: password`

.gitbook/assets/Screenshot 2023-11-22 at 13.25.33.png

@@ -2,7 +2,8 @@
 
 * [AdminJS](README.md)
 * [Contribute](https://github.com/orgs/SoftwareBrothers/projects/5)
-* [Stats Dashboard](https://stats.adminjs.co)
+* [Demo](https://demo.adminjs.co)
+* [Addons Marketplace](https://cloud.adminjs.co)
 
 ## Installation
 
@@ -51,6 +52,12 @@
   * [Delete](basics/api/delete.md)
   * [Bulk Delete](basics/api/bulk-delete.md)
 * [Themes](basics/themes.md)
+* [Authentication](basics/authentication/README.md)
+  * [FirebaseAuthProvider](basics/authentication/firebaseauthprovider.md)
+
+***
+
+* [How to write an addon?](how-to-write-an-addon.md)
 
 ## UI Customization
 

README.md

@@ -0,0 +1,118 @@
+# Authentication
+
+Version 7.4 of `adminjs` package introduces authentication providers which both simplify and extend authentication possibilities in your application.
+
+Every authentication provider extends `BaseAuthProvider` class (exported by `adminjs` package). `adminjs` also exports `DefaultAuthProvider` which functions exactly the same as the current `authenticate` method.
+
+### DefaultAuthProvider
+
+As of version >=7.4.0 of `adminjs`, `DefaultAuthProvider` is an alternative to `authenticate` method. In the next major release, `authenticate` method will be removed in favour of auth providers.
+
+<pre class="language-typescript"><code class="lang-typescript"><strong>import { DefaultAuthProvider } from 'adminjs';
+</strong><strong>
+</strong><strong>import componentLoader from '&#x3C;path to your component loader>';
+</strong><strong>
+</strong><strong>// Placeholder authentication function, add your logic for authenticating users
+</strong>const authenticate = ({ email, password }, ctx) => {
+  return { email };
+}
+
+const authProvider = new DefaultAuthProvider({
+  componentLoader,
+  authenticate,
+});
+
+// ...
+
+// Express example, in other plugins the change is exactly the same
+// "provider" should be configured at the same level as "authenticate" previously
+  const router = buildAuthenticatedRouter(
+    admin,
+    {
+      // "authenticate" was here
+      cookiePassword: 'test',
+      provider: authProvider,
+    },
+    null,
+    {
+      secret: 'test',
+      resave: false,
+      saveUninitialized: true,
+    }
+  );
+</code></pre>
+
+By migrating to class syntax, you should be able to modify any existing auth provider without making additional changes to your framework's plugin.
+
+### BaseAuthProvider
+
+```typescript
+export interface LoginHandlerOptions {
+  data: Record<string, any>;
+  query?: Record<string, any>;
+  params?: Record<string, any>;
+  headers: Record<string, any>;
+}
+
+export interface RefreshTokenHandlerOptions extends LoginHandlerOptions {}
+
+export class BaseAuthProvider {
+  public getUiProps(): Record<string, any> {
+    return {}
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public async handleLogin(opts: LoginHandlerOptions, context?: any) {
+    throw new NotImplementedError('BaseAuthProvider#handleLogin')
+  }
+
+  public async handleLogout(context?: any): Promise<any> {
+    return Promise.resolve()
+  }
+
+  public async handleRefreshToken(opts: RefreshTokenHandlerOptions, context?: any): Promise<any> {
+    return Promise.resolve({})
+  }
+}
+```
+
+You can use `getUiProps` method to define configuration that will be sent to the frontend.
+
+`handleLogin` method is neccessary to sign in your user and should return a user object or `null`, for example:
+
+```typescript
+  override async handleLogin(opts: LoginHandlerOptions, context) {
+    const { data = {} } = opts
+    const { email, password } = data
+
+    return this.authenticate({ email, password }, context)
+  }
+```
+
+`context` of `handleLogin` will always be an object containing Request/Response objects specific to your framework of choice.
+
+`handleLogout` and `handleRefreshToken` are optional. `handleLogout` will be called before your user's session is destroyed in case you have to perform additional actions to log out the user. `handleRefreshToken` can be used to refresh your user's session if it's matched with an external authentication service. `handleRefreshToken` should return an updated user object (i. e. with a new access token). It is not used by default, but you can override `AuthenticationBackgroundComponent` component to periodically refresh your session.
+
+```typescript
+import { useCurrentAdmin } from 'adminjs';
+
+const api = new ApiClient();
+
+// ...
+
+const AuthenticationBackgroundComponentOverride = () => {
+  const [currentAdmin, setCurrentAdmin] = useCurrentAdmin();
+  // ...
+  // A part of your code responsible for refreshing user's session
+  const requestBody = {};
+  const response = await api.refreshToken(requestBody);
+
+  const { data } = response;
+
+  setCurrentAdmin(data);
+  // ...
+  return null;
+}
+
+export default AuthenticationBackgroundComponentOverride;
+```

SUMMARY.md

@@ -0,0 +1,228 @@
+---
+description: '@adminjs/firebase-auth'
+---
+
+# FirebaseAuthProvider
+
+`@adminjs/firebase-auth` is an authentication provider which allows you to sign in using Firebase Authentication.
+
+
+
+<figure><img src="../../.gitbook/assets/Screenshot 2023-11-22 at 13.25.33.png" alt=""><figcaption></figcaption></figure>
+
+## Prerequisites
+
+Make sure you follow official Firebase documentation to properly set up Firebase Authentication in Firebase Console: [https://firebase.google.com/docs/auth](https://firebase.google.com/docs/auth)
+
+## Installation
+
+`@adminjs/firebase-auth` is a premium feature which can be purchased at [https://cloud.adminjs.co](https://cloud.adminjs.co)
+
+All premium features currently use **One Time Payment** model and you can use them in all apps that belong to you. Once you purchase the addon, you will receive a license key which you should provide in `@adminjs/firebase-auth` configuration in your application's code.
+
+Installing the library:
+
+```bash
+$ yarn add @adminjs/firebase-auth
+```
+
+The license key should be provided via `FirebaseAuthProvider` constructor:
+
+```typescript
+new FirebaseAuthProvider({
+  licenseKey: process.env.LICENSE_KEY,
+  // the rest of the config
+})
+```
+
+If you encounter any issues or require help installing the package please contact us through our Discord server.
+
+## Usage
+
+`FirebaseAuthProvider` requires you to prepare Firebase-specific configuration.
+
+#### UI Config
+
+`@adminjs/firebase-auth` uses `firebaseui-web` to generate Firebase UI inside the login form and it requires you to configure it. Please refer to the following link for configuration options: [https://github.com/firebase/firebaseui-web/blob/master/types/index.d.ts#L115](https://github.com/firebase/firebaseui-web/blob/master/types/index.d.ts#L115)
+
+Note that you can only configure raw values but you will not be able to configure functions or callbacks this way. A workaround will be described in the later part of this documentation.
+
+```typescript
+import { EmailAuthProvider } from 'firebase/auth';
+
+const uiConfig = {
+  popupMode: true,
+  signInFlow: 'popup',
+  signInOptions: [
+    {
+      provider: EmailAuthProvider.PROVIDER_ID,
+      disableSignUp: {
+        status: true,
+      },
+    },
+  ],
+};
+```
+
+#### Firebase Configuration
+
+`@adminjs/firebase-auth` initializes a Firebase App in the Login view. Make sure you copy the configuration from your project in Firebase Console.
+
+```typescript
+const firebaseConfig = {
+  apiKey: 'AIza...',
+  authDomain: 'XXXX.firebaseapp.com',
+  projectId: 'XXXX',
+  storageBucket: 'XXXX.appspot.com',
+  messagingSenderId: '11111111111',
+  appId: '1:11111111111:web:abcdef',
+};
+```
+
+You will most likely also have to initialize a Firebase app on your server's end to verify the user's access token later:
+
+```typescript
+import { initializeApp } from 'firebase-admin/app';
+
+// ...
+
+const firebaseApp = initializeApp(firebaseConfig);
+```
+
+#### Authenticate method
+
+Lastly, you must define an `authenticate` method which you will use to verify the user's access token and return the user object.
+
+```typescript
+import { getAuth } from 'firebase-admin/auth';
+import { FirebaseAuthenticatePayload } from '@adminjs/firebase-auth';
+
+export const authenticate = async ({
+  accessToken,
+}: FirebaseAuthenticatePayload) => {
+  const auth = getAuth(firebaseApp);
+
+  try {
+    const decodedToken = await auth.verifyIdToken(accessToken);
+
+    return {
+      id: decodedToken.uid,
+      email: decodedToken.email ?? '',
+      avatarUrl: decodedToken.picture,
+    };
+  } catch (error) {
+    console.log(error);
+    return null;
+  }
+};
+```
+
+### FirebaseAuthProvider Configuration
+
+After you are done with Firebase-specific configuration, you can instantiate `FirebaseAuthProvider`:
+
+```typescript
+import { FirebaseAuthProvider } from '@adminjs/firebase-auth';
+import componentLoader from '<path to your component loader file>';
+
+// ... assume Firebase related configuration is in the same file
+
+const authProvider = new FirebaseAuthProvider({
+  // make sure that the same ComponentLoader instance is configured in AdminJS!
+  componentLoader,
+  uiConfig,
+  firebaseConfig,
+  authenticate,
+  licenseKey: process.env.LICENSE_KEY,
+});
+
+// ...
+
+// Add "provider" to authentication options of your framework plugin, Express example:
+
+const router = buildAuthenticatedRouter(
+  admin,
+  {
+    cookiePassword: 'test',
+    provider: authProvider,
+  },
+  null,
+  {
+    secret: 'test',
+    resave: false,
+    saveUninitialized: true,
+  }
+);
+```
+
+With your plugin and auth provider configured you should be able to restart your server and a new login page with embedded Firebase UI should appear.
+
+## Troubleshooting
+
+#### How to prevent @adminjs/firebase-auth from overriding the Login page?
+
+By default, `@adminjs/firebase-auth` will override your Login page with it's own UI. You can disable that by adding `overrideLogin: false` in `FirebaseAuthProvider` configuration:
+
+```typescript
+const authProvider = new FirebaseAuthProvider({
+  componentLoader,
+  uiConfig,
+  firebaseConfig,
+  authenticate,
+  licenseKey: process.env.LICENSE_KEY,
+  overrideLogin: false,
+});
+```
+
+If you do this, though, Firebase won't render it's own UI. You will have to create your own Login page and import `FirebaseAuthForm` component from `@adminjs/firebase-auth` and put it wherever you want in your own Login component.
+
+```typescript
+import { FirebaseAuthForm } from '@adminjs/firebase-auth/components'
+
+const CustomLogin = () => {
+ return <FirebaseAuthForm />
+}
+
+export default CustomLogin
+```
+
+Remember to override `Login` using your component loader:
+
+```typescript
+componentLoader.override('Login', '<path to custom login>');
+```
+
+#### How to configure functions and callbacks of UI Config?
+
+Follow the steps above to create your custom Login page. Create UI configuration in your custom component and provide it as props of `FirebaseAuthForm`:
+
+```typescript
+const uiConfig = {/* custom config */};
+
+const CustomLogin = () => {
+ return <FirebaseAuthForm uiConfig={uiConfig} />
+}
+```
+
+#### How to customize the look of Firebase UI?
+
+If you decide to follow the steps above you will be able to create a styled component out of `FirebaseAuthForm` and customize it fully.
+
+Alternatively, you can create a CSS file and add it to your app's assets.
+
+```css
+.adminjs_firebaseui-container {
+  background: red;
+}
+```
+
+Make sure the CSS file is present in your server's public assets directory. Lastly, configure `assets` of AdminJS:
+
+```typescript
+const admin = new AdminJS({
+  assets: {
+    styles: ['/firebase-ui.css'],
+  },
+  // other config
+})
+```