authelia/integration-duo

Duo Integration Test CI/CD Container 技术文档

1. 镜像概述

Duo Integration Test CI/CD Container 是一个专为自动化测试设计的Docker镜像，用于验证应用程序与Duo Security服务的集成功能。该镜像预集成Duo官方工具链及测试框架，支持在CI/CD流水线中无缝执行集成测试，确保应用与Duo认证、授权等安全功能的兼容性和稳定性。

2. 核心功能与特性

• 预配置Duo环境：内置Duo Security官方SDK（如duo_client、duo_universal）及CLI工具（duoctl），无需手动安装依赖
• 多测试框架支持：兼容主流测试框架（JUnit、PyTest、RSpec），适配多语言项目（Java、Python、Ruby）
• 参数化测试配置：通过环境变量灵活定义测试参数（如Duo API密钥、测试用例路径、超时时间）
• 标准化测试输出：支持JUnit XML格式测试报告，便于CI/CD平台（Jenkins、GitHub Actions）解析结果
• 跨平台兼容性：适配Linux/amd64架构，兼容主流CI/CD系统（GitHub Actions、GitLab CI、Jenkins、CircleCI）

3. 使用场景与适用范围

使用场景

• 开发阶段验证：开发团队本地调试时快速验证Duo集成功能（如登录流程、权限检查）
• CI/CD流水线集成：在代码提交/合并阶段自动执行集成测试，拦截集成异常
• 版本发布前校验：在生产环境部署前验证Duo服务依赖的稳定性（如API连通性、配置有效性）

适用范围

• 集成Duo双因素认证（2FA）的Web应用、移动应用、API服务
• 基于Duo Admin API开发的自动化管理工具
• 需通过Duo MFA/SSO进行身份验证的内部系统

4. 使用方法与配置说明

4.1 环境准备

• 已安装Docker Engine（20.10+）或Docker Desktop
• 拥有Duo开发者账号及测试环境（需获取Duo API密钥、集成密钥、API主机名）
• 测试用例文件（如tests/目录下的.java/.py测试脚本）

4.2 环境变量配置

通过环境变量配置测试参数，必填项需在运行容器时指定：

4.3 运行容器执行测试

步骤1：挂载测试用例

将本地测试用例目录挂载至容器内TEST_CASE_DIR指定路径（如/app/tests）。

步骤2：运行容器

通过docker run命令启动容器，传入环境变量并执行测试：

bash
docker run -it --rm \
  -e DUO_API_HOST="api-abc123.duosecurity.com" \
  -e DUO_IKEY="DIXXXXXXXXXXXXXXXXXX" \
  -e DUO_SKEY="your-secret-key-here" \
  -e TEST_FRAMEWORK="pytest" \
  -e TEST_CASE_DIR="/app/tests" \
  -v $(pwd)/local-tests:/app/tests \  # 挂载本地测试用例目录
  -v $(pwd)/reports:/tmp/reports \    # 挂载本地目录保存测试报告
  duosecurity/duo-integration-test:latest

步骤3：查看测试结果

测试完成后，容器自动退出，测试报告（如pytest.xml）将输出至TEST_REPORT_PATH（默认/tmp/reports），可通过挂载目录在本地查看。

5. Docker部署示例

5.1 Docker Run 命令示例（Python项目，PyTest框架）

bash
docker run --rm \
  -e DUO_API_HOST="api-abc123.duosecurity.com" \
  -e DUO_IKEY="DIXXXXXXXXXXXXXXXXXX" \
  -e DUO_SKEY="your-secret-key-here" \
  -e TEST_FRAMEWORK="pytest" \
  -e TEST_CASE_DIR="/app/tests" \
  -e TEST_REPORT_PATH="/app/reports" \
  -v $(pwd)/tests:/app/tests \
  -v $(pwd)/duo-test-reports:/app/reports \
  docker.xuanyuan.run/duosecurity/duo-integration-test:latest

5.2 Docker Compose 配置示例

创建docker-compose.yml：

yaml
version: '3.8'
services:
  duo-test:
    image: docker.xuanyuan.run/duosecurity/duo-integration-test:latest
    environment:
      DUO_API_HOST: "api-abc123.duosecurity.com"
      DUO_IKEY: "DIXXXXXXXXXXXXXXXXXX"
      DUO_SKEY: "your-secret-key-here"
      TEST_FRAMEWORK: "pytest"
      TEST_CASE_DIR: "/app/tests"
      TEST_REPORT_PATH: "/app/reports"
    volumes:
      - ./tests:/app/tests:ro  # 只读挂载测试用例
      - ./duo-test-reports:/app/reports  # 持久化测试报告

执行测试：docker-compose up

5.3 GitHub Actions 集成示例

在.github/workflows/duo-test.yml中配置：

yaml
name: Duo Integration Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Duo integration test
        run: |
          docker run --rm \
            -e DUO_API_HOST="${{ secrets.DUO_API_HOST }}" \
            -e DUO_IKEY="${{ secrets.DUO_IKEY }}" \
            -e DUO_SKEY="${{ secrets.DUO_SKEY }}" \
            -e TEST_FRAMEWORK="pytest" \
            -e TEST_CASE_DIR="/app/tests" \
            -v ${{ docker.xuanyuan.run/github.workspace }}/tests:/app/tests \
            -v ${{ docker.xuanyuan.run/github.workspace }}/reports:/tmp/reports \
            duosecurity/duo-integration-test:latest

      - name: Upload test report
        uses: actions/upload-artifact@v3
        with:
          name: duo-test-report
          path: ./reports/

6. 配置参数说明

核心环境变量

可选环境变量

7. 注意事项

• 密钥安全：DUO_SKEY属于敏感信息，需通过CI/CD平台的密钥管理功能（如GitHub Secrets）传递，禁止硬编码在配置文件中
• 测试环境隔离：建议使用Duo测试环境（非生产环境）执行测试，避免影响生产数据
• 网络权限：容器需访问互联网（Duo API地址），确保CI/CD环境网络策略允许出站连接至DUO_API_HOST
• 测试用例规范：测试用例需符合指定框架格式（如PyTest需以test_前缀命名函数），否则可能导致测试失败