Руководство пользователя

Руководство пользователя

Управление учетными данными

Все запросы к API Epsilon должны быть аутентифицированы. При запуске проекта или создании приложения вы можете выбрать один из трех типов стратегий аутентификации:

  • API-токены доступа

  • Клиенты OAuth для одностраничных приложений (SPA)

  • Клиенты OAuth «машина-машина» (M2M)

Этот раздел позволяет вам легко создавать, редактировать и управлять Токены доступа к API, Клиенты SPA OAuth и Клиенты M2M OAuth. Он также содержит текущий API Base URL , который вы должны использовать во всех вызовах API. Узнайте больше базовым URL-адресе API.

Базовый URL-адрес API

API Base URL — это уникальный URL для каждого региона развертывания Epsilon. Вам следует использовать этот уникальный URL во всех вызовах API, иначе процесс аутентификации завершится неудачей.

Вы можете использовать этот раздел для копирования URL-адреса API Base.

Токены доступа к API

Все учетные данные разработчика можно создавать, редактировать и управлять ими в разделе Разработчикам > Учетные данные в Epsilon Workspace. Одним из наиболее распространенных типов учетных данных разработчика в Epsilon являются токены доступа API, управление которыми осуществляется на этой вкладке.

Что такое токены доступа API?

Токены доступа API — это самый простой способ авторизации разработчика или приложения для использования API Epsilon. Этот тип токенов является постоянным, то есть они полностью действительны, пока не будут удалены.

Токены доступа API могут быть ограничены:

  • Используйте только определенные API (разрешенные API)

  • Доступ только к определенным источникам данных для определенных соединений (Гранты)

  • Использоваться только определенными веб-сайтами (реферерами)

Управление токенами доступа API

После создания вашего первого токена доступа API вы сможете просмотреть список существующих токенов для вашего пользователя. Токены доступа API, созданные другими пользователями, не отображаются в этом списке.

Если вы создали токены программным способом с помощью API токенов, они также появятся в этом списке.

Создание токена доступа API
Если нажать «Создать новый», появится новый мастер со всеми необходимыми полями для создания нового токена доступа API:

Имя

Это уникальное имя, которое вы можете назначить своему токену, чтобы вы могли распознать его в контекстах, где отображаются другие токены, например, в списке токенов в Разработчикам. Если вы не добавите свое имя, Epsilon сгенерирует его, например, “tk_shortid”

Разрешенные API
Ваш токен сможет получить доступ только к тем API, которые вы здесь укажете.

Гранты
После того, как вы укажете один или несколько API, вам нужно будет включить по крайней мере один грант для работы с этими API. Как уже обсуждалось, гранты — это конкретные источники данных, к которым этот токен сможет получить доступ, и они привязаны к определенным соединениям. Выберите соединение для вашего гранта, и вы увидите три типа грантов:

  • Источник таблицы или набора плиток: выберите определенные таблицы или наборы плиток в обозревателе данных или вставьте полное имя, если вы его знаете (например: my-project.dataset.table).

  • Источник SQL-запроса: напишите или вставьте в редактор SQL конкретный запрос, который этот токен сможет использовать. Это мощно в сочетании с собственными параметрами SQL хранилища данных, как описано в нашей документации API.

  • Все источники: выберите этот параметр, если хотите, чтобы ваш токен имел доступ ко всем данным, доступным для этого соединения, включая будущие таблицы.

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

Для этого просто укажите список URL-адресов разрешенных рефереров , разделенных запятыми. Все запросы, использующие этот токен с этих URL-адресов, будут считаться действительными, а все остальные запросы будут отклонены.

Используя ваш новый токен
Чтобы использовать свой токен, просто вернитесь к списку доступных токенов, наведите указатель мыши на токен и нажмите «Копировать токен» . Ваш токен будет скопирован в буфер обмена, и вы сможете просто использовать его в вызовах API.

Редактирование и удаление токенов
В любой момент вы можете редактировать или удалять существующие токены. Если вы редактируете токен, вы можете изменить любое свойство, от добавления дополнительных грантов до удаления разрешенных рефереров.

Клиенты SPA OAuth

Все учетные данные разработчика можно создавать, редактировать и управлять ими в разделе Разработчики > Учетные данные в Epsilon Workspace. Одним из наиболее распространенных типов учетных данных разработчика в Epsilon являются клиенты SPA OAuth, управление которыми осуществляется на этой вкладке

Что такое клиенты SPA OAuth?
SPA OAuth Client означает Single-Page Application OAuth Client. Это учетные данные разработчика, которые позволяют вам создавать возможности аутентификации с использованием учетных данных Epsilon ( например: вход с помощью Epsilon ) в клиентских приложениях Javascript. После того, как конечный пользователь успешно пройдет аутентификацию с использованием своих учетных данных Epsilon, ваше приложение сможет использовать токен доступа OAuth .

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

Управление вашими клиентами SPA OAuth
После создания первого клиента SPA OAuth вы сможете просмотреть список существующих клиентов для своего пользователя. Клиенты SPA OAuth, созданные другими пользователями, не отображаются в этом списке.

Создание нового клиента SPA OAuth
Нажмите «Создать новый > Клиент SPA OAuth», чтобы начать. Вам нужно будет предоставить:

  • Имя: Это чисто информативное имя. Оно будет использоваться для идентификации этого клиента SPA OAuth в других списках.

  • URL входа в приложение: Это должен быть URL, который ваши конечные пользователи будут использовать для входа в ваше приложение. Например: https://my-custom-epsilon-app.ru/

