收集 PingOne Advanced Identity Cloud 日志

支持的平台：

Google SecOps SIEM

注意： 此功能受《Google Security Operations 服务专用条款》的正式发布前产品条款的约束。我们对正式发布前功能的支持可能有限，并且对正式发布前功能的更改与其他正式发布前版本可能不兼容。如需了解详情，请参阅 Google SecOps 技术支持服务准则和 Google SecOps 服务专用条款。

本文档介绍了如何使用 Google Cloud Storage 将 PingOne Advanced Identity Cloud 日志提取到 Google Security Operations。PingOne Advanced Identity Cloud 是一个身份和访问权限管理平台，可为基于云的应用提供身份验证、授权和用户管理功能。

准备工作

确保您满足以下前提条件：

• Google SecOps 实例
• 已启用 Cloud Storage API 的 GCP 项目
• 创建和管理 GCS 存储分区的权限
• 管理 GCS 存储分区的 IAM 政策的权限
• 创建 Cloud Run 服务、Pub/Sub 主题和 Cloud Scheduler 作业的权限
• 对 PingOne Advanced Identity Cloud 租户的特权访问权限

获取 PingOne API 密钥和租户 FQDN

1. 登录 Advanced Identity Cloud 管理控制台。
2. 依次点击用户图标 > 租户设置。
3. 在全局设置标签页上，点击 Log API Keys。
4. 点击 New Log API Key，然后为该密钥提供一个名称。
5. 点击创建密钥。
6. 将 api_key_id 和 api_key_secret 值复制并保存在安全位置。系统不会再显示 api_key_secret 值。
7. 点击完成。

8. 前往租户设置 > 详细信息，然后找到您的租户 FQDN（例如 example.tomcat.pingone.com）。

   注意： PingOne Advanced Identity Cloud 会将审核日志和调试日志保留 30 天。该 API 无法检索早于此保留期限的数据。相应地规划收集频率。

创建 Google Cloud Storage 存储分区

1. 前往 Google Cloud 控制台。
2. 选择您的项目或创建新项目。
3. 在导航菜单中，依次前往 Cloud Storage > 存储分区。
4. 点击创建存储分区。

5. 提供以下配置详细信息：

   设置	值
   为存储分区命名	输入一个全局唯一的名称（例如 pingone-aic-logs）
   位置类型	根据您的需求进行选择（区域级、双区域级、多区域级）
   位置	选择相应位置（例如 us-central1）
   存储类别	标准（建议用于经常访问的日志）
   访问权限控制	统一（推荐）
   保护工具	可选：启用对象版本控制或保留政策

6. 点击创建。

为 Cloud Run 函数创建服务账号

Cloud Run 函数需要一个服务账号，该账号具有向 GCS 存储分区写入内容以及被 Pub/Sub 调用的权限。

创建服务账号

1. 在 GCP 控制台中，依次前往 IAM 和管理 > 服务账号。
2. 点击创建服务账号。
3. 提供以下配置详细信息：
   • 服务账号名称：输入 pingone-aic-collector-sa。
   • 服务账号说明：输入 Service account for Cloud Run function to collect PingOne Advanced Identity Cloud logs。
4. 点击创建并继续。
5. 在向此服务账号授予对项目的访问权限部分中，添加以下角色：
   1. 点击选择角色。
   2. 搜索并选择 Storage Object Admin。
   3. 点击 + 添加其他角色。
   4. 搜索并选择 Cloud Run Invoker。
   5. 点击 + 添加其他角色。
   6. 搜索并选择 Cloud Functions Invoker。
6. 点击继续。
7. 点击完成。

必须拥有这些角色，才能：

• Storage Object Admin：将日志写入 GCS 存储分区并管理状态文件
• Cloud Run Invoker：允许 Pub/Sub 调用函数
• Cloud Functions Invoker：允许调用函数

授予对 GCS 存储分区的 IAM 权限

向服务账号授予对 GCS 存储分区的写入权限：

1. 前往 Cloud Storage > 存储分区。
2. 点击您的存储分区名称。
3. 前往权限标签页。
4. 点击授予访问权限。
5. 提供以下配置详细信息：
   • 添加主账号：输入服务账号电子邮件地址（例如 pingone-aic-collector-sa@PROJECT_ID.iam.gserviceaccount.com）。
   • 分配角色：选择 Storage Object Admin。
