Okta-integratie instellen

Overzicht

Okta kan genormaliseerde gegevens over de gebruikerslevenscyclus, authenticatie, MFA en beheerdersactiviteit aanleveren. Beoordeelde voorbeelden zijn onder andere:

account.locked — account vergrendeld
mfa.factor.activated — activeert extra MFA-factoren
auth.login.failed — kan niet inloggen

Beide verbindingsmethoden lezen dezelfde twee streams: de gebruikersmap (/api/v1/users) en het systeemlogboek (/api/v1/logs). Zie hoe integratiegegevens signalen worden.

Kies een verbindingsmethode

	Okta (SSWS)	Okta (OAuth 2.0)
Referentie	Een API-token dat u aanmaakt in de Admin Console	Een klant-ID en een privé-JWK die u genereert en registreert
Installatie	Drie stappen, geen sleutelmateriaal om te genereren	Negen stappen, inclusief een RSA-sleutelpaar
Vereiste beheerdersrol	Alleen-lezenbeheerder, toegewezen aan de eigenaar van het token	Alleen-lezenbeheerder, toegewezen aan de applicatie
Levensduur van het token	Wordt gedeactiveerd na 30 dagen zonder gebruik	Geen vervaldatum; het roteren van het sleutelpaar is uw verantwoordelijkheid
Gebruik deze methode wanneer	Dit is het aanbevolen pad voor de meeste organisaties	Uw beveiligingsbeleid langlevende API-tokens verbiedt

Beide methoden vereisen dezelfde toegang, dus de keuze gaat over het beheer van referenties en niet over wat het platform kan lezen.

Optie A — API-token (SSWS)

Aanbevolen.

Wat Living Security nodig heeft

Referentie	Beschrijving
API-sleutel	Een Okta API-token. In het verbindingsvenster heet dit veld API-sleutel
Tenant-subdomein	De `<tenant>` in `<tenant>.okta.com` — alleen het subdomein, niet de volledige URL

Vereisten

U moet Super Administrator in Okta zijn om een serviceaccountgebruiker aan te maken, beheerdersrollen toe te wijzen en API-tokens aan te maken.

Maak een gebruiker aan die eigenaar van het token wordt

Een Okta API-token heeft de machtigingen van de gebruiker die het heeft aangemaakt en werkt niet meer als die gebruiker wordt gedeactiveerd. Maak daarom een speciaal serviceaccount aan in plaats van een persoonlijk beheerdersaccount te gebruiken, zodat de verbinding personeelswisselingen overleeft.

Ga in de Admin Console naar Directory → People.
Klik op Add person en maak een gebruiker aan, bijvoorbeeld svc-livingsecurity@yourcompany.com.
Activeer het account.

Wijs de rol Alleen-lezenbeheerder toe

Het platform leest alleen. Als u meer dan leestoegang verleent, krijgt het token machtigingen die nooit worden gebruikt.

Ga naar Security → Administrators.
Klik op Add administrator en selecteer de gebruiker uit de vorige stap.
Wijs de rol Read-only Administrator toe.
Sla op.

Zonder beheerdersrol slagen aanroepen van de Okta Management API met 200 OK en leveren ze een lege lijst op. Er is geen 403 die aangeeft dat de rol ontbreekt — de streams blijven eenvoudig leeg.

Maak het API-token aan

Meld u aan bij de Admin Console als de serviceaccountgebruiker uit stap 1. Het token neemt de rechten over van het account dat het aanmaakt.
Ga naar Security → API en open het tabblad Tokens.
Klik op Create token, geef het een naam zoals Living Security Platform en klik op Create token.
Kopieer nu de tokenwaarde — Okta toont deze slechts één keer en daarna nooit meer.

Okta deactiveert een API-token na 30 dagen zonder gebruik. De synchronisaties in deze integratie draaien minimaal één keer per dag, zodat een actieve verbinding haar eigen token in leven houdt. Een verbinding die een maand gepauzeerd blijft, heeft een nieuw token nodig.

