# Authoriza — AI Context

Этот файл содержит контекст, необходимый AI-ассистенту для помощи разработчику
с интеграцией Authoriza.

Используй этот контекст как источник правил и терминологии Authoriza.
Если для ответа нужна более подробная или актуальная информация, используй
официальную документацию Authoriza по ссылкам ниже.

---

## 1. Что такое Authoriza

Authoriza — сервис аутентификации и авторизации пользователей для веб-приложений.

Authoriza реализует стандартные протоколы:

- OAuth 2.0
- OpenID Connect (OIDC)
- PKCE

Основная задача интеграции — добавить в приложение вход пользователей через
Authoriza и получить результат аутентификации.

Authoriza не требует использования собственного SDK для серверной интеграции.
Если подходящая библиотека OAuth 2.0 / OpenID Connect уже используется в проекте,
предпочтительно использовать её.

Для JavaScript/TypeScript SPA существует официальный SDK:

```bash
npm install @authoriza/sdk
```

---

## 2. Базовый сценарий интеграции

Для новой интеграции обычно требуется:

1. создать проект в Authoriza;
2. создать или использовать подключение (App) внутри проекта;
3. указать Redirect URI;
4. подключить Authoriza к приложению через SDK или OIDC-библиотеку;
5. реализовать вход пользователя;
6. обработать результат аутентификации.

Упрощённая схема:

```text
Пользователь
     │
     ▼
Ваше приложение
     │
     │ OAuth 2.0 / OpenID Connect
     ▼
Authoriza
     │
     │ пользователь проходит вход
     ▼
Ваше приложение
     │
     ▼
сессия пользователя
```

Подробный Quick Start:

