#Расширение типов аутентификации

#Обзор

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 коллекции authenticators также инкапсулирует несколько методов, которые можно использовать в классе 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.