Coletar registros do UKG

Compatível com:

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

O UKG (Ultimate Kronos Group) é uma plataforma de gerenciamento de capital humano que gera registros de gerenciamento de força de trabalho, autenticação e trilha de auditoria. O UKG Pro oferece uma API REST para acesso programático aos dados de auditoria.

Antes de começar

Verifique se você tem os pré-requisitos a seguir:

  • 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 ao UKG Pro com permissões de administrador e acesso à API

Criar um bucket do Google Cloud Storage

  1. Acesse o Console do Google Cloud.
  2. Selecione seu projeto ou crie um novo.
  3. No menu de navegação, acesse Cloud Storage > Buckets.
  4. Clique em Criar bucket.
  5. Informe os seguintes detalhes de configuração:

    Configuração Valor
    Nomeie seu bucket Insira um nome globalmente exclusivo (por exemplo, ukg-logs)
    Tipo de local Escolha de acordo com 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
  6. Clique em Criar.

Coletar credenciais da API UKG Pro

Receber credenciais de API

  1. Faça login no portal de administração do UKG Pro.
  2. Acesse Menu > Administração > Configuração do sistema > Serviços da Web.
  3. Crie ou localize suas credenciais de API:
    • Chave de API (US-Customer-Api-Key): a chave de API do cliente para autenticação.
    • Nome de usuário da conta de serviço: o nome de usuário da conta de serviço.
    • Senha da conta de serviço: a senha da conta de serviço.
  4. Anote o URL do host de serviço (por exemplo, https://SERVICE_HOST).

Verifique as permissões

Para verificar se as credenciais da API têm o acesso necessário:

  1. Faça login no portal de administração do UKG Pro.
  2. Acesse Menu > Administração > Configuração do sistema > Segurança > Trilha de auditoria.
  3. Verifique se é possível ver os registros de auditoria.
  4. Se não for possível acessar os dados de auditoria, entre em contato com o administrador do UKG Pro para conceder as permissões necessárias.

Testar o acesso à API

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

    # Replace with your actual credentials
    ACCESS_TOKEN="your-access-token"
    API_KEY="your-api-key"
    SERVICE_HOST="your-service-host"
    
    # Test API access - fetch audit logs
    curl -v -H "Authorization: Bearer ${ACCESS_TOKEN}" \
      -H "US-Customer-Api-Key: ${API_KEY}" \
      "https://${SERVICE_HOST}/personnel/v1/audit-logs?startDate=2024-01-01&endDate=2024-01-02"
    

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

  1. No Console do GCP, acesse IAM e administrador > Contas de serviço.
  2. Clique em Criar conta de serviço.
  3. Informe os seguintes detalhes de configuração:
    • Nome da conta de serviço: insira ukg-collector-sa.
    • Descrição da conta de serviço: insira Service account for Cloud Run function to collect UKG logs.
  4. Clique em Criar e continuar.
  5. 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.
  6. Clique em Continuar.
  7. Clique em Concluído.

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

  • Administrador de objetos do Storage: gravar registros no bucket do GCS e gerenciar 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 à conta de serviço permissões de gravação no bucket do GCS:

  1. Acesse Cloud Storage > Buckets.
  2. Clique no nome do bucket (por exemplo, ukg-logs).
  3. Acesse a guia Permissões.
  4. Clique em Conceder acesso.
  5. Informe os seguintes detalhes de configuração:
    • Adicionar participantes: insira o e-mail da conta de serviço (por exemplo, ukg-collector-sa@your-project.iam.gserviceaccount.com).
    • Atribuir papéis: selecione Administrador de objetos do Storage.
  6. 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.

  1. No Console do GCP, acesse Pub/Sub > Tópicos.
  2. Selecione Criar tópico.
  3. Informe os seguintes detalhes de configuração:
    • ID do tópico: insira ukg-trigger.
    • Não mude as outras configurações.
  4. 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 UKG Pro e gravá-los no GCS.

  1. No Console do GCP, acesse o Cloud Run.
  2. Clique em Criar serviço.
  3. Selecione Função (use um editor in-line para criar uma função).
  4. Na seção Configurar, forneça os seguintes detalhes de configuração:

    Configuração Valor
    Nome do serviço ukg-collector
    Região Selecione a região correspondente ao bucket do GCS (por exemplo, us-central1).
    Ambiente de execução Selecione Python 3.12 ou mais recente.
  5. 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 ukg-trigger.
    4. Clique em Salvar.
  6. Na seção Autenticação:

    1. Selecione Exigir autenticação.
    2. Verifique o Identity and Access Management (IAM).
  7. Role para baixo e abra Contêineres, rede, segurança.

  8. Acesse a guia Segurança:

    • Conta de serviço: selecione a conta de serviço ukg-collector-sa.
  9. Acesse a guia Contêineres:

    1. Clique em Variáveis e secrets.
    2. Clique em + Adicionar variável para cada variável de ambiente:
    Nome da variável Valor de exemplo Descrição
    GCS_BUCKET ukg-logs Nome do bucket do GCS
    GCS_PREFIX ukg Prefixo para arquivos de registro
    STATE_KEY ukg/state.json Caminho do arquivo de estado
    SERVICE_HOST your-service-host URL do host de serviço do UKG Pro
    UKG_USERNAME your-service-username Nome de usuário da conta de serviço
    UKG_PASSWORD your-service-password Senha da conta de serviço
    UKG_API_KEY your-api-key Chave de API do cliente
    MAX_RECORDS 10000 Máximo de registros por execução
    PAGE_SIZE 100 Registros por página
    LOOKBACK_HOURS 24 Período de lookback inicial
  10. Role para baixo na guia Variáveis e secrets até Solicitações:

    • Tempo limite da solicitação: insira 600 segundos (10 minutos).
  11. Acesse a guia Configurações em Contêineres:

    • Na seção Recursos:
      • Memória: selecione 512 MiB ou mais.
      • CPU: selecione 1.
  12. 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).
  13. Clique em Criar.

  14. Aguarde a criação do serviço (1 a 2 minutos).

  15. Depois que o serviço for criado, o editor de código inline será aberto automaticamente.

