Coletar registros do ForgeRock OpenIDM

Compatível com:

Google SecOps SIEM

Este documento explica como ingerir registros do ForgeRock OpenIDM no Google Security Operations usando o Google Cloud Storage V2.

O ForgeRock OpenIDM (agora chamado de PingIDM) é uma plataforma de gerenciamento de identidade que oferece provisionamento e sincronização de usuários, gerenciamento de senhas e governança de acesso. Ele registra eventos de ciclo de vida de identidade, tentativas de autenticação, operações de reconciliação e mudanças de configuração em registros de auditoria acessíveis por REST.

Antes de começar

Verifique se você atende os seguintes pré-requisitos:

Uma instância do Google SecOps
Um projeto do GCP com a API Cloud Storage ativada
Permissões para criar e gerenciar buckets do GCS
Permissões para gerenciar políticas do IAM em buckets do GCS
Permissões para criar serviços do Cloud Run, tópicos do Pub/Sub e jobs do Cloud Scheduler
Acesso privilegiado à instância do ForgeRock OpenIDM ou PingIDM com credenciais administrativas

Criar um bucket do Google Cloud Storage

Acesse o Console do Google Cloud.
Selecione seu projeto ou crie um novo.
No menu de navegação, acesse Cloud Storage > Buckets.
Clique em Criar bucket.

Informe os seguintes detalhes de configuração:

Configuração	Valor
Nomeie seu bucket	Insira um nome exclusivo globalmente, por exemplo, `forgerock-openidm-audit-logs`.
Tipo de local	Escolha com base nas suas necessidades (região, birregional, multirregional)
Local	Selecione o local (por exemplo, `us-central1`).
Classe de armazenamento	Padrão (recomendado para registros acessados com frequência)
Controle de acesso	Uniforme (recomendado)
Ferramentas de proteção	Opcional: ativar o controle de versões de objetos ou a política de retenção

Clique em Criar.

Coletar credenciais do ForgeRock OpenIDM

Acessar o URL base do ForgeRock OpenIDM

Faça login na sua instância do ForgeRock OpenIDM ou PingIDM.
Anote o URL base da barra de endereço do navegador.
- Formato: https://openidm.example.com
- Não inclua barras ou caminhos como /admin

Receber credenciais administrativas

Consiga credenciais administrativas para sua instância do ForgeRock OpenIDM.
Você precisará dos seguintes itens:
- Nome de usuário: nome de usuário administrativo (por exemplo, openidm-admin)
- Senha: senha administrativa
Observação: a conta de usuário precisa ter permissões para consultar registros de auditoria pela API REST. O usuário openidm-admin padrão tem essas permissões.

Verifique as permissões

Para verificar se a conta tem as permissões necessárias:

Faça login no ForgeRock OpenIDM.
Acesse Configurar > Preferências do Sistema > Auditoria.
Se você conseguir ver a configuração de auditoria e os tópicos, terá as permissões necessárias.
Se essa opção não aparecer, entre em contato com seu administrador para conceder permissões de leitura de auditoria.

Testar o acesso à API

Teste suas credenciais antes de prosseguir com a integração:

# Replace with your actual credentials
OPENIDM_BASE_URL="https://openidm.example.com"
OPENIDM_USERNAME="openidm-admin"
OPENIDM_PASSWORD="your-admin-password"

# Test API access to authentication audit topic
curl -v \
    -H "X-OpenIDM-Username: ${OPENIDM_USERNAME}" \
    -H "X-OpenIDM-Password: ${OPENIDM_PASSWORD}" \
    -H "Accept-API-Version: resource=1.0" \
    -H "Accept: application/json" \
    "${OPENIDM_BASE_URL}/openidm/audit/authentication?_queryFilter=true&_pageSize=1"

Resposta esperada: HTTP 200 com JSON contendo eventos de auditoria.

Criar uma conta de serviço para a função do Cloud Run

A função do Cloud Run precisa de uma conta de serviço com permissões para gravar no bucket do GCS e ser invocada pelo Pub/Sub.

Criar conta de serviço

