Авторизация

Любое взаимодействие с описанными в данном руководстве продуктами должно быть авторизовано.

Для начала необходимо отправить запрос на license@spatium.net, чтобы получить у команды Spatium ключ клиента (merchantKey).

Далее авторизация регулируется отдельным облачным сервисом, который позволяет клиентам регистрировать аккаунты своих пользователей, управлять факторами безопасности и получать токены для совершения различных действий.

Токены

Детальное описание сервиса и токенов доступно в соответствующем разделе документации облачных сервисов. Для ознакомления с продуктами достаточно понимания основного принципа работы с токеном доступа (permissionToken) и токеном обновления (refreshToken).

Токен доступа имеет короткое время жизни и позволяет выполнять действия, разрешенные определенным списком прав доступа, которые указываются при запросе на генерацию этого токена.

Токен обновления имеет длинное время жизни и хранит в себе все необходимые данные для генерации нового токена доступа.

Таким образом, единожды запросив эту пару токенов с указанием учетных данных, можно обновлять токен доступа без предъявления учетных данных в последующих запросах (в рамках времени жизни токена обновления).

Облако

Авторизация работы с облачными сервисами осуществляется отправкой в каждом запросе заголовка Authorization: Bearer token, где token - полученный с помощью сервиса авторизации токен доступа. Данный токен возможно получить двумя способами:

• как сервис - с использованием эндпоинта /api/permission/issue-by-key, необходимо предоставить ключ клиента merchantKey. Эту схему нужно использовать для отправки не связанных с конкретным аккаунтом пользователя запросов к апи с бэкенда клиента. Также эту схему можно использовать для ознакомления с продуктами облака.
• как аккаунт пользователя - с использованием эндпоинта /api/permission/issue-by-factors, необходимо предоставить токен безопасности (securityToken), предварительно запрошенный для конкретного аккаунта пользователя с предъявлением требуемых факторов безопасности в соответствующем запросе секции /api/security-factor или же полученный непосредственно при регистрации аккаунта пользователя. Эту схему нужно использовать для отправки связанных с конкретным аккаунтом пользователя запросов к апи.

Для базового ознакомления с продуктами облака удобно использовать первый вариант, так как он не требует предварительной регистрации аккаунта пользователя на сервисе авторизации и получения для него токена безопасности. Достаточно периодически получать токен доступа с предъявлением merchantKey и использовать его для запросов к облачным сервисам.

curl --location --request POST 'https://cloud.spatium.net/authorization/v1/api/permission/issue-by-key' \
--header 'Content-Type: application/json' \
--data-raw '{
"tokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"permissions": [
"read"
],
"payload": "string",
"merchantKey": merchantKey
}'

curl --location --request GET 'https://cloud.spatium.net/address-info-btc-like/v1/api/eth/?address=0x38e9a6dababD958080D1fB58FB18EFF76F6701bD' \
--header 'Authorization: Bearer PermissionToken'

import { AuthorizationSession } from '@spatium/signer-client';
import { uuid, randomBytes } from '@spatium/sdk';
import axios from 'axios';

const auth = new AuthorizationSession(`https://cloud.spatium.net/authorization/v1`, uuid(randomBytes), ['read', 'secret']);

const { data: { securityToken } } = await axios.post(
  `https://cloud.spatium.net/authorization/v1/api/security-factor/credentials`, 
  { username: 'username', password: 'password' },
  { 
    headers: { 
      'request-id': uuid(randomBytes), 
    }, 
  },
).then(({ data }) => data);

await auth.establish([securityToken]);


const token = await auth.getPermissionToken();

const result = await axios.get(
  `https://cloud.spatium.net/address-info-btc-like/v1/api/btc`, 
  { 
    params: { address: 'bc1qe24ajem88k5jgwl7ntqhyxmtgh59wuypl9ag4c' }, 
    headers: { 
      'request-id': uuid(randomBytes), 
      'authorization': `Bearer ${token}`, 
    }, 
  },
).then((result) => result.data);

СДК

Авторизация работы с СДК осуществляется с помощью модуля AuthorizationSession пакета Spatium Signer Client.