Adicionar código da função

  1. Insira main em Ponto de entrada da função.
  2. No editor de código inline, 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, timedelta
    import time
    import base64
    
    # 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', 'ukg')
    STATE_KEY = os.environ.get('STATE_KEY', 'ukg/state.json')
    SERVICE_HOST = os.environ.get('SERVICE_HOST', '').rstrip('/')
    UKG_USERNAME = os.environ.get('UKG_USERNAME', '')
    UKG_PASSWORD = os.environ.get('UKG_PASSWORD', '')
    UKG_API_KEY = os.environ.get('UKG_API_KEY', '')
    MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '10000'))
    PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '100'))
    LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
    
    def parse_datetime(value: str) -> datetime:
        """Parse ISO datetime string to datetime object."""
        if value.endswith("Z"):
            value = value[:-1] + "+00:00"
        return datetime.fromisoformat(value)
    
    def get_token():
        """Get OAuth 2.0 access token from UKG Pro."""
        token_url = f"https://{SERVICE_HOST}/authentication/token"
    
        auth_string = f"{UKG_USERNAME}:{UKG_PASSWORD}"
        auth_bytes = auth_string.encode('utf-8')
        auth_b64 = base64.b64encode(auth_bytes).decode('utf-8')
    
        headers = {
            'Authorization': f'Basic {auth_b64}',
            'US-Customer-Api-Key': UKG_API_KEY,
            'Content-Type': 'application/x-www-form-urlencoded',
            'Accept': 'application/json'
        }
    
        body = 'grant_type=client_credentials'
    
        backoff = 1.0
        max_retries = 3
    
        for attempt in range(max_retries):
            response = http.request('POST', token_url, body=body.encode('utf-8'), headers=headers)
    
            if response.status == 429:
                retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
                print(f"Rate limited (429) on token request. Retrying after {retry_after}s...")
                time.sleep(retry_after)
                backoff = min(backoff * 2, 30.0)
                continue
    
            if response.status != 200:
                raise RuntimeError(f"Failed to get access token: {response.status} - {response.data.decode('utf-8')}")
    
            data = json.loads(response.data.decode('utf-8'))
            return data['access_token']
    
        raise RuntimeError(f"Failed to get token after {max_retries} retries due to rate limiting")
    
    @functions_framework.cloud_event
    def main(cloud_event):
        """
        Cloud Run function triggered by Pub/Sub to fetch UKG logs and write to GCS.
    
        Args:
            cloud_event: CloudEvent object containing Pub/Sub message
        """
    
        if not all([GCS_BUCKET, SERVICE_HOST, UKG_USERNAME, UKG_PASSWORD, UKG_API_KEY]):
            print('Error: Missing required environment variables')
            return
    
        try:
            bucket = storage_client.bucket(GCS_BUCKET)
    
            # Load state
            state = load_state(bucket, STATE_KEY)
    
            # Determine time window
            now = datetime.now(timezone.utc)
            last_time = None
    
            if isinstance(state, dict) and state.get("last_event_time"):
                try:
                    last_time = parse_datetime(state["last_event_time"])
                    last_time = last_time - timedelta(minutes=2)
                except Exception as e:
                    print(f"Warning: Could not parse last_event_time: {e}")
    
            if last_time is None:
                last_time = now - timedelta(hours=LOOKBACK_HOURS)
    
            print(f"Fetching logs from {last_time.isoformat()} to {now.isoformat()}")
    
            # Get access token
            token = get_token()
    
            # Fetch logs
            records, newest_event_time = fetch_logs(
                token=token,
                start_time=last_time,
                end_time=now,
                page_size=PAGE_SIZE,
                max_records=MAX_RECORDS,
            )
    
            if not records:
                print("No new log records found.")
                save_state(bucket, STATE_KEY, now.isoformat())
                return
    
            # Write to GCS as NDJSON
            timestamp = now.strftime('%Y%m%d_%H%M%S')
            object_key = f"{GCS_PREFIX}/logs_{timestamp}.ndjson"
            blob = bucket.blob(object_key)
    
            ndjson = '\n'.join([json.dumps(record, ensure_ascii=False) for record in records]) + '\n'
            blob.upload_from_string(ndjson, content_type='application/x-ndjson')
    
            print(f"Wrote {len(records)} records to gs://{GCS_BUCKET}/{object_key}")
    
            if newest_event_time:
                save_state(bucket, STATE_KEY, newest_event_time)
            else:
                save_state(bucket, STATE_KEY, now.isoformat())
    
            print(f"Successfully processed {len(records)} records")
    
        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, last_event_time_iso: str):
        """Save the last event timestamp to GCS state file."""
        try:
            state = {'last_event_time': last_event_time_iso}
            blob = bucket.blob(key)
            blob.upload_from_string(
                json.dumps(state, indent=2),
                content_type='application/json'
            )
            print(f"Saved state: last_event_time={last_event_time_iso}")
        except Exception as e:
            print(f"Warning: Could not save state: {e}")
    
    def fetch_logs(token: str, start_time: datetime, end_time: datetime, page_size: int, max_records: int):
        """
        Fetch audit logs from UKG Pro API with pagination and rate limiting.
    
        Args:
            token: OAuth 2.0 access token
            start_time: Start time for log query
            end_time: End time for log query
            page_size: Number of records per page
            max_records: Maximum total records to fetch
    
        Returns:
            Tuple of (records list, newest_event_time ISO string)
        """
        endpoint = f"https://{SERVICE_HOST}/personnel/v1/audit-logs"
    
        headers = {
            'Authorization': f'Bearer {token}',
            'US-Customer-Api-Key': UKG_API_KEY,
            'Accept': 'application/json',
            'User-Agent': 'GoogleSecOps-UKGCollector/1.0'
        }
    
        records = []
        newest_time = None
        page_num = 0
        backoff = 1.0
        page = 1
    
        start_date = start_time.strftime('%Y-%m-%d')
        end_date = end_time.strftime('%Y-%m-%d')
    
        while True:
            page_num += 1
    
            if len(records) >= max_records:
                print(f"Reached max_records limit ({max_records})")
                break
    
            url = f"{endpoint}?startDate={start_date}&endDate={end_date}&page={page}&per_page={page_size}"
    
            try:
                response = http.request('GET', url, headers=headers)
    
                if response.status == 429:
                    retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
                    print(f"Rate limited (429). Retrying after {retry_after}s...")
                    time.sleep(retry_after)
                    backoff = min(backoff * 2, 30.0)
                    continue
    
                backoff = 1.0
    
                if response.status != 200:
                    print(f"HTTP Error: {response.status}")
                    response_text = response.data.decode('utf-8')
                    print(f"Response body: {response_text}")
                    return [], None
    
                data = json.loads(response.data.decode('utf-8'))
    
                # UKG may return results in different formats
                if isinstance(data, list):
                    page_results = data
                else:
                    page_results = data.get('data', data.get('results', data.get('auditLogs', [])))
    
                if not page_results:
                    print(f"No more results (empty page)")
                    break
    
                print(f"Page {page_num}: Retrieved {len(page_results)} events")
                records.extend(page_results)
    
                # Track newest event time
                for event in page_results:
                    try:
                        event_time = event.get('auditDate') or event.get('dateTime') or event.get('timestamp')
                        if event_time:
                            if newest_time is None or parse_datetime(event_time) > parse_datetime(newest_time):
                                newest_time = event_time
                    except Exception as e:
                        print(f"Warning: Could not parse event time: {e}")
    
                if len(page_results) < page_size:
                    print(f"Reached last page (size={len(page_results)} < limit={page_size})")
                    break
    
                page += 1
    
            except Exception as e:
                print(f"Error fetching logs: {e}")
                return [], None
    
        print(f"Retrieved {len(records)} total records from {page_num} pages")
        return records, newest_time
    
    • Segundo arquivo: requirements.txt::
    functions-framework==3.*
    google-cloud-storage==2.*
    urllib3>=2.0.0
    
  3. Clique em Implantar para salvar e implantar a função.

  4. Aguarde a conclusão da implantação (2 a 3 minutos).

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.

  1. No Console do GCP, acesse o Cloud Scheduler.
  2. Clique em Criar job.
  3. Informe os seguintes detalhes de configuração:

    Configuração Valor
    Nome ukg-collector-hourly
    Região Selecione a mesma região da função do Cloud Run
    Frequência 0 * * * * (de hora em hora)
    Fuso horário Selecione o fuso horário (UTC recomendado)
    Tipo de destino Pub/Sub
    Tópico Selecione o tópico ukg-trigger.
    Corpo da mensagem {} (objeto JSON vazio)
  4. 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 * * * Processamento em lote de baixo volume