No Console do GCP, acesse IAM e administrador > Contas de serviço.
Clique em Criar conta de serviço.
Informe os seguintes detalhes de configuração:
- Nome da conta de serviço: insira forgerock-openidm-collector-sa.
- Descrição da conta de serviço: insira Service account for Cloud Run function to collect ForgeRock OpenIDM logs.
Clique em Criar e continuar.
Na seção Conceder acesso a essa conta de serviço ao projeto, adicione os seguintes papéis:
1. Clique em Selecionar papel.
2. Pesquise e selecione Administrador de objetos do Storage.
3. Clique em + Adicionar outro papel.
4. Pesquise e selecione Invocador do Cloud Run.
5. Clique em + Adicionar outro papel.
6. Pesquise e selecione Invocador do Cloud Functions.
Clique em Continuar.
Clique em Concluído.

Esses papéis são necessários para:

Administrador de objetos do Storage: grava registros em um bucket do GCS e gerencia arquivos de estado.
Invocador do Cloud Run: permite que o Pub/Sub invoque a função
Invocador do Cloud Functions: permite a invocação de funções

Conceder permissões do IAM no bucket do GCS

Conceda permissões de gravação à conta de serviço no bucket do GCS:

Acesse Cloud Storage > Buckets.
Clique no nome do bucket (por exemplo, forgerock-openidm-audit-logs).
Acesse a guia Permissões.
Clique em Conceder acesso.
Informe os seguintes detalhes de configuração:
- Adicionar principais: insira o e-mail da conta de serviço (por exemplo, forgerock-openidm-collector-sa@PROJECT_ID.iam.gserviceaccount.com).
- Atribuir papéis: selecione Administrador de objetos do Storage.
Clique em Salvar.

Criar tópico Pub/Sub

Crie um tópico do Pub/Sub em que o Cloud Scheduler vai publicar e a função do Cloud Run vai se inscrever.

No Console do GCP, acesse Pub/Sub > Tópicos.
Selecione Criar tópico.
Informe os seguintes detalhes de configuração:
- ID do tópico: insira forgerock-openidm-trigger.
- Não altere as outras configurações.
Clique em Criar.

Criar uma função do Cloud Run para coletar registros

A função do Cloud Run será acionada por mensagens do Pub/Sub do Cloud Scheduler para buscar registros da API ForgeRock OpenIDM e gravá-los no GCS.

No console do GCP, acesse o Cloud Run.
Clique em Criar serviço.
Selecione Função (use um editor in-line para criar uma função).

Na seção Configurar, forneça os seguintes detalhes de configuração:

Configuração	Valor
Nome do serviço	`forgerock-openidm-collector`
Região	Selecione a região que corresponde ao seu bucket do GCS (por exemplo, `us-central1`).
Ambiente de execução	Selecione Python 3.12 ou uma versão mais recente.

Na seção Acionador (opcional):
1. Clique em + Adicionar gatilho.
2. Selecione Cloud Pub/Sub.
3. Em Selecionar um tópico do Cloud Pub/Sub, escolha o tópico do Pub/Sub forgerock-openidm-trigger.
4. Clique em Salvar.
Na seção Autenticação:
1. Selecione Exigir autenticação.
2. Confira o Identity and Access Management (IAM).
Observação: o Pub/Sub processa automaticamente a autenticação ao invocar a função.
Role a tela para baixo e abra Contêineres, rede, segurança.
Acesse a guia Segurança:
- Conta de serviço: selecione a conta de serviço forgerock-openidm-collector-sa.

Acesse a guia Contêineres:

Clique em Variáveis e secrets.

Clique em + Adicionar variável para cada variável de ambiente:

Nome da variável	Valor de exemplo	Descrição
`GCS_BUCKET`	`forgerock-openidm-audit-logs`	Nome do bucket do GCS
`GCS_PREFIX`	`openidm`	Prefixo para arquivos de registro
`STATE_KEY`	`openidm/state.json`	Caminho do arquivo de estado
`OPENIDM_BASE_URL`	`https://openidm.example.com`	URL base do OpenIDM
`OPENIDM_USERNAME`	`openidm-admin`	Nome de usuário do administrador do OpenIDM
`OPENIDM_PASSWORD`	`your-admin-password`	Senha de administrador do OpenIDM
`AUDIT_TOPICS`	`access,activity,authentication,config,sync`	Tópicos de auditoria separados por vírgulas
`PAGE_SIZE`	`100`	Registros por página
`MAX_PAGES`	`50`	Número máximo de páginas por tema

