Настройка интеграции с Okta

Обзор

Okta может предоставлять нормализованные данные о жизненном цикле пользователей, аутентификации, MFA и административной активности. Проанализированные примеры:

account.locked — учетная запись заблокирована
mfa.factor.activated — активирует дополнительные факторы MFA
auth.login.failed — не удается войти в систему

Оба способа подключения считывают одни и те же два потока: каталог пользователей (/api/v1/users) и системный журнал (/api/v1/logs). См. раздел как данные интеграции становятся сигналами.

Выбор способа подключения

	Okta (SSWS)	Okta (OAuth 2.0)
Учетные данные	Токен API, который вы создаете в Admin Console	Идентификатор клиента и закрытый ключ JWK, которые вы генерируете и регистрируете
Настройка	Три шага, генерировать ключевой материал не требуется	Девять шагов, включая создание пары ключей RSA
Необходимая роль администратора	Администратор с правами только на чтение, назначенный владельцу токена	Администратор с правами только на чтение, назначенный приложению
Срок действия токена	Деактивируется после 30 дней без использования	Срока действия нет; ротацию пары ключей вы выполняете самостоятельно
Когда использовать	Рекомендуемый вариант для большинства организаций	Политика безопасности вашей организации запрещает долгоживущие токены API

Оба способа требуют одинакового доступа, поэтому выбор определяется порядком обращения с учетными данными, а не тем, какие данные может считывать платформа.

Вариант A — токен API (SSWS)

Рекомендуется.

Что необходимо для Living Security

Учетные данные	Описание
Ключ API	Токен API Okta. В диалоговом окне подключения это поле называется Ключ API
Поддомен тенанта	`<tenant>` в `<tenant>.okta.com` — только поддомен, а не полный URL

Предварительные требования

Чтобы создать пользователя служебной учетной записи, назначать роли администратора и создавать токены API, вы должны обладать ролью Super Administrator в Okta.

Создайте пользователя — владельца токена

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

В Admin Console перейдите в раздел Directory → People.
Нажмите Add person и создайте пользователя, например svc-livingsecurity@yourcompany.com.
Активируйте учетную запись.

Назначьте роль администратора с правами только на чтение

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

Перейдите в раздел Security → Administrators.
Нажмите Add administrator и выберите пользователя, созданного на предыдущем шаге.
Назначьте роль Read-only Administrator.
Сохраните изменения.

Если роль администратора не назначена, вызовы Okta Management API завершаются успешно с кодом 200 OK и возвращают пустой список. Никакого 403, который сообщал бы об отсутствии роли, нет — потоки просто остаются пустыми.

Создайте токен API

Войдите в Admin Console под пользователем служебной учетной записи, созданным на шаге 1. Токен наследует права той учетной записи, которая его создает.
Перейдите в раздел Security → API и откройте вкладку Tokens.
Нажмите Create token, задайте имя, например Living Security Platform, и нажмите Create token.
Скопируйте значение токена сейчас — Okta показывает его только один раз.

Okta деактивирует токен API после 30 дней без использования. Синхронизации в этой интеграции выполняются не реже одного раза в сутки, поэтому активное подключение поддерживает свой токен в рабочем состоянии. Если подключение остается приостановленным в течение месяца, потребуется новый токен.

Приведенный выше список адресов важен только в том случае, если ваша организация Okta ограничивает доступ к API по сетевым зонам. В большинстве организаций такого ограничения нет.

Определите поддомен тенанта

URL вашей Admin Console выглядит как https://acme-admin.okta.com. Поддомен тенанта — это acme — без суффикса -admin, без .okta.com и без https://.

Подключение к Okta (SSWS) выполнено.

Устранение неполадок

401 Unauthorized

Токен недействителен, был отозван или деактивирован после 30 дней неактивности. Создайте новый токен под пользователем служебной учетной записи и введите его в подключении заново.

Подключение установлено, но все потоки пусты

У владельца токена нет роли администратора. Назначьте служебной учетной записи роль Read-only Administrator (шаг 2) — при отсутствии роли API возвращает 200 OK с пустым списком, а не ошибку.

Синхронизации завершаются с ошибкой после кадровых изменений

Токен перестает работать, если пользователь, создавший его, деактивирован. Поэтому токен должен принадлежать служебной учетной записи, а не конкретному человеку.

Вариант B — служебное приложение OAuth 2.0

Используйте этот способ, если политика безопасности вашей организации не допускает долгоживущие токены API. Вместо токена используются идентификатор клиента и пара ключей RSA, которыми вы владеете. В платформе этому способу соответствует плитка Okta (OAuth 2.0) в разделе Настройки → Интеграции → Каталог. Для аутентификации в Okta с использованием Client Credentials вам потребуется следующее:

Идентификатор клиента — уникальный идентификатор вашего приложения Okta API Services.
Закрытый ключ (JWK) — закрытый ключ RSA в формате JSON Web Key, открытый ключ которого зарегистрирован в вашем приложении Okta.
Домен Okta — только поддомен вашего тенанта Okta (например, dev-12345678), а не полное имя хоста.
Области доступа (scopes) — список областей доступа Okta Management API, разделенных пробелами (например, okta.users.read okta.logs.read).

В этом руководстве описано, как создать приложение API Services в Okta с аутентификацией private_key_jwt.

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

У вас должна быть учетная запись Okta. Вы можете зарегистрировать бесплатную учетную запись разработчика на сайте developer.okta.com.

Шаг 1. Создание приложения Okta API Services