6. 点击保存。

创建发布/订阅主题

创建一个 Pub/Sub 主题，供 Cloud Scheduler 发布消息，并供 Cloud Run 函数订阅。

1. 在 GCP 控制台中，前往 Pub/Sub > 主题。
2. 点击创建主题。
3. 提供以下配置详细信息：
   • 主题 ID：输入 pingone-aic-trigger。
   • 将其他设置保留为默认值。
4. 点击创建。

创建 Cloud Run 函数以收集日志

Cloud Run 函数由来自 Cloud Scheduler 的 Pub/Sub 消息触发，用于从 PingOne Advanced Identity Cloud API 中提取日志并将其写入 GCS。

1. 在 GCP 控制台中，前往 Cloud Run。
2. 点击创建服务。
3. 选择函数（使用内嵌编辑器创建函数）。

4. 在配置部分中，提供以下配置详细信息：

   设置	值
   Service 名称	pingone-aic-collector
   区域	选择与您的 GCS 存储分区匹配的区域（例如 us-central1）
   运行时	选择 Python 3.12 或更高版本

5. 在触发器（可选）部分中：

   1. 点击 + 添加触发器。
   2. 选择 Cloud Pub/Sub。
   3. 在选择 Cloud Pub/Sub 主题中，选择 Pub/Sub 主题 (pingone-aic-trigger)。
   4. 点击保存。

6. 在身份验证部分中：

   1. 选择需要进行身份验证。
   2. 检查 Identity and Access Management (IAM)。
   注意： 调用函数时，Pub/Sub 会自动处理身份验证。

7. 向下滚动并展开容器、网络、安全性。

8. 前往安全标签页：

   • 服务账号：选择服务账号 (pingone-aic-collector-sa)。

9. 前往容器标签页：

   1. 点击变量和密钥。
   2. 为每个环境变量点击 + 添加变量：

   变量名称	示例值	说明
   GCS_BUCKET	pingone-aic-logs	GCS 存储分区名称
   GCS_PREFIX	pingone-aic/logs	日志文件的前缀
   STATE_KEY	pingone-aic/logs/state.json	状态文件路径
   AIC_TENANT_FQDN	example.tomcat.pingone.com	租户 FQDN
   AIC_API_KEY_ID	your-api-key-id	API 密钥 ID
   AIC_API_SECRET	your-api-key-secret	API 密钥
   SOURCES	am-everything,idm-everything	以英文逗号分隔的日志源（请参阅下文中的备注）
   PAGE_SIZE	500	每页记录数
   MAX_PAGES	20	每次运行的页数上限
   LOOKBACK_SECONDS	3600	初始回溯期

   注意： 上面显示的 SOURCES 值包含常见的默认日志来源。如需发现您租户的所有可用日志源，请调用 /monitoring/logs/sources 端点。可用的来源可能包括 am-access、am-activity、am-authentication、am-core、idm-authentication、idm-core、idm-sync 等。使用适合您部署的英文逗号分隔列表配置 SOURCES 环境变量。

10. 在变量和 Secret 部分中，滚动到请求：

    • 请求超时：输入 600 秒（10 分钟）。

11. 前往设置标签页：

    • 在资源部分中：
      • 内存：选择 512 MiB 或更高值。
      • CPU：选择 1。

12. 在修订版本扩缩部分中：

    • 实例数下限：输入 0。
    • 实例数上限：输入 100（或根据预期负载进行调整）。

13. 点击创建。

14. 等待服务创建完成（1-2 分钟）。

15. 创建服务后，系统会自动打开内嵌代码编辑器。

添加函数代码

1. 在函数入口点中输入 main

