Okta-integraation käyttöönotto

Yleiskatsaus

Okta voi tuottaa normalisoitua tietoa käyttäjien elinkaaresta, todennuksesta, MFA:sta ja hallinnollisesta toiminnasta. Tarkastettuja esimerkkejä ovat:

account.locked — tili lukittu
mfa.factor.activated — ottaa käyttöön lisää MFA-tekijöitä
auth.login.failed — kirjautuminen epäonnistuu

Molemmat yhteystavat lukevat samat kaksi virtaa: käyttäjähakemiston (/api/v1/users) ja järjestelmälokin (/api/v1/logs). Katso miten integraatioiden tiedoista muodostuu signaaleja.

Yhteystavan valinta

	Okta (SSWS)	Okta (OAuth 2.0)
Tunniste	Admin Consolessa luotava API-tunnus	Luomasi ja rekisteröimäsi asiakastunnus ja yksityinen JWK
Käyttöönotto	Kolme vaihetta, ei luotavaa avainmateriaalia	Yhdeksän vaihetta, mukaan lukien RSA-avainpari
Vaadittava ylläpitäjän rooli	Vain luku -oikeuksilla varustettu ylläpitäjä, määritetään tunnuksen omistajalle	Vain luku -oikeuksilla varustettu ylläpitäjä, määritetään sovellukselle
Tunnuksen voimassaolo	Deaktivoituu 30 päivän käyttämättömyyden jälkeen	Ei vanhene; avainparin kierrätys on omalla vastuullasi
Käytä, kun	Tämä on suositeltu vaihtoehto useimmille organisaatioille	Tietoturvakäytäntösi kieltää pitkäikäiset API-tunnukset

Molemmat tavat vaativat saman käyttöoikeuden, joten valinta koskee tunnistetietojen käsittelyä eikä sitä, mitä alusta voi lukea.

Vaihtoehto A — API-tunnus (SSWS)

Suositeltu.

Mitä Living Security tarvitsee

Tunniste	Kuvaus
API-avain	Okta API -tunnus. Yhdistämisikkunassa tämän kentän nimi on API-avain
Vuokraajan aliverkkotunnus	`<tenant>` osoitteessa `<tenant>.okta.com` — pelkkä aliverkkotunnus, ei koko URL-osoitetta

Edellytykset

Sinulla on oltava Oktassa Super Administrator -rooli, jotta voit luoda palvelutilin käyttäjän, määrittää ylläpitäjärooleja ja luoda API-tunnuksia.

Luo tunnuksen omistava käyttäjä

Okta API -tunnus perii sen luoneen käyttäjän oikeudet, ja se lakkaa toimimasta, jos kyseinen käyttäjä deaktivoidaan. Luo erillinen palvelutili henkilökohtaisen ylläpitäjätilin käyttämisen sijaan, jotta yhteys säilyy henkilöstömuutosten yli.

Siirry Admin Consolessa kohtaan Directory → People.
Valitse Add person ja luo käyttäjä, esimerkiksi svc-livingsecurity@yourcompany.com.
Aktivoi tili.

Määritä vain luku -oikeuksilla varustettu ylläpitäjärooli

Alusta vain lukee tietoja. Laajempien kuin lukuoikeuksien myöntäminen antaa tunnukselle oikeuksia, joita se ei koskaan käytä.

Siirry kohtaan Security → Administrators.
Valitse Add administrator ja valitse edellisessä vaiheessa luotu käyttäjä.
Määritä rooli Read-only Administrator.
Tallenna.

Ilman ylläpitäjäroolia Okta Management API -kutsut onnistuvat vastauksella 200 OK ja palauttavat tyhjän luettelon. Mikään 403 ei ilmaise, että rooli puuttuu — virrat vain pysyvät tyhjinä.

Luo API-tunnus

Kirjaudu Admin Consoleen vaiheessa 1 luotuna palvelutilin käyttäjänä. Tunnus perii sen tilin oikeudet, jolla se luodaan.
Siirry kohtaan Security → API ja avaa Tokens-välilehti.
Valitse Create token, anna tunnukselle nimi, esimerkiksi Living Security Platform, ja valitse Create token.
Kopioi tunnuksen arvo nyt — Okta näyttää sen vain kerran.

