Configuração da integração com o Okta

Visão geral

O Okta pode fornecer dados normalizados de ciclo de vida de usuários, autenticação, MFA e atividade administrativa. Exemplos analisados incluem:

account.locked — conta bloqueada
mfa.factor.activated — ativa fatores de MFA adicionais
auth.login.failed — falha ao fazer login

Ambos os métodos de conexão leem os mesmos dois fluxos — o diretório de usuários (/api/v1/users) e o log do sistema (/api/v1/logs). Consulte como os dados de integração se tornam sinais.

Escolha um método de conexão

	Okta (SSWS)	Okta (OAuth 2.0)
Credencial	Um token de API que você cria no Admin Console	Um ID do cliente e um JWK privado que você gera e registra
Configuração	Três etapas, sem material de chave para gerar	Nove etapas, incluindo um par de chaves RSA
Função de administrador necessária	Administrador somente leitura, atribuída ao proprietário do token	Administrador somente leitura, atribuída ao aplicativo
Vida útil do token	Desativado após 30 dias sem uso	Sem expiração; a rotação do par de chaves é de sua responsabilidade
Quando usar	Este é o caminho recomendado para a maioria das organizações	Sua política de segurança proíbe tokens de API de longa duração

Ambos os métodos exigem o mesmo acesso, portanto a escolha diz respeito ao tratamento das credenciais, e não ao que a plataforma consegue ler.

Opção A — Token de API (SSWS)

Recomendado.

O que o Living Security precisa

Credencial	Descrição
Chave de API	Um token de API do Okta. A caixa de diálogo de conexão identifica este campo como Chave de API
Subdomínio do tenant	O `<tenant>` em `<tenant>.okta.com` — apenas o subdomínio, não a URL completa

Pré-requisitos

Você deve ser Super Administrator do Okta para criar um usuário de conta de serviço, atribuir funções de administrador e criar tokens de API.

Crie um usuário para ser o proprietário do token

Um token de API do Okta possui as permissões do usuário que o criou e deixa de funcionar se esse usuário for desativado. Crie uma conta de serviço dedicada em vez de usar uma conta de administrador pessoal, para que a conexão não seja afetada por mudanças na equipe.

No Admin Console, acesse Directory → Pessoas.
Clique em Add person e crie um usuário como svc-livingsecurity@yourcompany.com.
Ative a conta.

Atribua a função de administrador somente leitura

A plataforma apenas lê dados. Conceder mais do que acesso de leitura dá ao token permissões que ele nunca utiliza.

Acesse Segurança → Administrators.
Clique em Add administrator e selecione o usuário da etapa anterior.
Atribua a função Read-only Administrator.
Salve.

Sem uma função de administrador, as chamadas à Okta Management API são bem-sucedidas com 200 OK e retornam uma lista vazia. Não há 403 que indique a ausência da função — os fluxos simplesmente permanecem vazios.

Crie o token de API

Faça login no Admin Console como o usuário da conta de serviço da etapa 1. O token herda as permissões da conta que o criar.
Acesse Segurança → API e abra a guia Tokens.
Clique em Create token, atribua um nome como Living Security Platform e clique em Create token.
Copie agora o valor do token — o Okta o exibe uma única vez e nunca mais.

O Okta desativa um token de API após 30 dias sem uso. As sincronizações desta integração são executadas pelo menos uma vez por dia, portanto uma conexão ativa mantém o próprio token ativo. Uma conexão pausada por um mês exigirá um novo token.

A lista de endereços acima só é relevante se a sua organização do Okta restringir o acesso à API por network zone. A maioria das organizações não o faz.

Localize o subdomínio do seu tenant

A URL do seu Admin Console tem a aparência de https://acme-admin.okta.com. O subdomínio do tenant é acme — sem o sufixo -admin, sem .okta.com e sem https://.

Agora você está conectado ao Okta (SSWS).

Solução de problemas

401 Unauthorized

O token é inválido, foi revogado ou foi desativado após 30 dias de inatividade. Crie um novo token como o usuário da conta de serviço e insira-o novamente na conexão.

Conectado, mas todos os fluxos estão vazios

O proprietário do token não possui uma função de administrador. Atribua Read-only Administrator à conta de serviço (etapa 2) — a API retorna 200 OK com uma lista vazia, em vez de um erro, quando a função está ausente.

As sincronizações falham após uma mudança na equipe

O token deixa de funcionar se o usuário que o criou for desativado. É por isso que o token deve pertencer a uma conta de serviço, e não a uma pessoa.

Opção B — Aplicativo de serviço OAuth 2.0

Use este método quando a sua política de segurança não permitir tokens de API de longa duração. Ele substitui o token por um ID do cliente e um par de chaves RSA que pertencem a você. Na plataforma, este é o bloco Okta (OAuth 2.0), em Configurações → Integrações → Catálogo. Para autenticar-se no Okta usando Client Credentials, você precisa do seguinte:

ID do cliente - Um identificador exclusivo do seu aplicativo API Services do Okta.
Chave privada (JWK) - A chave privada RSA no formato JSON Web Key, cuja chave pública está registrada no seu aplicativo do Okta.
Domínio do Okta - Apenas o subdomínio do seu tenant do Okta (por exemplo, dev-12345678), não o nome de host completo.
Escopos - Uma lista de escopos da Okta Management API separados por espaço (por exemplo, okta.users.read okta.logs.read).

