Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

UKG ログを収集する

以下でサポートされています。

Google SecOps SIEM

このドキュメントでは、Google Cloud Storage V2 を使用して UKG ログを Google Security Operations に取り込む方法について説明します。

UKG（Ultimate Kronos Group）は、勤怠管理、認証、監査証跡のログを生成する人的資本管理プラットフォームです。UKG Pro は、監査データにプログラムでアクセスするための REST API を提供しています。

始める前に

次の前提条件を満たしていることを確認してください。

Google SecOps インスタンス
Cloud Storage API が有効になっている GCP プロジェクト
GCS バケットを作成および管理する権限
GCS バケットの IAM ポリシーを管理する権限
Cloud Run サービス、Pub/Sub トピック、Cloud Scheduler ジョブを作成する権限
管理者権限と API アクセス権を持つ UKG Pro への特権アクセス

Google Cloud Storage バケットを作成する

Google Cloud コンソールに移動します。
プロジェクトを選択するか、新しいプロジェクトを作成します。
ナビゲーションメニューで、[Cloud Storage > バケット] に移動します。
[バケットを作成] をクリックします。

次の構成情報を提供してください。

設定	値
バケットに名前を付ける	グローバルに一意の名前（`ukg-logs` など）を入力します。
ロケーションタイプ	ニーズに応じて選択します（リージョン、デュアルリージョン、マルチリージョン）。
ロケーション	場所を選択します（例: `us-central1`）。
ストレージクラス	Standard（アクセス頻度の高いログにおすすめ）
アクセス制御	均一（推奨）
保護ツール	省略可: オブジェクトのバージョニングまたは保持ポリシーを有効にする

[作成] をクリックします。

UKG Pro API 認証情報を収集する

API 認証情報を取得する

UKG Pro 管理ポータルにログインします。
[Menu] > [Administration] > [System Configuration] > [Web Services] に移動します。
API 認証情報を作成または特定します。
- API Key (US-Customer-Api-Key): 認証用の顧客 API キー。
- サービスアカウントのユーザー名: サービスアカウントのユーザー名。
- Service Account Password: サービスアカウントのパスワード。
サービスホスト URL（https://SERVICE_HOST など）をメモします。

注: トークンベースのアクセスを使用している場合は、UKG Pro API のドキュメントを参照して OAuth 2.0 認証を設定してください。

権限を確認する

API 認証情報に必要なアクセス権があることを確認するには:

UKG Pro 管理ポータルにログインします。
[Menu] > [Administration] > [System Configuration] > [Security] > [Audit Trail] に移動します。
監査レコードを表示できることを確認します。
監査データにアクセスできない場合は、UKG Pro 管理者に連絡して、必要な権限を付与してもらってください。

テスト API へのアクセス

統合に進む前に、認証情報をテストします。

# 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"

Cloud Run functions のサービスアカウントを作成する

Cloud Run functions には、GCS バケットへの書き込み権限があり、Pub/Sub によって呼び出されるサービスアカウントが必要です。

サービスアカウントの作成

GCP コンソールで、[IAM と管理>サービスアカウント] に移動します。
[サービスアカウントを作成] をクリックします。
次の構成情報を指定します。
- サービスアカウント名: 「ukg-collector-sa」と入力します。
- サービスアカウントの説明: 「Service account for Cloud Run function to collect UKG logs」と入力します。
[作成して続行] をクリックします。
[このサービスアカウントにプロジェクトへのアクセスを許可する] セクションで、次のロールを追加します。
1. [ロールを選択] をクリックします。
2. [ストレージオブジェクト管理者] を検索して選択します。
3. [+ 別のロールを追加] をクリックします。
4. [Cloud Run 起動元] を検索して選択します。
5. [+ 別のロールを追加] をクリックします。
6. [Cloud Functions 起動元] を検索して選択します。
[続行] をクリックします。
[完了] をクリックします。

これらのロールは、次の操作に必要です。

Storage オブジェクト管理者: ログを GCS バケットに書き込み、状態ファイルを管理する
Cloud Run 起動元: Pub/Sub が関数を呼び出すことを許可します。
Cloud Functions 起動元: 関数の呼び出しを許可する

GCS バケットに対する IAM 権限を付与する

GCS バケットに対する書き込み権限をサービスアカウントに付与します。

[Cloud Storage] > [バケット] に移動します。
バケット名（ukg-logs など）をクリックします。
[権限] タブに移動します。
[アクセス権を付与] をクリックします。
次の構成情報を指定します。
- プリンシパルを追加: サービスアカウントのメールアドレス（例: ukg-collector-sa@your-project.iam.gserviceaccount.com）を入力します。
- ロールを割り当てる: [ストレージオブジェクト管理者] を選択します。
[保存] をクリックします。

Pub/Sub トピックの作成

Cloud Scheduler がパブリッシュし、Cloud Run 関数がサブスクライブする Pub/Sub トピックを作成します。

