configuring-identity-aware-proxy-with-google-iap

# 使用 Google IAP 配置身份感知代理

## 适用场景

- 需要为 Google Cloud 应用程序（App Engine、Cloud Run、GKE、Compute Engine）提供基于身份的访问保护时
- 实施需要设备态势和位置验证的上下文感知访问时
- 无需 VPN 或公开 IP 即可安全访问内部工具时
- 需要对 Web 应用程序和 TCP 服务进行每请求认证和授权时
- 使用服务账号为 IAP 保护的资源配置程序化访问时

**不适用于**无法置于 HTTPS 负载均衡器后方的非 HTTP 应用程序、需要未经认证访问的面向公众的应用程序，或应用程序自行处理认证且 IAP 会与现有认证流程冲突的场景。

## 前置条件

- 已启用计费的 Google Cloud 项目
- 已启用 IAP API（`gcloud services enable iap.googleapis.com`）
- 部署在 HTTPS 负载均衡器、App Engine 或 Cloud Run 后方的应用程序
- 用于用户管理的 Cloud Identity 或 Google Workspace
- 已启用 Access Context Manager API 用于访问级别
- 已为项目配置 OAuth 同意屏幕

## 工作流程

### 步骤 1：在后端服务上启用 IAP

为不同 GCP 计算平台配置 IAP。

```bash
# 启用所需 API
gcloud services enable iap.googleapis.com
gcloud services enable accesscontextmanager.googleapis.com

# 创建 OAuth 同意屏幕
gcloud iap oauth-brands create \
  --application_title="Internal Applications" \
  --support_email=security@company.com

# 创建 OAuth 客户端
gcloud iap oauth-clients create \
  projects/PROJECT_ID/brands/BRAND_ID \
  --display_name="IAP Web Client"

# === 在 Compute Engine 后端服务上启用 IAP ===
gcloud compute backend-services update my-backend-service \
  --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET \
  --global

# === 在 App Engine 上启用 IAP ===
gcloud iap web enable \
  --resource-type=app-engine \
  --oauth2-client-id=CLIENT_ID \
  --oauth2-client-secret=CLIENT_SECRET

# === 在 Cloud Run 上启用 IAP ===
# 首先授予 IAP 服务账号 Cloud Run Invoker 角色
gcloud run services add-iam-policy-binding my-service \
  --member="serviceAccount:service-PROJECT_NUM@gcp-sa-iap.iam.gserviceaccount.com" \
  --role="roles/run.invoker" \
  --region=us-central1

# 在 Cloud Run 后端服务上启用 IAP
gcloud compute backend-services update my-cloud-run-backend \
  --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET \
  --global

# === 为 SSH/RDP 启用 IAP TCP 转发 ===
# 无需负载均衡器 - 使用 IAP 隧道
gcloud compute instances add-iam-policy-binding my-vm \
  --member="group:developers@company.com" \
  --role="roles/iap.tunnelResourceAccessor" \
  --zone=us-central1-a

# 通过 IAP 隧道进行 SSH
gcloud compute ssh my-vm --zone=us-central1-a --tunnel-through-iap

# 通过 IAP 隧道进行 RDP
gcloud compute start-iap-tunnel my-windows-vm 3389 \
  --local-host-port=localhost:3390 \
  --zone=us-central1-a
```

### 步骤 2：配置访问控制的 IAM 绑定

向特定用户和组授权，并可选设置访问级别条件。