2. 在内嵌代码编辑器中，创建两个文件：

   • 第一个文件：main.py:：

   import functions_framework
   from google.cloud import storage
   import json
   import os
   import urllib3
   from datetime import datetime, timezone
   import time
   
   # 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()
   
   @functions_framework.cloud_event
   def main(cloud_event):
       """
       Cloud Run function triggered by Pub/Sub to fetch logs from PingOne Advanced Identity Cloud API and write to GCS.
   
       Args:
           cloud_event: CloudEvent object containing Pub/Sub message
       """
   
       # Get environment variables
       bucket_name = os.environ.get('GCS_BUCKET')
       prefix = os.environ.get('GCS_PREFIX', 'pingone-aic/logs')
       state_key = os.environ.get('STATE_KEY', 'pingone-aic/logs/state.json')
   
       fqdn = os.environ.get('AIC_TENANT_FQDN', '').strip('/')
       api_key_id = os.environ.get('AIC_API_KEY_ID')
       api_key_secret = os.environ.get('AIC_API_SECRET')
   
       sources = [s.strip() for s in os.environ.get('SOURCES', 'am-everything,idm-everything').split(',') if s.strip()]
       page_size = min(int(os.environ.get('PAGE_SIZE', '500')), 1000)
       max_pages = int(os.environ.get('MAX_PAGES', '20'))
       lookback_seconds = int(os.environ.get('LOOKBACK_SECONDS', '3600'))
   
       if not all([bucket_name, fqdn, api_key_id, api_key_secret]):
           print('Error: Missing required environment variables')
           return
   
       try:
           # Get GCS bucket
           bucket = storage_client.bucket(bucket_name)
   
           # Load state
           state = load_state(bucket, state_key)
           state.setdefault('sources', {})
   
           summary = []
   
           for source in sources:
               last_ts = state['sources'].get(source, {}).get('last_ts')
               res = fetch_source(bucket, prefix, fqdn, api_key_id, api_key_secret, source, last_ts, page_size, max_pages, lookback_seconds)
   
               if res.get('newest_ts'):
                   state['sources'][source] = {'last_ts': res['newest_ts']}
   
               summary.append(res)
   
           # Save state
           save_state(bucket, state_key, state)
   
           print(f'Successfully processed logs: {json.dumps(summary)}')
   
       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: {str(e)}')
       return {'sources': {}}
   
   def save_state(bucket, key, state):
       """Save state to GCS."""
       try:
           blob = bucket.blob(key)
           blob.upload_from_string(
               json.dumps(state, separators=(',', ':')),
               content_type='application/json'
           )
       except Exception as e:
           print(f'Warning: Could not save state: {str(e)}')
   
   def fetch_source(bucket, prefix, fqdn, api_key_id, api_key_secret, source, last_ts, page_size, max_pages, lookback_seconds):
       """Fetch logs for a specific source."""
       base_url = f"https://{fqdn}/monitoring/logs"
       now = time.time()
   
       begin_time = bounded_begin_time(last_ts, now, lookback_seconds)
   
       params = {
           'source': source,
           '_pageSize': str(page_size),
           '_sortKeys': 'timestamp',
           'beginTime': begin_time
       }
   
       headers = {
           'x-api-key': api_key_id,
           'x-api-secret': api_key_secret
       }
   
       pages = 0
       written = 0
       newest_ts = last_ts
       cookie = None
   
       while pages < max_pages:
           if cookie:
               params['_pagedResultsCookie'] = cookie
   
           # Build query string
           query_parts = [f"{k}={v}" for k, v in params.items()]
           query_string = '&'.join(query_parts)
           url = f"{base_url}?{query_string}"
   
           # Make request with retry logic
           data = http_get_with_retry(url, headers)
   
           # Write page to GCS
           write_page(bucket, prefix, data, source)
   
           # Process results
           results = data.get('result') or data.get('results') or []
           for item in results:
               t = item.get('timestamp') or item.get('payload', {}).get('timestamp')
               if t and (newest_ts is None or t > newest_ts):
                   newest_ts = t
   
           written += len(results)
           cookie = data.get('pagedResultsCookie')
           pages += 1
   
           if not cookie:
               break
   
       return {
           'source': source,
           'pages': pages,
           'written': written,
           'newest_ts': newest_ts
       }
   
   def http_get_with_retry(url, headers, timeout=60, max_retries=5):
       """Make HTTP GET request with retry logic."""
       attempt = 0
       backoff = 1.0
   
       while True:
           try:
               response = http.request('GET', url, headers=headers, timeout=timeout)
   
               if response.status == 429 and attempt < max_retries:
                   # Rate limited - check for X-RateLimit-Reset header
                   reset_header = response.headers.get('X-RateLimit-Reset')
                   if reset_header:
                       delay = max(1, int(reset_header) - int(time.time()))
                   else:
                       delay = int(backoff)
   
                   print(f'Rate limited, waiting {delay} seconds')
                   time.sleep(delay)
                   attempt += 1
                   backoff *= 2
                   continue
   
               if 500 <= response.status < 600 and attempt < max_retries:
                   print(f'Server error {response.status}, retrying in {backoff} seconds')
                   time.sleep(backoff)
                   attempt += 1
                   backoff *= 2
                   continue
   
               if response.status != 200:
                   raise Exception(f'HTTP {response.status}: {response.data.decode("utf-8")}')
   
               return json.loads(response.data.decode('utf-8'))
   
           except Exception as e:
               if attempt < max_retries:
                   print(f'Request failed: {str(e)}, retrying in {backoff} seconds')
                   time.sleep(backoff)
                   attempt += 1
                   backoff *= 2
                   continue
               raise
   
   def write_page(bucket, prefix, payload, source):
       """Write a page of logs to GCS."""
       ts = datetime.now(timezone.utc)
       blob_name = f"{prefix}/{ts.strftime('%Y/%m/%d/%H%M%S')}-pingone-aic-{source}.json"
   
       blob = bucket.blob(blob_name)
       blob.upload_from_string(
           json.dumps(payload, separators=(',', ':')),
           content_type='application/json'
       )
   
       print(f'Wrote logs to {blob_name}')
   
   def bounded_begin_time(last_ts, now, lookback_seconds):
       """Calculate begin time bounded by 24 hour limit."""
       twenty_four_h_ago = now - 24 * 3600
   
       if last_ts:
           try:
               # Parse ISO timestamp
               t_struct = time.strptime(last_ts[:19] + 'Z', '%Y-%m-%dT%H:%M:%SZ')
               t_epoch = int(time.mktime(t_struct))
           except Exception:
               t_epoch = int(now - lookback_seconds)
   
           begin_epoch = max(t_epoch, int(twenty_four_h_ago))
       else:
           begin_epoch = max(int(now - lookback_seconds), int(twenty_four_h_ago))
   
       return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(begin_epoch))
   

   • 第二个文件：requirements.txt:：

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

