#Розширення типів автентифікації

#Огляд

NocoBase дозволяє розширювати типи автентифікації користувачів за потреби. Зазвичай існує два типи автентифікації користувачів: перший – це визначення особи користувача безпосередньо в застосунку NocoBase, наприклад, вхід за паролем або SMS; другий – це коли сторонні сервіси визначають особу користувача та повідомляють застосунок NocoBase про результат через зворотні виклики, наприклад, методи автентифікації OIDC, SAML тощо. Процес автентифікації для цих двох типів у NocoBase виглядає наступним чином:

#Без сторонніх зворотних викликів

1. Клієнт використовує NocoBase SDK для виклику інтерфейсу входу api.auth.signIn(), надсилаючи запит до інтерфейсу auth:signIn, при цьому передаючи ідентифікатор поточного автентифікатора через заголовок запиту X-Authenticator на бек-енд.
2. Інтерфейс auth:signIn, використовуючи ідентифікатор автентифікатора із заголовка запиту, перенаправляє запит до відповідного типу автентифікації. Метод validate у зареєстрованому класі автентифікації цього типу виконує відповідну логічну обробку.
3. Клієнт отримує інформацію про користувача та токен автентифікації з відповіді інтерфейсу auth:signIn, зберігає токен у Local Storage та завершує вхід. Цей крок автоматично обробляється всередині SDK.

#Зі сторонніми зворотними викликами

1. Клієнт отримує URL-адресу стороннього входу через власноруч зареєстрований інтерфейс (наприклад, auth:getAuthUrl), передаючи згідно з протоколом таку інформацію, як назва застосунку та ідентифікатор автентифікатора.
2. Перенаправлення на сторонню URL-адресу для завершення входу. Сторонній сервіс викликає інтерфейс зворотного виклику застосунку NocoBase (який потрібно зареєструвати самостійно, наприклад, auth:redirect), повертає результат автентифікації, а також інформацію, таку як назва застосунку та ідентифікатор автентифікатора.
3. Метод інтерфейсу зворотного виклику розбирає параметри для отримання ідентифікатора автентифікатора, через AuthManager отримує відповідний клас автентифікації та активно викликає метод auth.signIn(). Метод auth.signIn() викликає метод validate() для обробки логіки авторизації.
4. Метод зворотного виклику отримує токен автентифікації, потім перенаправляє (302) назад на фронтенд-сторінку, передаючи token та ідентифікатор автентифікатора в параметрах URL, наприклад, ?authenticator=xxx&token=yyy.

Далі ми розглянемо, як зареєструвати серверні інтерфейси та клієнтські інтерфейси користувача.

#Серверна частина

#Інтерфейс автентифікації

Ядро NocoBase надає можливості для реєстрації та управління розширеними типами автентифікації. Обробка основної логіки для розширення плагіна входу вимагає успадкування від абстрактного класу Auth ядра та реалізації відповідних стандартних інтерфейсів.
Повну довідку API дивіться у Auth.

import { Auth } from '@nocobase/auth';

class CustomAuth extends Auth {
  set user(user) {}
  get user() {}

  async check() {}
  async signIn() {}
}

Ядро також реєструє базові операції з ресурсами, пов'язані з автентифікацією користувачів.

У більшості випадків розширений тип автентифікації користувачів також може використовувати наявну логіку авторизації JWT для генерації облікових даних для доступу користувачів до API. Клас BaseAuth у ядрі містить базову реалізацію абстрактного класу Auth; дивіться BaseAuth. Плагіни можуть безпосередньо успадковувати клас BaseAuth, щоб повторно використовувати частину логічного коду та знизити витрати на розробку.

import { BaseAuth } from '@nocobase/auth';

class CustomAuth extends BaseAuth {
  constructor(config: AuthConfig) {
    // Встановити колекцію користувачів
    const userCollection = config.ctx.db.getCollection('users');
    super({ ...config, userCollection });
  }

  // Реалізувати логіку автентифікації користувача
  async validate() {}
}

#Дані користувача

При реалізації логіки автентифікації користувача зазвичай включається обробка даних користувача. У застосунку NocoBase відповідні колекції за замовчуванням визначені як:

Зазвичай розширені методи входу використовують колекції users та usersAuthenticators для зберігання відповідних даних користувача. Лише в особливих випадках вам потрібно буде самостійно додавати нову колекцію.

Основними полями колекції usersAuthenticators є:

Для операцій запиту та створення користувачів модель даних AuthModel автентифікаторів також інкапсулює кілька методів, які можна використовувати в класі CustomAuth через this.authenticator[ім'яМетоду]. Повну довідку API дивіться у AuthModel.

import { AuthModel } from '@nocobase/plugin-auth';

class CustomAuth extends BaseAuth {
  async validate() {
    // ...
    const authenticator = this.authenticator as AuthModel;
    this.authenticator.findUser(); // Запит користувача
    this.authenticator.newUser(); // Створити нового користувача
    this.authenticator.findOrCreateUser(); // Запитати або створити нового користувача
    // ...
  }
}

#Реєстрація типу автентифікації

Розширений метод автентифікації потрібно зареєструвати в модулі управління автентифікацією.

class CustomAuthPlugin extends Plugin {
  async load() {
    this.app.authManager.registerTypes('custom-auth-type', {
      auth: CustomAuth,
    });
  }
}

#Клієнтська частина

Клієнтський інтерфейс користувача реєструється через інтерфейс registerType, наданий клієнтом плагіна автентифікації користувачів:

import AuthPlugin from '@nocobase/plugin-auth/client';

class CustomAuthPlugin extends Plugin {
  async load() {
    const auth = this.app.pm.get(AuthPlugin);
    auth.registerType('custom-auth-type', {
      components: {
        SignInForm, // Форма входу
        SignInButton, // Кнопка входу (стороннього), може бути альтернативою формі входу
        SignUpForm, // Форма реєстрації
        AdminSettingsForm, // Форма налаштувань адміністратора
      },
    });
  }
}

#Форма входу

Якщо кілька автентифікаторів, що відповідають типу автентифікації, зареєстрували форми входу, вони відображатимуться у вигляді вкладок. Заголовок вкладки буде назвою автентифікатора, налаштованою в бек-енді.

#Кнопка входу

Зазвичай це кнопки стороннього входу, але насправді це може бути будь-який компонент.

#Форма реєстрації

Якщо вам потрібно перейти зі сторінки входу на сторінку реєстрації, це потрібно обробити самостійно в компоненті входу.

#Форма налаштувань адміністратора

Вгорі знаходиться загальна конфігурація автентифікатора, а внизу – частина форми користувацьких налаштувань, яку можна зареєструвати.

#Запити до API

Щоб ініціювати на клієнтській стороні запити до інтерфейсів, пов'язаних з автентифікацією користувачів, можна використовувати SDK, наданий NocoBase.

import { useAPIClient } from '@nocobase/client';

// використовувати в компоненті
const api = useAPIClient();
api.auth.signIn(data, authenticator);

Детальну довідку API дивіться у @nocobase/sdk - Auth.