Na seção Variáveis e secrets, role a tela para baixo até Solicitações:
- Tempo limite da solicitação: insira 600 segundos (10 minutos).
Acesse a guia Configurações:
- Na seção Recursos:
  - Memória: selecione 512 MiB ou mais.
  - CPU: selecione 1.
- Na seção Escalonamento de revisão:
  - Número mínimo de instâncias: insira 0.
  - Número máximo de instâncias: insira 100 ou ajuste com base na carga esperada.
Clique em Criar.
Aguarde a criação do serviço (1 a 2 minutos).
Depois que o serviço for criado, o editor de código inline será aberto automaticamente.

Adicionar código da função

Insira main no campo Ponto de entrada.

No editor de código em linha, crie dois arquivos:

Primeiro arquivo: main.py::

import functions_framework
from google.cloud import storage
import json
import os
import urllib3
from datetime import datetime, timezone

# Initialize HTTP client with timeouts
http = urllib3.PoolManager(
    timeout=urllib3.Timeout(connect=5.0, read=30.0),
    retries=False,
)

# Initialize Storage client
storage_client = storage.Client()

# Environment variables
GCS_BUCKET = os.environ.get('GCS_BUCKET')
GCS_PREFIX = os.environ.get('GCS_PREFIX', 'openidm')
STATE_KEY = os.environ.get('STATE_KEY', 'openidm/state.json')
OPENIDM_BASE_URL = os.environ.get('OPENIDM_BASE_URL')
OPENIDM_USERNAME = os.environ.get('OPENIDM_USERNAME')
OPENIDM_PASSWORD = os.environ.get('OPENIDM_PASSWORD')
AUDIT_TOPICS = os.environ.get('AUDIT_TOPICS', 'access,activity,authentication,config,sync').split(',')
PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '100'))
MAX_PAGES = int(os.environ.get('MAX_PAGES', '50'))

@functions_framework.cloud_event
def main(cloud_event):
    """
    Cloud Run function triggered by Pub/Sub to fetch ForgeRock OpenIDM logs and write to GCS.

    Args:
        cloud_event: CloudEvent object containing Pub/Sub message
    """

    if not all([GCS_BUCKET, OPENIDM_BASE_URL, OPENIDM_USERNAME, OPENIDM_PASSWORD]):
        print('Error: Missing required environment variables')
        return

    try:
        # Get GCS bucket
        bucket = storage_client.bucket(GCS_BUCKET)

        # Load state
        state = load_state(bucket, STATE_KEY)

        all_events = []
        for topic in AUDIT_TOPICS:
            topic = topic.strip()
            print(f"Fetching audit logs for topic: {topic}")
            events = fetch_audit_logs(topic, state.get(topic, {}))
            all_events.extend(events)

            if events:
                latest_timestamp = max(e.get('timestamp', '') for e in events)
                state[topic] = {
                    'last_timestamp': latest_timestamp,
                    'last_run': datetime.now(timezone.utc).isoformat(),
                    'events_count': len(events)
                }

        if all_events:
            write_to_gcs(bucket, all_events)
            save_state(bucket, STATE_KEY, state)
            print(f"Successfully processed {len(all_events)} audit events")
        else:
            print("No new audit events to process")

    except Exception as e:
        print(f'Error processing logs: {str(e)}')
        raise

def load_state(bucket, key):
    """Load state from GCS."""
    try:
        blob = bucket.blob(key)
        if blob.exists():
            state_data = blob.download_as_text()
            return json.loads(state_data)
    except Exception as e:
        print(f"Warning: Could not load state: {e}")

    return {}

def save_state(bucket, key, state):
    """Save state to GCS."""
    try:
        blob = bucket.blob(key)
        blob.upload_from_string(
            json.dumps(state, indent=2),
            content_type='application/json'
        )
        print(f"Saved state: {json.dumps(state)}")
    except Exception as e:
        print(f"Warning: Could not save state: {e}")