3. 点击部署以保存并部署该函数。

4. 等待部署完成（2-3 分钟）。

   注意： Pub/Sub 触发器配置会自动创建必要的订阅和权限。

创建 Cloud Scheduler 作业

Cloud Scheduler 会定期向 Pub/Sub 主题发布消息，从而触发 Cloud Run 函数。

1. 在 GCP Console 中，前往 Cloud Scheduler。
2. 点击创建作业。

3. 提供以下配置详细信息：

   设置	值
   名称	pingone-aic-collector-hourly
   区域	选择与 Cloud Run 函数相同的区域
   频率	0 * * * *（每小时一次，在整点时）
   时区	选择时区（建议选择世界协调时间 [UTC]）
   目标类型	Pub/Sub
   主题	选择 Pub/Sub 主题 (pingone-aic-trigger)
   消息正文	{}（空 JSON 对象）

4. 点击创建。

时间表频率选项

• 根据日志量和延迟时间要求选择频次：

  频率	Cron 表达式	使用场景
  每隔 5 分钟	*/5 * * * *	高容量、低延迟
  每隔 15 分钟	*/15 * * * *	搜索量中等
  每小时	0 * * * *	标准（推荐）
  每 6 小时	0 */6 * * *	量小、批处理
  每天	0 0 * * *	历史数据收集

测试集成

1. 在 Cloud Scheduler 控制台中，找到您的作业 (pingone-aic-collector-hourly)。
2. 点击强制运行以手动触发作业。
3. 等待几秒钟。
4. 前往 Cloud Run > 服务。
5. 点击函数名称 (pingone-aic-collector)。
6. 点击日志标签页。