De bovenstaande adreslijst is alleen van belang als uw Okta-org API-toegang beperkt via een netwerkzone. De meeste orgs doen dat niet.

Zoek uw tenant-subdomein

De URL van uw Admin Console ziet er als volgt uit: https://acme-admin.okta.com. Het tenant-subdomein is acme — zonder het achtervoegsel -admin, zonder .okta.com en zonder https://.

U bent nu verbonden met Okta (SSWS).

Probleemoplossing

401 Unauthorized

Het token is ongeldig, is ingetrokken of is na 30 dagen inactiviteit gedeactiveerd. Maak als serviceaccountgebruiker een nieuw token aan en voer dit opnieuw in bij de verbinding.

Verbonden, maar alle streams zijn leeg

De eigenaar van het token heeft geen beheerdersrol. Wijs Read-only Administrator toe aan het serviceaccount (stap 2) — de API retourneert 200 OK met een lege lijst in plaats van een foutmelding als de rol ontbreekt.

Synchronisaties mislukken na een personeelswijziging

Het token werkt niet meer als de gebruiker die het heeft aangemaakt wordt gedeactiveerd. Daarom moet het token eigendom zijn van een serviceaccount en niet van een persoon.

Optie B — OAuth 2.0-serviceapplicatie

Gebruik deze methode als uw beveiligingsbeleid geen langlevende API-tokens toestaat. Hierbij wordt het token vervangen door een Klant-ID en een RSA-sleutelpaar waarvan u zelf eigenaar bent. In het platform is dit de tegel Okta (OAuth 2.0), onder Instellingen → Integraties → Catalog. Om met Okta te authenticeren via Client Credentials hebt u het volgende nodig:

Klant-ID - Een unieke identificatie voor uw Okta API Services-applicatie.
Private Key (JWK) - De RSA-privésleutel in JSON Web Key-indeling, waarvan de publieke sleutel is geregistreerd in uw Okta-applicatie.
Okta Domain - Alleen het subdomein van uw Okta-tenant (bijv. dev-12345678), niet de volledige hostnaam.
Scopes - Een door spaties gescheiden lijst met scopes van de Okta Management API (bijv. okta.users.read okta.logs.read).

Deze handleiding begeleidt u bij het aanmaken van een API Services-applicatie in Okta met private_key_jwt-authenticatie.

Vereisten:

U moet een Okta-account hebben. Meld u aan voor een gratis ontwikkelaarsaccount via developer.okta.com.

Stap 1: Uw Okta API Services-applicatie aanmaken

Log in bij uw Okta Admin Console.
Navigeer in de linkerzijbalk naar Applications > Applications.
Klik op Create App Integration.
Selecteer API Services als aanmeldmethode en klik op Volgende.

Geef uw applicatie een naam en klik op Opslaan.
Zoek op het tabblad General van de applicatie uw Klant-ID — die hebt u nodig in de laatste stap.
Stel Client authentication in op Public key / Private key. okta.*-scopes worden alleen met deze authenticatiemethode ondersteund.

Schakel Proof of possession (DPoP) uit — dit wordt niet ondersteund.

De applicatie moet worden aangemaakt als API Services.

Stap 2: Uw RSA-sleutelpaar genereren en registreren

De sleutelgenerator van Okta gebruiken

Okta kan het RSA-sleutelpaar rechtstreeks in de Admin Console voor u genereren:

Open in de Admin Console uw API Services-applicatie.
Ga naar het tabblad General en scrol naar de sectie PUBLIC KEYS.
Klik op Add Key en selecteer vervolgens Generate new key.
Klik op Opslaan — Okta genereert het sleutelpaar en toont de Private Key (JWK) één keer.
Kopieer en bewaar de JSON van de privésleutel onmiddellijk — deze wordt niet opnieuw getoond.