def fetch_audit_logs(topic, topic_state):
    """
    Fetch audit logs from ForgeRock OpenIDM API with pagination.

    Args:
        topic: Audit topic name
        topic_state: State dictionary for this topic

    Returns:
        List of audit events
    """
    base_url = OPENIDM_BASE_URL.rstrip('/')

    all_events = []
    last_timestamp = topic_state.get('last_timestamp')

    query_filter = 'true'
    if last_timestamp:
        query_filter = f'timestamp gt "{last_timestamp}"'

    page_offset = 0
    page_count = 0

    while page_count < MAX_PAGES:
        try:
            url = f"{base_url}/openidm/audit/{topic}"
            params = {
                '_queryFilter': query_filter,
                '_pageSize': str(PAGE_SIZE),
                '_pagedResultsOffset': str(page_offset),
                '_sortKeys': 'timestamp'
            }

            query_string = '&'.join([f"{k}={urllib3.request.urlencode({k: v})[len(k)+1:]}" for k, v in params.items()])
            full_url = f"{url}?{query_string}"

            headers = {
                'X-OpenIDM-Username': OPENIDM_USERNAME,
                'X-OpenIDM-Password': OPENIDM_PASSWORD,
                'Accept-API-Version': 'resource=1.0',
                'Accept': 'application/json'
            }

            response = http.request('GET', full_url, headers=headers)

            if response.status != 200:
                print(f"API error for topic {topic}: {response.status} - {response.data.decode('utf-8')}")
                break

            data = json.loads(response.data.decode('utf-8'))
            events = data.get('result', [])

            if not events:
                print(f"No more events for topic {topic}")
                break

            all_events.extend(events)
            page_offset += PAGE_SIZE
            page_count += 1

            print(f"Fetched page {page_count} for topic {topic}, total events: {len(all_events)}")

            if len(events) < PAGE_SIZE:
                break

        except urllib3.exceptions.HTTPError as e:
            print(f"HTTP error for topic {topic}: {str(e)}")
            break
        except json.JSONDecodeError as e:
            print(f"JSON decode error for topic {topic}: {str(e)}")
            break
        except Exception as e:
            print(f"Unexpected error for topic {topic}: {str(e)}")
            break

    return all_events

def write_to_gcs(bucket, events):
    """Write events to GCS as NDJSON."""
    timestamp = datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')
    filename = f"{GCS_PREFIX}/openidm_audit_{timestamp}.json"

    ndjson_content = '\n'.join([json.dumps(event) for event in events])

    blob = bucket.blob(filename)
    blob.upload_from_string(
        ndjson_content.encode('utf-8'),
        content_type='application/x-ndjson'
    )

    print(f"Wrote {len(events)} events to gs://{GCS_BUCKET}/{filename}")

Segundo arquivo: requirements.txt:

functions-framework==3.*
google-cloud-storage==2.*
urllib3>=2.0.0

Clique em Implantar para salvar e implantar a função.
Aguarde a conclusão da implantação (2 a 3 minutos).

Observação: a configuração do acionador do Pub/Sub cria automaticamente as assinaturas e permissões necessárias.

Criar o job do Cloud Scheduler

O Cloud Scheduler vai publicar mensagens no tópico do Pub/Sub em intervalos regulares, acionando a função do Cloud Run.

No Console do GCP, acesse o Cloud Scheduler.
Clique em Criar job.

Informe os seguintes detalhes de configuração:

Configuração	Valor
Nome	`forgerock-openidm-collector-hourly`
Região	Selecione a mesma região da função do Cloud Run
Frequência	`0 * * * *` (a cada hora, na hora)
Fuso horário	Selecione o fuso horário (UTC recomendado)
Tipo de destino	Pub/Sub
Tópico	Selecione o tópico do Pub/Sub `forgerock-openidm-trigger`
Corpo da mensagem	`{}` (objeto JSON vazio)

Clique em Criar.

Opções de frequência de programação

Escolha a frequência com base no volume de registros e nos requisitos de latência:

Frequência	Expressão Cron	Caso de uso
A cada 5 minutos	`/5 * * *`	Alto volume e baixa latência
A cada 15 minutos	`/15 * * *`	Volume médio
A cada hora	`0 * * * *`	Padrão (recomendado)
A cada 6 horas	`0 /6 * *`	Baixo volume, processamento em lote
Diariamente	`0 0 * * *`	Coleta de dados históricos