GCP Console で、[Pub/Sub> トピック] に移動します。
[トピックを作成] をクリックします。
次の構成情報を指定します。
- トピック ID: 「ukg-trigger」と入力します。
- その他の設定はデフォルトのままにします。
[作成] をクリックします。

ログを収集する Cloud Run 関数を作成する

Cloud Run 関数は、Cloud Scheduler からの Pub/Sub メッセージによってトリガーされ、UKG Pro API からログを取得して GCS に書き込みます。

GCP Console で、[Cloud Run] に移動します。
[サービスを作成] をクリックします。
[関数] を選択します（インラインエディタを使用して関数を作成します）。

[構成] セクションで、次の構成の詳細を指定します。

設定	値
サービス名	`ukg-collector`
リージョン	GCS バケットと一致するリージョンを選択します（例: `us-central1`）。
ランタイム	[Python 3.12] 以降を選択します。

[トリガー（省略可）] セクションで、次の操作を行います。
1. [+ トリガーを追加] をクリックします。
2. [Cloud Pub/Sub] を選択します。
3. [Cloud Pub/Sub トピックを選択してください] で、トピック ukg-trigger を選択します。
4. [保存] をクリックします。
[認証] セクションで、次の操作を行います。
1. [認証が必要] を選択します。
2. Identity and Access Management（IAM）を確認します。
注: Pub/Sub は、関数を呼び出すときに認証を自動的に処理します。
下にスクロールして、[コンテナ、ネットワーキング、セキュリティ] を開きます。
[セキュリティ] タブに移動します。
- サービスアカウント: サービスアカウント ukg-collector-sa を選択します。

[コンテナ] タブに移動します。

[変数とシークレット] をクリックします。
環境変数ごとに [+ 変数を追加] をクリックします。

変数名	値の例	説明
`GCS_BUCKET`	`ukg-logs`	GCS バケット名
`GCS_PREFIX`	`ukg`	ログファイルの接頭辞
`STATE_KEY`	`ukg/state.json`	状態ファイルのパス
`SERVICE_HOST`	`your-service-host`	UKG Pro サービスホストの URL
`UKG_USERNAME`	`your-service-username`	サービスアカウントのユーザー名
`UKG_PASSWORD`	`your-service-password`	サービスアカウントのパスワード
`UKG_API_KEY`	`your-api-key`	顧客 API キー
`MAX_RECORDS`	`10000`	実行あたりの最大レコード数
`PAGE_SIZE`	`100`	1 ページあたりのレコード数
`LOOKBACK_HOURS`	`24`	初期ルックバック期間

[変数とシークレット] タブで [リクエスト] まで下にスクロールします。
- リクエストのタイムアウト: 600 秒（10 分）を入力します。
[コンテナ] の [設定] タブに移動します。
- [リソース] セクションで次の操作を行います。
  - メモリ: 512 MiB 以上を選択します。
  - CPU: [1] を選択します。
[リビジョンスケーリング] セクションで、次の操作を行います。
- [インスタンスの最小数] に「0」と入力します。
- インスタンスの最大数: 100 と入力します（または、想定される負荷に基づいて調整します）。
[作成] をクリックします。
サービスが作成されるまで待ちます（1 ～ 2 分）。
サービスを作成すると、インラインコードエディタが自動的に開きます。

関数コードを追加する

[関数のエントリポイント] に「main」と入力します。

インラインコードエディタで、次の 2 つのファイルを作成します。

最初のファイル: 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

2 つ目のファイル: requirements.txt:

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

[デプロイ] をクリックして、関数を保存してデプロイします。
デプロイが完了するまで待ちます（2 ～ 3 分）。

注: Pub/Sub トリガー構成では、必要なサブスクリプションと権限が自動的に作成されます。

Cloud Scheduler ジョブの作成

Cloud Scheduler は、定期的に Pub/Sub トピックにメッセージをパブリッシュし、Cloud Run functions の関数をトリガーします。

GCP Console で、[Cloud Scheduler] に移動します。
[ジョブを作成] をクリックします。

次の構成情報を提供してください。

設定	値
名前	`ukg-collector-hourly`
リージョン	Cloud Run functions と同じリージョンを選択する
周波数	`0 * * * *`（1 時間ごと、毎正時）
タイムゾーン	タイムゾーンを選択（UTC を推奨）
ターゲットタイプ	Pub/Sub
トピック	トピック「`ukg-trigger`」を選択します
メッセージ本文	`{}`（空の JSON オブジェクト）

[作成] をクリックします。

スケジュールの頻度オプション

ログの量とレイテンシの要件に基づいて頻度を選択します。

頻度	CRON 式	ユースケース
5 分おき	`/5 * * *`	大容量、低レイテンシ
15 分ごと	`/15 * * *`	検索量が普通
1 時間ごと	`0 * * * *`	標準（推奨）
6 時間ごと	`0 /6 * *`	少量、バッチ処理
毎日	`0 0 * * *`	過去のデータの収集

統合をテストする

