Авторизация

📌 Прежде чем начать

Для авторизации/аутентификации пользователя необходимо создать и настроить коллекцию специального типа — "Пользователи". Именно в ней будут храниться данные пользователей, а также осуществляться настройки авторизации.

Модуль Auth в Kodzero SDK включает:

базовые методы авторизации;
методы стратегий авторизации:
- стратегия Email-Password;
- стратегия Email-OTP (one time password) в разработке
- стратегия Яндекс OAuth в разработке
- стратегия Telegram OAuth в разработке
управление access/refresh токенами.

Для работы с коллекциями, доступность которых User или Workspace (см. Уровни доступа коллекций), клиент Kodzero SDK должен быть авторизован.

📚 Что такое access/refresh токены?

Токены — это временные ключи доступа, которые генерируются при аутентификации пользователя (входе в учётную запись). Токена два и они работают в паре. При каждом запросе к серверу, отправляется access-токен (токен доступа, имеющий короткий срок жизни). Когда срок жизни access-токена будет окончен, необходимо запросить у сервера выдачу нового access. Такой запрос делается с refresh-токеном. Kodzero SDK делает всё это автоматически.

Инициализация

При создании образца Kodzero SDK необходимо указать id коллекции, которая используется для работы с пользователями. Текущий образец будет использовать эту коллекцию для авторизации.

import Kodzero from 'kodzero-sdk'

const kodzero = new Kodzero({
    host: 'https://api.kodzero.pro/v1/10007', // хост + id вашего проекта
    authCollection: '100026', // id коллекции типа "Пользователи"
    autoRefreshToken: true // авто-обновление токенов при необходимости
})

export default kodzero

После инициализации пользователь не авторизован — токены пусты.

console.log(kodzero.tokensManager)
// TokensManagerClass { access: '', refresh: '' }

При необходимости вы можете создать два отдельных инстанса Kodzero с разными пользовательскими коллекциями.

import Kodzero from 'kodzero-sdk'

export const KodzeroByUser = new Kodzero({
    host: 'https://api.kodzero.pro/v1/10007',
    authCollection: '100001',
    autoRefreshToken: true
})

export const KodzeroByAdmin = new Kodzero({
    host: 'https://api.kodzero.pro/v1/10007',
    authCollection: '100000',
    autoRefreshToken: true
})

Базовые методы и стратегии

При создании коллекции вы можете настроить разные способы аутентификации, которые называются стратегиями.

Каждая стратегия предлагает свой набор методов, соответствующий выбранному протоколу (например, Email+пароль, OAuth, магическая ссылка). Однако независимо от выбранной стратегии, все методы делятся на две группы: базовые (доступны всегда) и специфичные (уникальные для конкретной стратегии).

Пример

Например, регистрация (метод register) по электронной почте и паролю отличается от регистрации через OAuth Яндекс. При этом выход из учетной записи (метод logout) будет работать одинаково (при помощи базового метода).

Базовые методы

Базовые методы могут быть вызваны вне зависимости от того, какие стратегии вы используете.

Проверка токена (verify)

Проверяет access-токен текущего пользователя (если вход уже был осуществлен).

const verifyResult = await kodzero.auth.email.verify()
console.log(verifyResult) // true / false

Тип ответа:

type VerifyResult = boolean

Обновление токена (refresh)

Метод обновляет access-токен, используя текущий refresh-токен пользователя. Новый токен сразу же будет сохранен в текущем образце Kodzero SDK.

const result = await kodzero.auth.email.refresh()

Тип ответа:

type RefreshResult = {
    tokens: {
        access: string;
        refresh: string;
    }
}

Автоматическое обновление токена

Обратите внимание, что при инициализации можно активировать автоматическое обновление токенов:

const kodzero = new Kodzero({
    host: 'https://api.kodzero.pro/v1/10007/',
    authCollection: "100026",
    autoRefreshToken: true // ⬅️ автоматическое обновление токенов при необходимости
});

Выход (logout)

Аннулирует токен. Также заканчивает сессию на стороне клиента (в образце Kodzero, в котором метод был вызван). После этого запросы текущего образца будут осуществляться как неавторизованные.

const logoutResult = await kodzero.auth.logout()
console.log(logoutResult) // true / false

Тип ответа:

type LogoutResult = boolean

Стратегии: Email-Password

Для регистрации и входа используется адрес электронной почты и пароль.

Осуществляет вход пользователя в текущем образце Kodzero SDK.

В случае успеха: Токены доступа сохраняются автоматически. Текущий образец Kodzero SDK готов к осуществлению запросов от лица пользователя (без необходимости добавлять токены в заголовок запроса).

const credentials = {
    email: 'user@example.com',
    password: 'StrongPassword123'
}

try {
    const loginResult = await kodzero.auth.email.login(credentials)
} catch (error) {
    console.log(error)
}

Тип ответа:

type LoginResult = {
    tokens: {
        access: string,
        refresh: string,
    },
    session: number,
    user: Record<string, unknown> // Данные пользователя
}

Регистрация (register)

Регистрация пользователя и вход в созданную учётную запись в текущем образце Kodzero SDK.