Testar a integração

No console do Cloud Scheduler, encontre o job forgerock-openidm-collector-hourly.
Clique em Executar à força para acionar o job manualmente.
Aguarde alguns segundos.
Acesse Cloud Run > Serviços.
Clique no nome da função forgerock-openidm-collector.
Clique na guia Registros.

Verifique se a função foi executada com sucesso. Procure:

Fetching audit logs for topic: access
Fetched page 1 for topic access, total events: X
Wrote X events to gs://forgerock-openidm-audit-logs/openidm/openidm_audit_YYYYMMDD_HHMMSS.json
Successfully processed X audit events

Acesse Cloud Storage > Buckets.
Clique no nome do bucket forgerock-openidm-audit-logs.
Navegue até a pasta de prefixo openidm/.
Verifique se um novo arquivo .json foi criado com o carimbo de data/hora atual.

Se você encontrar erros nos registros:

HTTP 401: verifique as credenciais do OpenIDM nas variáveis de ambiente
HTTP 403: verifique se a conta tem permissões de leitura de auditoria
HTTP 404: verifique se OPENIDM_BASE_URL está correto e não inclui caminhos finais.
Variáveis de ambiente ausentes: verifique se todas as variáveis necessárias estão definidas.

Recuperar a conta de serviço do Google SecOps

O Google SecOps usa uma conta de serviço exclusiva para ler dados do seu bucket do GCS. Você precisa conceder a essa conta de serviço acesso ao seu bucket.

Configurar um feed no Google SecOps para ingerir registros do ForgeRock OpenIDM

Acesse Configurações do SIEM > Feeds.
Clique em Adicionar novo feed.
Clique em Configurar um único feed.
No campo Nome do feed, insira um nome para o feed (por exemplo, ForgeRock OpenIDM Audit Logs).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione FORGEROCK_OPENIDM como o Tipo de registro.
Clique em Receber conta de serviço.
Um e-mail exclusivo da conta de serviço será exibido, por exemplo:
```
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
```
Copie o endereço de e-mail. Você vai usá-la na próxima etapa.

Observação: cada instância do Google SecOps tem uma conta de serviço exclusiva. Não use contas de serviço de outras documentações ou exemplos.
Clique em Próxima.
Especifique valores para os seguintes parâmetros de entrada:
- URL do bucket de armazenamento: insira o URI do bucket do GCS com o caminho do prefixo:
```
gs://forgerock-openidm-audit-logs/openidm/
```
- Substitua:
  - forgerock-openidm-audit-logs: o nome do bucket do GCS.
  - openidm: o caminho do prefixo onde os registros são armazenados.
Observação: sempre inclua a barra (/) no final do URI.
- Opção de exclusão da fonte: selecione a opção de exclusão de acordo com sua preferência:
  - Nunca: nunca exclui arquivos após as transferências (recomendado para testes).
  - Excluir arquivos transferidos: exclui os arquivos após a transferência bem-sucedida.
  - Excluir arquivos transferidos e diretórios vazios: exclui arquivos e diretórios vazios após a transferência bem-sucedida.
Observação: se você selecionar uma opção de exclusão, a conta de serviço precisará ter o papel Administrador de objetos do Storage em vez de Leitor de objetos do Storage. Atualize as permissões do IAM de acordo com a necessidade.
- Idade máxima do arquivo: inclui arquivos modificados no último número de dias. O padrão é de 180 dias.
- Namespace do recurso: o namespace do recurso.
- Rótulos de ingestão: o rótulo a ser aplicado aos eventos deste feed.
Clique em Próxima.
Revise a nova configuração do feed na tela Finalizar e clique em Enviar.

Conceder permissões do IAM à conta de serviço do Google SecOps

A conta de serviço do Google SecOps precisa do papel de Leitor de objetos do Storage no seu bucket do GCS.

Acesse Cloud Storage > Buckets.
Clique no nome do bucket forgerock-openidm-audit-logs.
Acesse a guia Permissões.
Clique em Conceder acesso.
Informe os seguintes detalhes de configuração:
- Adicionar participantes: cole o e-mail da conta de serviço do Google SecOps.
- Atribuir papéis: selecione Leitor de objetos do Storage.
Clique em Salvar.