Okta deaktivoi API-tunnuksen 30 päivän käyttämättömyyden jälkeen. Tämän integraation synkronoinnit suoritetaan vähintään kerran päivässä, joten toimiva yhteys pitää oman tunnuksensa aktiivisena. Kuukauden ajan keskeytettynä ollut yhteys tarvitsee uuden tunnuksen.

Yllä oleva osoiteluettelo on merkityksellinen vain, jos Okta-organisaatiosi rajoittaa API-käyttöä verkkovyöhykkeen perusteella. Useimmissa organisaatioissa näin ei ole.

Selvitä vuokraajan aliverkkotunnus

Admin Consolen URL-osoite on muotoa https://acme-admin.okta.com. Vuokraajan aliverkkotunnus on acme — ilman -admin-päätettä, ilman .okta.com ja ilman https://.

Yhteys Oktaan (SSWS) on nyt muodostettu.

Vianmääritys

401 Unauthorized

Tunnus on virheellinen, se on peruutettu tai se on deaktivoitu 30 päivän käyttämättömyyden jälkeen. Luo uusi tunnus palvelutilin käyttäjänä ja syötä se yhteyteen uudelleen.

Yhteys on muodostettu, mutta kaikki virrat ovat tyhjiä

Tunnuksen omistajalla ei ole ylläpitäjärooli. Määritä palvelutilille Read-only Administrator (vaihe 2) — kun rooli puuttuu, API palauttaa 200 OK ja tyhjän luettelon virheen sijaan.

Synkronoinnit epäonnistuvat henkilöstömuutoksen jälkeen

Tunnus lakkaa toimimasta, jos sen luonut käyttäjä deaktivoidaan. Tästä syystä tunnuksen tulee kuulua palvelutilille eikä henkilölle.

Vaihtoehto B — OAuth 2.0 -palvelusovellus

Käytä tätä tapaa, kun tietoturvakäytäntösi ei salli pitkäikäisiä API-tunnuksia. Se korvaa tunnuksen asiakastunnuksella ja omistamallasi RSA-avainparilla. Alustassa tämä on Okta (OAuth 2.0) -ruutu kohdassa Asetukset → Integraatiot → Luettelo. Todennus Oktaan Client Credentials -menetelmällä edellyttää seuraavia tietoja:

Client ID (asiakastunnus) - Okta API Services -sovelluksesi yksilöivä tunniste.
Private Key (JWK) - RSA-yksityisavain JSON Web Key -muodossa, jonka julkinen avain on rekisteröity Okta-sovellukseesi.
Okta Domain - Vain Okta-vuokraajasi aliverkkotunnus (esim. dev-12345678), ei koko isäntänimeä.
Scopes - Välilyönnein erotettu luettelo Okta Management API -oikeuksista (esim. okta.users.read okta.logs.read).

Tämä ohje opastaa luomaan Oktassa API Services -sovelluksen, jossa käytetään private_key_jwt-todennusta.

Edellytykset:

Sinulla on oltava Okta-tili. Voit rekisteröidä maksuttoman kehittäjätilin osoitteessa developer.okta.com.

Vaihe 1: Okta API Services -sovelluksen luominen

Kirjaudu Okta Admin Consoleen.
Siirry vasemman reunan valikossa kohtaan Applications > Applications.
Valitse Create App Integration.
Valitse kirjautumistavaksi API Services ja valitse Seuraava.

Anna sovellukselle nimi ja valitse Tallenna.
Etsi sovelluksen General-välilehdeltä Client ID (asiakastunnus) — tarvitset sitä viimeisessä vaiheessa.
Aseta Client authentication -asetukseksi Public key / Private key. okta.*-oikeudet tuetaan vain tällä todennustavalla.

Poista Proof of possession (DPoP) käytöstä — sitä ei tueta.

Sovellus on luotava tyypillä API Services.

Vaihe 2: RSA-avainparin luominen ja rekisteröinti

Okta-avaingeneraattorin käyttö

Okta voi luoda RSA-avainparin puolestasi suoraan Admin Consolessa:

Avaa Admin Consolessa API Services -sovelluksesi.
Siirry General-välilehdelle ja vieritä PUBLIC KEYS -osioon.
Valitse Add Key ja sitten Generate new key.
Valitse Tallenna — Okta luo avainparin ja näyttää Private Key (JWK) -yksityisavaimen kerran.
Kopioi ja tallenna yksityisavaimen JSON heti — sitä ei näytetä uudelleen.