De publieke sleutel wordt automatisch geregistreerd bij uw applicatie.

Kopieer de private JWK voordat u het dialoogvenster sluit. Plak deze in de laatste stap in het veld Private Key in het Living Security Platform.

Uw eigen sleutel aanmaken

Okta gebruikt private_key_jwt voor API Services-apps. U genereert een RSA-sleutelpaar, registreert de publieke JWK bij Okta en levert de private JWK aan het Living Security Platform. Genereer een private JWK met het volgende Node.js-script (vereist 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));

Registreer de publieke JWK in Okta:

Open in de Admin Console uw API Services-applicatie.
Ga naar het tabblad General en scrol naar de sectie PUBLIC KEYS.
Klik op Add Key, plak de JSON van de publieke JWK uit de uitvoer van het bovenstaande script en klik op Opslaan.

De private JWK is wat u in het Living Security Platform plakt. Deze bevat al het sleutelmateriaal (d, p, q, dp, dq, qi) en de kid. Houd deze geheim.

Stap 3: Uw Okta Domain vinden

Voer alleen het subdomein van uw Okta-tenant in — het deel vóór .okta.com.

In de Admin Console toont de adresbalk van uw browser een URL zoals https://dev-12345678-admin.okta.com.
Uw Okta Domain is alleen het subdomein (bijv. dev-12345678), niet dev-12345678.okta.com.
U kunt ook in de Admin Console naar Settings > Account gaan om uw Okta-domein te vinden en vervolgens het subdomeingedeelte gebruiken.

Stap 4: API-scopes aan uw applicatie toekennen

Okta vereist minimaal één scope in elke tokenaanvraag. Voordat uw applicatie specifieke scopes kan aanvragen, moeten die worden toegekend:

Navigeer in de Admin Console naar Applications > Applications en open uw applicatie.
Klik op het tabblad Okta API Scopes.
Ken de scopes toe die uw integratie nodig heeft: okta.users.read en okta.logs.read.

Een volledige lijst met beschikbare scopes vindt u in de Okta Management API-referentie.

Stap 5: Een beheerdersrol aan uw applicatie toewijzen

Alleen scopes toekennen is niet voldoende — endpoints van de Okta Management API (bijv. /api/v1/users) retourneren stilzwijgend een leeg 200 []-antwoord als uw applicatie geen beheerdersrol heeft. U moet minimaal Read-Only Administrator toewijzen:

Navigeer in de Admin Console naar Security > Administrators (of ga naar Applications > Applications > uw app > Admin roles).
Klik op Add administrator assignment en selecteer uw API Services-applicatie.

Wijs de rol Read-Only Administrator toe (of een hogere rol, afhankelijk van de scopes die u nodig hebt).
Klik op Opslaan.

Zonder beheerdersrol slagen API-aanroepen met 200 OK, maar leveren ze lege resultaten op en is er geen 403-fout die op het probleem wijst.

Stap 6: Referenties invoeren in het Living Security Platform

Zodra u uw Klant-ID, Private Key (JWK), Okta Domain en Scopes hebt:

Open het formulier waarin u zich bij Okta moet authenticeren (Client Credentials).
Voer uw Klant-ID in.
Plak uw Private Key (JWK) — het volledige JSON-object uit het bovenstaande script (op één regel of opgemaakt).
Voer uw Okta Domain in als alleen het tenant-subdomein (bijv. dev-12345678).
Voer de Scopes in als een door spaties gescheiden lijst (bijv. okta.users.read okta.logs.read).
Verstuur het formulier, waarna u succesvol geauthenticeerd zou moeten zijn.

U bent nu verbonden met Okta (Client Credentials).

Delen van deze documentatie zijn overgenomen en aangepast van Nango, gebruikt onder de Elastic License 2.0.

Integraties

Integratie-instellingen

Catalogus

Uitgaande kanalen

Overzicht

Kies een verbindingsmethode