Предварительно необходимо с бэкенда клиента зарегистрировать аккаунт пользователя на облачном сервисе авторизации с предоставлением требуемых факторов безопасности с помощью соответствующего эндпоинта секции /api/account (см. раздел Регистрация аккаунта пользователя). А также выпустить для него токен безопасности с предъявлением требуемых факторов безопасности в соответствующем запросе секции /api/security-factor (или же применить полученный непосредственно при регистрации аккаунта пользователя токен безопасности).

Затем после инициализации экземпляра AuthorizationSession необходимо вызвать метод establish с использованием токена безопасности (для выпуска токенов доступа и обновления). Далее доступны любые вызовы методов СДК в авторизованном режиме, получение и обновление токена доступа при этих вызовах происходят автоматически.

import { AuthorizationSession,ServiceStorage, SignerClient } from '@spatium/signer-client';
import {
uuid,
randomBytes,
syncDistributedEcdsaKey,
MemoryStorageDriver,
SpatiumCrypto,
} from '@spatium/sdk';
import axios from 'axios';

const auth = new AuthorizationSession(`https://cloud.spatium.net/authorization/v1`, uuid(randomBytes), ['read', 'secret']);

const cache = new MemoryStorageDriver();
const storage = new ServiceStorage(`https://cloud.spatium.net/storage/v1`, auth);

const crypto = new SpatiumCrypto(cache, storage);
const signer = new SignerClient(`https://cloud.spatium.net/signer/v1`, auth, crypto, 15 * 1000);

const { data: { securityToken } } = await axios.post(
  `https://cloud.spatium.net/authorization/v1/api/security-factor/credentials`, 
  { username: username, password: password },
  { headers: { 
    'request-id': uuid(randomBytes), 
    }, 
  },
).then(({ data }) => data);

await auth.establish([securityToken]);

const secretId = 'uuidv4';
const syncSessionId = 'uuidv4';

try {
  await signer.connect(10 * 1000);

await signer.generateDistributedSecret(secretId);

const publicKey = await syncDistributedEcdsaKey(signer, secretId, syncSessionId, 'secp256k1', 0, 0);
} finally {
  await signer.disconnect();
}

ВАЖНО! При использовании модуля AuthorizationSession в режиме ожидания не происходит периодического обновления токенов доступа и безопасности. Поэтому срок действия сессии неминуемо истечет по окончанию времени жизни токена обновления. Однако, можно периодически вызывать метод refresh или же вызвать метод establish по истечению срока действия сессии.

Регистрация аккаунта пользователя

Процесс регистрации аккаунта пользователя должен осуществляться с бэкенда клиента.

Сначала необходимо получить токен доступа с правом на создание аккаунта пользователя (merchantKey должен иметь соответствующие права доступа) с помощью эндпоинта /api/permission/issue-by-key. Для обеспечения безопасности в этом запросе следует использовать статический идентификатор токена, соответствующий сервису бэкенда клиента.

import axios from 'axios';

const { data: { permissionToken: { permissionToken } } } = await axios.post(
  `https://cloud.spatium.net/authorization/v1/api/permission/issue-by-key`, 
  { 
    tokenId: '3fa85f64-5717-4562-b3fc-2c963f66afa6', 
    permissions: [
      'register'
    ], 
    merchantKey: 'merchantKey',
  }, 
  { 
    headers: { 
      'request-id': uuid(randomBytes), 
    }, 
  },
).then(({ data }) => data);

Далее с полученным токеном доступа можно регистрировать аккаунт пользователя с предоставлением необходимых факторов безопасности с помощью соответствующего эндпоинта секции /api/account

import axios from 'axios';

const { data: { securityToken } } = await axios.post(
  `https://cloud.spatium.net/authorization/v1/api/account/credentials`, 
  { 
    username: "CoolUser", 
    password: "A.1234567", 
  }, 
  { 
    headers: { 
      'request-id': uuid(randomBytes), 
    }, 
  },
).then(({ data }) => data);

Для удобства последующего получения токена доступа для зарегистрированного аккаунта пользователя эндпоинты секции /api/account сразу возвращают токен безопасности.