Cloud Scheduler コンソールで、ジョブ（ukg-collector-hourly）を見つけます。
[強制実行] をクリックして、手動でトリガーします。
数秒待ってから、[Cloud Run> サービス> ukg-collector > ログ] に移動します。

関数が正常に実行されたことを確認します。以下のものを探します。

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

GCS バケット（ukg-logs）を調べて、ログが書き込まれたことを確認します。

ログにエラーが表示された場合:

HTTP 401: 環境変数で API 認証情報を確認する
HTTP 403: サービスアカウントに UKG Pro で必要な権限があることを確認する
HTTP 429: レート制限 - 関数はバックオフで自動的に再試行されます
アクセストークンの取得に失敗しました: SERVICE_HOST、UKG_USERNAME、UKG_PASSWORD、UKG_API_KEY が正しいことを確認します

UKG のログを取り込むように Google SecOps でフィードを構成する

[SIEM 設定] > [フィード] に移動します。
[Add New Feed] をクリックします。
[単一フィードを設定] をクリックします。
[フィード名] フィールドに、フィードの名前を入力します（例: UKG Logs）。
[ソースタイプ] として [Google Cloud Storage V2] を選択します。
[ログタイプ] として [UKG] を選択します。
[サービスアカウントを取得する] をクリックします。一意のサービスアカウントのメールアドレスが表示されます（例:）。
```
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
```
このメールアドレスをコピーします。次のステップでこれを使用します。

注: 各 Google SecOps インスタンスには一意のサービスアカウントがあります。他のドキュメントや例のサービスアカウントは使用しないでください。
[次へ] をクリックします。
次の入力パラメータの値を指定します。
- ストレージバケットの URL: 接頭辞パスを含む GCS バケット URI を入力します。
```
gs://ukg-logs/ukg/
```
  - 次のように置き換えます。
    - ukg-logs: GCS バケット名。
    - ukg: ログが保存されるオプションの接頭辞/フォルダパス（ルートの場合は空のままにします）。
注: URI の末尾には常にスラッシュ（/）を含めてください。
- Source deletion option: 必要に応じて削除オプションを選択します。
  - なし: 転送後にファイルを削除しません（テストにおすすめ）。
  - 転送されたファイルを削除する: 転送が完了した後にファイルを削除します。
  - 転送されたファイルと空のディレクトリを削除する: 転送が完了した後にファイルと空のディレクトリを削除します。
    
    注: 削除オプションを選択する場合は、サービスアカウントに Storage オブジェクト閲覧者ではなく、Storage オブジェクト管理者のロールが必要です。必要に応じて IAM 権限を更新します。
- ファイルの最大経過日数: 過去の日数以内に変更されたファイルを含めます（デフォルトは 180 日）。
- アセットの名前空間: アセットの名前空間。
- Ingestion labels: このフィードのイベントに適用されるラベル。
[次へ] をクリックします。
[Finalize] 画面で新しいフィードの設定を確認し、[送信] をクリックします。

Google SecOps サービスアカウントに IAM 権限を付与する

Google SecOps サービスアカウントには、GCS バケットに対する Storage オブジェクト閲覧者のロールが必要です。

[Cloud Storage] > [バケット] に移動します。
バケット名（ukg-logs）をクリックします。
[権限] タブに移動します。
[アクセス権を付与] をクリックします。
次の構成情報を指定します。
- プリンシパルを追加: Google SecOps サービスアカウントのメールアドレスを貼り付けます。
- ロールを割り当てる: [Storage オブジェクト閲覧者] を選択します。
[保存] をクリックします。

注: 削除オプションの [転送されたファイルを削除] または [転送されたファイルと空のディレクトリを削除] を使用する場合は、Storage オブジェクト閲覧者ではなく、Storage オブジェクト管理者ロールを付与します。

UDM マッピングテーブル

ログフィールド	UDM マッピング	ロジック
integrationUserKey、userStatus	entity.user.attribute.labels	キーがフィールド名、値がフィールドの値に設定された Key-Value ラベルとして統合されます
userName	entity.user.email_addresses	メールの正規表現に一致する場合、配列に統合されます
employeeId	entity.user.employee_id	空でない場合、値が直接コピーされます
userLastLogonDate	entity.user.last_login_time	yyyy-MM-ddTHH:mm:ss.SS または ISO8601 形式の日付と一致するタイムスタンプに変換されました
userLastPasswordChangeDate	entity.user.last_password_change_time	yyyy-MM-ddTHH:mm:ss.SSS または ISO8601 形式の日付と一致するタイムスタンプに変換されました
userId	entity.user.product_object_id	文字列に変換しました
fullName	entity.user.user_display_name	値を直接コピーする
userId	entity.user.userid	文字列に変換しました
has_user	metadata.entity_type	has_user == 「true」の場合は「USER」、それ以外の場合は「UNKNOWN_ENTITYTYPE」に設定します。

変更ログ

このパーサーの変更ログを表示する

さらにサポートが必要な場合 コミュニティメンバーや Google SecOps のプロフェッショナルから回答を得ることができます。