Войдите в Okta Admin Console.
На левой боковой панели перейдите в раздел Applications > Applications.
Нажмите Create App Integration.
В качестве метода входа выберите API Services и нажмите Далее.

Укажите имя приложения и нажмите Сохранить.
На вкладке General приложения найдите свой Идентификатор клиента — он понадобится на завершающем шаге.
Установите для Client authentication значение Public key / Private key. Области доступа okta.* поддерживаются только при использовании этого метода аутентификации.

Отключите Proof of possession (DPoP) — эта функция не поддерживается.

Приложение необходимо создавать как API Services.

Шаг 2. Создание и регистрация пары ключей RSA

Использование генератора ключей Okta

Okta может сгенерировать пару ключей RSA непосредственно в Admin Console:

В Admin Console откройте ваше приложение API Services.
Перейдите на вкладку General и прокрутите страницу до раздела PUBLIC KEYS.
Нажмите Add Key, затем выберите Generate new key.
Нажмите Сохранить — Okta сгенерирует пару ключей и один раз отобразит закрытый ключ (JWK).
Сразу скопируйте и сохраните JSON закрытого ключа — повторно он показан не будет.

Открытый ключ автоматически регистрируется в вашем приложении.

Скопируйте закрытый ключ JWK, прежде чем закрывать диалоговое окно. На завершающем шаге вставьте его в поле Private Key в Living Security Platform.

Создание собственного ключа

Для приложений API Services Okta использует private_key_jwt. Вы генерируете пару ключей RSA, регистрируете в Okta открытый ключ JWK и передаете закрытый ключ JWK в Living Security Platform. Сгенерируйте закрытый ключ JWK с помощью следующего скрипта Node.js (требуется Node.js 18+):

const { generateKeyPairSync } = require('crypto');
const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });

const privateJwk = privateKey.export({ format: 'jwk' });
const publicJwk  = publicKey.export({ format: 'jwk' });

// Assign a kid — must match between private and public JWK
const kid = require('crypto').randomUUID();
privateJwk.kid = kid;
publicJwk.kid  = kid;

console.log('=== PUBLIC JWK (upload to Okta) ===');
console.log(JSON.stringify(publicJwk, null, 2));
console.log('\n=== PRIVATE JWK (paste into the Living Security Platform) ===');
console.log(JSON.stringify(privateJwk));

Зарегистрируйте открытый ключ JWK в Okta:

В Admin Console откройте ваше приложение API Services.
Перейдите на вкладку General и прокрутите страницу до раздела PUBLIC KEYS.
Нажмите Add Key, вставьте JSON открытого ключа JWK, полученный в результате работы приведенного выше скрипта, и нажмите Сохранить.

В Living Security Platform вставляется закрытый ключ JWK. Он содержит весь ключевой материал (d, p, q, dp, dq, qi) и kid. Храните его в тайне.

Шаг 3. Определение домена Okta

Введите только поддомен вашего тенанта Okta — часть перед .okta.com.

В Admin Console в адресной строке браузера будет отображаться URL вида https://dev-12345678-admin.okta.com.
Ваш домен Okta — это только поддомен (например, dev-12345678), а не dev-12345678.okta.com.
Также вы можете перейти в раздел Settings > Account в Admin Console, чтобы найти свой домен Okta, а затем использовать его часть, соответствующую поддомену.

Шаг 4. Предоставление приложению областей доступа API

Okta требует указывать как минимум одну область доступа в каждом запросе токена. Прежде чем приложение сможет запрашивать определенные области доступа, они должны быть предоставлены:

В Admin Console перейдите в раздел Applications > Applications и откройте ваше приложение.
Перейдите на вкладку Okta API Scopes.
Предоставьте области доступа, необходимые для вашей интеграции: okta.users.read и okta.logs.read.

Полный список доступных областей доступа приведен в справочнике Okta Management API.

Шаг 5. Назначение роли администратора приложению

Одного предоставления областей доступа недостаточно: конечные точки Okta Management API (например, /api/v1/users) без уведомления возвращают пустой ответ 200 [], если у приложения нет роли администратора. Необходимо назначить как минимум роль Read-Only Administrator:

В Admin Console перейдите в раздел Security > Administrators (или откройте Applications > Applications > ваше приложение > Admin roles).
Нажмите Add administrator assignment и выберите ваше приложение API Services.

Назначьте роль Read-Only Administrator (или более высокую, в зависимости от необходимых областей доступа).
Нажмите Сохранить.

Если роль администратора не назначена, вызовы API завершаются успешно с кодом 200 OK, но возвращают пустые результаты, а ошибка 403, указывающая на проблему, отсутствует.

Шаг 6. Ввод учетных данных в Living Security Platform

Когда у вас есть идентификатор клиента, закрытый ключ (JWK), домен Okta и области доступа:

Откройте форму, в которой необходимо выполнить аутентификацию в Okta (Client Credentials).
Введите свой Идентификатор клиента.
Вставьте свой закрытый ключ (JWK) — полный объект JSON, полученный с помощью приведенного выше скрипта (в одну строку или в отформатированном виде).
Введите домен Okta в виде только поддомена тенанта (например, dev-12345678).
Введите области доступа в виде списка, разделенного пробелами (например, okta.users.read okta.logs.read).
Отправьте форму, после чего аутентификация должна быть выполнена успешно.

Подключение к Okta (Client Credentials) выполнено.

Отдельные части этой документации адаптированы из материалов Nango и используются на условиях Elastic License 2.0.

Интеграции