Heimdall Docker镜像文档

1. 镜像概述与主要用途

Heimdall 是一款云原生身份感知代理（Identity Aware Proxy）和访问控制决策服务，受零信任（Zero Trust）理念启发，旨在为Web应用提供细粒度的身份认证、授权及上下文信息管理能力。其核心功能包括对传入的HTTP请求进行认证与授权校验、丰富请求上下文信息，并将处理后的主体信息（Subject Information）转换为上游服务所需的格式，且所有控制逻辑可由各后端服务独立配置。

2. 核心功能与特性

• 身份认证与授权：对传入的HTTP请求进行统一的身份认证和权限校验，拒绝未授权请求。
• 上下文信息增强：为请求添加额外的上下文信息（如用户属性、环境 metadata 等），辅助上游服务决策。
• 主体信息转换：将认证后的用户主体信息（如身份标识、权限声明）转换为上游服务兼容的格式（如JWT、HTTP头）。
• 后端服务独立控制：支持各后端服务根据自身需求独立配置认证授权策略，实现差异化访问控制。
• 多平台支持：提供跨架构镜像，支持 linux/amd64、linux/arm64、linux/arm/v7 平台。
• 安全保障：所有镜像通过 Cosign 进行签名，附带有 SBOM（软件物料清单） attestation，支持无密钥签名验证，确保镜像完整性与安全性。

3. 使用场景与适用范围

3.1 反向代理模式

作为反向代理部署于上游 API 或 Web 服务器前端，直接拦截并处理所有请求：

• 拒绝未通过认证授权的请求，保护上游服务免受未授权访问。
• 转发通过校验的请求，并附加处理后的身份信息。
• 适用场景：独立 API 服务保护、Web 应用身份前置验证。

3.2 决策服务模式

与现有 API 网关（如 Kong、NGINX、Envoy、Traefik 等）集成，作为策略决策点（PDP）：

• 接收网关转发的请求上下文，返回授权决策结果（允许/拒绝）。
• 无需直接处理流量，仅提供访问控制逻辑。
• 适用场景：复杂网关架构、已有流量路由层需增强身份认证能力。

4. 使用方法与配置说明

4.1 镜像选择

4.1.1 支持平台

Heimdall 提供多平台镜像，支持以下架构：

• linux/amd64
• linux/arm64
• linux/arm/v7

如需其他平台支持，可在 GitHub 仓库 提交 issue 或贡献代码。

4.1.2 镜像标签规则

• 稳定版：已发布版本，标签格式为 dadrus/heimdall:<version>（如 dadrus/heimdall:0.17.1），latest 标签指向最新稳定版。
• 开发版：基于 main 分支构建，标签格式为 dev（最新开发版）或 dev-<SHA>（特定提交，如 dev-730b2206）。

4.2 基本部署示例

4.2.1 Docker Run 命令

bash
# 使用最新稳定版镜像，挂载本地配置目录
docker run -d \
  --name heimdall \
  -p 8080:8080 \  # 暴露服务端口
  -v /path/to/local/config:/etc/heimdall \  # 挂载配置文件目录（需提前准备配置）
  dadrus/heimdall:latest

4.2.2 Docker Compose 配置

yaml
version: '3.8'
services:
  heimdall:
    image: dadrus/heimdall:latest
    container_name: heimdall
    ports:
      - "8080:8080"
    volumes:
      - ./config:/etc/heimdall  # 本地配置目录映射到容器内配置路径
    restart: unless-stopped
    # 如需自定义环境变量，可添加 environment 字段
    # environment:
    #   - LOG_LEVEL=info

注意：配置文件需参考 ***文档 编写，容器内默认配置路径为 /etc/heimdall。

4.3 镜像验证

Heimdall 镜像通过 Cosign 进行签名，签名与 SBOM attestation 存储于同一仓库，标签格式分别为 sha256-<SHA256>.sig（签名）和 sha256-<SHA256>.att（SBOM），采用无密钥签名机制。

验证方法及 SBOM 提取步骤详见 ***文档。

5. 许可证

Heimdall 基于 Apache-2.0 许可证开源。

6. 参考链接

• ***文档
• GitHub 仓库