```bash
# 向组授予基本访问权限
gcloud iap web add-iam-policy-binding \
  --resource-type=backend-services \
  --service=my-backend-service \
  --member="group:engineering@company.com" \
  --role="roles/iap.httpsResourceAccessor"

# 使用访问级别条件授予访问权限
gcloud iap web add-iam-policy-binding \
  --resource-type=backend-services \
  --service=finance-app \
  --member="group:finance@company.com" \
  --role="roles/iap.httpsResourceAccessor" \
  --condition='expression=request.auth.access_levels.exists(x, x == "accessPolicies/POLICY_ID/accessLevels/corporate-device"),title=RequireCorporateDevice,description=需要托管企业设备'

# 仅在工作时间授予访问权限
gcloud iap web add-iam-policy-binding \
  --resource-type=backend-services \
  --service=admin-console \
  --member="group:admins@company.com" \
  --role="roles/iap.httpsResourceAccessor" \
  --condition='expression=request.time.getHours("America/New_York") >= 8 && request.time.getHours("America/New_York") <= 18 && request.time.getDayOfWeek("America/New_York") >= 1 && request.time.getDayOfWeek("America/New_York") <= 5,title=BusinessHoursOnly'
```

### 步骤 3：使用 Access Context Manager 创建访问级别

使用设备属性和网络条件定义基于上下文的访问要求。

```bash
# 创建需要加密企业设备的访问级别
cat > managed-device.yaml << 'EOF'
- devicePolicy:
    allowedEncryptionStatuses:
      - ENCRYPTED
    osConstraints:
      - osType: DESKTOP_WINDOWS
        minimumVersion: "10.0.19045"
      - osType: DESKTOP_MAC
        minimumVersion: "14.0"
      - osType: DESKTOP_CHROME_OS
    requireScreenlock: true
    requireAdminApproval: true
    allowedDeviceManagementLevels:
      - ADVANCED
EOF

gcloud access-context-manager levels create managed-device \
  --policy=POLICY_ID \
  --title="托管设备" \
  --basic-level-spec=managed-device.yaml
```

### 步骤 4：配置会话设置和重新认证

为每个应用程序设置会话持续时间和重新认证策略。

```bash
# 为后端服务配置重新认证
# 敏感应用每 4 小时需要登录
gcloud iap settings set \
  --project=PROJECT_ID \
  --resource-type=compute \
  --service=finance-app \
  reauthSettings.method=LOGIN \
  reauthSettings.maxAge=14400s \
  reauthSettings.policyType=MINIMUM
```

### 步骤 5：为服务账号配置程序化访问

通过 IAP 保护的端点启用服务间通信。

```python
#!/usr/bin/env python3
"""使用服务账号凭据访问 IAP 保护的资源。"""

import google.auth
import google.auth.transport.requests
from google.auth import impersonated_credentials
import requests as req

IAP_CLIENT_ID = "YOUR_IAP_OAUTH_CLIENT_ID.apps.googleusercontent.com"
IAP_URL = "https://my-app.company.com/api/data"

def access_iap_resource():
    # 获取默认凭据（支持服务账号密钥或工作负载身份）
    credentials, project = google.auth.default()

    # 创建 IAP 认证请求
    authed_session = google.auth.transport.requests.AuthorizedSession(
        credentials,
        target_audience=IAP_CLIENT_ID
    )

    # 向 IAP 保护的资源发出请求
    response = authed_session.get(IAP_URL)
    print(f"状态: {response.status_code}")
    print(f"响应: {response.text[:500]}")

    return response

if __name__ == "__main__":
    access_iap_resource()
```

### 步骤 6：设置审计日志和监控

为所有 IAP 访问决策配置日志记录。

```bash
# 为 IAP 启用数据访问审计日志
gcloud projects get-iam-policy PROJECT_ID --format=json > policy.json

# 创建 IAP 访问拒绝的基于日志的指标
gcloud logging metrics create iap-denied-access \
  --description="IAP 访问拒绝次数" \
  --log-filter='resource.type="gce_backend_service" AND protoPayload.status.code=16'

# 查询 IAP 访问日志
gcloud logging read '
  resource.type="gce_backend_service"
  protoPayload.serviceName="iap.googleapis.com"
  timestamp >= "2026-02-22T00:00:00Z"
' --project=PROJECT_ID --format='table(timestamp,protoPayload.authenticationInfo.principalEmail,protoPayload.status.code,resource.labels.backend_service_name)' --limit=50
```

