Configurazione dell'integrazione con Okta

Panoramica

Okta può fornire dati normalizzati sul ciclo di vita degli utenti, sull’autenticazione, sull’MFA e sull’attività amministrativa. Tra gli esempi esaminati figurano:

account.locked — account bloccato
mfa.factor.activated — attiva fattori MFA aggiuntivi
auth.login.failed — non riesce ad accedere

Entrambi i metodi di connessione leggono gli stessi due flussi: la directory degli utenti (/api/v1/users) e il log di sistema (/api/v1/logs). Consultare come i dati delle integrazioni diventano Segnali.

Scelta del metodo di connessione

	Okta (SSWS)	Okta (OAuth 2.0)
Credenziale	Un token API creato nella Admin Console	Un ID cliente e una JWK privata generati e registrati dall’utente
Configurazione	Tre passaggi, senza materiale crittografico da generare	Nove passaggi, inclusa una coppia di chiavi RSA
Ruolo di amministratore richiesto	Amministratore di sola lettura, assegnato al proprietario del token	Amministratore di sola lettura, assegnato all’applicazione
Durata del token	Si disattiva dopo 30 giorni di inutilizzo	Nessuna scadenza; la rotazione della coppia di chiavi è a carico dell’utente
Quando utilizzarlo	È il percorso consigliato per la maggior parte delle organizzazioni	Il criterio di sicurezza dell’organizzazione vieta i token API di lunga durata

Entrambi i metodi richiedono gli stessi accessi, quindi la scelta riguarda la gestione delle credenziali e non ciò che la piattaforma può leggere.

Opzione A — Token API (SSWS)

Consigliata.

Cosa serve a Living Security

Credenziale	Descrizione
Chiave API	Un token API di Okta. La finestra di connessione etichetta questo campo come Chiave API
Sottodominio del tenant	`<tenant>` in `<tenant>.okta.com` — solo il sottodominio, non l’URL completo

Prerequisiti

È necessario essere Super Administrator di Okta per creare un utente di account di servizio, assegnare ruoli di amministratore e creare token API.

Creare un utente proprietario del token

Un token API di Okta possiede le autorizzazioni dell’utente che lo ha creato e smette di funzionare se tale utente viene disattivato. Creare un account di servizio dedicato anziché utilizzare un account amministratore personale, in modo che la connessione resti valida anche in caso di cambiamenti nel personale.

Nella Admin Console, andare a Directory → Persone.
Fare clic su Add person e creare un utente come svc-livingsecurity@yourcompany.com.
Attivare l’account.

Assegnare il ruolo di amministratore di sola lettura

La piattaforma esegue solo operazioni di lettura. Concedere più del semplice accesso in lettura attribuisce al token autorizzazioni che non utilizzerà mai.

Andare a Sicurezza → Administrators.
Fare clic su Add administrator e selezionare l’utente creato nel passaggio precedente.
Assegnare il ruolo Read-only Administrator.
Salva.

Senza un ruolo di amministratore, le chiamate alla Okta Management API riescono con 200 OK e restituiscono un elenco vuoto. Non è presente alcun 403 che segnali la mancanza del ruolo: i flussi rimangono semplicemente vuoti.

Creare il token API

Accedere alla Admin Console come utente dell’account di servizio del passaggio 1. Il token eredita i privilegi dell’account che lo crea.
Andare a Sicurezza → API e aprire la scheda Tokens.
Fare clic su Create token, assegnargli un nome come Living Security Platform e fare clic su Create token.
Copiare subito il valore del token: Okta lo mostra una sola volta e non più in seguito.

Okta disattiva un token API dopo 30 giorni di inutilizzo. Le sincronizzazioni di questa integrazione vengono eseguite almeno una volta al giorno, quindi una connessione attiva mantiene valido il proprio token. Una connessione lasciata in pausa per un mese richiede un nuovo token.

L’elenco di indirizzi riportato sopra è rilevante solo se la propria organizzazione Okta limita l’accesso alle API tramite network zone. La maggior parte delle organizzazioni non lo fa.

Individuare il sottodominio del tenant

L’URL della Admin Console ha un aspetto simile a https://acme-admin.okta.com. Il sottodominio del tenant è acme, senza il suffisso -admin, senza .okta.com e senza https://.

La connessione a Okta (SSWS) è stata stabilita.

Risoluzione dei problemi

401 Unauthorized

Il token non è valido, è stato revocato oppure è stato disattivato dopo 30 giorni di inattività. Creare un nuovo token come utente dell’account di servizio e inserirlo nuovamente nella connessione.

Connessione riuscita, ma tutti i flussi sono vuoti

Il proprietario del token non ha alcun ruolo di amministratore. Assegnare Read-only Administrator all’account di servizio (passaggio 2): quando il ruolo manca, l’API restituisce 200 OK con un elenco vuoto anziché un errore.

Le sincronizzazioni non riescono dopo un cambiamento nel personale

Il token smette di funzionare se l’utente che lo ha creato viene disattivato. Per questo motivo il token deve appartenere a un account di servizio e non a una persona.

Opzione B — Applicazione di servizio OAuth 2.0

Utilizzare questo metodo quando il criterio di sicurezza dell’organizzazione non consente token API di lunga durata. Sostituisce il token con un ID cliente e una coppia di chiavi RSA di cui l’utente è proprietario. Nella piattaforma corrisponde al riquadro Okta (OAuth 2.0), in Impostazioni → Integrazioni → Catalogo. Per autenticarsi con Okta tramite Client Credentials sono necessari i seguenti elementi:

ID cliente - Un identificatore univoco per l’applicazione Okta API Services.
Private Key (JWK) - La chiave privata RSA in formato JSON Web Key, la cui chiave pubblica è registrata nell’applicazione Okta.
Okta Domain - Solo il sottodominio del tenant Okta (ad es. dev-12345678), non il nome host completo.
Scopes - Un elenco di scope della Okta Management API separati da spazi (ad es. okta.users.read okta.logs.read).

Questa guida illustra come creare in Okta un’applicazione API Services con autenticazione private_key_jwt.

Prerequisiti:

È necessario disporre di un account Okta. Registrarsi per ottenere un account sviluppatore gratuito su developer.okta.com.

Passaggio 1: Creazione dell’applicazione Okta API Services

Accedere alla Okta Admin Console.
Nella barra laterale sinistra, andare a Applications > Applications.
Fare clic su Create App Integration.
Selezionare API Services come metodo di accesso e fare clic su Avanti.

Assegnare un nome all’applicazione e fare clic su Salva.
Nella scheda General dell’applicazione, individuare l’ID cliente: servirà nell’ultimo passaggio.
Impostare Client authentication su Public key / Private key. Gli scope okta.* sono supportati solo con questo metodo di autenticazione.

Disattivare Proof of possession (DPoP): non è supportato.

L’applicazione deve essere creata come API Services.

Passaggio 2: Generazione e registrazione della coppia di chiavi RSA

Utilizzo del generatore di chiavi di Okta

Okta può generare la coppia di chiavi RSA direttamente nella Admin Console:

Nella Admin Console, aprire l’applicazione API Services.
Andare alla scheda General e scorrere fino alla sezione PUBLIC KEYS.
Fare clic su Add Key, quindi selezionare Generate new key.
Fare clic su Salva: Okta genera la coppia di chiavi e mostra la Private Key (JWK) una sola volta.
Copiare e salvare immediatamente il JSON della chiave privata: non verrà mostrato di nuovo.

La chiave pubblica viene registrata automaticamente nell’applicazione.

Copiare la JWK privata prima di chiudere la finestra di dialogo. Incollarla nel campo Private Key della Living Security Platform nell’ultimo passaggio.

Creazione di una chiave propria

Okta utilizza private_key_jwt per le applicazioni API Services. L’utente genera una coppia di chiavi RSA, registra la JWK pubblica in Okta e fornisce la JWK privata alla Living Security Platform. Generare una JWK privata utilizzando il seguente script Node.js (richiede 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));

Registrare la JWK pubblica in Okta:

Nella Admin Console, aprire l’applicazione API Services.
Andare alla scheda General e scorrere fino alla sezione PUBLIC KEYS.
Fare clic su Add Key, incollare il JSON della JWK pubblica prodotto dallo script precedente e fare clic su Salva.

La JWK privata è quella da incollare nella Living Security Platform. Include tutto il materiale della chiave (d, p, q, dp, dq, qi) e il valore kid. Mantenerla riservata.

Passaggio 3: Individuazione dell’Okta Domain

Inserire solo il sottodominio del tenant Okta, ovvero la parte che precede .okta.com.

Nella Admin Console, la barra degli indirizzi del browser mostrerà un URL simile a https://dev-12345678-admin.okta.com.
L’Okta Domain è solo il sottodominio (ad es. dev-12345678), non dev-12345678.okta.com.
In alternativa, andare a Impostazioni > Account nella Admin Console per trovare il proprio dominio Okta, quindi utilizzare la parte del sottodominio.

Passaggio 4: Concessione degli scope API all’applicazione

Okta richiede almeno uno scope in ogni richiesta di token. Prima che l’applicazione possa richiedere scope specifici, questi devono essere concessi:

Nella Admin Console, andare a Applications > Applications e aprire l’applicazione.
Fare clic sulla scheda Okta API Scopes.
Concedere gli scope richiesti dall’integrazione: okta.users.read e okta.logs.read.

L’elenco completo degli scope disponibili è riportato nel riferimento della Okta Management API.

Passaggio 5: Assegnazione di un ruolo di amministratore all’applicazione

La sola concessione degli scope non è sufficiente: gli endpoint della Okta Management API (ad es. /api/v1/users) restituiscono silenziosamente una risposta 200 [] vuota se l’applicazione non ha alcun ruolo di amministratore. È necessario assegnare almeno Read-Only Administrator:

Nella Admin Console, andare a Sicurezza > Administrators (oppure a Applications > Applications > la propria app > Admin roles).
Fare clic su Add administrator assignment e selezionare l’applicazione API Services.

Assegnare il ruolo Read-Only Administrator (o superiore, in base agli scope necessari).
Fare clic su Salva.

Senza un ruolo di amministratore, le chiamate API riescono con 200 OK ma restituiscono risultati vuoti e non viene segnalato alcun errore 403 che indichi il problema.

Passaggio 6: Inserimento delle credenziali nella Living Security Platform

Una volta ottenuti ID cliente, Private Key (JWK), Okta Domain e Scopes:

Aprire il modulo in cui è necessario eseguire l’autenticazione con Okta (Client Credentials).
Inserire l’ID cliente.
Incollare la Private Key (JWK): l’intero oggetto JSON dello script precedente (su una sola riga o formattato).
Inserire l’Okta Domain indicando solo il sottodominio del tenant (ad es. dev-12345678).
Inserire gli Scopes come elenco separato da spazi (ad es. okta.users.read okta.logs.read).
Inviare il modulo: l’autenticazione dovrebbe riuscire.

La connessione a Okta (Client Credentials) è stata stabilita.

Parti di questa documentazione sono adattate da Nango e utilizzate ai sensi della Elastic License 2.0.

Integrazioni

Configurazione delle integrazioni

Catalogo

Canali in uscita

Configurazione dell'integrazione con Okta

Panoramica

Scelta del metodo di connessione