const credentials = {
    email: 'user@example.com',
    password: 'StrongPassword123',
    password2: 'StrongPassword123',
}

const registrationResult = await kodzero.auth.register(credentials)

Тип ответа:

type RegisterResult = {
    tokens: {
        access: string,
        refresh: string
    },
    session: number,
    user: { ... } // Данные пользователя
}

Работа с токенами

Ручное управление

При необходимости вы можете установить токены доступа или сбросить их вручную

kodzero.auth.setTokens(access, refresh || '')
kodzero.auth.clearTokens()

Встроенный TokensManager

Позволяет безопасно работать с токенами текущего образца Kodzero SDK.

class TokensManagerClass {
    access: string
    refresh: string

    constructor(access: string = '', refresh: string = '') {
        this.access = access
        this.refresh = refresh
    }

    hasAccess() {
        return this.access && this.access !== ''
    }

    hasRefresh() {
        return this.refresh && this.refresh !== ''
    }

    setAccess(token: string) {
        this.access = token
    }

    setRefresh(token: string) {
        this.refresh = token
    }

    clear() {
        this.access = ''
        this.refresh = ''
    }
}

Данные пользователя

Некоторые ответы включают данные пользователя: технические (обязательные) свойства, а также свойства, которые вы добавили в схеме коллекции.

interface AuthUser {
    // Технические автоматические поля:
    _id: string
    _identity: string
    _workspace: string
    _createdAt: string
    _updatedAt: string
    // Дополнительные поля вашей auth-коллекции:
    // ...
}

Полный сценарий

// 1️⃣ Инициализация клиента
const kodzero = new Kodzero({
    host: 'https://api.kodzero.pro/v1/10007/',
    authCollection: "100026"
});

// Токены пустые, клиент не авторизован
console.log(kodzero.tokensManager)
// TokensManagerClass { access: '', refresh: '' }

console.log(kodzero.tokensManager.hasAccess())
// false
// ✅ access-токен отсутствует

// 2️⃣ Верификация текущего токена клиента на сервере
const verifyResult = await kodzero.auth?.email.verify();
console.log('token verified:', verifyResult)
// token verified: false
// ✅ Всё верно, вход не был выполнен

// 3️⃣ Регистрация нового пользователя
const credentials = {
    email: `new-user@test.com`,
    password: 'n3W-paSSw0rd'
}

const registerResult = await kodzero.auth?.email.register(credentials);
console.log('register result:', registerResult)
// register result: { tokens: { access: '...', refresh: '...' }, user: { ... }, session: 1 }
// ✅ Пользователь зарегистрирован и сразу же осуществлён вход

// 4️⃣ Проверка токена после регистрации
const verifyResult2 = await kodzero.auth?.email.verify();
console.log('token verified:', verifyResult2)
// token verified: true
// ✅ Клиент авторизован

console.log(kodzero.tokensManager)
// TokensManagerClass { access: '...', refresh: '...' }

// 5️⃣ Обновление текущего access-токена вручную
const refreshResult = await kodzero.auth?.email.refresh();
console.log('refresh result:', refreshResult)
// refresh result: { tokens: { access: '...', refresh: '...' } }
// ✅ Обновление токена выполнено успешно

// 6️⃣ Выход из учетной записи пользователя
const logoutResult = await kodzero.auth?.logout();
console.log('logout result:', logoutResult)
// logout result: true
// ✅ Выход из учётной записи выполнен

console.log(kodzero.tokensManager)
// TokensManagerClass { access: '', refresh: '' }
// Токены сброшены

// 7️⃣ Вход с данными, используемыми ранее для регистрации пользователя
const loginResult = await kodzero.auth?.email.login(credentials);
console.log('loginResult:', loginResult)
// loginResult: { tokens: { access: '...', refresh: '...' }, user: { ... }, session: 1 }
// ✅ Клиент успешно авторизован

// Любые запросы клиента (образца Kodzero SDK) будут осуществлены от лица текущего пользователя

// Например, создадим модель, связанную с коллекцией 100033:
const Task = kodzero.createModel({
  collection: '100033'
})

// Доступность коллекции `user`
// что означает, что для работы требуется авторизация

// Попробуем создать запись:
const newTask = new Task({title: 'Задача пользователя'})
await newTask.save()
// ✅ Запись создана

Авторизация ​

Инициализация ​

Базовые методы и стратегии ​

Базовые методы ​

Проверка токена (verify) ​

Обновление токена (refresh) ​

Автоматическое обновление токена ​

Выход (logout) ​

Стратегии: Email-Password ​

Вход (login) ​

Регистрация (register) ​

Работа с токенами ​

Ручное управление ​

Встроенный TokensManager ​

Данные пользователя ​

Полный сценарий ​

Авторизация

Инициализация

Базовые методы и стратегии

Базовые методы

Проверка токена (verify)

Обновление токена (refresh)

Автоматическое обновление токена

Выход (logout)

Стратегии: Email-Password

Вход (login)

Регистрация (register)

Работа с токенами

Ручное управление

Встроенный TokensManager

Данные пользователя

Полный сценарий