Команда authorize — описание и примеры

Команда authorize реализует авторизацию пользователя через протокол OpenID Connect (OIDC) с поддержкой PKCE. Может вызываться как самостоятельная команда или автоматически при наличии authType=oidc в других командах.

Содержание:

• Общая информация
• Формат ссылки
• Получение параметров авторизации
• Процесс авторизации
• Callback (обратный вызов)
• Справочник интерфейсов
• Интерфейс приложения

---

Общая информация

Команда authorize выполняет аутентификацию пользователя через OIDC-провайдер:

1. Запрашивает параметры авторизации с сервера (или получает их из локального JSON).
2. Строит URL авторизации с PKCE (Proof Key for Code Exchange).
3. Открывает браузер пользователя для входа на стороне провайдера.
4. Получает код авторизации через callback и обменивает его на токены доступа.
5. Сохраняет токены в доверенном сервисе и использует для последующих запросов.

Поддерживается также безвзаимодейственная (silent) авторизация с использованием клиентского сертификата (mTLS), если prompt=none.

Все запросы между КриптоАРМ и сервером ДОЛЖНЫ соответствовать спецификации протокола JSON-RPC 2.0.

---

Формат ссылки

cryptoarm://authorize/<URL>/?id=<id>

• cryptoarm:// - зарегистрированный протокол
• authorize - выполняемая команда
• <URL> - ссылка на получение JSON с параметрами авторизации
• id - уникальный идентификатор транзакции

Пример:

cryptoarm://authorize/https://example.com/json?id=2c48eb32-a0a8-405c-ade9-eed130605cba

---

Получение параметров авторизации

После получения команды authorize КриптоАРМ запрашивает параметры авторизации с сервера.

Формат запроса

Ключ	Значение	Описание
jsonrpc	«2.0»	Версия JSON-RPC протокола. Всегда «2.0».
method	authorization.parameters	Используемый метод. Всегда authorization.parameters.
id	Уникальный идентификатор	Используется идентификатор, который указан в ссылке на операцию.

Пример:

Content-Type: application/json
Content-Length: ...
Accept: application/json
{
    "jsonrpc": "2.0",
    "method": "authorization.parameters",
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba"
}

Формат ответа

Ключ	Значение	Описание
jsonrpc	«2.0»	Версия JSON-RPC протокола. Всегда «2.0».
params	{ authorizationParams: IAuthorizationParams }	Параметры авторизации
id	Уникальный идентификатор	Используется идентификатор, который указан в ссылке на операцию.

Пример:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "jsonrpc": "2.0",
    "params": {
        "authorizationParams": {
            "clientId": "my-client-id",
            "issuer": "https://auth.example.com",
            "redirectUri": "http://localhost:3000/callback",
            "scope": "openid profile",
            "wellKnownUrl": "https://auth.example.com/.well-known/openid-configuration",
            "resource": "https://api.example.com",
            "responseTypes": "code",
            "prompt": "login"
        }
    },
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba"
}

---

Процесс авторизации

После получения параметров авторизации:

1. КриптоАРМ отображает диалог авторизации с информацией о сервисе.

2. Если пользователь подтверждает (prompt != "none"):

   • Генерируется code_verifier и code_challenge (PKCE).
   • Строится URL авторизации провайдера.
   • Открывается браузер пользователя.
   • Пользователь проходит аутентификацию на стороне провайдера.
   • После успешного входа провайдер перенаправляет на redirectUri с параметрами code и state.
   • Этот редирект должен быть перехвачен и передан КриптоАРМ через команду callback.

3. Если prompt="none" (безвзаимодейственная авторизация):

   • Используется клиентский сертификат (mTLS) для получения кода авторизации напрямую.
   • Код обменивается на токены через token endpoint.

После успешной авторизации:

• Токены (access_token, id_token, refresh_token) сохраняются в доверенном сервисе.
• Профиль пользователя извлекается из id_token или через userinfo endpoint.
• Отображается диалог успешной авторизации с именем пользователя.

---

Callback (обратный вызов)

Команда callback используется для обработки редиректа от OIDC-провайдера после успешной аутентификации. Обычно вызывается автоматически операционной системой при переходе по зарегистрированному протоколу cryptoarm://.

Формат ссылки

cryptoarm://callback/<redirected_url>?id=<id>&authType=<authType>

Параметры state, code, session_state и другие передаются в query-строке редиректа от провайдера и извлекаются КриптоАРМ автоматически.

КриптоАРМ обменивает полученный код авторизации на токены, извлекает профиль пользователя и сохраняет всё в доверенном сервисе.

Важно: Команда callback является внутренней и не предназначена для прямого вызова. Она автоматически обрабатывается КриптоАРМ при получении редиректа от OIDC-провайдера.

---

Справочник интерфейсов

Интерфейс IAuthorizationParams

Параметры, необходимые для OIDC-авторизации.

Свойство	Тип	Описание
clientId	string	Идентификатор клиента, зарегистрированный у OIDC-провайдера
issuer	string	URL издателя токенов (Issuer)
redirectUri	string	URI для редиректа после авторизации
scope	string	Запрашиваемые области (scopes), например "openid profile"
wellKnownUrl?	string	URL well-known конфигурации OIDC (если отличается от стандартного .well-known/openid-configuration)
resource?	string/string[]	Идентификатор ресурса, к которому запрашивается доступ
responseTypes?	string/string[]	Типы ответа (response_type). По умолчанию "code".
prompt?	string	Параметр prompt. "login" — интерактивная авторизация, "none" — безвзаимодейственная (silent).
override?	{ issuer: { authorization_endpoint, token_endpoint, ... } }	Переопределение метаданных издателя (если well-known недоступен).

Интерфейс ICustomAuth (настройки передачи токена)

После успешной OIDC-авторизации токен доступа может передаваться в последующих запросах. Настройки customAuth определяют способ передачи:

Свойство	Тип	Описание
token?	string	Токен доступа (заполняется автоматически)
in?	string	Способ передачи: "header" (заголовок), "query" (параметр), "body" (тело). По умолчанию: "header".
key?	string	Имя ключа/заголовка. По умолчанию: "Authorization" для header, "token" для query/body.
scheme?	string	Схема авторизации. По умолчанию: "Bearer".
thumbprint?	string	Отпечаток клиентского сертификата для mTLS.

---

Интерфейс приложения

Процесс авторизации состоит из нескольких этапов:

1. Диалог подтверждения — отображается информация о запрашиваемом сервисе. Кнопки: «Продолжить» и «Отмена».
2. Авторизация в браузере — открывается системный браузер со страницей входа провайдера.
3. Ожидание редиректа — КриптоАРМ ожидает callback с кодом авторизации.
4. Успешная авторизация — отображается имя авторизованного пользователя. Кнопка «Готово».

При отмене на любом этапе процесс прерывается.

Предыдущая

Следующая