> For the complete documentation index, see [llms.txt](https://docs.payanyway.ru/marketplace/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payanyway.ru/marketplace/zaprosy-dlya-registracii-fl/identifikaciya-s-pomoshyu-monetaid/autentifikaciya.md).

# Аутентификация

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

Для обновления информации в профиле Пользователя ЭСП МОНЕТА.РУ сервисом MonetaId маркетплейс должен сформировать специальный одноразовый токен.

## Формирование токена и подписи

Предварительные условия:

1. Необходимо пройти процедуру [регистрации маркетплейса](https://docs.payanyway.ru/marketplace/zaprosy-dlya-registracii-fl/identifikaciya-s-pomoshyu-monetaid/registraciya-marketpleisa) и получить `ApiKey` и `ApiSecret`.
2. Необходимо [установить доверительные отношения](https://docs.payanyway.ru/marketplace/zaprosy-dlya-registracii-fl/identifikaciya-s-pomoshyu-monetaid/ustanovlenie-doveriya) с сервисом MonetaId.

Для реализации алгоритма формирования единовременного токена использованы следующие стандарты:

1. RFC 3986 Uniform Resource Identifier (URI): Generic Syntax.
2. RFC 2104 HMAC: Keyed-Hashing for Message Authentication.
3. RFC 4648 The Base16, Base32, and Base64 Data Encodings.

Токен состоит из 2-х частей:

1. Информационное сообщение, содержащее ключевую информацию о маркетплейсе и Пользователе ЭСП МОНЕТА.РУ, служебную информацию.
2. Подпись/Хеш от информационного сообщения из п.1., и использование заранее полученного общего секрета - `ApiSecret`.

### Формирование информационного сообщения

Информационное сообщение состоит из набора ключ-значение, которые закодированы в соответствии с правилами URL-кодирования строк по RFC 3986. Пример:

```javascript
key1=someKey&key2=Some%20Key2&extraKey=100500
```

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

| Ключ                    | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Тип                | Пример               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------- |
| **callbackUrlOverride** | <p><strong>Опциональный параметр</strong> <br>для дев окружения: </p><p>Возможность задать <a href="https://docs.payanyway.ru/marketplace/zaprosy-dlya-registracii-fl/identifikaciya-s-pomoshyu-monetaid/webhook-o-statuse-identifikacii">тестовый callback урл,</a> отличный от того, что задан партнеру при <a href="https://docs.payanyway.ru/marketplace/zaprosy-dlya-registracii-fl/identifikaciya-s-pomoshyu-monetaid/registraciya-marketpleisa">регистрации</a>.</p> | Url Encoded String | *http%3A%2F%2Fya.ru* |
| **key**                 | ApiKey полученный при регистрации в MonetaId                                                                                                                                                                                                                                                                                                                                                                                                                                | Url Encoded String | *site-x*             |
| **mode**                | <p>Требуемый тип идентификации (any, simple, full):</p><p><strong>any</strong> - можно проводить уприд и мобильное id</p><p><strong>full</strong> - только мобильное id</p><p><strong>simple</strong> - только уприд</p>                                                                                                                                                                                                                                                    | Url Encoded String | *any*                |
| **nonce**               | Число, использующееся для невозможности повторного использования одного и того же токена (см. ниже)                                                                                                                                                                                                                                                                                                                                                                         | Число              | *10201010*           |
| **unitId**              | Идентификатор профиля/юнита в НКО "Монета", для которого необходимо провести  идентификацию.                                                                                                                                                                                                                                                                                                                                                                                | Число              | *100500*             |
| **userEmail**           | E-mail Пользователя в системе маркетплейса для оповещения о статусе идентификации                                                                                                                                                                                                                                                                                                                                                                                           | Url Encoded Email  | *john%40acme.com*    |

При формировании `nonce` удобно использовать текущее время в секундах на момент формирования токена. Каждый новый `nonce` в новом токене, формирующийся для данного `unitId` должен быть строго больше предыдущего **для данного юнита** (т.е. nonce должен строго монотонно возрастать), иначе он будет отброшен как некорректный.&#x20;

Пример итогового информационного сообщения:

```javascript
key=partner123&mode=any&nonce=1601375468244&unitId=544&userEmail=pertov%40acme.com
```

### Формирование подписи

После того, как информационное сообщение сформировано, необходимо вычислить подпись/хеш с использованием общего секрета - `ApiSecret`.&#x20;

Алгоритм формирования:

1. Вычислить HMAC-SHA512 хеш используя пару (информационное сообщение, секрет).
2. Полученный массив байт перевести в строку в шестнадцатеричном представлении.

```javascript
// message - инф. сообщение
// secret  - секрет/apiSecret

signatureBytes  = hmac_sha512(message, secret)
signatureString = bytesToHex(signatureBytes)
```

После того, как подпись в виде hex-строки сформирована, необходимо добавить ее к информационному сообщению с ключом signature:

key=partner123\&nonce=1601375468244\&unitId=544\&userEmail=<pertov@acme.co>&#x6D;**\&signature=7d7b968768f664bcdbd67bbd4e3f59347b300226734ade68bed660ab7794522fe0e3e66ecdb211f746dae1c44681a306ee221f8706c63195607e525e979360**

Финальным шагом необходимо полученную строку (информационное сообщение + подпись) закодировать при помощи base64, использовать при перенаправлении на виджет идентификации.

```javascript
// СЕРВЕР
// на стороне сервера формируем итоговый токен
message = "key=partner123&mode=any&nonce=1601375468244&unitId=544&userEmail=pertov%40acme.com&signature=abc8ed8919d89d98d"
token   = base64(message)

// БРАУЗЕР КЛИЕНТА
// делаем редирект в браузере клиента на указанный адрес с этим токеном

// DEV окружение
https://mid-ui.dev.mnxsc.tech/?token={{token}}

// PROD окружение
https://mid-ui.prod.mnxsc.tech/?token={{token}}


```