Получение мастер-токена из 1С

Гайд показывает, как сформировать JWT в 1С, подписать его приватным ключом RSA и получить мастер-токен через метод Создать мастер-токен.

Что получится в конце

1С сформирует Bearer-токен JWT, подпишет его приватным ключом RSA, вызовет ESA и получит masterToken для запросов к API HRlink.

Что нужно заранее

Используйте этот пример после регистрации интегратора. До запуска кода подготовьте:

Значение	Где взять
`tenantHost`	Домен тенанта, например `company.hr-link.ru`
`iss`	Значение издателя, которое зарегистрировала Служба заботы
`sub`	UUID интегратора из ответа Службы заботы
Приватный ключ	Файл `integrator_private.key`, который соответствует сертификату, переданному в Службу заботы

Какие методы используются

Шаг	Метод
Получить мастер-токен	Создать мастер-токен
Выполнить запрос от имени пользователя	Любой метод HRlink с заголовками мастер-токена, например Получить текущего пользователя

Версия платформы

Используйте 1С:Предприятие 8.3.24+. В версиях 8.3.21–8.3.23 есть ошибка: поля iat и exp могут попасть в JWT строками, а HRlink ожидает числа.

Алгоритм подписи

Статья 1С про ТокенДоступа показывает общий механизм JWT и пример с HS256. HRlink не принимает HS256: подписывайте токен алгоритмом RS256, RS384 или RS512; рекомендуемый вариант — RS256.

Пример кода

В примере 1С формирует JWT с алгоритмом RS256, передаёт его как Bearer-токен и получает masterToken от esa.hr-link.ru.

Функция ПолучитьМастерТокен() Экспорт

	Сервер = "esa.hr-link.ru";
	АдресРесурса = "/api/v1/masterTokens";

	ТелоЗапроса = "{""tenantHost"": ""company.hr-link.ru""}";

	Возврат ВыполнитьМетодPOST(Сервер, АдресРесурса, ТелоЗапроса);

КонецФункции

Функция ВыполнитьМетодPOST(Сервер, АдресРесурса, ТелоЗапроса)

	Соединение = Новый HTTPСоединение(Сервер,,,,,30, Новый ЗащищенноеСоединениеOpenSSL());

	Заголовки = Новый Соответствие;
	Заголовки.Вставить("Content-Type", "application/json");
	Заголовки.Вставить("Accept", "application/json");

	Запрос = Новый HTTPЗапрос(АдресРесурса, Заголовки);
	Запрос.УстановитьТелоИзСтроки(ТелоЗапроса);
	Запрос.ДобавитьТокенДоступа(СформироватьBearerТокен());

	Результат = Новый Соответствие;
	Результат.Вставить("result", Ложь);

	Попытка
		Ответ = Соединение.POST(Запрос);
		ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();

		Если ЗначениеЗаполнено(ТелоОтвета) Тогда
			Результат = ОбщегоНазначения.JSONЗначение(ТелоОтвета);
		КонецЕсли;

		Если Ответ.КодСостояния = 200 Тогда
			// Результат содержит masterToken.
		ИначеЕсли Ответ.КодСостояния >= 400 Тогда
			// Разберите код ошибки из тела ответа.
		Иначе
			// Зафиксируйте неожиданный код ответа сервиса.
		КонецЕсли;

	Исключение
		// Зафиксируйте ошибку подключения или разбора ответа.
	КонецПопытки;

	Возврат Результат;

КонецФункции

Функция СформироватьBearerТокен()

	АлгоритмПодписи = АлгоритмПодписиТокенаДоступа.RS256;
	ТекущееВремя = ТекущаяДата();

	ТокенДоступа = Новый ТокенДоступа;
	ТокенДоступа.Заголовки.Вставить("alg", Строка(АлгоритмПодписи));
	ТокенДоступа.Получатели = ОбщегоНазначенияКлиентСервер.ЗначениеВМассиве("esa.hr-link.ru");
	ТокенДоступа.Эмитент = "RogaKopyta";
	ТокенДоступа.КлючСопоставленияПользователя = ИдентификаторИнтегратораHRlink();
	ТокенДоступа.ВремяСоздания = ДатаВUnixTimestamp(ТекущееВремя);
	ТокенДоступа.ВремяЖизни = 600;
	ТокенДоступа.Идентификатор = Новый УникальныйИдентификатор;

	ТокенДоступа.Подписать(АлгоритмПодписи, КлючПодписи());

	Возврат ТокенДоступа;

КонецФункции

Функция ИдентификаторИнтегратораHRlink()

	Возврат "1aaa11a1-111a-1a1a-a11a-11a1a11a1a1a";

КонецФункции

Функция ДатаВUnixTimestamp(Дата)

	Возврат УниверсальноеВремя(Дата) - '19700101';

КонецФункции

Функция КлючПодписи()

	Возврат Константы.КлючПодписи.Получить();

КонецФункции

Замените в примере:

Значение в коде	На что заменить
`company.hr-link.ru`	Домен вашего тенанта
`RogaKopyta`	Зарегистрированное значение `iss`
`1aaa11a1-111a-1a1a-a11a-11a1a11a1a1a`	UUID интегратора (`sub`)
`Константы.КлючПодписи.Получить()`	Ваш способ получения приватного ключа

Требования к приватному ключу

Передавайте в КлючПодписи() приватный ключ в формате PEM:

-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----

Если ключ хранится в формате ENCRYPTED PRIVATE KEY, сначала конвертируйте его в PRIVATE KEY. HRlink проверяет JWT по сертификату, который вы передали в Службу заботы, поэтому ключ должен соответствовать этому сертификату.

Не передавайте приватный ключ

Приватный ключ подписывает JWT от имени интегратора. Не отправляйте его в HRlink, не храните в репозитории и не показывайте в логах. В Службу заботы передавайте только сертификат.

Ответ HRlink

При успешном запросе метод Создать мастер-токен вернёт masterToken:

{
  "result": true,
  "masterToken": "eyJhbGc..."
}

После получения masterToken передавайте его в заголовке Master-Api-Token при запросах к API HRlink. Чтобы выполнить запрос от имени пользователя, добавьте заголовки Impersonated-User-Id и Impersonated-User-Id-Type; подробнее — в разделе Запросы от имени пользователя.

Частые ошибки

Ошибка	Что проверить
`51.214`	JWT подписан не RSA-алгоритмом. Используйте `RS256`, `RS384` или `RS512`; рекомендуемый вариант — `RS256`
`51.205`	Истёк Bearer-токен. Сформируйте новый JWT
`51.210`	Bearer-токен превысил максимальный срок жизни. В примере срок жизни JWT — `600` секунд
Ошибка проверки подписи	В Службу заботы передали сертификат, который не соответствует приватному ключу, или код подписывает JWT другим приватным ключом
Ошибка разбора JWT	Проверьте версию 1С и убедитесь, что `iat` и `exp` попадают в JWT числами

Что получится в конце​

Что нужно заранее​

Какие методы используются​

Пример кода​

Требования к приватному ключу​

Ответ HRlink​

Частые ошибки​