SATOSA Docker镜像文档

镜像概述

SATOSA（Secure Attribute Token Service）是一款可配置的代理工具，核心功能是在不同的认证协议之间进行转换，如SAML2、OpenID Connect和OAuth2。该镜像提供了SATOSA的容器化部署方案，便于快速集成到身份认证架构中，支持多种操作系统基础镜像和硬件架构。

!logo

维护与支持

• 维护方：Identity Python项目
• 获取帮助：Identity Python邮件列表 或 Identity Python Slack工作区（邀请链接）
• 问题反馈：GitHub Issues

支持的标签及对应Dockerfile链接

简单标签（Simple Tags）

• 8.5.1-bookworm, 8.5-bookworm, 8-bookworm, bookworm
• 8.5.1-alpine3.22, 8.5-alpine3.22, 8-alpine3.22, alpine3.22, 8.5.1-alpine, 8.5-alpine, 8-alpine, alpine

共享标签（Shared Tags）

• 8.5.1, 8.5, 8, latest:
  • 对应 8.5.1-bookworm

其他参考信息

• 支持的架构：amd64, arm64v8（更多信息）
• 镜像 artifact 详情：repo-info 仓库的 repos/satosa/ 目录（历史记录）（包含镜像元数据、传输大小等）
• 镜像更新：official-images 仓库的 library/satosa 标签、official-images 仓库的 library/satosa 文件（历史记录）
• 本文档来源：docs 仓库的 satosa/ 目录（历史记录）

核心功能与特性

• 多协议转换：支持SAML2、OpenID Connect、OAuth2等主流认证协议之间的双向转换
• 可配置代理：通过灵活的配置文件定制认证流程和协议映射规则
• 加密状态跟踪：使用加密Cookie跟踪认证流程进度，确保安全性
• SAML联邦支持：集成SAML发现服务，支持身份提供商选择
• 密钥自动生成：默认自动生成RSA密钥对，简化初始部署流程

使用场景

• 企业身份系统整合：在现有SAML2身份提供商与基于OpenID Connect的应用之间建立桥梁
• 跨平台认证代理：为不同协议的应用提供统一的认证入口
• 身份联邦接入：作为服务提供者接入SAML联邦，或作为身份提供者对接依赖方

使用方法

基本运行

启动SATOSA实例的基本命令：

docker run --name some-satosa -d satosa

端口映射

如需从主机访问实例（无需容器IP），使用端口映射：

docker run --name some-satosa -p 80:8080 -d satosa

注意：入口脚本在启动时会将SAML2元数据输出到容器日志，元数据中包含实例的基础URL（如 [***]）。浏览器必须能通过HTTPS访问实例。

配置文件

SATOSA镜像的配置文件存储在 /etc/satosa 目录。为保证实例间配置一致性（尤其是SAML2实体ID及相关密钥材料），需通过卷、绑定挂载或自定义镜像持久化配置。

入口脚本

默认情况下，若第一个参数为命令行标志，入口脚本会运行Gunicorn。例如，使用绑定挂载提供X.509证书和私钥，并启用HTTPS运行Gunicorn：

docker run --name some-satosa -p 443:8443 \
    -v /etc/letsencrypt/live/some-satosa/fullchain.pem:/etc/https.crt \
    -v /etc/letsencrypt/live/some-satosa/privkey.pem:/etc/https.key \
    -d satosa \
    -b0.0.0.0:8443 --certfile /etc/https.crt --keyfile /etc/https.key satosa.wsgi:app

若第一个参数为命令（非标志），入口脚本会运行该命令。例如，启动容器内的交互式非特权shell：

docker run -it --name some-satosa satosa bash

环境变量

入口脚本使用环境变量生成初始配置，所有变量均为可选。变量值可通过Docker密钥读取：在变量名后添加 _FILE（如 STATE_ENCRYPTION_KEY_FILE），并将其值设为密钥文件路径（如 /run/secrets/state_encryption_key）。

BASE_URL

SATOSA必须托管在网站根目录。此变量指定网站基础URL，默认值为 [***]。若设置，基础URL必须包含协议和主机名，不含尾部斜杠或路径，例如 [***]（不可为 [***] 或 [***]）。

STATE_ENCRYPTION_KEY

SATOSA使用加密Cookie跟踪认证流程进度。此变量可选设置状态Cookie的加密密钥，必须为字母数字值（如 ***SameAsMyLuggage）。若未指定，将自动生成32字符随机密钥。

SAML2_BACKEND_DISCO_SRV

在SAML信任联邦中，SATOSA通过SAML发现服务让用户选择身份提供商。此变量设置发现服务URL，默认值为SeamlessAccess。

SAML2_BACKEND_CERT 和 SAML2_BACKEND_KEY

SATOSA默认SAML后端微服务作为服务提供者（依赖方），向用户选择的身份提供商请求认证和属性。该微服务使用公钥加密技术签名认证请求并解密响应。这两个变量提供PEM格式的密钥材料，若未指定，将使用 BASE_URL 的主机名部分自动生成2048位RSA密钥对。