Julkinen avain rekisteröidään sovellukseesi automaattisesti.

Kopioi yksityinen JWK ennen ikkunan sulkemista. Liitä se Living Security Platformin Private Key -kenttään viimeisessä vaiheessa.

Oman avaimen luominen

Okta käyttää private_key_jwt-menetelmää API Services -sovelluksille. Luot RSA-avainparin, rekisteröit julkisen JWK:n Oktaan ja annat yksityisen JWK:n Living Security Platformille. Luo yksityinen JWK seuraavalla Node.js-skriptillä (vaatii 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));

Rekisteröi julkinen JWK Oktaan:

Avaa Admin Consolessa API Services -sovelluksesi.
Siirry General-välilehdelle ja vieritä PUBLIC KEYS -osioon.
Valitse Add Key, liitä yllä olevan skriptin tulostama julkisen JWK:n JSON ja valitse Tallenna.

Living Security Platformiin liitetään yksityinen JWK. Se sisältää kaiken avainmateriaalin (d, p, q, dp, dq, qi) sekä kid. Pidä se salassa.

Vaihe 3: Okta Domain -arvon selvittäminen

Syötä vain Okta-vuokraajasi aliverkkotunnus — osa ennen .okta.com.

Admin Consolessa selaimen osoiterivillä näkyy URL-osoite, joka on muotoa https://dev-12345678-admin.okta.com.
Okta Domain on pelkkä aliverkkotunnus (esim. dev-12345678), ei dev-12345678.okta.com.
Vaihtoehtoisesti voit etsiä Okta-verkkotunnuksesi Admin Consolen kohdasta Settings > Account ja käyttää siitä aliverkkotunnusosaa.

Vaihe 4: API-oikeuksien myöntäminen sovellukselle

Okta edellyttää vähintään yhtä oikeutta (scope) jokaisessa tunnuspyynnössä. Ennen kuin sovelluksesi voi pyytää tiettyjä oikeuksia, ne on myönnettävä:

Siirry Admin Consolessa kohtaan Applications > Applications ja avaa sovelluksesi.
Valitse Okta API Scopes -välilehti.
Myönnä integraatiosi tarvitsemat oikeudet: okta.users.read ja okta.logs.read.

Täydellinen luettelo käytettävissä olevista oikeuksista on Okta Management API -viitteessä.

Vaihe 5: Ylläpitäjäroolin määrittäminen sovellukselle

Pelkkä oikeuksien myöntäminen ei riitä — Okta Management API -päätepisteet (esim. /api/v1/users) palauttavat äänettömästi tyhjän 200 []-vastauksen, jos sovelluksella ei ole ylläpitäjäroolia. Sinun on määritettävä vähintään Read-Only Administrator:

Siirry Admin Consolessa kohtaan Security > Administrators (tai kohtaan Applications > Applications > sovelluksesi > Admin roles).
Valitse Add administrator assignment ja valitse API Services -sovelluksesi.

Määritä rooli Read-Only Administrator (tai laajempi tarvitsemistasi oikeuksista riippuen).
Valitse Tallenna.

Ilman ylläpitäjäroolia API-kutsut onnistuvat vastauksella 200 OK mutta palauttavat tyhjiä tuloksia, eikä ongelmasta kerro mikään 403-virhe.

Vaihe 6: Tunnistetietojen syöttäminen Living Security Platformiin

Kun sinulla on Client ID (asiakastunnus), Private Key (JWK), Okta Domain ja Scopes:

Avaa lomake, jossa todennus Oktaan (Client Credentials) tehdään.
Syötä asiakastunnus.
Liitä Private Key (JWK) — koko JSON-objekti yllä olevasta skriptistä (yhdellä rivillä tai muotoiltuna).
Syötä Okta Domain pelkkänä vuokraajan aliverkkotunnuksena (esim. dev-12345678).
Syötä Scopes välilyönnein erotettuna luettelona (esim. okta.users.read okta.logs.read).
Lähetä lomake, ja todennuksen pitäisi onnistua.

Yhteys Oktaan (Client Credentials) on nyt muodostettu.

Osia tästä dokumentaatiosta on mukautettu Nango-dokumentaatiosta, ja niitä käytetään Elastic License 2.0 -lisenssin mukaisesti.

Integraatiot

Integraatioiden käyttöönotto

Luettelo

Lähtevät kanavat

Yleiskatsaus

Yhteystavan valinta