7. 验证函数是否已成功执行。查找以下项：

   Fetching logs from YYYY-MM-DDTHH:MM:SS+00:00 to YYYY-MM-DDTHH:MM:SS+00:00
   Page 1: Retrieved X events
   Wrote logs to gs://bucket-name/prefix/logs_YYYYMMDD_HHMMSS.json
   Successfully processed X records
   

8. 前往 Cloud Storage > 存储分区。

9. 点击您的存储分区名称 (pingone-aic-logs)。

10. 前往前缀文件夹 (pingone-aic/logs/)。

11. 验证是否已创建具有当前时间戳的新 .json 文件。

如果您在日志中看到错误，请执行以下操作：

• HTTP 401：检查环境变量中的 API 凭据
• HTTP 403：验证账号是否具有所需权限
• HTTP 429：速率限制 - 函数将自动重试并进行退避
• 缺少环境变量：检查是否已设置所有必需的变量

检索 Google SecOps 服务账号

Google SecOps 使用唯一的服务账号从您的 GCS 存储分区中读取数据。您必须授予此服务账号对您的存储分区的访问权限。

获取服务账号电子邮件地址

1. 依次前往 SIEM 设置 > Feed。
2. 点击添加新 Feed。
3. 点击配置单个 Feed。
4. 在Feed 名称字段中，输入 Feed 的名称（例如 PingOne Advanced Identity Cloud）。
5. 选择 Google Cloud Storage V2 作为来源类型。
6. 选择 PingOne Advanced Identity Cloud 作为日志类型。

7. 点击获取服务账号。系统会显示一个唯一的服务账号电子邮件地址，例如：

   [e-mail]
   

8. 复制此电子邮件地址，以便在下一步中使用。

   注意： 每个 Google SecOps 实例都有一个唯一的服务账号。请勿使用其他文档或示例中的服务账号。

向 Google SecOps 服务账号授予 IAM 权限

Google SecOps 服务账号需要对您的 GCS 存储分区具有 Storage Object Viewer 角色。

1. 前往 Cloud Storage > 存储分区。
2. 点击您的存储分区名称 (pingone-aic-logs)。
3. 前往权限标签页。
4. 点击授予访问权限。
5. 提供以下配置详细信息：
   • 添加主账号：粘贴 Google SecOps 服务账号电子邮件地址。
   • 分配角色：选择 Storage Object Viewer。

6. 点击保存。

   注意： 如果您打算使用“删除已转移的文件”或“删除已转移的文件和空目录”删除选项，请授予存储对象管理员角色，而不是存储对象查看者角色。

在 Google SecOps 中配置 Feed 以提取 PingOne Advanced Identity Cloud 日志

1. 依次前往 SIEM 设置 > Feed。
2. 点击添加新 Feed。
3. 点击配置单个 Feed。
4. 在Feed 名称字段中，输入 Feed 的名称（例如 PingOne Advanced Identity Cloud）。
5. 选择 Google Cloud Storage V2 作为来源类型。
6. 选择 PingOne Advanced Identity Cloud 作为日志类型。
7. 点击下一步。

8. 为以下输入参数指定值：

   • 存储分区网址：输入带有前缀路径的 GCS 存储分区 URI：

     gs://pingone-aic-logs/pingone-aic/logs/
     

     • 将

       • pingone-aic-logs：您的 GCS 存储分区名称。
       • pingone-aic/logs/：存储日志的可选前缀/文件夹路径。
     注意： 请务必在 URI 末尾添加尾随斜杠 (/)。

   • 来源删除选项：根据您的偏好选择删除选项：

     • 永不：永不删除转移后的任何文件（建议用于测试）。
     • 删除已转移的文件：在成功转移后删除文件。

     • 删除已转移的文件和空目录：在成功转移后删除文件和空目录。

       注意 ：如果您选择删除选项，服务账号必须具有 Storage Object Admin 角色，而不是 Storage Object Viewer 角色。相应地更新 IAM 权限。

   • 文件存在时间上限：包含在过去指定天数内修改的文件。默认值为 180 天。

   • 资产命名空间：资产命名空间。

   • 注入标签：要应用于此 Feed 中事件的标签。

9. 点击下一步。

10. 在最终确定界面中查看新的 Feed 配置，然后点击提交。

需要更多帮助？获得社区成员和 Google SecOps 专业人士的解答。