SAML2_FRONTEND_CERT 和 SAML2_FRONTEND_KEY

SATOSA默认SAML前端微服务作为身份提供商（凭证服务提供者），处理来自可信网站的认证请求并返回用户属性，使用公钥加密技术签名认证响应。这两个变量提供PEM格式的密钥材料，若未指定，将使用 BASE_URL 的主机名部分自动生成2048位RSA密钥对。

镜像变体

SATOSA镜像提供多种版本，适用于不同场景：

satosa:<version>（默认版本）

基于Debian系统（如bookworm），是通用镜像。若不确定需求，建议使用此版本。适合作为临时容器（挂载源码启动应用）或构建其他镜像的基础。标签中包含的 bookworm 等名称是Debian发行版的代号，指定基础系统版本，如需安装额外包，建议显式指定以减少版本变更带来的影响。

satosa:<version>-alpine

基于Alpine Linux（来自 alpine ***镜像），以极小的镜像体积为主要优势（基础镜像约5MB）。适合对镜像大小有严格要求的场景。注意：该变体使用musl libc而非glibc，部分依赖glibc的软件可能存在兼容性问题。此外，Alpine镜像通常不包含额外工具（如 git 或 bash），需在Dockerfile中自行安装（参考 alpine 镜像说明 了解包安装方法）。

许可信息

查看软件许可信息。与所有Docker镜像一样，本镜像可能包含其他软件，需遵守各自许可（如基础系统的Bash等）。自动检测的额外许可信息可在repo-info 仓库的 satosa/ 目录中找到。使用本镜像时，用户需确保遵守所有包含软件的相关许可。===SHORT_DESC=== SATOSA是一款可配置的代理工具，用于在SAML2、OpenID Connect和OAuth2等不同认证协议之间进行转换。 ===FULL_DESC===# SATOSA Docker镜像文档

镜像概述

SATOSA（Secure Attribute Token Service）是一款可配置的代理工具，核心功能是在不同的认证协议之间进行转换，如SAML2、OpenID Connect、OAuth2等。该镜像提供容器化部署方案，便于快速集成到身份认证架构中，支持多种操作系统基础和硬件架构。

!logo

维护与支持

• 维护方：Identity Python项目
• 获取帮助：Identity Python邮件列表 或 Identity Python Slack工作区（邀请链接）
• 问题反馈：GitHub Issues

支持的标签及Dockerfile链接

简单标签（Simple Tags）

• 8.5.1-bookworm, 8.5-bookworm, 8-bookworm, bookworm
• 8.5.1-alpine3.22, 8.5-alpine3.22, 8-alpine3.22, alpine3.22, 8.5.1-alpine, 8.5-alpine, 8-alpine, alpine

共享标签（Shared Tags）

• 8.5.1, 8.5, 8, latest:
  • 对应 8.5.1-bookworm

其他参考信息

• 支持架构：amd64, arm64v8（更多信息）
• 镜像详情：repo-info仓库repos/satosa/目录（历史记录）（含元数据、传输大小等）
• 镜像更新：official-images仓库library/satosa标签、library/satosa文件（历史记录）
• 文档来源：docs仓库satosa/目录（历史记录）

核心功能与特性

• 多协议转换：支持SAML2、OpenID Connect、OAuth2等协议双向转换
• 可配置代理：通过配置文件定制认证流程和协议映射规则
• 安全状态跟踪：使用加密Cookie跟踪认证流程，保障数据安全
• SAML联邦支持：集成发现服务，支持身份提供商选择
• 密钥自动管理：默认自动生成RSA密钥对，简化部署

使用场景

• 企业身份系统整合：连接SAML2身份提供商与OpenID Connect应用
• 跨平台认证代理：为不同协议应用提供统一认证入口
• 身份联邦接入：作为服务提供者接入SAML联邦或作为身份提供者对接依赖方

使用方法

基本运行

docker run --name some-satosa -d satosa

端口映射

如需从主机访问，映射容器端口（默认8080）：

docker run --name some-satosa -p 80:8080 -d satosa

注意：启动时容器日志会输出SAML2元数据，元数据中的基础URL需确保浏览器可通过HTTPS访问。

配置文件

配置存储路径：/etc/satosa，需通过卷、绑定挂载或自定义镜像持久化，以保留SAML2实体ID及密钥材料。

入口脚本

默认运行Gunicorn（若参数为命令行标志），示例：启用HTTPS运行

docker run --name some-satosa -p 443:8443 \
    -v /etc/letsencrypt/live/some-satosa/fullchain.pem:/etc/https.crt \
    -v /etc/letsencrypt/live/some-satosa/privkey.pem:/etc/https.key \
    -d satosa \
    -b0.0.0.0:8443 --certfile /etc/https.crt --keyfile /etc/https.key satosa.wsgi:app

若参数为命令，直接运行命令（如启动交互式shell）：