收集 OneLogin by One Identity 日志
本文档介绍了如何使用 Google Cloud Storage V2 将 OneLogin by One Identity 日志注入到 Google Security Operations。
One Identity 的 OneLogin 是一个基于云的身份和访问权限管理 (IAM) 平台,可为企业应用提供单点登录 (SSO)、多重身份验证 (MFA) 和用户配置功能。OneLogin Events API 可提供对事件日志的程序化访问,包括用户身份验证、配置、政策变更和管理操作。
准备工作
请确保您满足以下前提条件:
- Google SecOps 实例
- 已启用 Cloud Storage API 的 GCP 项目
- 创建和管理 GCS 存储分区的权限
- 管理 GCS 存储分区的 IAM 政策的权限
- 创建 Cloud Run 服务、Pub/Sub 主题和 Cloud Scheduler 作业的权限
- 通过超级用户或同等角色对 OneLogin 管理门户网站拥有特权访问权限
- 在 OneLogin 管理门户中配置的 API 凭据(客户端 ID 和客户端密钥)
创建 Google Cloud Storage 存储桶
- 前往 Google Cloud 控制台。
- 选择您的项目或创建新项目。
- 在导航菜单中,依次前往 Cloud Storage > 存储分区。
- 点击创建存储分区。
提供以下配置详细信息:
设置 值 为存储桶命名 输入一个全局唯一的名称(例如 onelogin-sso-logs)位置类型 根据您的需求进行选择(区域级、双区域、多区域) 位置 选择营业地点(例如 us-central1)存储类别 标准(建议用于经常访问的日志) 访问权限控制 均匀(推荐) 保护工具 可选:启用对象版本控制或保留政策 点击创建。
收集 OneLogin by One Identity API 凭据
创建 API 凭据
- 登录 OneLogin 管理门户。
- 前往开发者 > API 凭据。
- 点击新凭据。
- 输入凭据的名称(例如,
Google SecOps Integration)。 - 选择读取所有内容作为权限范围。
点击保存。
复制以下详细信息并将其保存在安全的位置:
- 客户端 ID:凭据页面上显示的 API 客户端 ID
- 客户端密钥:凭据页面上显示的 API 客户端密钥
确定您的 OneLogin API 区域
OneLogin API 基准网址取决于您的数据中心区域:
| 区域 | API 基本网址 |
|---|---|
| 美国 | https://api.us.onelogin.com |
| 欧盟 | https://api.eu.onelogin.com |
验证权限
如需验证 API 凭据是否具有所需的权限,请执行以下操作:
- 登录 OneLogin 管理门户。
- 前往开发者 > API 凭据。
- 点击凭据名称(例如
Google SecOps Integration)。 - 确认已选择读取所有内容范围。如果不是,请更新范围,然后点击保存。
测试 API 访问权限
在继续进行集成之前,请先测试您的凭据:
# Replace with your actual credentials ONELOGIN_CLIENT_ID="your-client-id" ONELOGIN_CLIENT_SECRET="your-client-secret" ONELOGIN_API_BASE="[https://api.us.onelogin.com](https://api.us.onelogin.com)" # Get access token TOKEN=$(curl -s -X POST "${ONELOGIN_API_BASE}/auth/oauth2/v2/token" \ -H "Content-Type: application/json" \ -d "{\"grant_type\": \"client_credentials\", \"client_id\": \"${ONELOGIN_CLIENT_ID}\", \"client_secret\": \"${ONELOGIN_CLIENT_SECRET}\"}" \ | jq -r '.access_token') # Test API access - list recent events curl -s -X GET "${ONELOGIN_API_BASE}/api/2/events?limit=1" \ -H "Authorization: Bearer ${TOKEN}"
为 Cloud Run 函数创建服务账号
Cloud Run 函数需要一个服务账号,该账号具有写入 GCS 存储桶的权限,并且可以由 Pub/Sub 调用。
创建服务账号
- 在 GCP 控制台中,依次前往 IAM 和管理 > 服务账号。
- 点击创建服务账号。
提供以下配置详细信息:
- 服务账号名称:输入
onelogin-sso-logs-collector-sa - 服务账号说明:输入
Service account for Cloud Run function to collect OneLogin by One Identity logs
- 服务账号名称:输入
点击创建并继续。
在向此服务账号授予对项目的访问权限部分中,添加以下角色:
- 点击选择角色。
- 搜索并选择 Storage Object Admin。
- 点击 + 添加其他角色。
- 搜索并选择 Cloud Run Invoker。
- 点击 + 添加其他角色。
- 搜索并选择 Cloud Functions Invoker。
点击继续。
点击完成。
必须拥有这些角色,才能:
- Storage Object Admin:将日志写入 GCS 存储桶并管理状态文件
- Cloud Run Invoker:允许 Pub/Sub 调用函数
- Cloud Functions Invoker:允许调用函数
授予对 GCS 存储桶的 IAM 权限
向服务账号授予对 GCS 存储桶的写入权限:
- 前往 Cloud Storage > 存储分区。
- 点击您的存储桶名称(例如
onelogin-sso-logs)。 - 前往权限标签页。
- 点击授予访问权限。
提供以下配置详细信息:
- 添加主账号:输入服务账号电子邮件地址(例如
onelogin-sso-logs-collector-sa@PROJECT_ID.iam.gserviceaccount.com) - 分配角色:选择 Storage Object Admin
- 添加主账号:输入服务账号电子邮件地址(例如
点击保存。
创建 Pub/Sub 主题
创建一个 Pub/Sub 主题,Cloud Scheduler 将向该主题发布消息,而 Cloud Run 函数将订阅该主题。
- 在 GCP 控制台中,前往 Pub/Sub > 主题。
- 点击创建主题。
提供以下配置详细信息:
- 主题 ID:输入
onelogin-sso-logs-trigger - 将其他设置保留为默认值
- 主题 ID:输入
点击创建。
创建 Cloud Run 函数以收集日志
Cloud Run 函数将由来自 Cloud Scheduler 的 Pub/Sub 消息触发,以从 OneLogin Events API 中提取日志并将其写入 GCS。
- 在 GCP 控制台中,前往 Cloud Run。
- 点击创建服务。
- 选择函数(使用内嵌编辑器创建函数)。
在配置部分中,提供以下配置详细信息:
设置 值 Service 名称 onelogin-sso-logs-collector区域 选择与您的 GCS 存储桶匹配的区域(例如 us-central1)运行时 选择 Python 3.12 或更高版本 在触发器(可选)部分中:
- 点击 + 添加触发器。
- 选择 Cloud Pub/Sub。
- 在选择 Cloud Pub/Sub 主题部分,选择主题
onelogin-sso-logs-trigger。 - 点击保存。
在身份验证部分中:
- 选择需要进行身份验证。
- 检查 Identity and Access Management (IAM)。
向下滚动并展开容器、网络、安全性。
前往安全性标签页:
- 服务账号:选择服务账号
onelogin-sso-logs-collector-sa。
- 服务账号:选择服务账号
前往容器标签页:
- 点击变量和密钥。
- 为每个环境变量点击+ 添加变量:
变量名称 示例值 说明 GCS_BUCKETonelogin-sso-logsGCS 存储桶名称 GCS_PREFIXonelogin日志文件的前缀 STATE_KEYonelogin/state.json状态文件路径 ONELOGIN_CLIENT_IDyour-client-idOneLogin API 客户端 ID ONELOGIN_CLIENT_SECRETyour-client-secretOneLogin API 客户端密钥 ONELOGIN_API_BASEhttps://api.us.onelogin.comOneLogin API 基本网址 MAX_RECORDS5000每次运行的记录数上限 PAGE_SIZE250每页记录数(最多 250 条) LOOKBACK_HOURS24初始回溯期 在变量和 Secret 部分中,向下滚动到请求:
- 请求超时:输入
600秒(10 分钟)
- 请求超时:输入
前往设置标签页:
- 在资源部分中:
- 内存:选择 512 MiB 或更高值
- CPU:选择 1
- 在资源部分中:
在修订版本伸缩部分中:
- 实例数下限:输入
0 - 实例数上限:输入
100(或根据预期负载进行调整)
- 实例数下限:输入
点击创建。
等待服务创建完成(1-2 分钟)。
创建服务后,系统会自动打开内嵌代码编辑器。
添加函数代码
- 在入口点字段中输入 main。
在内嵌代码编辑器中,创建两个文件:
- main.py:
import functions_framework from google.cloud import storage import json import os import urllib3 from datetime import datetime, timezone, timedelta 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() # Environment variables GCS_BUCKET = os.environ.get('GCS_BUCKET') GCS_PREFIX = os.environ.get('GCS_PREFIX', 'onelogin') STATE_KEY = os.environ.get('STATE_KEY', 'onelogin/state.json') ONELOGIN_CLIENT_ID = os.environ.get('ONELOGIN_CLIENT_ID') ONELOGIN_CLIENT_SECRET = os.environ.get('ONELOGIN_CLIENT_SECRET') ONELOGIN_API_BASE = os.environ.get('ONELOGIN_API_BASE') MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '5000')) PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '250')) 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_access_token(): """ Obtain OAuth2 access token using client credentials grant. OneLogin uses /auth/oauth2/v2/token endpoint. """ base_url = ONELOGIN_API_BASE.rstrip('/') token_url = f"{base_url}/auth/oauth2/v2/token" headers = { 'Content-Type': 'application/json', 'Accept': 'application/json' } body = json.dumps({ 'grant_type': 'client_credentials', 'client_id': ONELOGIN_CLIENT_ID, 'client_secret': ONELOGIN_CLIENT_SECRET }) backoff = 1.0 for attempt in range(3): response = http.request('POST', token_url, body=body, 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("Failed to get access token after 3 retries") @functions_framework.cloud_event def main(cloud_event): """ Cloud Run function triggered by Pub/Sub to fetch OneLogin event logs and write to GCS. Args: cloud_event: CloudEvent object containing Pub/Sub message """ if not all([GCS_BUCKET, ONELOGIN_CLIENT_ID, ONELOGIN_CLIENT_SECRET, ONELOGIN_API_BASE]): 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"]) # Overlap by 2 minutes to catch any delayed events 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_access_token() # Fetch events 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}") # Update state with newest event time 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 event logs from the OneLogin Events API v2 with cursor-based pagination and rate limiting. Args: token: OAuth2 access token start_time: Start time for log query end_time: End time for log query page_size: Number of records per page (max 250) max_records: Maximum total records to fetch Returns: Tuple of (records list, newest_event_time ISO string) """ base_url = ONELOGIN_API_BASE.rstrip('/') endpoint = f"{base_url}/api/2/events" headers = { 'Authorization': f'Bearer {token}', 'Accept': 'application/json', 'User-Agent': 'GoogleSecOps-OneLoginSSOCollector/1.0' } records = [] newest_time = None page_num = 0 backoff = 1.0 start_iso = start_time.strftime('%Y-%m-%dT%H:%M:%SZ') end_iso = end_time.strftime('%Y-%m-%dT%H:%M:%SZ') cursor = None while True: page_num += 1 if len(records) >= max_records: print(f"Reached max_records limit ({max_records})") break params = [ f"limit={min(page_size, max_records - len(records))}", f"since={start_iso}", f"until={end_iso}" ] if cursor: params.append(f"cursor={cursor}") url = f"{endpoint}?{'&'.join(params)}" try: response = http.request('GET', url, headers=headers) # Handle rate limiting with exponential backoff 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 records, newest_time data = json.loads(response.data.decode('utf-8')) page_results = data.get('data', []) 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('created_at') 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}") # Check for next page using cursor from pagination pagination = data.get('pagination', {}) cursor = pagination.get('after_cursor') if not cursor: print("No more pages (no next cursor)") break except Exception as e: print(f"Error fetching logs: {e}") return records, newest_time print(f"Retrieved {len(records)} total records from {page_num} pages") return records, newest_time- requirements.txt:
functions-framework==3.* google-cloud-storage==2.* urllib3>=2.0.0点击部署以保存并部署该函数。
等待部署完成(2-3 分钟)。
创建 Cloud Scheduler 作业
Cloud Scheduler 会定期向 Pub/Sub 主题发布消息,从而触发 Cloud Run 函数。
- 在 GCP Console 中,前往 Cloud Scheduler。
- 点击创建作业。
提供以下配置详细信息:
设置 值 名称 onelogin-sso-logs-collector-hourly区域 选择与 Cloud Run 函数相同的区域 频率 0 * * * *(每小时一次,整点时)时区 选择时区(建议选择世界协调时间 [UTC]) 目标类型 Pub/Sub 主题 选择主题 onelogin-sso-logs-trigger消息正文 {}(空 JSON 对象)点击创建。
时间表频率选项
根据日志量和延迟时间要求选择频次:
| 频率 | Cron 表达式 | 使用场景 |
|---|---|---|
| 每隔 5 分钟 | */5 * * * * |
大批量、低延迟 |
| 每隔 15 分钟 | */15 * * * * |
搜索量中等 |
| 每小时 | 0 * * * * |
标准(推荐) |
| 每 6 小时 | 0 */6 * * * |
低成交量、批处理 |
| 每天 | 0 0 * * * |
历史数据收集 |
测试集成
- 在 Cloud Scheduler 控制台中,找到您的作业。
- 点击强制运行以手动触发作业。
- 等待几秒钟。
- 前往 Cloud Run > 服务。
- 点击
onelogin-sso-logs-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://onelogin-sso-logs/onelogin/logs_YYYYMMDD_HHMMSS.ndjson Successfully processed X records前往 Cloud Storage > 存储分区。
点击您的存储桶名称 (
onelogin-sso-logs)。转到
onelogin/文件夹。验证是否已创建具有当前时间戳的新
.ndjson文件。
如果您在日志中看到错误,请执行以下操作:
- HTTP 401:检查环境变量中的 API 凭据
- HTTP 403:在 OneLogin 管理门户中验证 API 凭据是否具有“读取所有内容”范围
- HTTP 429:速率限制 - 函数将自动重试并进行退避
- 缺少环境变量:检查是否已设置所有必需的变量
在 Google SecOps 中配置 Feed 以注入 OneLogin by One Identity 日志
- 依次前往 SIEM 设置 > Feed。
- 点击添加新 Feed。
- 点击配置单个 Feed。
- 在 Feed 名称字段中,输入 Feed 的名称(例如
OneLogin SSO Logs)。 - 选择 Google Cloud Storage V2 作为来源类型。
- 选择 OneLogin 作为日志类型。
点击获取服务账号。系统会显示一个唯一的服务账号电子邮件地址,例如:
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com复制此电子邮件地址。
点击下一步。
为以下输入参数指定值:
存储桶网址:输入带有前缀路径的 GCS 存储桶 URI:
gs://onelogin-sso-logs/onelogin/- 替换:
onelogin-sso-logs:您的 GCS 存储桶名称。onelogin:存储日志的可选前缀/文件夹路径(留空表示根目录)。
- 替换:
来源删除选项:根据您的偏好选择删除选项:
- 永不:转移后永不删除任何文件(建议用于测试)。
- 删除已转移的文件:在成功转移后删除文件。
删除已转移的文件和空目录:成功转移后删除文件和空目录。
文件存在时间上限:包含在过去指定天数内修改过的文件(默认值为 180 天)
资产命名空间:资产命名空间
注入标签:要应用于此 Feed 中事件的标签
点击下一步。
在最终确定界面中查看新的 Feed 配置,然后点击提交。
向 Google SecOps 服务账号授予 IAM 权限
Google SecOps 服务账号需要您的 GCS 存储桶的 Storage Object Viewer 角色。
- 前往 Cloud Storage > 存储分区。
- 点击您的存储桶名称。
- 前往权限标签页。
- 点击授予访问权限。
提供以下配置详细信息:
- 添加主账号:粘贴 Google SecOps 服务账号电子邮件地址
- 分配角色:选择 Storage Object Viewer
点击保存。
UDM 映射表
| 日志字段 | UDM 映射 | 逻辑 |
|---|---|---|
| id | metadata.product_log_id | 直接映射 |
| created_at | metadata.event_timestamp | 已转换为时间戳 |
| account_id | principal.namespace | 直接映射,转换为字符串 |
| actor_user_id | principal.user.userid | 直接映射,转换为字符串 |
| actor_user_name | principal.user.user_display_name | 直接映射 |
| user_id | target.user.userid | 直接映射,转换为字符串 |
| user_name | target.user.user_display_name | 直接映射 |
| event_type_id | metadata.product_event_type | 直接映射,转换为字符串 |
| ipaddr | principal.ip | 直接映射 |
| notes | metadata.description | 直接映射 |
| app_id | target.application | 直接映射,转换为字符串 |
| app_name | target.resource.name | 直接映射 |
| group_id | target.group.product_object_id | 直接映射,转换为字符串 |
| group_name | target.group.group_display_name | 直接映射 |
| directory_id | additional.fields.value.string_value(键:directory_id) | 直接映射 |
| role_id | principal.user.attribute.roles.id | 直接映射,转换为字符串 |
| role_name | principal.user.attribute.roles.name | 直接映射 |
| otp_device_id | additional.fields.value.string_value(键:otp_device_id) | 直接映射 |
| otp_device_name | additional.fields.value.string_value(键:otp_device_name) | 直接映射 |
| policy_id | security_result.rule_id | 直接映射,转换为字符串 |
| policy_name | security_result.rule_name | 直接映射 |
| client_id | additional.fields.value.string_value(键:client_id) | 直接映射 |
| browser_fingerprint | additional.fields.value.string_value(键:browser_fingerprint) | 直接映射 |
| custom_message | security_result.description | 直接映射 |
| error_description | security_result.description | 如果 custom_message 为空,则直接映射 |
| metadata.vendor_name | 设置为“OneLogin” | |
| metadata.product_name | 设置为“OneLogin SSO” | |
| metadata.log_type | 设置为“ONELOGIN_SSO” | |
| metadata.event_type | 根据 event_type_id 确定:对于身份验证事件,为 USER_LOGIN;对于应用访问事件,为 USER_RESOURCE_ACCESS;对于角色/权限更改,为 USER_CHANGE_PERMISSIONS;否则为 GENERIC_EVENT | |
user_attributes.username |
event.idm.read_only_udm.additional.fields |
从变更日志映射 |
adc_id |
event.idm.read_only_udm.additional.fields |
从变更日志映射 |
adc_name |
event.idm.read_only_udm.additional.fields |
从变更日志映射 |
user_attributes.openid_name |
event.idm.read_only_udm.additional.fields |
从变更日志映射 |
user_attributes.samaccountname |
event.idm.read_only_udm.additional.fields |
从变更日志映射 |
user_attributes.member_of |
event.idm.read_only_udm.additional.fields |
从变更日志映射 |
user_attributes.group_id |
event.idm.read_only_udm.target.group.product_object_id |
从变更日志映射 |
user_attributes.lastname |
principal.user.last_name |
从变更日志映射 |
user_attributes.firstname |
principal.user.first_name |
从变更日志映射 |
user_attributes.department |
principal.user.department |
从变更日志映射 |
user_attributes.title |
principal.user.title |
从变更日志映射 |
user_attributes.email |
principal.user.email_addresses |
从变更日志映射 |
id |
metadata.product_object_id |
从变更日志映射 |
assuming_acting_user_id |
additional.fields |
从变更日志映射 |
directory_sync_run_id |
additional.fields |
从变更日志映射 |
resource_type_id |
additional.fields |
从变更日志映射 |
user_agent |
network.http.parsed_user_agent |
从变更日志映射 |
otp_device_id |
principal.asset_id |
从变更日志映射 |
actor_system |
additional.fields |
从变更日志映射 |
operation_name |
additional.fields |
从变更日志映射 |
resolution |
additional.fields |
从变更日志映射 |
risk_cookie_id |
additional.fields |
从变更日志映射 |
event_type_ids |
additional.fields |
从变更日志映射 |
since |
additional.fields |
从变更日志映射 |
until |
additional.fields |
从变更日志映射 |
proxy_ip |
intermediary.ip |
从变更日志映射 |
更新日志
需要更多帮助?获得社区成员和 Google SecOps 专业人士的解答。