[https://authoriza.ru/docs/start/quick-start](https://authoriza.ru/docs/start/quick-start)

---

## 3. Основные сущности

### Project

Project — контейнер, внутри которого находятся настройки и подключения приложений.

У проекта есть два идентификатора:

* `uuid` — внутренний UUID проекта;
* `projectId` — человекочитаемый идентификатор (slug).

Не путай эти значения.

`uuid` используется API для обращения к существующему проекту.

`projectId` используется, в частности, при создании подключения.

Пример:

```text
uuid:
550e8400-e29b-41d4-a716-446655440000

projectId:
my-saas
```

### App / Подключение

Подключение связывает конкретное приложение разработчика с проектом Authoriza.

В API App имеет UUID, `client_id`, тип, Redirect URI и другие настройки.

Основные типы:

```text
CONFIDENTIAL
PUBLIC
```

`CONFIDENTIAL` подходит для приложений, способных безопасно хранить client secret.

`PUBLIC` используется для приложений, в которых секрет хранить нельзя
(например, браузерное SPA).

Не следует путать тип `CONFIDENTIAL` / `PUBLIC` с типом приложения
(web, mobile и т.п.).

---

## 4. Redirect URI

Redirect URI — адрес, на который Authoriza возвращает пользователя после
завершения аутентификации.

Redirect URI должен быть заранее настроен в подключении приложения.

Например:

```text
https://example.com/auth/callback
```

Для локальной разработки:

```text
http://localhost:3000/auth/callback
```

В OAuth/OIDC flow значение Redirect URI должно соответствовать зарегистрированному
значению.

Если пользователь сообщает ошибку, связанную с redirect URI, сначала проверь:

1. точное значение URI;
2. протокол (`http` / `https`);
3. hostname;
4. port;
5. path;
6. наличие или отсутствие trailing slash;
7. что URI зарегистрирован именно в нужном подключении.

Документация:

[https://authoriza.ru/docs/start/redirect-uri](https://authoriza.ru/docs/start/redirect-uri)

---

## 5. OAuth 2.0 / OpenID Connect

Authoriza является OIDC-провайдером.

Если приложение уже использует OAuth 2.0 / OIDC библиотеку, не нужно писать
OAuth/OIDC реализацию самостоятельно.

Используй стандартную библиотеку соответствующего языка или фреймворка.

Основной OIDC issuer Authoriza:

```text
https://oidc.authoriza.ru/oidc
```

Для discovery используется стандартный OIDC endpoint:

```text
https://oidc.authoriza.ru/oidc/.well-known/openid-configuration
```

При выборе между собственной реализацией OAuth/OIDC и стандартной библиотекой
предпочитай библиотеку.

Документация:

[https://authoriza.ru/docs/start/oidc-libraries](https://authoriza.ru/docs/start/oidc-libraries)

---

## 6. PKCE

Для публичных клиентов и браузерных приложений следует использовать Authorization
Code Flow с PKCE.

Не помещай client secret в:

* frontend code;
* JavaScript bundle;
* localStorage;
* публичный конфигурационный файл;
* Git repository.

Если приложение не способно безопасно хранить секрет, используй `PUBLIC`
подключение и соответствующий flow.

---

## 7. JavaScript / TypeScript

Для frontend-приложений рекомендуется официальный Authoriza SDK.

Установка:

```bash
npm install @authoriza/sdk
```

SDK предназначен для упрощения:

* запуска входа;
* обработки OAuth/OIDC callback;
* получения токенов;
* работы с пользовательской сессией.

Прежде чем писать собственную OAuth/OIDC реализацию для JavaScript/TypeScript,
проверь возможность использования SDK.

Документация:

[https://authoriza.ru/docs/start/sdk](https://authoriza.ru/docs/start/sdk)

---

## 8. SDK и Redirect URI

В SDK необходимо различать два разных понятия.

### `redirect_uri`

Это технический OAuth/OIDC callback URL.

Он должен быть зарегистрирован в настройках подключения.

Например:

```text
https://example.com/auth/callback
```

### `redirectAfterLoginTo`

Это адрес frontend-приложения, куда SDK может перенаправить пользователя
после успешного завершения login flow.

Это не OAuth Redirect URI.

Не смешивай эти параметры.

---

## 9. Что должен сделать AI при помощи разработчику

Если разработчик просит:

> Подключи Authoriza к моему приложению

сначала определи:

1. какой тип приложения используется;
2. какой frontend/backend stack используется;
3. есть ли уже OAuth/OIDC библиотека;
4. есть ли созданный Project;
5. есть ли App/Подключение;
6. какой Redirect URI должен использоваться.

Не заставляй пользователя вручную выполнять действия, если подключён
Authoriza MCP и необходимая операция может быть выполнена через него.

Если MCP недоступен, объясни пользователю, какие действия нужно выполнить
в кабинете Authoriza.

---

## 10. Если Project или App ещё не создан

Для базовой интеграции пользователю нужен Project и App.

Рекомендуемый порядок:

```text
Project
   │
   └── App / Подключение
          │
          ├── type
          ├── client_id
          └── redirect_uris
```

При создании App необходимо определить:

* название;
* тип `PUBLIC` или `CONFIDENTIAL`;
* Redirect URI;
* проект.

Для `create_app` API использует `projectId` (slug), а не UUID проекта.

---

## 11. Как выбирать PUBLIC или CONFIDENTIAL

Используй `PUBLIC`, если приложение не может безопасно хранить секрет.

Типичные примеры:

* SPA;
* frontend-приложение, выполняющееся в браузере;
* мобильное приложение.

Используй `CONFIDENTIAL`, если приложение имеет защищённое серверное окружение,
в котором можно хранить client secret.

Например:

* серверное веб-приложение;
* backend;
* server-side application.

Никогда не помещай `client_secret` в frontend-код.

---

## 12. Что делать после создания App

Для интеграции понадобятся параметры созданного подключения.

В первую очередь:

```text
client_id
redirect_uri
issuer
```

Для confidential-приложения client secret используется только на защищённой
серверной стороне.

Для frontend/public-приложения секрет не должен использоваться в браузере.

---

## 13. Первый вход пользователя

После настройки подключения приложение отправляет пользователя в Authoriza.

После успешной аутентификации Authoriza возвращает пользователя на
зарегистрированный Redirect URI.

Далее приложение завершает OAuth/OIDC flow и получает необходимые токены.

ID token содержит идентификационные данные пользователя в соответствии
с запрошенными scopes.

Не следует самостоятельно придумывать формат токенов или callback-параметров —
используй стандартный OAuth 2.0 / OpenID Connect flow и документацию Authoriza.

Документация:

[https://authoriza.ru/docs/start/first-user](https://authoriza.ru/docs/start/first-user)

---

## 14. Scopes

Основной обязательный scope для OIDC:

```text
openid
```

Дополнительные scopes используются для получения соответствующих данных.

В зависимости от задачи могут использоваться:

```text
profile
email
offline_access
```

Не запрашивай scopes без необходимости.

Если приложению нужен email пользователя, проверь, что используется соответствующий
scope и что приложение корректно обрабатывает отсутствие этого значения.

---

## 15. Токены

В OIDC-интеграции могут использоваться:

* ID Token — информация об аутентифицированном пользователе;
* Access Token — токен доступа;
* Refresh Token — получение нового Access Token без повторного входа,
  если flow и scopes это позволяют.

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

Не помещай секреты и токены в Git.

---

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

Не предполагай, что все пользовательские поля всегда доступны.

Набор данных зависит от:

* scopes;
* настроек;
* результата OIDC flow.

Если разработчику нужны конкретные данные пользователя, сначала определи,
какой стандартный OIDC scope или endpoint для этого предназначен.

Не изобретай собственные claims, если соответствующий стандартный механизм уже есть.

---

## 17. Безопасность

При помощи с интеграцией всегда учитывай:

* не хранить client secret во frontend;
* не публиковать API keys;
* не публиковать access/refresh tokens;
* не коммитить credentials в Git;
* использовать HTTPS в production;
* использовать PKCE для public clients;
* точно настраивать Redirect URI.

Если пользователь вставил секрет, API key или токен в чат, не включай его
в сгенерированный код, документацию или commit.

Используй placeholders:

```text
YOUR_CLIENT_ID
YOUR_CLIENT_SECRET
YOUR_API_KEY
```

---

## 18. Authoriza MCP

Authoriza предоставляет MCP-сервер для AI coding agents и других AI-клиентов,
которые поддерживают MCP.

MCP позволяет AI-агенту работать с Authoriza непосредственно во время разработки.

Endpoint:

```text
https://mcp.authoriza.ru/mcp
```

Аутентификация MCP выполняется с помощью API Key Authoriza.

API Key передаётся в HTTP header:

```http
X-API-KEY: az_...
```

Пример конфигурации MCP:

```json
{
  "mcpServers": {
    "Authoriza": {
      "url": "https://mcp.authoriza.ru/mcp",
      "headers": {
        "X-API-KEY": "az_ВАШ_КЛЮЧ"
      }
    }
  }
}
```

API Key нельзя помещать в tool arguments или исходный код приложения.

После подключения MCP AI-агент может самостоятельно получить актуальный контекст
Authoriza и выполнять доступные операции.

Если MCP подключён, сначала используй его для получения состояния текущего
Project/App и актуальной документации, а не проси пользователя вручную копировать
эти данные.

---

## 19. Если MCP недоступен

Если AI-чат не поддерживает MCP или MCP не подключён, продолжай помогать
разработчику на основании этого контекста и официальной документации Authoriza.

Для актуальной документации используй:

[https://authoriza.ru/docs/](https://authoriza.ru/docs/)

Полезные разделы:

* Быстрый старт:
  [https://authoriza.ru/docs/start/quick-start](https://authoriza.ru/docs/start/quick-start)
* Основные концепции:
  [https://authoriza.ru/docs/concepts](https://authoriza.ru/docs/concepts)
* Redirect URI:
  [https://authoriza.ru/docs/start/redirect-uri](https://authoriza.ru/docs/start/redirect-uri)
* SDK:
  [https://authoriza.ru/docs/start/sdk](https://authoriza.ru/docs/start/sdk)
* OIDC-библиотеки:
  [https://authoriza.ru/docs/start/oidc-libraries](https://authoriza.ru/docs/start/oidc-libraries)
* Первый вход пользователя:
  [https://authoriza.ru/docs/start/first-user](https://authoriza.ru/docs/start/first-user)

Если документация и этот файл противоречат друг другу, для деталей текущей
интеграции используй более свежую официальную документацию.

---

## 20. Как отвечать на вопросы об интеграции

При решении задачи интеграции:

1. сначала определи стек и архитектуру приложения;
2. определи тип OAuth/OIDC клиента;
3. проверь, нужен ли SDK или уже используется OIDC-библиотека;
4. проверь Project и App;
5. проверь Redirect URI;
6. используй стандартный OAuth 2.0 / OIDC flow;
7. не создавай собственную реализацию протокола без необходимости;
8. не проси пользователя повторно сообщать информацию, которую можно получить
   через подключённый MCP;
9. если информации недостаточно — задай минимально необходимый вопрос;
10. при изменении конфигурации объясняй, какой параметр меняется и зачем.

При работе с существующим проектом сначала изучи его текущую архитектуру и зависимости.
Не предлагай переписать authentication layer, если достаточно добавить Authoriza
в существующую OAuth/OIDC-инфраструктуру.

---

## 21. Главное правило

Authoriza следует стандартам OAuth 2.0 и OpenID Connect.

Поэтому при разработке интеграции:

```text
существующий стек приложения
        ↓
стандартный OAuth 2.0 / OIDC
        ↓
Authoriza
```

Предпочтительно использовать существующие стандартные библиотеки и SDK,
а не реализовывать протокол самостоятельно.

Если задача относится к настройке Project/App или требует актуального состояния
Authoriza, используй MCP, если он доступен.

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