Observação: se você planeja usar a opção de exclusão "Excluir arquivos transferidos" ou "Excluir arquivos transferidos e diretórios vazios", conceda o papel Administrador de objetos do Storage em vez de Leitor de objetos do Storage.

Tabela de mapeamento do UDM

Campo de registro	Mapeamento do UDM	Lógica
additional_label, additional_elapsed_time, additional_ContentLength, additional_accept_encoding, additional_Accept, additional_accept_language, additional_origin_hop, additional_cache_control, additional_Connection, additional_Cookie, additional_Pragma, additional_exchange_id, additional_contentType, additional_X-content_type-Options, fluenttag_label, source_label, topic_label, request_protocol_label, taskName_label, linkQualifier_label, situation_label, mapping_label, eventid_label, context_roles_label, field_names_label	additional.fields	Outros pares de chave-valor
Via	intermediary.hostname	Nome do host do intermediário
x_forwarded_ip, ip, caller.callerIps	intermediary.ip	Endereço IP do intermediário
timestamp	metadata.event_timestamp	Carimbo de data/hora do evento
	metadata.event_type	Tipo de evento
transactionId	metadata.product_deployment_id	Identificador de implantação do produto
eventName	metadata.product_event_type	Tipo de evento do produto
_id, trackingIds	metadata.product_log_id	Identificador de registros do produto
http.request.secure	network.application_protocol	Protocolo de aplicativo
http_version	network.application_protocol_version	Versão do protocolo de aplicativo
request_method, http.request.method	network.http.method	Método HTTP
user_agent, http.request.headers.user_agent.0	network.http.parsed_user_agent	User agent analisado
refferal_url	network.http.referral_url	URL de referência
response.statusCode, status_code	network.http.response_code	Código de resposta HTTP
user_agent, http.request.headers.user_agent	network.http.user_agent	String do user agent
transaction_id, transactionId	network.session_id	Identificador de sessão
Host	principal.asset.hostname	Nome do host do recurso do principal
true_client_ip, client.ip, context.ipAddress, entry.info.ipAddress, src_ip	principal.asset.ip	Endereço IP do recurso do principal
Host	principal.hostname	Nome do host do principal
true_client_ip, client.ip, context.ipAddress, entry.info.ipAddress, src_ip	principal.ip	Endereço IP do principal
client.port, src_port	principal.port	Porto do principal
component_label, moduleId_label, query_id_label	principal.resource.attribute.labels	Rótulos de atributos para o recurso da entidade principal
entry.info.treeName	principal.resource.name	Nome do recurso do principal
sourceObjectId, objectId, entry.info.nodeId	principal.resource.product_object_id	ID do objeto do produto para o recurso do principal
entry.info.authLevel	principal.resource.resource_subtype	Subtipo do recurso da entidade principal.
user_roles_property_label, authentication_id_label, authentication_id_property_label	principal.user.attribute.labels	Rótulos de atributos para o usuário da entidade principal
userId, principalData.0	principal.user.userid	ID do usuário do principal
security_action	security_result.action	Ação realizada no resultado de segurança
resultado, ação	security_result.action_details	Detalhes da ação
result_label, moduleId_label, nodeType_label, displayName_label, nodeOutcome_label, elapsedTimeUnits_label, elapsedTime_label, operation_label, taskName_label, linkQualifier_label, situation_label, mapping_label	security_result.detection_fields	Campos de detecção
level	security_result.severity	Gravidade do resultado de segurança
level	security_result.severity_details	Detalhes da gravidade
response_detail_reason	security_result.summary	Resumo do resultado de segurança
http.request.headers.host.0	target.asset.hostname	Nome do host do recurso de destino
server.ip, x_forwarded_ip	target.asset.ip	Endereço IP do recurso de destino
http.request.headers.host.0	target.hostname	Nome do host do destino
server.ip, x_forwarded_ip	target.ip	Endereço IP do destino
server.port	target.port	Porta do destino
targetObjectId	target.resource.product_object_id	ID do objeto do produto para o recurso de destino
http.request.path	target.url	URL do destino
	metadata.product_name	Nome do produto
	metadata.vendor_name	Nome do fornecedor

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.