Diário 0 0 * * * Coleta de dados históricos

Testar a integração

  1. No console do Cloud Scheduler, encontre seu job (ukg-collector-hourly).
  2. Clique em Forçar execução para acionar manualmente.
  3. Aguarde alguns segundos e acesse Cloud Run > Serviços > ukg-collector > Registros.
  4. Verifique se a função foi executada com sucesso. Procure por:

    Fetching logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
    Page 1: Retrieved X events
    Wrote X records to gs://ukg-logs/ukg/logs_YYYYMMDD_HHMMSS.ndjson
    Successfully processed X records
    
  5. Verifique o bucket do GCS (ukg-logs) para confirmar se os registros foram gravados.

Se você encontrar erros nos registros:

  • HTTP 401: verifique as credenciais da API nas variáveis de ambiente.
  • HTTP 403: verifique se a conta de serviço tem as permissões necessárias no UKG Pro.
  • HTTP 429: limitação de taxa. A função vai tentar novamente de forma automática com espera
  • Falha ao receber o token de acesso: verifique se SERVICE_HOST, UKG_USERNAME, UKG_PASSWORD e UKG_API_KEY estão corretos.

Configurar um feed no Google SecOps para ingerir registros do UKG

  1. Acesse Configurações > Gerenciamento de dados > Feeds. Se você estiver em uma plataforma somente SIEM, acesse Configurações > Feeds.
  2. Clique em Adicionar novo feed.
  3. Clique em Configurar um único feed.
  4. No campo Nome do feed, insira um nome para o feed (por exemplo, UKG Logs).
  5. Selecione Google Cloud Storage V2 como o Tipo de origem.
  6. Selecione UKG como o Tipo de registro.
  7. Clique em Get Service Account. Um e-mail exclusivo da conta de serviço será exibido, por exemplo:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. Copie o endereço de e-mail. Você vai usá-la na próxima etapa.

  9. Clique em Próxima.

  10. 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://ukg-logs/ukg/
      
      • Substitua:
        • ukg-logs: o nome do bucket do GCS.
        • ukg: prefixo/caminho de pasta opcional em que os registros são armazenados (deixe em branco para a raiz).
    • 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 arquivos após a transferência.
      • Excluir arquivos transferidos e diretórios vazios: exclui arquivos e diretórios vazios após a transferência.

    • Idade máxima do arquivo: inclua arquivos modificados nos últimos dias (o padrão é 180 dias).

    • Namespace do recurso: o namespace do recurso.

    • Rótulos de ingestão: o rótulo a ser aplicado aos eventos desse feed.

  11. Clique em Próxima.

  12. Revise a configuração do novo feed de notícias 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 Leitor de objetos do Storage no bucket do GCS.

  1. Acesse Cloud Storage > Buckets.
  2. Clique no nome do bucket (ukg-logs).
  3. Acesse a guia Permissões.
  4. Clique em Conceder acesso.
  5. Informe os seguintes detalhes de configuração:
    • Adicionar principais: cole o e-mail da conta de serviço do Google SecOps.
    • Atribuir papéis: selecione Leitor de objetos do Storage.
  6. Clique em Salvar.

Tabela de mapeamento de UDM

Campo de registro Mapeamento de UDM Lógica
integrationUserKey, userStatus entity.user.attribute.labels Mesclados como rótulos de chave-valor com a chave definida como o nome do campo e o valor do campo
userName entity.user.email_addresses Mesclado na matriz se corresponder à regex de e-mail
employeeId entity.user.employee_id Valor copiado diretamente se não estiver vazio
userLastLogonDate entity.user.last_login_time Convertido em carimbo de data/hora usando a correspondência de data com os formatos yyyy-MM-ddTHH:mm:ss.SS ou ISO8601
userLastPasswordChangeDate entity.user.last_password_change_time Convertido em carimbo de data/hora usando a correspondência de data com os formatos yyyy-MM-ddTHH:mm:ss.SSS ou ISO8601
userId entity.user.product_object_id Convertido em string
fullName entity.user.user_display_name Valor copiado diretamente
userId entity.user.userid Convertido em string
has_user metadata.entity_type Defina como "USER" se has_user == "true", caso contrário, "UNKNOWN_ENTITYTYPE"

Registro de alterações

Confira o registro de alterações deste analisador

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