Este guia o orientará na criação de um aplicativo API Services no Okta com autenticação private_key_jwt.

Pré-requisitos:

Você deve ter uma conta do Okta. Cadastre-se para obter uma conta de desenvolvedor gratuita em developer.okta.com.

Etapa 1: Criação do seu aplicativo API Services do Okta

Faça login no Okta Admin Console.
Na barra lateral esquerda, navegue até Applications > Applications.
Clique em Create App Integration.
Selecione API Services como método de login e clique em Próximo.

Dê um nome ao seu aplicativo e clique em Salvar.
Na guia General do aplicativo, localize o ID do cliente — você precisará dele na etapa final.
Defina Client authentication como Public key / Private key. Os escopos okta.* são compatíveis apenas com este método de autenticação.

Desative Proof of possession (DPoP) — não é compatível.

O aplicativo deve ser criado como API Services.

Etapa 2: Geração e registro do seu par de chaves RSA

Use o gerador de chaves do Okta

O Okta pode gerar o par de chaves RSA para você diretamente no Admin Console:

No Admin Console, abra o seu aplicativo API Services.
Acesse a guia General e role até a seção PUBLIC KEYS.
Clique em Add Key e, em seguida, selecione Generate new key.
Clique em Salvar — o Okta gera o par de chaves e exibe a Chave privada (JWK) uma única vez.
Copie e salve imediatamente o JSON da chave privada — ele não será exibido novamente.

A chave pública é registrada automaticamente no seu aplicativo.

Copie o JWK privado antes de fechar a caixa de diálogo. Cole-o no campo Chave privada da Living Security Platform na etapa final.

Crie a sua própria chave

O Okta usa private_key_jwt para aplicativos API Services. Você gera um par de chaves RSA, registra o JWK público no Okta e fornece o JWK privado à Living Security Platform. Gere um JWK privado usando o seguinte script Node.js (requer 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));

Registre o JWK público no Okta:

No Admin Console, abra o seu aplicativo API Services.
Acesse a guia General e role até a seção PUBLIC KEYS.
Clique em Add Key, cole o JSON do JWK público gerado pelo script acima e clique em Salvar.

O JWK privado é o que você cola na Living Security Platform. Ele inclui todo o material da chave (d, p, q, dp, dq, qi) e o kid. Mantenha-o em sigilo.

Etapa 3: Localização do seu Domínio do Okta

Insira apenas o subdomínio do seu tenant do Okta — a parte antes de .okta.com.

No Admin Console, a barra de endereços do navegador exibirá uma URL como https://dev-12345678-admin.okta.com.
Seu Domínio do Okta é apenas o subdomínio (por exemplo, dev-12345678), não dev-12345678.okta.com.
Como alternativa, acesse Configurações > Account no Admin Console para encontrar o seu domínio do Okta e, em seguida, use a parte do subdomínio.

Etapa 4: Concessão de escopos de API ao seu aplicativo

O Okta exige pelo menos um escopo em cada solicitação de token. Antes que o seu aplicativo possa solicitar escopos específicos, eles devem ser concedidos:

No Admin Console, navegue até Applications > Applications e abra o seu aplicativo.
Clique na guia Okta API Scopes.
Conceda os escopos exigidos pela sua integração: okta.users.read e okta.logs.read.

Uma lista completa dos escopos disponíveis está na referência da Okta Management API.

Etapa 5: Atribuição de uma função de administrador ao seu aplicativo

Conceder escopos não é suficiente — os endpoints da Okta Management API (por exemplo, /api/v1/users) retornam silenciosamente uma resposta 200 [] vazia se o seu aplicativo não tiver uma função de administrador. Você deve atribuir pelo menos Read-Only Administrator:

No Admin Console, navegue até Segurança > Administrators (ou acesse Applications > Applications > seu aplicativo > Admin roles).
Clique em Add administrator assignment e selecione o seu aplicativo API Services.

Atribua a função Read-Only Administrator (ou superior, dependendo dos escopos de que você precisa).
Clique em Salvar.

Sem uma função de administrador, as chamadas de API são bem-sucedidas com 200 OK, mas retornam resultados vazios, e não há erro 403 que indique o problema.

Etapa 6: Inserção das credenciais na Living Security Platform

Depois de ter o seu ID do cliente, a Chave privada (JWK), o Domínio do Okta e os Escopos:

Abra o formulário em que você precisa autenticar-se no Okta (Client Credentials).
Insira o seu ID do cliente.
Cole a sua Chave privada (JWK) — o objeto JSON completo gerado pelo script acima (em uma única linha ou formatado).
Insira o seu Domínio do Okta apenas como o subdomínio do tenant (por exemplo, dev-12345678).
Insira os Escopos como uma lista separada por espaços (por exemplo, okta.users.read okta.logs.read).
Envie o formulário e você deverá ser autenticado com sucesso.

Agora você está conectado ao Okta (Client Credentials).

Partes desta documentação são adaptadas do Nango, usado sob a Elastic License 2.0.

Integrações

Configuração de integração

Catálogo

Canais de saída

Configuração da integração com o Okta

Visão geral

Escolha um método de conexão