Konfiguracja integracji z Okta - Living Security Platform

Omówienie

Okta może dostarczać znormalizowane dane o cyklu życia użytkowników, uwierzytelnianiu, MFA i aktywności administracyjnej. Sprawdzone przykłady obejmują:

account.locked — konto zostało zablokowane
mfa.factor.activated — aktywuje dodatkowe czynniki MFA
auth.login.failed — nie może się zalogować

Obie metody połączenia odczytują te same dwa strumienie — katalog użytkowników (/api/v1/users) oraz dziennik systemowy (/api/v1/logs). Zobacz jak dane z integracji stają się sygnałami.

Wybór metody połączenia

	Okta (SSWS)	Okta (OAuth 2.0)
Poświadczenia	Token API tworzony w konsoli administracyjnej (Admin Console)	Identyfikator klienta oraz prywatny klucz JWK, które samodzielnie generujesz i rejestrujesz
Konfiguracja	Trzy kroki, bez generowania materiału kluczowego	Dziewięć kroków, w tym para kluczy RSA
Wymagana rola administratora	Administrator tylko do odczytu, przypisany do właściciela tokenu	Administrator tylko do odczytu, przypisany do aplikacji
Okres ważności tokenu	Jest dezaktywowany po 30 dniach bez użycia	Bez wygaśnięcia; rotacja pary kluczy należy do Ciebie
Kiedy wybrać	Zalecana ścieżka dla większości organizacji	Polityka bezpieczeństwa zabrania używania długoterminowych tokenów API

Obie metody wymagają tego samego dostępu, więc wybór dotyczy sposobu obsługi poświadczeń, a nie tego, co platforma może odczytać.

Opcja A — token API (SSWS)

Zalecana.

Czego potrzebuje Living Security

Poświadczenie	Opis
Klucz API	Token API Okta. W oknie połączenia to pole ma etykietę Klucz API
Subdomena dzierżawy	`<tenant>` w `<tenant>.okta.com` — sama subdomena, a nie pełny adres URL

Wymagania wstępne

Musisz mieć w Okta rolę Super Administrator, aby utworzyć użytkownika konta usługi, przypisać role administratora i tworzyć tokeny API.

Utwórz użytkownika, który będzie właścicielem tokenu

Token API Okta ma uprawnienia użytkownika, który go utworzył, i przestaje działać, jeśli ten użytkownik zostanie dezaktywowany. Utwórz dedykowane konto usługi zamiast używać osobistego konta administratora, aby połączenie przetrwało zmiany kadrowe.

W konsoli administracyjnej (Admin Console) przejdź do Directory → People.
Kliknij Add person i utwórz użytkownika, na przykład svc-livingsecurity@yourcompany.com.
Aktywuj konto.

Przypisz rolę administratora tylko do odczytu

Platforma wyłącznie odczytuje dane. Przyznanie uprawnień wykraczających poza odczyt nadaje tokenowi uprawnienia, z których nigdy nie korzysta.

Przejdź do Security → Administrators.
Kliknij Add administrator i wybierz użytkownika z poprzedniego kroku.
Przypisz rolę Read-only Administrator.
Zapisz.

Bez roli administratora wywołania Okta Management API kończą się powodzeniem z kodem 200 OK i zwracają pustą listę. Nie ma 403 informującego o braku roli — strumienie po prostu pozostają puste.

Utwórz token API

Zaloguj się do konsoli administracyjnej (Admin Console) jako użytkownik konta usługi z kroku 1. Token dziedziczy uprawnienia konta, które go tworzy.
Przejdź do Security → API i otwórz kartę Tokens.
Kliknij Create token, nadaj mu nazwę, na przykład Living Security Platform, a następnie kliknij Create token.
Skopiuj wartość tokenu teraz — Okta wyświetla ją tylko raz.

Okta dezaktywuje token API po 30 dniach bez użycia. Synchronizacje w tej integracji są uruchamiane co najmniej raz dziennie, więc aktywne połączenie utrzymuje ważność własnego tokenu. Połączenie wstrzymane na miesiąc wymaga nowego tokenu.