В большинстве случаев такой настройки должно быть достаточно, поскольку URL-адрес входа в приложение уже содержит достаточно информации для обработки всех потоков аутентификации (обратный вызов, выход из системы, источники…). Однако, сняв флажок «Использовать URL-адреса выхода из системы/обратного вызова и источники по умолчанию», вы можете указать отдельные наборы URL-адресов для каждого потока OAuth:

  • Разрешенные URL-адреса обратного вызова: после успешного входа с использованием этого клиента SPA OAuth это список URL-адресов, на которые Epsilon разрешено перенаправлять пользователя.

  • Разрешенные URL-адреса для выхода из системы: после успешного выхода из системы с помощью этого клиента SPA OAuth это список URL-адресов, на которые Epsilon разрешено перенаправлять пользователя.

  • Разрешенные веб-источники: Epsilon будет принимать только запросы на авторизацию, использующие этот клиент SPA OAuth, поступающие из этого списка URL-адресов.

  • Разрешенные источники (CORS): API Epsilon будут принимать только запросы (аутентифицированные с использованием этого клиента SPA OAuth), поступающие из этого списка URL-адресов.

Когда закончите, нажмите «Сохранить изменения». Вы вернетесь к списку учетных данных.

Использование нового клиента SPA OAuth
Чтобы использовать новый клиент SPA OAuth в приложении, вам понадобятся как идентификатор клиента, так и секретный ключ клиента:

Client ID: это уникальный идентификатор — открытый ключ для этого клиента OAuth. Его можно скопировать напрямую из списка учетных данных.

Client Secret: это секретный ключ. Любой, у кого есть доступ к этому Client Secret и Client ID, может использовать этот клиент OAuth.

Оба значения можно получить, нажав кнопку «Просмотреть или изменить учетные данные» в контекстном меню.

После просмотра или редактирования существующего клиента SPA OAuth, идентификатор клиента и секрет клиента будут доступны для копирования. Секрет клиента будет скрыт на экране по умолчанию, чтобы минимизировать риски.

Вы также можете внести любые необходимые изменения в клиент SPA OAuth, включая изменение имени, URL-адреса или расширенных URL-адресов выхода из системы/обратного вызова/источника.

Если на предыдущем шаге вы выбрали «Удалить» своего клиента SPA OAuth, вы получите предупреждение об этом действии и запрос на подтверждение.

Клиенты M2M OAuth

Все учетные данные разработчика можно создавать, редактировать и управлять ими в разделе Разработчики > Учетные данные в рабочей области Epsilon. Одним из наиболее распространенных типов учетных данных разработчика в Epsilon являются клиенты M2M OAuth, управление которыми осуществляется на этой вкладке.

Что такое клиенты M2M OAuth?
M2M OAuth Client означает Machine-to-machine OAuth Client. Это учетные данные разработчика, которые позволяют вам создавать аутентификацию без необходимости ввода данных пользователем. Это полезно в сценариях, где нет конечного пользователя-человека (например, приложение только для бэкенда) или при интеграции Epsilon в существующие приложения, которые не используют учетные данные Epsilon. Используя ваш M2M OAuth Client, ваше приложение может запрашивать токен доступа OAuth по требованию.

Этот токен доступа OAuth имеет те же разрешения, что и владелец клиента M2M OAuth, и может использоваться для выполнения любых запросов API от имени этого пользователя, например, для загрузки карт, запросов или запуска рабочих процессов.

Распространенной стратегией для гранулярной, надежной аутентификации является использование полученного токена доступа OAuth для программного (серверного) создания токенов доступа API с определенными грантами данных с использованием API токенов. Эти токены доступа API затем могут использоваться конечным приложением на стороне клиента.

Управление клиентами M2M OAuth
После создания первого клиента M2M OAuth вы сможете просмотреть список существующих клиентов для вашего пользователя. Клиенты M2M OAuth, созданные другими пользователями, не отображаются в этом списке.

Создание нового клиента M2M OAuth
Нажмите «Создать новый > Клиент M2M OAuth», чтобы начать. Вам нужно будет предоставить только:

  • Имя: Это чисто информативное имя. Оно будет использоваться для идентификации этого M2M OAuth Client в других списках.

Использование нового клиента M2M OAuth
Чтобы использовать новый клиент M2M OAuth в приложении, вам понадобятся как идентификатор клиента, так и секретный ключ клиента:

  • Client ID: это уникальный идентификатор — открытый ключ для этого клиента OAuth. Его можно скопировать напрямую из списка учетных данных.

  • Client Secret: это секретный ключ. Любой, у кого есть доступ к этому Client Secret и Client ID, может использовать этот клиент OAuth.

Оба значения можно получить, нажав кнопку «Просмотреть или изменить учетные данные» в контекстном меню.

После просмотра или редактирования существующего клиента M2M OAuth, идентификатор клиента и секрет клиента будут доступны для копирования. Секрет клиента будет скрыт на экране по умолчанию, чтобы минимизировать риски.

Вы также можете внести любые необходимые изменения в имя клиента M2M OAuth.

Если на предыдущем шаге вы выбрали «Удалить» своего клиента M2M OAuth, вы получите предупреждение об этом действии и запрос на подтверждение.