## 核心概念

| 术语 | 定义 |
|------|------|
| Identity-Aware Proxy | GCP 服务，拦截 Web 请求和 TCP 连接，认证用户并在代理到后端服务前评估访问策略 |
| 后端服务（Backend Service）| IAP 保护的 GCP 负载均衡器组件；可服务于 Compute Engine 实例、GKE Pod、Cloud Run 服务或 App Engine |
| IAP 隧道（IAP Tunnel）| 通过 IAP 的安全 TCP 隧道，允许在没有公开 IP 或 VPN 的情况下 SSH、RDP 访问虚拟机 |
| OAuth 同意屏幕 | GCP 配置，指定 IAP 认证期间向用户显示的应用名称和支持邮箱 |
| 访问级别（Access Level）| Access Context Manager 中 IAP 授权时评估的命名条件（设备态势、IP、地理位置）|
| 重新认证（Re-authentication）| IAP 功能，在可配置的会话持续时间后要求用户重新证明身份 |

## 工具与系统

- **Google Cloud IAP**：用于 GCP 应用程序和 TCP 服务的身份感知反向代理
- **Access Context Manager**：根据设备、网络和地理属性定义访问级别
- **gcloud CLI**：配置 IAP、访问级别和 IAM 绑定的命令行工具
- **IAP TCP Forwarding**：基于隧道的虚拟机访问，用于无公开 IP 的 SSH/RDP
- **Cloud Audit Logs**：所有 IAP 访问决策的不可变记录，用于合规性
- **Endpoint Verification**：Chrome 扩展程序，收集设备属性用于访问级别评估

## 常见场景

### 场景：使用 IAP 保护 15 个内部 GCP 服务

**场景背景**：一家电商公司在 GKE 和 Cloud Run 上运行 15 个内部服务（管理仪表板、内部 API、监控工具）。目前这些服务仅由 VPN 和防火墙规则保护，造成过多网络级访问。

**方法**：
1. 将所有服务部署在带托管 SSL 证书的 HTTPS 负载均衡器后方
2. 为每个后端服务启用 IAP，使用每服务独立的 OAuth 客户端
3. 创建将 Google Groups 映射到特定服务的 IAM 绑定（管理组 -> 管理仪表板，工程团队 -> 监控）
4. 定义访问级别：managed-device（加密 + 屏幕锁），corp-network（办公室 IP 范围）
5. 对管理仪表板和财务工具应用 managed-device 访问级别
6. 配置 IAP TCP 隧道用于 GKE 节点的 SSH 访问（替换 SSH 跳板机）
7. 为管理工具设置 4 小时重新认证，为监控工具设置 8 小时
8. 配置 Cloud Audit Logs 并为重复拒绝创建告警

**常见陷阱**：IAP 每请求增加 10-50ms 延迟；测试应用性能。通过 IAP 的 WebSocket 连接需要特定后端服务配置。GKE 内部的服务间调用应通过内部服务网格绕过 IAP，而非使用外部 IAP 端点。紧急访问应使用没有访问级别条件的单独 IAM 绑定。

## 输出格式

```
Google Cloud IAP 配置报告
==================================================
项目: ecommerce-internal
报告日期: 2026-02-23

IAP 保护的服务:
  后端服务:          12
  App Engine:         1
  Cloud Run:          2
  IAP TCP 隧道:       4（SSH 访问）
  总计:              19

访问控制:
  IAM 绑定:          34
  带访问级别:        18（52.9%）
  访问级别:           3（managed-device, corp-network, high-trust）

会话策略:
  管理工具:          4 小时重新认证（SECURE_KEY）
  敏感应用:          4 小时重新认证（LOGIN）
  通用工具:          8 小时重新认证（LOGIN）

访问日志（过去 24 小时）:
  总请求数:          23,456
  已认证:            23,289（99.3%）
  IAM 拒绝:             112
  访问级别拒绝:          55
  唯一用户数:            134
```