Powyższa lista adresów ma znaczenie tylko wtedy, gdy Twoja organizacja Okta ogranicza dostęp do API za pomocą stref sieciowych (network zones). Większość organizacji tego nie robi.

Znajdź subdomenę dzierżawy

Adres URL Twojej konsoli administracyjnej wygląda jak https://acme-admin.okta.com. Subdomena dzierżawy to acme — bez sufiksu -admin, bez .okta.com i bez https://.

Połączenie z Okta (SSWS) zostało skonfigurowane.

Rozwiązywanie problemów

401 Unauthorized

Token jest nieprawidłowy, został unieważniony lub został dezaktywowany po 30 dniach braku aktywności. Utwórz nowy token jako użytkownik konta usługi i wprowadź go ponownie w połączeniu.

Połączono, ale wszystkie strumienie są puste

Właściciel tokenu nie ma roli administratora. Przypisz kontu usługi rolę Read-only Administrator (krok 2) — gdy brakuje roli, API zwraca 200 OK z pustą listą zamiast błędu.

Synchronizacje kończą się błędem po zmianie kadrowej

Token przestaje działać, jeśli użytkownik, który go utworzył, zostanie dezaktywowany. Dlatego token powinien należeć do konta usługi, a nie do osoby.

Opcja B — aplikacja usługowa OAuth 2.0

Użyj tej metody, jeśli Twoja polityka bezpieczeństwa nie zezwala na długoterminowe tokeny API. Zastępuje ona token identyfikatorem klienta i parą kluczy RSA, których jesteś właścicielem. W platformie jest to kafelek Okta (OAuth 2.0) w sekcji Ustawienia → Integracje → Katalog. Aby uwierzytelnić się w Okta za pomocą Client Credentials, potrzebujesz następujących elementów:

Identyfikator klienta — unikalny identyfikator Twojej aplikacji Okta API Services.
Klucz prywatny (JWK) — prywatny klucz RSA w formacie JSON Web Key, którego klucz publiczny jest zarejestrowany w Twojej aplikacji Okta.
Domena Okta — wyłącznie subdomena Twojej dzierżawy Okta (np. dev-12345678), a nie pełna nazwa hosta.
Zakresy (Scopes) — lista zakresów Okta Management API oddzielonych spacjami (np. okta.users.read okta.logs.read).

Ten przewodnik przeprowadzi Cię przez tworzenie aplikacji API Services w Okta z uwierzytelnianiem private_key_jwt.

Wymagania wstępne:

Musisz mieć konto Okta. Możesz zarejestrować bezpłatne konto deweloperskie na stronie developer.okta.com.

Krok 1: Tworzenie aplikacji Okta API Services

Zaloguj się do konsoli administracyjnej Okta (Okta Admin Console).
W lewym pasku bocznym przejdź do Applications > Applications.
Kliknij Create App Integration.
Jako metodę logowania wybierz API Services i kliknij Dalej.

Nadaj aplikacji nazwę i kliknij Zapisz.
Na karcie General aplikacji znajdź swój Identyfikator klienta — będzie potrzebny w ostatnim kroku.
Ustaw opcję Client authentication na Public key / Private key. Zakresy okta.* są obsługiwane wyłącznie przy tej metodzie uwierzytelniania.

Wyłącz Proof of possession (DPoP) — ta funkcja nie jest obsługiwana.

Aplikacja musi zostać utworzona jako API Services.

Krok 2: Generowanie i rejestrowanie pary kluczy RSA

Użyj generatora kluczy Okta

Okta może wygenerować parę kluczy RSA bezpośrednio w konsoli administracyjnej (Admin Console):

W konsoli administracyjnej otwórz swoją aplikację API Services.
Przejdź na kartę General i przewiń do sekcji PUBLIC KEYS.
Kliknij Add Key, a następnie wybierz Generate new key.
Kliknij Zapisz — Okta generuje parę kluczy i jednorazowo wyświetla klucz prywatny (JWK).
Natychmiast skopiuj i zapisz kod JSON klucza prywatnego — nie zostanie wyświetlony ponownie.

