# Подключение сервиса к SHID

SHID использует стандартный OpenID Connect. Вход подтверждает личность; доступ к конкретному сервису проверяется отдельно. Добавленная в каталог ссылка сама по себе не закрывает внешний сайт.

## 1. Создать OIDC-клиент

В Keycloak выберите realm `shid`, создайте отдельный confidential OIDC client для серверного приложения.
Issuer: `https://id.shid.online/realms/shid`.
Разрешите Authorization Code Flow с PKCE S256; задайте точные HTTPS redirect URI и logout URI.
Отключите Direct Access Grants. Секрет храните только на сервере приложения. Используйте поддерживаемую OIDC-библиотеку, state, nonce и проверку подписи ID token.

Для access token добавьте Audience mapper со значением `shid-services` (access token only).
Запрашивайте `openid profile`. Не используйте ID token вместо access token для вызова API.

## 2. Создать запись в каталоге

В кабинете SHID укажите название, реальный URL, короткое имя (slug), видимость и способ доступа.
Бесплатная активация, одобренная заявка и подтверждённый заказ создают записи доступа в SHID.
Платёжные данные и стоимость заказа задаёт сервер. URL «успешная оплата» ничего не подтверждает.

## 3. Проверять доступ на сервере сервиса

После входа передавайте access token пользователя серверным запросом:

```
GET https://shid.online/api/access/your-service-slug
Authorization: Bearer USER_ACCESS_TOKEN
```

200 и `allowed: true` разрешают доступ. 401 требует нового входа/обновления токена; 403 запрещает доступ.
При ошибке связи закрывайте защищённую операцию. Не доверяйте присланному браузером user ID, email, роли, цене или флагу оплаты.
Проверяйте доступ для каждой защищённой операции. Не кэшируйте разрешение, если нужен немедленный отзыв.
Пара `issuer + sub` — постоянный идентификатор; username и email могут меняться.

Сервис сам защищает свои данные и прямые URL. Для сервисов без поддержки OIDC понадобится отдельный проверенный адаптер перед сервисом; скрытие ссылки в каталоге не заменяет его.

## 4. Сессии

Cookie приложения: Secure, HttpOnly, SameSite=Lax, без общего Domain. Ограничивайте срок своей сессии сроком сессии SHID.
Обновляйте access token через стандартный refresh flow; не храните токены в localStorage.
Подключите RP-Initiated Logout и подписанный back-channel logout. Не обещайте глобальный выход без проверки доставки.

## Проверка

- Незарегистрированный посетитель не получает защищённые данные.
- У вошедшего пользователя без разрешения ответ 403.
- После активации/одобрения/подтверждения оплаты доступ появляется.
- После истечения срока, отзыва или блокировки пользователя доступ закрывается.
- Повторное подтверждение одного заказа не создаёт второй доступ и не продлевает срок.
- Пользователь не может подставить ID другого пользователя или сумму заказа.

В Keycloak оставь default client scopes `basic`, `profile`, `roles`. Scope `basic` добавляет `sub` в access token; без него проверка личности должна завершаться отказом.