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. Entre os exemplos analisados, estão:

account.locked — conta bloqueada
mfa.factor.activated — ativa fatores adicionais de MFA
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 transformam em 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 uma JWK privada 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 gerenciamento de 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` — somente o subdomínio, não a URL completa

Pré-requisitos

Você deve ser um 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 assume 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 continue funcionando mesmo após mudanças na equipe.

No Admin Console, acesse Directory → People.
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 Security → Administrators.
Clique em Add administrator e selecione o usuário da etapa anterior.
Atribua a função Read-only Administrator.
Clique em Salvar.

Sem uma função de administrador, as chamadas à API de gerenciamento do Okta são bem-sucedidas com 200 OK e retornam uma lista vazia. Não há 403 para indicar que a função está ausente — 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 cria.
Acesse Security → API e abra a guia Tokens.
Clique em Create token, atribua um nome como Living Security Platform e clique em Create token.
Copie o valor do token agora — 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 mantida em pausa 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 zona de rede. A maioria das organizações não faz isso.

Encontre o subdomínio do seu tenant

A URL do seu Admin Console tem o formato 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 tem 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, 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 de sua propriedade. Na plataforma, trata-se do bloco Okta (OAuth 2.0), em Configurações → Integrações → Catálogo. Para se autenticar no Okta usando Client Credentials, você precisa do seguinte:

ID do cliente - Um identificador exclusivo para o 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 - Somente 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 API de gerenciamento do Okta separados por espaço (por exemplo, okta.users.read okta.logs.read).

Este guia orienta você 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 gratuita de desenvolvedor 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 Next.

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

Desative Proof of possession (DPoP) — ele 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 Save — 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 a JWK privada antes de fechar a caixa de diálogo. Cole-a no campo Private Key na Living Security Platform, na etapa final.

Crie sua própria chave

O Okta usa private_key_jwt para aplicativos API Services. Você gera um par de chaves RSA, registra a JWK pública no Okta e fornece a JWK privada à Living Security Platform. Gere uma JWK privada 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 a JWK pública 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 da JWK pública gerado pelo script acima e clique em Save.

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

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

Insira somente o subdomínio do seu tenant do Okta — a parte anterior a .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 é somente 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 precisam 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 API de gerenciamento do Okta.

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

Conceder escopos, por si só, não é suficiente — os endpoints da API de gerenciamento do Okta (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é Security > 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 Save.

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á nenhum erro 403 que indique o problema.

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

Depois de obter 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 se autenticar 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 a autenticação deverá ser concluída com sucesso.

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

Partes desta documentação foram adaptadas do Nango, usadas 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