Klucz publiczny jest automatycznie rejestrowany w Twojej aplikacji.

Skopiuj prywatny klucz JWK przed zamknięciem okna dialogowego. Wklej go w ostatnim kroku do pola Klucz prywatny w Living Security Platform.

Utwórz własny klucz

Okta używa private_key_jwt dla aplikacji API Services. Generujesz parę kluczy RSA, rejestrujesz w Okta publiczny klucz JWK i przekazujesz prywatny klucz JWK do Living Security Platform. Wygeneruj prywatny klucz JWK za pomocą poniższego skryptu Node.js (wymagany 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));

Zarejestruj publiczny klucz JWK w Okta:

W konsoli administracyjnej otwórz swoją aplikację API Services.
Przejdź na kartę General i przewiń do sekcji PUBLIC KEYS.
Kliknij Add Key, wklej kod JSON publicznego klucza JWK wygenerowany przez powyższy skrypt i kliknij Zapisz.

Do Living Security Platform wklejasz prywatny klucz JWK. Zawiera on cały materiał kluczowy (d, p, q, dp, dq, qi) oraz kid. Zachowaj go w tajemnicy.

Krok 3: Znajdowanie domeny Okta

Wprowadź wyłącznie subdomenę swojej dzierżawy Okta — część przed .okta.com.

W konsoli administracyjnej pasek adresu przeglądarki wyświetli adres URL podobny do https://dev-12345678-admin.okta.com.
Twoja Domena Okta to wyłącznie subdomena (np. dev-12345678), a nie dev-12345678.okta.com.
Możesz też przejść w konsoli administracyjnej do Ustawienia > Account, aby znaleźć swoją domenę Okta, a następnie użyć jej części będącej subdomeną.

Krok 4: Przyznawanie zakresów API aplikacji

Okta wymaga co najmniej jednego zakresu w każdym żądaniu tokenu. Zanim aplikacja będzie mogła żądać określonych zakresów, muszą one zostać przyznane:

W konsoli administracyjnej przejdź do Applications > Applications i otwórz swoją aplikację.
Kliknij kartę Okta API Scopes.
Przyznaj zakresy wymagane przez integrację: okta.users.read i okta.logs.read.

Pełną listę dostępnych zakresów znajdziesz w dokumentacji Okta Management API.

Krok 5: Przypisywanie roli administratora do aplikacji

Samo przyznanie zakresów nie wystarcza — punkty końcowe Okta Management API (np. /api/v1/users) po cichu zwracają pustą odpowiedź 200 [], jeśli aplikacja nie ma roli administratora. Musisz przypisać co najmniej Read-Only Administrator:

W konsoli administracyjnej przejdź do Security > Administrators (lub do Applications > Applications > Twoja aplikacja > Admin roles).
Kliknij Add administrator assignment i wybierz swoją aplikację API Services.

Przypisz rolę Read-Only Administrator (lub wyższą, w zależności od potrzebnych zakresów).
Kliknij Zapisz.

Bez roli administratora wywołania API kończą się powodzeniem z kodem 200 OK, ale zwracają puste wyniki, a błąd 403 nie informuje o problemie.

Krok 6: Wprowadzanie poświadczeń w Living Security Platform

Gdy masz już swój Identyfikator klienta, Klucz prywatny (JWK), Domenę Okta i Zakresy:

Otwórz formularz, w którym chcesz uwierzytelnić się w Okta (Client Credentials).
Wprowadź swój Identyfikator klienta.
Wklej swój Klucz prywatny (JWK) — pełny obiekt JSON ze skryptu powyżej (w jednym wierszu lub sformatowany).
Wprowadź swoją Domenę Okta jako samą subdomenę dzierżawy (np. dev-12345678).
Wprowadź Zakresy jako listę oddzieloną spacjami (np. okta.users.read okta.logs.read).
Prześlij formularz, a uwierzytelnianie powinno zakończyć się powodzeniem.

Połączenie z Okta (Client Credentials) zostało skonfigurowane.

Fragmenty tej dokumentacji zostały zaadaptowane z Nango i są używane na podstawie Elastic License 2.0.

Integracje